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