Debian Codegraph @

Doc/library/fcntl.rst

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