https://github.com/python/cpython/commit/5f50541ebd420a2d21a20c6f492e343657e06c1a
commit: 5f50541ebd420a2d21a20c6f492e343657e06c1a
branch: main
author: Serhiy Storchaka <storch...@gmail.com>
committer: serhiy-storchaka <storch...@gmail.com>
date: 2025-04-23T14:27:21+03:00
summary:
gh-132742: Update documentation for the fcntl module (GH-132765)
files:
M Doc/library/fcntl.rst
diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index 7bd64e43dd5bfe..3dcfe3b87f93d6 100644
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -82,65 +82,82 @@ descriptor.
The module defines the following functions:
-.. function:: fcntl(fd, cmd, arg=0)
+.. function:: fcntl(fd, cmd, arg=0, /)
Perform the operation *cmd* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). The values used
for *cmd* are operating system dependent, and are available as constants
in the :mod:`fcntl` module, using the same names as used in the relevant C
- header files. The argument *arg* can either be an integer value, or a
- :class:`bytes` object. With an integer value, the return value of this
- function is the integer return value of the C :c:func:`fcntl` call. When
- the argument is bytes it represents a binary structure, e.g. created by
- :func:`struct.pack`. The binary data is copied to a buffer whose address is
+ header files. The argument *arg* can either be an integer value, a
+ :class:`bytes` object, or a string.
+ The type and size of *arg* must match the type and size of
+ the argument of the operation as specified in the relevant C documentation.
+
+ When *arg* is an integer, the function returns the integer
+ return value of the C :c:func:`fcntl` call.
+
+ When the argument is bytes, it represents a binary structure,
+ for example, created by :func:`struct.pack`.
+ A string value is encoded to binary using the UTF-8 encoding.
+ The binary data is copied to a buffer whose address is
passed to the C :c:func:`fcntl` call. The return value after a successful
call is the contents of the buffer, converted to a :class:`bytes` object.
The length of the returned object will be the same as the length of the
- *arg* argument. This is limited to 1024 bytes. If the information returned
- in the buffer by the operating system is larger than 1024 bytes, this is
- most likely to result in a segmentation violation or a more subtle data
- corruption.
+ *arg* argument. This is limited to 1024 bytes.
If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
+ .. note::
+ If the type or the size of *arg* does not match the type or size
+ of the argument of the operation (for example, if an integer is
+ passed when a pointer is expected, or the information returned in
+ the buffer by the operating system is larger than 1024 bytes),
+ this is most likely to result in a segmentation violation or
+ a more subtle data corruption.
+
.. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
-.. function:: ioctl(fd, request, arg=0, mutate_flag=True)
+.. function:: ioctl(fd, request, arg=0, mutate_flag=True, /)
This function is identical to the :func:`~fcntl.fcntl` function, except
that the argument handling is even more complicated.
- The *request* parameter is limited to values that can fit in 32-bits.
+ The *request* parameter is limited to values that can fit in 32-bits
+ or 64-bits, depending on the platform.
Additional constants of interest for use as the *request* argument can be
found in the :mod:`termios` module, under the same names as used in
the relevant C header files.
- The parameter *arg* can be one of an integer, an object supporting the
- read-only buffer interface (like :class:`bytes`) or an object supporting
- the read-write buffer interface (like :class:`bytearray`).
+ The parameter *arg* can be an integer, a :term:`bytes-like object`,
+ or a string.
+ The type and size of *arg* must match the type and size of
+ the argument of the operation as specified in the relevant C documentation.
- In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
+ If *arg* does not support the read-write buffer interface or
+ the *mutate_flag* is false, behavior is as for the :func:`~fcntl.fcntl`
function.
- If a mutable buffer is passed, then the behaviour is determined by the
value of
- the *mutate_flag* parameter.
-
- If it is false, the buffer's mutability is ignored and behaviour is as for a
- read-only buffer, except that the 1024 byte limit mentioned above is
avoided --
- so long as the buffer you pass is at least as long as what the operating
system
- wants to put there, things should work.
-
- If *mutate_flag* is true (the default), then the buffer is (in effect)
passed
- to the underlying :func:`ioctl` system call, the latter's return code is
+ If *arg* supports the read-write buffer interface (like :class:`bytearray`)
+ and *mutate_flag* is true (the default), then the buffer is (in effect)
passed
+ to the underlying :c:func:`!ioctl` system call, the latter's return code is
passed back to the calling Python, and the buffer's new contents reflect the
- action of the :func:`ioctl`. This is a slight simplification, because if
the
+ action of the :c:func:`ioctl`. This is a slight simplification, because if
the
supplied buffer is less than 1024 bytes long it is first copied into a
static
buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
into the supplied buffer.
If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised.
+ .. note::
+ If the type or size of *arg* does not match the type or size
+ of the operation's argument (for example, if an integer is
+ passed when a pointer is expected, or the information returned in
+ the buffer by the operating system is larger than 1024 bytes,
+ or the size of the mutable bytes-like object is too small),
+ this is most likely to result in a segmentation violation or
+ a more subtle data corruption.
+
An example::
>>> import array, fcntl, struct, termios, os
@@ -157,7 +174,7 @@ The module defines the following functions:
.. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl
-.. function:: flock(fd, operation)
+.. function:: flock(fd, operation, /)
Perform the lock operation *operation* on file descriptor *fd* (file
objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix
manual
@@ -169,7 +186,7 @@ The module defines the following functions:
.. audit-event:: fcntl.flock fd,operation fcntl.flock
-.. function:: lockf(fd, cmd, len=0, start=0, whence=0)
+.. function:: lockf(fd, cmd, len=0, start=0, whence=0, /)
This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls.
*fd* is the file descriptor (file objects providing a
:meth:`~io.IOBase.fileno`
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
