34.9.fcntl — Thefcntl andioctl system calls¶

This module performs file control and I/O control on file descriptors. It is aninterface to thefcntl() andioctl() Unix routines.

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 aio.IOBase object, such assys.stdinitself, which provides afileno() that returns a genuine filedescriptor.

The module defines the following functions:

fcntl.fcntl(fd,op[,arg])¶

Perform the operationop on file descriptorfd (file objects providingafileno() method are accepted as well). The values usedforop are operating system dependent, and are available as constantsin thefcntl module, using the same names as used in the relevant Cheader files. The argumentarg is optional, and defaults to the integervalue0. When present, it can either be an integer value, or a string.With the argument missing or an integer value, the return value of this functionis the integer return value of the Cfcntl() call. When the argument isa string it represents a binary structure, e.g. created bystruct.pack().The binary data is copied to a buffer whose address is passed to the Cfcntl() call. The return value after a successful call is the contentsof the buffer, converted to a string object. The length of the returned stringwill be the same as the length of thearg argument. This is limited to 1024bytes. If the information returned in the buffer by the operating system islarger than 1024 bytes, this is most likely to result in a segmentationviolation or a more subtle data corruption.

If thefcntl() fails, anOSError is raised.

fcntl.ioctl(fd,op[,arg[,mutate_flag]])¶

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

The op parameter is limited to values that can fit in 32-bits.Additional constants of interest for use as theop argument can befound in thetermios module, under the same names as used inthe relevant C header files.

The parameterarg can be one of an integer, absent (treated identically to theinteger0), an object supporting the read-only buffer interface (most likelya plain Python string) or an object supporting the read-write buffer interface.

In all but the last case, behaviour is as for thefcntl()function.

If a mutable buffer is passed, then the behaviour is determined by the value ofthemutate_flag parameter.

If it is false, the buffer’s mutability is ignored and behaviour is as for aread-only buffer, except that the 1024 byte limit mentioned above is avoided –so long as the buffer you pass is as least as long as what the operating systemwants to put there, things should work.

Ifmutate_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.

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])

fcntl.flock(fd,op)¶

Perform the lock operationop 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().)

fcntl.lockf(fd,operation[,length[,start[,whence]]])¶

This is essentially a wrapper around thefcntl() locking calls.fd is the file descriptor of the file to lock or unlock, andoperationis one of the following values:

• LOCK_UN – unlock
• LOCK_SH – acquire a shared lock
• LOCK_EX – acquire an exclusive lock

Whenoperation isLOCK_SH orLOCK_EX, it can also bebitwise ORed withLOCK_NB to avoid blocking on lock acquisition.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.

length 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 forlength is 0 which means to lock to the end of the file. Thedefault forwhence is also 0.

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 a string value. The structurelay-out for thelockdata variable is system dependent — therefore using theflock() call may be better.