https://github.com/python/cpython/commit/7307b562b049d886fc616596748540a6f8ae16eb
commit: 7307b562b049d886fc616596748540a6f8ae16eb
branch: 3.12
author: Carol Willing <carolc...@willingconsulting.com>
committer: willingc <carolc...@willingconsulting.com>
date: 2024-02-25T17:27:35-08:00
summary:
[3.12] gh-101100: Fix broken xrefs in fcntl module doc (GH-115691) (#115924)
* clean up fcntl module doc
* simplify
* a few changes, based on suggestion by CAM-Gerlach
* nitpick ignore for a couple other C functions mentioned in the fcntl module
doc
* more changes, especially related to LOCK_* constants
* :data: back to :const:
* Apply suggestions from code review
---------
(cherry picked from commit 84a275c4a2c8a22d198c6f227d538e6b27bbb029)
Co-authored-by: Skip Montanaro <skip.montan...@gmail.com>
Co-authored-by: C.A.M. Gerlach <cam.gerl...@gerlach.cam>
files:
M Doc/conf.py
M Doc/library/fcntl.rst
M Doc/tools/.nitignore
diff --git a/Doc/conf.py b/Doc/conf.py
index a6205e9eed068b..fdd4ac75df2c1d 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -93,10 +93,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'),
diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index 309ad652d4af34..4e083e122bb7f1 100644
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -13,10 +13,10 @@
----------------
-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
-:manpage:`ioctl(2)` Unix manual pages.
+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.
@@ -80,7 +80,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
@@ -118,7 +118,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::
@@ -143,7 +143,7 @@ The module defines the following functions:
:manpage:`flock(2)` for details. (On some systems, this function is
emulated
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
@@ -155,17 +155,28 @@ 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
- 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
+ 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 ``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*
- attribute set to :const:`EACCES` or :const:`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
+ 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 3dc0b1b5627032..e4b3cbbcd2336f 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -36,7 +36,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/getopt.rst
Doc/library/http.cookiejar.rst
_______________________________________________
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
