From 77dcb64ec6b78c3496e974c2393d8419f079593f Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Mon, 19 Feb 2024 14:42:31 -0600 Subject: [PATCH 1/7] clean up fcntl module doc --- Doc/library/fcntl.rst | 32 ++++++++++++++++---------------- Doc/tools/.nitignore | 1 - 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 13ad2dd7da5090..921776c1dabf90 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -14,8 +14,8 @@ ---------------- This module performs file control and I/O control on file descriptors. It is an -interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a -complete description of these calls, see :manpage:`fcntl(2)` and +interface to the :c:func:`!fcntl` and :c:func:`!ioctl` Unix system calls. For a +complete description of these calls, see the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages. .. availability:: Unix, not Emscripten, not WASI. @@ -90,10 +90,10 @@ The module defines the following functions: 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 + 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 - passed to the C :c:func:`fcntl` call. The return value after a successful + 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 @@ -101,7 +101,7 @@ The module defines the following functions: most likely to result in a segmentation violation or a more subtle data corruption. - If the :c:func:`fcntl` fails, an :exc:`OSError` is raised. + If the :c:func:`!fcntl` fails, an :exc:`OSError` is raised. .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl @@ -139,7 +139,7 @@ The module defines the following functions: buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back into the supplied buffer. - If the :c:func:`ioctl` fails, an :exc:`OSError` exception is raised. + If the :c:func:`!ioctl` fails, an :exc:`OSError` exception is raised. An example:: @@ -162,9 +162,9 @@ The module defines the following functions: 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 :manpage:`flock(2)` for details. (On some systems, this function is emulated - using :c:func:`fcntl`.) + using :c:func:`!fcntl`.) - If the :c:func:`flock` fails, an :exc:`OSError` exception is raised. + If the :c:func:`!flock` fails, an :exc:`OSError` exception is raised. .. audit-event:: fcntl.flock fd,operation fcntl.flock @@ -176,17 +176,17 @@ The module defines the following functions: method are accepted as well) of the file to lock or unlock, and *cmd* is one of the following values: - * :const:`LOCK_UN` -- unlock - * :const:`LOCK_SH` -- acquire a shared lock - * :const:`LOCK_EX` -- acquire an exclusive lock + * :const:`!LOCK_UN` -- unlock + * :const:`!LOCK_SH` -- acquire a shared lock + * :const:`!LOCK_EX` -- acquire an exclusive lock - When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be - bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. - If :const:`LOCK_NB` is used and the lock cannot be acquired, an + When *cmd* is :const:`!LOCK_SH` or :const:`!LOCK_EX`, it can also be + bitwise ORed with :const:`!LOCK_NB` to avoid blocking on lock acquisition. + If :const:`!LOCK_NB` is used and the lock cannot be acquired, an :exc:`OSError` will be raised and the exception will have an *errno* - attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the + attribute set to :data:`~errno.EACCES` or :data:`~errno.EAGAIN` (depending on the operating system; for portability, check for both values). On at least some - systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a + systems, :const:`!LOCK_EX` can only be used if the file descriptor refers to a file opened for writing. *len* is the number of bytes to lock, *start* is the byte offset at diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index eb45413d7cef78..a137dfc7e00e45 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -29,7 +29,6 @@ Doc/library/email.parser.rst Doc/library/email.policy.rst Doc/library/exceptions.rst Doc/library/faulthandler.rst -Doc/library/fcntl.rst Doc/library/functools.rst Doc/library/http.cookiejar.rst Doc/library/http.server.rst From 4e762742a683261fcd551d654cd07e49ec198089 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Mon, 19 Feb 2024 15:23:02 -0600 Subject: [PATCH 2/7] simplify --- Doc/library/fcntl.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 921776c1dabf90..7bbcaa75e9d57e 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -13,10 +13,9 @@ ---------------- -This module performs file control and I/O control on file descriptors. It is an -interface to the :c:func:`!fcntl` and :c:func:`!ioctl` Unix system calls. For a -complete description of these calls, see the :manpage:`fcntl(2)` and -:manpage:`ioctl(2)` Unix manual pages. +This module performs file control and I/O control on file +descriptors. See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix +manual pages for full details. .. availability:: Unix, not Emscripten, not WASI. From c1bde3f3b00d701c519467515b3293cb207dbf41 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Tue, 20 Feb 2024 19:31:50 -0600 Subject: [PATCH 3/7] a few changes, based on suggestion by CAM-Gerlach --- Doc/library/fcntl.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 7bbcaa75e9d57e..b547c18e4152b1 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -89,10 +89,10 @@ The module defines the following functions: 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 + 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 - passed to the C :c:func:`!fcntl` call. The return value after a successful + 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 @@ -100,7 +100,7 @@ The module defines the following functions: most likely to result in a segmentation violation or a more subtle data corruption. - If the :c:func:`!fcntl` fails, an :exc:`OSError` is raised. + If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised. .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl @@ -138,7 +138,7 @@ The module defines the following functions: buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back into the supplied buffer. - If the :c:func:`!ioctl` fails, an :exc:`OSError` exception is raised. + If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised. An example:: @@ -161,9 +161,9 @@ The module defines the following functions: 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 :manpage:`flock(2)` for details. (On some systems, this function is emulated - using :c:func:`!fcntl`.) + using :c:func:`fcntl`.) - If the :c:func:`!flock` fails, an :exc:`OSError` exception is raised. + If the :c:func:`flock` call fails, an :exc:`OSError` exception is raised. .. audit-event:: fcntl.flock fd,operation fcntl.flock From 26d22472442c986f4bd4fff02b57a1d8e5aabc17 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Tue, 20 Feb 2024 19:32:32 -0600 Subject: [PATCH 4/7] nitpick ignore for a couple other C functions mentioned in the fcntl module doc --- Doc/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/conf.py b/Doc/conf.py index 7c4817320a7de2..f4c75c5758cb28 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -101,11 +101,13 @@ ('c:func', 'dlopen'), ('c:func', 'exec'), ('c:func', 'fcntl'), + ('c:func', 'flock'), ('c:func', 'fork'), ('c:func', 'free'), ('c:func', 'gettimeofday'), ('c:func', 'gmtime'), ('c:func', 'grantpt'), + ('c:func', 'ioctl'), ('c:func', 'localeconv'), ('c:func', 'localtime'), ('c:func', 'main'), From 2dd471bf41460c54adad0bf17437a6494e6f9f81 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Wed, 21 Feb 2024 16:29:40 -0600 Subject: [PATCH 5/7] more changes, especially related to LOCK_* constants --- Doc/library/fcntl.rst | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index b547c18e4152b1..a92b7d501316a5 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -13,9 +13,10 @@ ---------------- -This module performs file control and I/O control on file -descriptors. See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix -manual pages for full details. +This module performs file and I/O control on file descriptors. It is +an interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. +See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages +for full details. .. availability:: Unix, not Emscripten, not WASI. @@ -175,12 +176,23 @@ The module defines the following functions: method are accepted as well) of the file to lock or unlock, and *cmd* is one of the following values: - * :const:`!LOCK_UN` -- unlock - * :const:`!LOCK_SH` -- acquire a shared lock - * :const:`!LOCK_EX` -- acquire an exclusive lock + .. data:: LOCK_UN + + release an existing lock + + .. data:: LOCK_SH + + acquire a shared lock + + .. data:: LOCK_EX + + acquire an exclusive lock + + .. data:: LOCK_NB + + bitwise OR with any of the other three constantsoperations to make + the request non-blocking. - When *cmd* is :const:`!LOCK_SH` or :const:`!LOCK_EX`, it can also be - bitwise ORed with :const:`!LOCK_NB` to avoid blocking on lock acquisition. If :const:`!LOCK_NB` is used and the lock cannot be acquired, an :exc:`OSError` will be raised and the exception will have an *errno* attribute set to :data:`~errno.EACCES` or :data:`~errno.EAGAIN` (depending on the From a697a0f8a4256f19af5a52fff37178d80519fa04 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Wed, 21 Feb 2024 16:31:22 -0600 Subject: [PATCH 6/7] :data: back to :const: --- 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 a92b7d501316a5..8cdab0950768cf 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -195,7 +195,7 @@ The module defines the following functions: If :const:`!LOCK_NB` is used and the lock cannot be acquired, an :exc:`OSError` will be raised and the exception will have an *errno* - attribute set to :data:`~errno.EACCES` or :data:`~errno.EAGAIN` (depending on the + attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending on the operating system; for portability, check for both values). On at least some systems, :const:`!LOCK_EX` can only be used if the file descriptor refers to a file opened for writing. From 5b5bf130d4d2179f31812fe530cda16abcb1f42e Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Fri, 23 Feb 2024 18:45:37 -0600 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/fcntl.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 8cdab0950768cf..b93d6ac7aab956 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -13,8 +13,8 @@ ---------------- -This module performs file and I/O control on file descriptors. It is -an interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. +This module performs file and I/O control on file descriptors. It is an +interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages for full details. @@ -178,20 +178,20 @@ The module defines the following functions: .. data:: LOCK_UN - release an existing lock + Release an existing lock. .. data:: LOCK_SH - acquire a shared lock + Acquire a shared lock. .. data:: LOCK_EX - acquire an exclusive lock + Acquire an exclusive lock. .. data:: LOCK_NB - bitwise OR with any of the other three constantsoperations to make - the request non-blocking. + Bitwise OR with any of the other three ``LOCK_*`` constants to make + the request non-blocking. If :const:`!LOCK_NB` is used and the lock cannot be acquired, an :exc:`OSError` will be raised and the exception will have an *errno*