Skip to content

Commit 8f12a21

Browse files
serhiy-storchakaserhiy-storchaka
committed
pythongh-132742: Update documentation for the fcntl module
1 parent 035823f commit 8f12a21

1 file changed

Lines changed: 41 additions & 24 deletions

File tree

‎Doc/library/fcntl.rst‎

Lines changed: 41 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -89,20 +89,32 @@ The module defines the following functions:
8989
for *cmd* are operating system dependent, and are available as constants
9090
in the :mod:`fcntl` module, using the same names as used in the relevant C
9191
header files. The argument *arg* can either be an integer value, or a
92-
:class:`bytes` object. With an integer value, the return value of this
93-
function is the integer return value of the C :c:func:`fcntl` call. When
94-
the argument is bytes it represents a binary structure, e.g. created by
95-
:func:`struct.pack`. The binary data is copied to a buffer whose address is
92+
:class:`bytes` object, or a string.
93+
The type and the size of *arg* must match the type and the size of
94+
the argument of the operation as specified in the relevant C documentation.
95+
96+
With an integer value, the return value of this function is the integer
97+
return value of the C :c:func:`fcntl` call.
98+
99+
When the argument is bytes, it represents a binary structure,
100+
e.g. created by :func:`struct.pack`.
101+
A string value is encoded to binary using the UTF-8 encoding.
102+
The binary data is copied to a buffer whose address is
96103
passed to the C :c:func:`fcntl` call. The return value after a successful
97104
call is the contents of the buffer, converted to a :class:`bytes` object.
98105
The length of the returned object will be the same as the length of the
99-
*arg* argument. This is limited to 1024 bytes. If the information returned
100-
in the buffer by the operating system is larger than 1024 bytes, this is
101-
most likely to result in a segmentation violation or a more subtle data
102-
corruption.
106+
*arg* argument. This is limited to 1024 bytes.
103107

104108
If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
105109

110+
.. note::
111+
If the type or the size of *arg* does not match the type or the size
112+
of the argument of the operation (for example, if an integer is
113+
passed when a pointer is expected, or the information returned in
114+
the buffer by the operating system is larger than 1024 bytes),
115+
this is most likely to result in a segmentation violation or
116+
a more subtle data corruption.
117+
106118
.. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
107119

108120

@@ -111,36 +123,41 @@ The module defines the following functions:
111123
This function is identical to the :func:`~fcntl.fcntl` function, except
112124
that the argument handling is even more complicated.
113125

114-
The *request* parameter is limited to values that can fit in 32-bits.
126+
The *request* parameter is limited to values that can fit in 32-bits
127+
or 64-bits, depending on platform.
115128
Additional constants of interest for use as the *request* argument can be
116129
found in the :mod:`termios` module, under the same names as used in
117130
the relevant C header files.
118131

119-
The parameter *arg* can be one of an integer, an object supporting the
120-
read-only buffer interface (like :class:`bytes`) or an object supporting
121-
the read-write buffer interface (like :class:`bytearray`).
132+
The parameter *arg* can be one of an integer, a :term:`bytes-like object`,
133+
or a string.
134+
The type and the size of *arg* must match the type and the size of
135+
the argument of the operation as specified in the relevant C documentation.
122136

123-
In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
137+
If *arg* does not support the read-write buffer interface or
138+
a *mutate_flag* is false, behaviour is as for the :func:`~fcntl.fcntl`
124139
function.
125140

126-
If a mutable buffer is passed, then the behaviour is determined by the value of
127-
the *mutate_flag* parameter.
128-
129-
If it is false, the buffer's mutability is ignored and behaviour is as for a
130-
read-only buffer, except that the 1024 byte limit mentioned above is avoided --
131-
so long as the buffer you pass is at least as long as what the operating system
132-
wants to put there, things should work.
133-
134-
If *mutate_flag* is true (the default), then the buffer is (in effect) passed
135-
to the underlying :func:`ioctl` system call, the latter's return code is
141+
If *arg* supports the read-write buffer interface (like :class:`bytearray`)
142+
and *mutate_flag* is true (the default), then the buffer is (in effect) passed
143+
to the underlying :c:func:`!ioctl` system call, the latter's return code is
136144
passed back to the calling Python, and the buffer's new contents reflect the
137-
action of the :func:`ioctl`. This is a slight simplification, because if the
145+
action of the :c:func:`ioctl`. This is a slight simplification, because if the
138146
supplied buffer is less than 1024 bytes long it is first copied into a static
139147
buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
140148
into the supplied buffer.
141149

142150
If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised.
143151

152+
.. note::
153+
If the type or the size of *arg* does not match the type or the size
154+
of the argument of the operation (for example, if an integer is
155+
passed when a pointer is expected, or the information returned in
156+
the buffer by the operating system is larger than 1024 bytes,
157+
or the size of the mutable bytes-like object is too small),
158+
this is most likely to result in a segmentation violation or
159+
a more subtle data corruption.
160+
144161
An example::
145162

146163
>>> import array, fcntl, struct, termios, os

0 commit comments

Comments
 (0)