fcntl — Thefcntl andioctl system calls¶

This module performs file and I/O control on file descriptors. It is aninterface to thefcntl() andioctl() Unix routines.See thefcntl(2) andioctl(2) Unix manual pagesfor full details.

All functions in this module take a file descriptorfd as their firstargument. This can be an integer file descriptor, such as returned bysys.stdin.fileno(), or anio.IOBase object, such assys.stdinitself, which provides afileno() that returns a genuine filedescriptor.

The module defines the following functions:

fcntl.fcntl(fd,cmd,arg=0,/)¶

Perform the operationcmd on file descriptorfd (file objects providingafileno() method are accepted as well). The values usedforcmd are operating system dependent, and are available as constantsin thefcntl module, using the same names as used in the relevant Cheader files. The argumentarg can either be an integer value, abytes-like object, or a string.The type and size ofarg must match the type and size ofthe argument of the operation as specified in the relevant C documentation.

Whenarg is an integer, the function returns the integerreturn value of the Cfcntl() call.

When the argument is bytes-like object, it represents a binary structure,for example, created bystruct.pack().A string value is encoded to binary using the UTF-8 encoding.The binary data is copied to a buffer whose address ispassed to the Cfcntl() call. The return value after a successfulcall is the contents of the buffer, converted to abytes object.The length of the returned object will be the same as the length of thearg argument. This is limited to 1024 bytes.

If thefcntl() call fails, anOSError is raised.

Σημείωση

If the type or the size ofarg does not match the type or sizeof the argument of the operation (for example, if an integer ispassed when a pointer is expected, or the information returned inthe buffer by the operating system is larger than 1024 bytes),this is most likely to result in a segmentation violation ora more subtle data corruption.

Raises anauditing eventfcntl.fcntl with argumentsfd,cmd,arg.

Άλλαξε στην έκδοση 3.14:Add support of arbitrarybytes-like objects,not onlybytes.

fcntl.ioctl(fd,request,arg=0,mutate_flag=True,/)¶

This function is identical to thefcntl() function, exceptthat the argument handling is even more complicated.

Therequest parameter is limited to values that can fit in 32-bitsor 64-bits, depending on the platform.Additional constants of interest for use as therequest argument can befound in thetermios module, under the same names as used inthe relevant C header files.

The parameterarg can be an integer, abytes-like object,or a string.The type and size ofarg must match the type and size ofthe argument of the operation as specified in the relevant C documentation.

Ifarg does not support the read-write buffer interface orthemutate_flag is false, behavior is as for thefcntl()function.

Ifarg supports the read-write buffer interface (likebytearray)andmutate_flag is true (the default), then the buffer is (in effect) passedto the underlyingioctl() system call, the latter’s return code ispassed back to the calling Python, and the buffer’s new contents reflect theaction of theioctl(). This is a slight simplification, because if thesupplied buffer is less than 1024 bytes long it is first copied into a staticbuffer 1024 bytes long which is then passed toioctl() and copied backinto the supplied buffer.

If theioctl() call fails, anOSError exception is raised.

Σημείωση

If the type or size ofarg does not match the type or sizeof the operation’s argument (for example, if an integer ispassed when a pointer is expected, or the information returned inthe buffer by the operating system is larger than 1024 bytes,or the size of the mutable bytes-like object is too small),this is most likely to result in a segmentation violation ora more subtle data corruption.

An example:

>>>importarray,fcntl,struct,termios,os>>>os.getpgrp()13341>>>struct.unpack('h',fcntl.ioctl(0,termios.TIOCGPGRP,"  "))[0]13341>>>buf=array.array('h',[0])>>>fcntl.ioctl(0,termios.TIOCGPGRP,buf,1)0>>>bufarray('h', [13341])

Raises anauditing eventfcntl.ioctl with argumentsfd,request,arg.

Άλλαξε στην έκδοση 3.14:The GIL is always released during a system call.System calls failing with EINTR are automatically retried.

fcntl.flock(fd,operation,/)¶

Perform the lock operationoperation on file descriptorfd (file objects providingafileno() method are accepted as well). See the Unix manualflock(2) for details. (On some systems, this function is emulatedusingfcntl().)

If theflock() call fails, anOSError exception is raised.

Raises anauditing eventfcntl.flock with argumentsfd,operation.

fcntl.lockf(fd,cmd,len=0,start=0,whence=0,/)¶

This is essentially a wrapper around thefcntl() locking calls.fd is the file descriptor (file objects providing afileno()method are accepted as well) of the file to lock or unlock, andcmdis one of the following values:

fcntl.LOCK_UN¶

Release an existing lock.

fcntl.LOCK_SH¶

Acquire a shared lock.

fcntl.LOCK_EX¶

Acquire an exclusive lock.

fcntl.LOCK_NB¶

Bitwise OR with any of the other threeLOCK_* constants to makethe request non-blocking.

IfLOCK_NB is used and the lock cannot be acquired, anOSError will be raised and the exception will have anerrnoattribute set toEACCES orEAGAIN (depending on theoperating system; for portability, check for both values). On at least somesystems,LOCK_EX can only be used if the file descriptor refers to afile opened for writing.

len is the number of bytes to lock,start is the byte offset atwhich the lock starts, relative towhence, andwhence is as withio.IOBase.seek(), specifically:

• 0 – relative to the start of the file (os.SEEK_SET)

• 1 – relative to the current buffer position (os.SEEK_CUR)

• 2 – relative to the end of the file (os.SEEK_END)

The default forstart is 0, which means to start at the beginning of the file.The default forlen is 0 which means to lock to the end of the file. Thedefault forwhence is also 0.

Raises anauditing eventfcntl.lockf with argumentsfd,cmd,len,start,whence.

Examples (all on a SVR4 compliant system):

importstruct,fcntl,osf=open(...)rv=fcntl.fcntl(f,fcntl.F_SETFL,os.O_NDELAY)lockdata=struct.pack('hhllhh',fcntl.F_WRLCK,0,0,0,0,0)rv=fcntl.fcntl(f,fcntl.F_SETLKW,lockdata)

Note that in the first example the return value variablerv will hold aninteger value; in the second example it will hold abytes object. Thestructure lay-out for thelockdata variable is system dependent — thereforeusing theflock() call may be better.