1:mod:`fcntl` --- The ``fcntl`` and ``ioctl`` system calls 2========================================================= 3 4.. module:: fcntl 5 :platform: Unix 6 :synopsis: The fcntl() and ioctl() system calls. 7 8.. sectionauthor:: Jaap Vermeulen 9 10.. index:: 11 pair: UNIX; file control 12 pair: UNIX; I/O control 13 14---------------- 15 16This module performs file control and I/O control on file descriptors. It is an 17interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a 18complete description of these calls, see :manpage:`fcntl(2)` and 19:manpage:`ioctl(2)` Unix manual pages. 20 21All functions in this module take a file descriptor *fd* as their first 22argument. This can be an integer file descriptor, such as returned by 23``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as ``sys.stdin`` 24itself, which provides a :meth:`~io.IOBase.fileno` that returns a genuine file 25descriptor. 26 27.. versionchanged:: 3.3 28 Operations in this module used to raise an :exc:`IOError` where they now 29 raise an :exc:`OSError`. 30 31.. versionchanged:: 3.8 32 The fcntl module now contains ``F_ADD_SEALS``, ``F_GET_SEALS``, and 33 ``F_SEAL_*`` constants for sealing of :func:`os.memfd_create` file 34 descriptors. 35 36The module defines the following functions: 37 38 39.. function:: fcntl(fd, cmd, arg=0) 40 41 Perform the operation *cmd* on file descriptor *fd* (file objects providing 42 a :meth:`~io.IOBase.fileno` method are accepted as well). The values used 43 for *cmd* are operating system dependent, and are available as constants 44 in the :mod:`fcntl` module, using the same names as used in the relevant C 45 header files. The argument *arg* can either be an integer value, or a 46 :class:`bytes` object. With an integer value, the return value of this 47 function is the integer return value of the C :c:func:`fcntl` call. When 48 the argument is bytes it represents a binary structure, e.g. created by 49 :func:`struct.pack`. The binary data is copied to a buffer whose address is 50 passed to the C :c:func:`fcntl` call. The return value after a successful 51 call is the contents of the buffer, converted to a :class:`bytes` object. 52 The length of the returned object will be the same as the length of the 53 *arg* argument. This is limited to 1024 bytes. If the information returned 54 in the buffer by the operating system is larger than 1024 bytes, this is 55 most likely to result in a segmentation violation or a more subtle data 56 corruption. 57 58 If the :c:func:`fcntl` fails, an :exc:`OSError` is raised. 59 60 .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl 61 62 63.. function:: ioctl(fd, request, arg=0, mutate_flag=True) 64 65 This function is identical to the :func:`~fcntl.fcntl` function, except 66 that the argument handling is even more complicated. 67 68 The *request* parameter is limited to values that can fit in 32-bits. 69 Additional constants of interest for use as the *request* argument can be 70 found in the :mod:`termios` module, under the same names as used in 71 the relevant C header files. 72 73 The parameter *arg* can be one of an integer, an object supporting the 74 read-only buffer interface (like :class:`bytes`) or an object supporting 75 the read-write buffer interface (like :class:`bytearray`). 76 77 In all but the last case, behaviour is as for the :func:`~fcntl.fcntl` 78 function. 79 80 If a mutable buffer is passed, then the behaviour is determined by the value of 81 the *mutate_flag* parameter. 82 83 If it is false, the buffer's mutability is ignored and behaviour is as for a 84 read-only buffer, except that the 1024 byte limit mentioned above is avoided -- 85 so long as the buffer you pass is at least as long as what the operating system 86 wants to put there, things should work. 87 88 If *mutate_flag* is true (the default), then the buffer is (in effect) passed 89 to the underlying :func:`ioctl` system call, the latter's return code is 90 passed back to the calling Python, and the buffer's new contents reflect the 91 action of the :func:`ioctl`. This is a slight simplification, because if the 92 supplied buffer is less than 1024 bytes long it is first copied into a static 93 buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back 94 into the supplied buffer. 95 96 If the :c:func:`ioctl` fails, an :exc:`OSError` exception is raised. 97 98 An example:: 99 100 >>> import array, fcntl, struct, termios, os 101 >>> os.getpgrp() 102 13341 103 >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] 104 13341 105 >>> buf = array.array('h', [0]) 106 >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) 107 0 108 >>> buf 109 array('h', [13341]) 110 111 .. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl 112 113 114.. function:: flock(fd, operation) 115 116 Perform the lock operation *operation* on file descriptor *fd* (file objects providing 117 a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual 118 :manpage:`flock(2)` for details. (On some systems, this function is emulated 119 using :c:func:`fcntl`.) 120 121 If the :c:func:`flock` fails, an :exc:`OSError` exception is raised. 122 123 .. audit-event:: fcntl.flock fd,operation fcntl.flock 124 125 126.. function:: lockf(fd, cmd, len=0, start=0, whence=0) 127 128 This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. 129 *fd* is the file descriptor (file objects providing a :meth:`~io.IOBase.fileno` 130 method are accepted as well) of the file to lock or unlock, and *cmd* 131 is one of the following values: 132 133 * :const:`LOCK_UN` -- unlock 134 * :const:`LOCK_SH` -- acquire a shared lock 135 * :const:`LOCK_EX` -- acquire an exclusive lock 136 137 When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be 138 bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. 139 If :const:`LOCK_NB` is used and the lock cannot be acquired, an 140 :exc:`OSError` will be raised and the exception will have an *errno* 141 attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the 142 operating system; for portability, check for both values). On at least some 143 systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a 144 file opened for writing. 145 146 *len* is the number of bytes to lock, *start* is the byte offset at 147 which the lock starts, relative to *whence*, and *whence* is as with 148 :func:`io.IOBase.seek`, specifically: 149 150 * :const:`0` -- relative to the start of the file (:data:`os.SEEK_SET`) 151 * :const:`1` -- relative to the current buffer position (:data:`os.SEEK_CUR`) 152 * :const:`2` -- relative to the end of the file (:data:`os.SEEK_END`) 153 154 The default for *start* is 0, which means to start at the beginning of the file. 155 The default for *len* is 0 which means to lock to the end of the file. The 156 default for *whence* is also 0. 157 158 .. audit-event:: fcntl.lockf fd,cmd,len,start,whence fcntl.lockf 159 160Examples (all on a SVR4 compliant system):: 161 162 import struct, fcntl, os 163 164 f = open(...) 165 rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) 166 167 lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) 168 rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) 169 170Note that in the first example the return value variable *rv* will hold an 171integer value; in the second example it will hold a :class:`bytes` object. The 172structure lay-out for the *lockdata* variable is system dependent --- therefore 173using the :func:`flock` call may be better. 174 175 176.. seealso:: 177 178 Module :mod:`os` 179 If the locking flags :data:`~os.O_SHLOCK` and :data:`~os.O_EXLOCK` are 180 present in the :mod:`os` module (on BSD only), the :func:`os.open` 181 function provides an alternative to the :func:`lockf` and :func:`flock` 182 functions. 183