| 1 |
:mod:`!fcntl` --- The ``fcntl`` and ``ioctl`` system calls |
| 2 |
========================================================== |
| 3 |
|
| 4 |
.. module:: fcntl |
| 5 |
:synopsis: The fcntl() and ioctl() system calls. |
| 6 |
|
| 7 |
.. sectionauthor:: Jaap Vermeulen |
| 8 |
|
| 9 |
.. index:: |
| 10 |
pair: UNIX; file control |
| 11 |
pair: UNIX; I/O control |
| 12 |
|
| 13 |
---------------- |
| 14 |
|
| 15 |
This module performs file and I/O control on file descriptors. It is an |
| 16 |
interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. |
| 17 |
See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages |
| 18 |
for full details. |
| 19 |
|
| 20 |
.. availability:: Unix, not WASI. |
| 21 |
|
| 22 |
All functions in this module take a file descriptor *fd* as their first |
| 23 |
argument. This can be an integer file descriptor, such as returned by |
| 24 |
``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as ``sys.stdin`` |
| 25 |
itself, which provides a :meth:`~io.IOBase.fileno` that returns a genuine file |
| 26 |
descriptor. |
| 27 |
|
| 28 |
.. versionchanged:: 3.3 |
| 29 |
Operations in this module used to raise an :exc:`IOError` where they now |
| 30 |
raise an :exc:`OSError`. |
| 31 |
|
| 32 |
.. versionchanged:: 3.8 |
| 33 |
The :mod:`!fcntl` module now contains ``F_ADD_SEALS``, ``F_GET_SEALS``, and |
| 34 |
``F_SEAL_*`` constants for sealing of :func:`os.memfd_create` file |
| 35 |
descriptors. |
| 36 |
|
| 37 |
.. versionchanged:: 3.9 |
| 38 |
On macOS, the :mod:`!fcntl` module exposes the ``F_GETPATH`` constant, |
| 39 |
which obtains the path of a file from a file descriptor. |
| 40 |
On Linux(>=3.15), the :mod:`!fcntl` module exposes the ``F_OFD_GETLK``, |
| 41 |
``F_OFD_SETLK`` and ``F_OFD_SETLKW`` constants, which are used when working |
| 42 |
with open file description locks. |
| 43 |
|
| 44 |
.. versionchanged:: 3.10 |
| 45 |
On Linux >= 2.6.11, the :mod:`!fcntl` module exposes the ``F_GETPIPE_SZ`` and |
| 46 |
``F_SETPIPE_SZ`` constants, which allow to check and modify a pipe's size |
| 47 |
respectively. |
| 48 |
|
| 49 |
.. versionchanged:: 3.11 |
| 50 |
On FreeBSD, the :mod:`!fcntl` module exposes the ``F_DUP2FD`` and |
| 51 |
``F_DUP2FD_CLOEXEC`` constants, which allow to duplicate a file descriptor, |
| 52 |
the latter setting ``FD_CLOEXEC`` flag in addition. |
| 53 |
|
| 54 |
.. versionchanged:: 3.12 |
| 55 |
On Linux >= 4.5, the :mod:`!fcntl` module exposes the ``FICLONE`` and |
| 56 |
``FICLONERANGE`` constants, which allow to share some data of one file with |
| 57 |
another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and |
| 58 |
XFS). This behavior is commonly referred to as "copy-on-write". |
| 59 |
|
| 60 |
.. versionchanged:: 3.13 |
| 61 |
On Linux >= 2.6.32, the :mod:`!fcntl` module exposes the |
| 62 |
``F_GETOWN_EX``, ``F_SETOWN_EX``, ``F_OWNER_TID``, ``F_OWNER_PID``, ``F_OWNER_PGRP`` constants, which allow to direct I/O availability signals |
| 63 |
to a specific thread, process, or process group. |
| 64 |
On Linux >= 4.13, the :mod:`!fcntl` module exposes the |
| 65 |
``F_GET_RW_HINT``, ``F_SET_RW_HINT``, ``F_GET_FILE_RW_HINT``, |
| 66 |
``F_SET_FILE_RW_HINT``, and ``RWH_WRITE_LIFE_*`` constants, which allow |
| 67 |
to inform the kernel about the relative expected lifetime of writes on |
| 68 |
a given inode or via a particular open file description. |
| 69 |
On Linux >= 5.1 and NetBSD, the :mod:`!fcntl` module exposes the |
| 70 |
``F_SEAL_FUTURE_WRITE`` constant for use with ``F_ADD_SEALS`` and |
| 71 |
``F_GET_SEALS`` operations. |
| 72 |
On FreeBSD, the :mod:`!fcntl` module exposes the ``F_READAHEAD``, ``F_ISUNIONSTACK``, and ``F_KINFO`` constants. |
| 73 |
On macOS and FreeBSD, the :mod:`!fcntl` module exposes the ``F_RDAHEAD`` |
| 74 |
constant. |
| 75 |
On NetBSD and AIX, the :mod:`!fcntl` module exposes the ``F_CLOSEM`` |
| 76 |
constant. |
| 77 |
On NetBSD, the :mod:`!fcntl` module exposes the ``F_MAXFD`` constant. |
| 78 |
On macOS and NetBSD, the :mod:`!fcntl` module exposes the ``F_GETNOSIGPIPE`` |
| 79 |
and ``F_SETNOSIGPIPE`` constant. |
| 80 |
|
| 81 |
.. versionchanged:: 3.14 |
| 82 |
On Linux >= 6.1, the :mod:`!fcntl` module exposes the ``F_DUPFD_QUERY`` |
| 83 |
to query a file descriptor pointing to the same file. |
| 84 |
|
| 85 |
The module defines the following functions: |
| 86 |
|
| 87 |
|
| 88 |
.. function:: fcntl(fd, cmd, arg=0, /) |
| 89 |
|
| 90 |
Perform the operation *cmd* on file descriptor *fd* (file objects providing |
| 91 |
a :meth:`~io.IOBase.fileno` method are accepted as well). The values used |
| 92 |
for *cmd* are operating system dependent, and are available as constants |
| 93 |
in the :mod:`!fcntl` module, using the same names as used in the relevant C |
| 94 |
header files. The argument *arg* can either be an integer value, a |
| 95 |
:term:`bytes-like object`, or a string. |
| 96 |
The type and size of *arg* must match the type and size of |
| 97 |
the argument of the operation as specified in the relevant C documentation. |
| 98 |
|
| 99 |
When *arg* is an integer, the function returns the integer |
| 100 |
return value of the C :c:func:`fcntl` call. |
| 101 |
|
| 102 |
When the argument is bytes-like object, it represents a binary structure, |
| 103 |
for example, created by :func:`struct.pack`. |
| 104 |
A string value is encoded to binary using the UTF-8 encoding. |
| 105 |
The binary data is copied to a buffer whose address is |
| 106 |
passed to the C :c:func:`fcntl` call. The return value after a successful |
| 107 |
call is the contents of the buffer, converted to a :class:`bytes` object. |
| 108 |
The length of the returned object will be the same as the length of the |
| 109 |
*arg* argument. This is limited to 1024 bytes. |
| 110 |
|
| 111 |
If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised. |
| 112 |
|
| 113 |
.. note:: |
| 114 |
If the type or the size of *arg* does not match the type or size |
| 115 |
of the argument of the operation (for example, if an integer is |
| 116 |
passed when a pointer is expected, or the information returned in |
| 117 |
the buffer by the operating system is larger than 1024 bytes), |
| 118 |
this is most likely to result in a segmentation violation or |
| 119 |
a more subtle data corruption. |
| 120 |
|
| 121 |
.. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl |
| 122 |
|
| 123 |
.. versionchanged:: 3.14 |
| 124 |
Add support of arbitrary :term:`bytes-like objects <bytes-like object>`, |
| 125 |
not only :class:`bytes`. |
| 126 |
|
| 127 |
|
| 128 |
.. function:: ioctl(fd, request, arg=0, mutate_flag=True, /) |
| 129 |
|
| 130 |
This function is identical to the :func:`~fcntl.fcntl` function, except |
| 131 |
that the argument handling is even more complicated. |
| 132 |
|
| 133 |
The *request* parameter is limited to values that can fit in 32-bits |
| 134 |
or 64-bits, depending on the platform. |
| 135 |
Additional constants of interest for use as the *request* argument can be |
| 136 |
found in the :mod:`termios` module, under the same names as used in |
| 137 |
the relevant C header files. |
| 138 |
|
| 139 |
The parameter *arg* can be an integer, a :term:`bytes-like object`, |
| 140 |
or a string. |
| 141 |
The type and size of *arg* must match the type and size of |
| 142 |
the argument of the operation as specified in the relevant C documentation. |
| 143 |
|
| 144 |
If *arg* does not support the read-write buffer interface or |
| 145 |
the *mutate_flag* is false, behavior is as for the :func:`~fcntl.fcntl` |
| 146 |
function. |
| 147 |
|
| 148 |
If *arg* supports the read-write buffer interface (like :class:`bytearray`) |
| 149 |
and *mutate_flag* is true (the default), then the buffer is (in effect) passed |
| 150 |
to the underlying :c:func:`!ioctl` system call, the latter's return code is |
| 151 |
passed back to the calling Python, and the buffer's new contents reflect the |
| 152 |
action of the :c:func:`ioctl`. This is a slight simplification, because if the |
| 153 |
supplied buffer is less than 1024 bytes long it is first copied into a static |
| 154 |
buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back |
| 155 |
into the supplied buffer. |
| 156 |
|
| 157 |
If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised. |
| 158 |
|
| 159 |
.. note:: |
| 160 |
If the type or size of *arg* does not match the type or size |
| 161 |
of the operation's argument (for example, if an integer is |
| 162 |
passed when a pointer is expected, or the information returned in |
| 163 |
the buffer by the operating system is larger than 1024 bytes, |
| 164 |
or the size of the mutable bytes-like object is too small), |
| 165 |
this is most likely to result in a segmentation violation or |
| 166 |
a more subtle data corruption. |
| 167 |
|
| 168 |
An example:: |
| 169 |
|
| 170 |
>>> import array, fcntl, struct, termios, os |
| 171 |
>>> os.getpgrp() |
| 172 |
13341 |
| 173 |
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] |
| 174 |
13341 |
| 175 |
>>> buf = array.array('h', [0]) |
| 176 |
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) |
| 177 |
0 |
| 178 |
>>> buf |
| 179 |
array('h', [13341]) |
| 180 |
|
| 181 |
.. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl |
| 182 |
|
| 183 |
.. versionchanged:: 3.14 |
| 184 |
The GIL is always released during a system call. |
| 185 |
System calls failing with EINTR are automatically retried. |
| 186 |
|
| 187 |
.. function:: flock(fd, operation, /) |
| 188 |
|
| 189 |
Perform the lock operation *operation* on file descriptor *fd* (file objects providing |
| 190 |
a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual |
| 191 |
:manpage:`flock(2)` for details. (On some systems, this function is emulated |
| 192 |
using :c:func:`fcntl`.) |
| 193 |
|
| 194 |
If the :c:func:`flock` call fails, an :exc:`OSError` exception is raised. |
| 195 |
|
| 196 |
.. audit-event:: fcntl.flock fd,operation fcntl.flock |
| 197 |
|
| 198 |
|
| 199 |
.. function:: lockf(fd, cmd, len=0, start=0, whence=0, /) |
| 200 |
|
| 201 |
This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. |
| 202 |
*fd* is the file descriptor (file objects providing a :meth:`~io.IOBase.fileno` |
| 203 |
method are accepted as well) of the file to lock or unlock, and *cmd* |
| 204 |
is one of the following values: |
| 205 |
|
| 206 |
.. data:: LOCK_UN |
| 207 |
|
| 208 |
Release an existing lock. |
| 209 |
|
| 210 |
.. data:: LOCK_SH |
| 211 |
|
| 212 |
Acquire a shared lock. |
| 213 |
|
| 214 |
.. data:: LOCK_EX |
| 215 |
|
| 216 |
Acquire an exclusive lock. |
| 217 |
|
| 218 |
.. data:: LOCK_NB |
| 219 |
|
| 220 |
Bitwise OR with any of the other three ``LOCK_*`` constants to make |
| 221 |
the request non-blocking. |
| 222 |
|
| 223 |
If :const:`!LOCK_NB` is used and the lock cannot be acquired, an |
| 224 |
:exc:`OSError` will be raised and the exception will have an *errno* |
| 225 |
attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending on the |
| 226 |
operating system; for portability, check for both values). On at least some |
| 227 |
systems, :const:`!LOCK_EX` can only be used if the file descriptor refers to a |
| 228 |
file opened for writing. |
| 229 |
|
| 230 |
*len* is the number of bytes to lock, *start* is the byte offset at |
| 231 |
which the lock starts, relative to *whence*, and *whence* is as with |
| 232 |
:func:`io.IOBase.seek`, specifically: |
| 233 |
|
| 234 |
* ``0`` -- relative to the start of the file (:const:`os.SEEK_SET`) |
| 235 |
* ``1`` -- relative to the current buffer position (:const:`os.SEEK_CUR`) |
| 236 |
* ``2`` -- relative to the end of the file (:const:`os.SEEK_END`) |
| 237 |
|
| 238 |
The default for *start* is 0, which means to start at the beginning of the file. |
| 239 |
The default for *len* is 0 which means to lock to the end of the file. The |
| 240 |
default for *whence* is also 0. |
| 241 |
|
| 242 |
.. audit-event:: fcntl.lockf fd,cmd,len,start,whence fcntl.lockf |
| 243 |
|
| 244 |
Examples (all on a SVR4 compliant system):: |
| 245 |
|
| 246 |
import struct, fcntl, os |
| 247 |
|
| 248 |
f = open(...) |
| 249 |
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) |
| 250 |
|
| 251 |
lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) |
| 252 |
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) |
| 253 |
|
| 254 |
Note that in the first example the return value variable *rv* will hold an |
| 255 |
integer value; in the second example it will hold a :class:`bytes` object. The |
| 256 |
structure lay-out for the *lockdata* variable is system dependent --- therefore |
| 257 |
using the :func:`flock` call may be better. |
| 258 |
|
| 259 |
|
| 260 |
.. seealso:: |
| 261 |
|
| 262 |
Module :mod:`os` |
| 263 |
If the locking flags :const:`~os.O_SHLOCK` and :const:`~os.O_EXLOCK` are |
| 264 |
present in the :mod:`os` module (on BSD only), the :func:`os.open` |
| 265 |
function provides an alternative to the :func:`lockf` and :func:`flock` |
| 266 |
functions. |