gh-101100: Fix broken xrefs in fcntl module doc (#115691)

* 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

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

---------

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
Skip Montanaro 2024-02-25 14:02:18 -06:00 committed by GitHub
parent 4827968af8
commit 84a275c4a2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 28 additions and 16 deletions

View File

@ -101,11 +101,13 @@ nitpick_ignore = [
('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'),

View File

@ -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.
@ -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` call 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` call fails, an :exc:`OSError` exception is raised.
An example::
@ -164,7 +164,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
@ -176,17 +176,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

View File

@ -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