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 The module defines the following functions:
82
83
84 .. function:: fcntl(fd, cmd, arg=0, /)
85
86 Perform the operation *cmd* on file descriptor *fd* (file objects providing
87 a :meth:`~io.IOBase.fileno` method are accepted as well). The values used
88 for *cmd* are operating system dependent, and are available as constants
89 in the :mod:`fcntl` module, using the same names as used in the relevant C
90 header files. The argument *arg* can either be an integer value, a
91 :class:`bytes` object, or a string.
92 The type and size of *arg* must match the type and size of
93 the argument of the operation as specified in the relevant C documentation.
94
95 When *arg* is an integer, the function returns the integer
96 return value of the C :c:func:`fcntl` call.
97
98 When the argument is bytes, it represents a binary structure,
99 for example, created by :func:`struct.pack`.
100 A string value is encoded to binary using the UTF-8 encoding.
101 The binary data is copied to a buffer whose address is
102 passed to the C :c:func:`fcntl` call. The return value after a successful
103 call is the contents of the buffer, converted to a :class:`bytes` object.
104 The length of the returned object will be the same as the length of the
105 *arg* argument. This is limited to 1024 bytes.
106
107 If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
108
109 .. note::
110 If the type or the size of *arg* does not match the type or size
111 of the argument of the operation (for example, if an integer is
112 passed when a pointer is expected, or the information returned in
113 the buffer by the operating system is larger than 1024 bytes),
114 this is most likely to result in a segmentation violation or
115 a more subtle data corruption.
116
117 .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
118
119
120 .. function:: ioctl(fd, request, arg=0, mutate_flag=True, /)
121
122 This function is identical to the :func:`~fcntl.fcntl` function, except
123 that the argument handling is even more complicated.
124
125 The *request* parameter is limited to values that can fit in 32-bits
126 or 64-bits, depending on the platform.
127 Additional constants of interest for use as the *request* argument can be
128 found in the :mod:`termios` module, under the same names as used in
129 the relevant C header files.
130
131 The parameter *arg* can be an integer, a :term:`bytes-like object`,
132 or a string.
133 The type and size of *arg* must match the type and size of
134 the argument of the operation as specified in the relevant C documentation.
135
136 If *arg* does not support the read-write buffer interface or
137 the *mutate_flag* is false, behavior is as for the :func:`~fcntl.fcntl`
138 function.
139
140 If *arg* supports the read-write buffer interface (like :class:`bytearray`)
141 and *mutate_flag* is true (the default), then the buffer is (in effect) passed
142 to the underlying :c:func:`!ioctl` system call, the latter's return code is
143 passed back to the calling Python, and the buffer's new contents reflect the
144 action of the :c:func:`ioctl`. This is a slight simplification, because if the
145 supplied buffer is less than 1024 bytes long it is first copied into a static
146 buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
147 into the supplied buffer.
148
149 If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised.
150
151 .. note::
152 If the type or size of *arg* does not match the type or size
153 of the operation's argument (for example, if an integer is
154 passed when a pointer is expected, or the information returned in
155 the buffer by the operating system is larger than 1024 bytes,
156 or the size of the mutable bytes-like object is too small),
157 this is most likely to result in a segmentation violation or
158 a more subtle data corruption.
159
160 An example::
161
162 >>> import array, fcntl, struct, termios, os
163 >>> os.getpgrp()
164 13341
165 >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]
166 13341
167 >>> buf = array.array('h', [0])
168 >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
169 0
170 >>> buf
171 array('h', [13341])
172
173 .. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl
174
175
176 .. function:: flock(fd, operation, /)
177
178 Perform the lock operation *operation* on file descriptor *fd* (file objects providing
179 a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual
180 :manpage:`flock(2)` for details. (On some systems, this function is emulated
181 using :c:func:`fcntl`.)
182
183 If the :c:func:`flock` call fails, an :exc:`OSError` exception is raised.
184
185 .. audit-event:: fcntl.flock fd,operation fcntl.flock
186
187
188 .. function:: lockf(fd, cmd, len=0, start=0, whence=0, /)
189
190 This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls.
191 *fd* is the file descriptor (file objects providing a :meth:`~io.IOBase.fileno`
192 method are accepted as well) of the file to lock or unlock, and *cmd*
193 is one of the following values:
194
195 .. data:: LOCK_UN
196
197 Release an existing lock.
198
199 .. data:: LOCK_SH
200
201 Acquire a shared lock.
202
203 .. data:: LOCK_EX
204
205 Acquire an exclusive lock.
206
207 .. data:: LOCK_NB
208
209 Bitwise OR with any of the other three ``LOCK_*`` constants to make
210 the request non-blocking.
211
212 If :const:`!LOCK_NB` is used and the lock cannot be acquired, an
213 :exc:`OSError` will be raised and the exception will have an *errno*
214 attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending on the
215 operating system; for portability, check for both values). On at least some
216 systems, :const:`!LOCK_EX` can only be used if the file descriptor refers to a
217 file opened for writing.
218
219 *len* is the number of bytes to lock, *start* is the byte offset at
220 which the lock starts, relative to *whence*, and *whence* is as with
221 :func:`io.IOBase.seek`, specifically:
222
223 * ``0`` -- relative to the start of the file (:const:`os.SEEK_SET`)
224 * ``1`` -- relative to the current buffer position (:const:`os.SEEK_CUR`)
225 * ``2`` -- relative to the end of the file (:const:`os.SEEK_END`)
226
227 The default for *start* is 0, which means to start at the beginning of the file.
228 The default for *len* is 0 which means to lock to the end of the file. The
229 default for *whence* is also 0.
230
231 .. audit-event:: fcntl.lockf fd,cmd,len,start,whence fcntl.lockf
232
233 Examples (all on a SVR4 compliant system)::
234
235 import struct, fcntl, os
236
237 f = open(...)
238 rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
239
240 lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
241 rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
242
243 Note that in the first example the return value variable *rv* will hold an
244 integer value; in the second example it will hold a :class:`bytes` object. The
245 structure lay-out for the *lockdata* variable is system dependent --- therefore
246 using the :func:`flock` call may be better.
247
248
249 .. seealso::
250
251 Module :mod:`os`
252 If the locking flags :const:`~os.O_SHLOCK` and :const:`~os.O_EXLOCK` are
253 present in the :mod:`os` module (on BSD only), the :func:`os.open`
254 function provides an alternative to the :func:`lockf` and :func:`flock`
255 functions.