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. For acomplete description of these calls, seefcntl(2) andioctl(2) Unix manual pages.

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, or abytes object. With an integer value, the return value of thisfunction is the integer return value of the Cfcntl() call. Whenthe argument is bytes it represents a binary structure, e.g. created bystruct.pack(). 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 the information returnedin the buffer by the operating system is larger than 1024 bytes, this ismost likely to result in a segmentation violation or a more subtle datacorruption.

If thefcntl() fails, anOSError is raised.

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

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-bits.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 one of an integer, an object supporting theread-only buffer interface (likebytes) or an object supportingthe read-write buffer interface (likebytearray).

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

If theioctl() fails, anOSError exception is raised.

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.

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() 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:

• LOCK_UN – unlock

• LOCK_SH – acquire a shared lock

• LOCK_EX – acquire an exclusive lock

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

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.