From 07b081d11b0d47120ec915adb826cf6ea4c16977 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 21 Apr 2025 09:23:42 +0300 Subject: [PATCH 1/5] gh-132742: Update documentation for the fcntl module --- Doc/library/fcntl.rst | 65 +++++++++++++++++++++++++++---------------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 7bd64e43dd5bfe..25a98f379f347a 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -89,20 +89,32 @@ The module defines the following functions: 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 + :class:`bytes` object, or a string. + The type and the size of *arg* must match the type and the size of + the argument of the operation as specified in the relevant C documentation. + + 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`. + 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 the 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 @@ -111,36 +123,41 @@ The module defines the following functions: 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 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 one of an integer, a :term:`bytes-like object`, + or a string. + The type and the size of *arg* must match the type and the 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 + a *mutate_flag* is false, behaviour 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 the size of *arg* does not match the type or the 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, + 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 From a35188d6ba6b8e2b494a042e913f5cf7040da867 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 21 Apr 2025 12:37:31 +0300 Subject: [PATCH 2/5] document all parameters as positional-only. --- Doc/library/fcntl.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 25a98f379f347a..8054e4ea7d949a 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -82,7 +82,7 @@ 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 @@ -118,7 +118,7 @@ The module defines the following functions: .. 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. @@ -174,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 @@ -186,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` From a8f1537b79061b5983db0b90c70927aae6e4b131 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 21 Apr 2025 13:50:32 +0300 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/fcntl.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 8054e4ea7d949a..f31b15b4a07753 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -88,9 +88,9 @@ The module defines the following functions: 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 + header files. The argument *arg* can either be an integer value, a :class:`bytes` object, or a string. - The type and the size of *arg* must match the type and the size of + 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. With an integer value, the return value of this function is the integer @@ -108,7 +108,7 @@ The module defines the following functions: 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 the size + 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), @@ -124,18 +124,18 @@ The module defines the following functions: that the argument handling is even more complicated. The *request* parameter is limited to values that can fit in 32-bits - or 64-bits, depending on platform. + 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, a :term:`bytes-like object`, or a string. - The type and the size of *arg* must match the type and the size of + 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. If *arg* does not support the read-write buffer interface or - a *mutate_flag* is false, behaviour is as for the :func:`~fcntl.fcntl` + the *mutate_flag* is false, behavior is as for the :func:`~fcntl.fcntl` function. If *arg* supports the read-write buffer interface (like :class:`bytearray`) @@ -150,8 +150,8 @@ The module defines the following functions: If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised. .. note:: - If the type or the size of *arg* does not match the type or the size - of the argument of the operation (for example, if an integer is + If the type or size of *arg* does not match the type or size + operations 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), From a4e24f4df95db8164822e2a7ebed5e2dde6c2f1a Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 21 Apr 2025 16:53:45 +0300 Subject: [PATCH 4/5] Update Doc/library/fcntl.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/fcntl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index f31b15b4a07753..28835d54441b80 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -151,7 +151,7 @@ The module defines the following functions: .. note:: If the type or size of *arg* does not match the type or size - operations argument (for example, if an integer is + 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), From ebbfe6ecbbbb574c08857f86704021d1291f7c26 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 22 Apr 2025 09:45:03 +0300 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Jelle Zijlstra Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/fcntl.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 28835d54441b80..3dcfe3b87f93d6 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -93,11 +93,11 @@ The module defines the following functions: 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. - With an integer value, the return value of this function is the integer + 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, - e.g. created by :func:`struct.pack`. + 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 @@ -129,7 +129,7 @@ The module defines the following functions: 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, a :term:`bytes-like object`, + 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.