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 61.. function:: ioctl(fd, request, arg=0, mutate_flag=True) 62 63 This function is identical to the :func:`~fcntl.fcntl` function, except 64 that the argument handling is even more complicated. 65 66 The *request* parameter is limited to values that can fit in 32-bits. 67 Additional constants of interest for use as the *request* argument can be 68 found in the :mod:`termios` module, under the same names as used in 69 the relevant C header files. 70 71 The parameter *arg* can be one of an integer, an object supporting the 72 read-only buffer interface (like :class:`bytes`) or an object supporting 73 the read-write buffer interface (like :class:`bytearray`). 74 75 In all but the last case, behaviour is as for the :func:`~fcntl.fcntl` 76 function. 77 78 If a mutable buffer is passed, then the behaviour is determined by the value of 79 the *mutate_flag* parameter. 80 81 If it is false, the buffer's mutability is ignored and behaviour is as for a 82 read-only buffer, except that the 1024 byte limit mentioned above is avoided -- 83 so long as the buffer you pass is at least as long as what the operating system 84 wants to put there, things should work. 85 86 If *mutate_flag* is true (the default), then the buffer is (in effect) passed 87 to the underlying :func:`ioctl` system call, the latter's return code is 88 passed back to the calling Python, and the buffer's new contents reflect the 89 action of the :func:`ioctl`. This is a slight simplification, because if the 90 supplied buffer is less than 1024 bytes long it is first copied into a static 91 buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back 92 into the supplied buffer. 93 94 If the :c:func:`ioctl` fails, an :exc:`OSError` exception is raised. 95 96 An example:: 97 98 >>> import array, fcntl, struct, termios, os 99 >>> os.getpgrp() 100 13341 101 >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] 102 13341 103 >>> buf = array.array('h', [0]) 104 >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) 105 0 106 >>> buf 107 array('h', [13341]) 108 109 110.. function:: flock(fd, operation) 111 112 Perform the lock operation *operation* on file descriptor *fd* (file objects providing 113 a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual 114 :manpage:`flock(2)` for details. (On some systems, this function is emulated 115 using :c:func:`fcntl`.) 116 117 If the :c:func:`flock` fails, an :exc:`OSError` exception is raised. 118 119 120.. function:: lockf(fd, cmd, len=0, start=0, whence=0) 121 122 This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. 123 *fd* is the file descriptor (file objects providing a :meth:`~io.IOBase.fileno` 124 method are accepted as well) of the file to lock or unlock, and *cmd* 125 is one of the following values: 126 127 * :const:`LOCK_UN` -- unlock 128 * :const:`LOCK_SH` -- acquire a shared lock 129 * :const:`LOCK_EX` -- acquire an exclusive lock 130 131 When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be 132 bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. 133 If :const:`LOCK_NB` is used and the lock cannot be acquired, an 134 :exc:`OSError` will be raised and the exception will have an *errno* 135 attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the 136 operating system; for portability, check for both values). On at least some 137 systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a 138 file opened for writing. 139 140 *len* is the number of bytes to lock, *start* is the byte offset at 141 which the lock starts, relative to *whence*, and *whence* is as with 142 :func:`io.IOBase.seek`, specifically: 143 144 * :const:`0` -- relative to the start of the file (:data:`os.SEEK_SET`) 145 * :const:`1` -- relative to the current buffer position (:data:`os.SEEK_CUR`) 146 * :const:`2` -- relative to the end of the file (:data:`os.SEEK_END`) 147 148 The default for *start* is 0, which means to start at the beginning of the file. 149 The default for *len* is 0 which means to lock to the end of the file. The 150 default for *whence* is also 0. 151 152Examples (all on a SVR4 compliant system):: 153 154 import struct, fcntl, os 155 156 f = open(...) 157 rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) 158 159 lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) 160 rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) 161 162Note that in the first example the return value variable *rv* will hold an 163integer value; in the second example it will hold a :class:`bytes` object. The 164structure lay-out for the *lockdata* variable is system dependent --- therefore 165using the :func:`flock` call may be better. 166 167 168.. seealso:: 169 170 Module :mod:`os` 171 If the locking flags :data:`~os.O_SHLOCK` and :data:`~os.O_EXLOCK` are 172 present in the :mod:`os` module (on BSD only), the :func:`os.open` 173 function provides an alternative to the :func:`lockf` and :func:`flock` 174 functions. 175