8000 [3.11] gh-101100: Fix broken xrefs in fcntl module doc (GH-115691) (#… · python/cpython@2110ae8 · GitHub
[go: up one dir, main page]

Skip to content

Commit 2110ae8

Browse files
willingcsmontanaroCAM-Gerlach
authored
[3.11] gh-101100: Fix broken xrefs in fcntl module doc (GH-115691) (#115925)
* 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 84a275c) Co-authored-by: Skip Montanaro <skip.montanaro@gmail.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
1 parent 6324d9b commit 2110ae8

File tree

3 files changed

+29
-16
lines changed

3 files changed

+29
-16
lines changed

Doc/conf.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,13 @@
8888
('c:func', 'dlopen'),
8989
('c:func', 'exec'),
9090
('c:func', 'fcntl'),
91+
('c:func', 'flock'),
9192
('c:func', 'fork'),
9293
('c:func', 'free'),
9394
('c:func', 'gettimeofday'),
9495
('c:func', 'gmtime'),
96+
('c:func', 'grantpt'),
97+
('c:func', 'ioctl'),
9598
('c:func', 'localeconv'),
9699
('c:func', 'localtime'),
97100
('c:func', 'main'),

Doc/library/fcntl.rst

Lines changed: 26 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@
1313

1414
----------------
1515

16-
This module performs file control and I/O control on file descriptors. It is an
17-
interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a
18-
complete description of these calls, see :manpage:`fcntl(2)` and
19-
:manpage:`ioctl(2)` Unix manual pages.
16+
This module performs file and I/O control on file descriptors. It is an
17+
interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines.
18+
See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages
19+
for full details.
2020

2121
.. availability:: Unix, not Emscripten, not WASI.
2222

@@ -74,7 +74,7 @@ The module defines the following functions:
7474
most likely to result in a segmentation violation or a more subtle data
7575
corruption.
7676

77-
If the :c:func:`fcntl` fails, an :exc:`OSError` is raised.
77+
If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
7878

7979
.. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
8080

@@ -112,7 +112,7 @@ The module defines the following functions:
112112
buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
113113
into the supplied buffer.
114114

115-
If the :c:func:`ioctl` fails, an :exc:`OSError` exception is raised.
115+
If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised.
116116

117117
An example::
118118

@@ -137,7 +137,7 @@ The module defines the following functions:
137137
:manpage:`flock(2)` for details. (On some systems, this function is emulated
138138
using :c:func:`fcntl`.)
139139

140-
If the :c:func:`flock` fails, an :exc:`OSError` exception is raised.
140+
If the :c:func:`flock` call fails, an :exc:`OSError` exception is raised.
141141

142142
.. audit-event:: fcntl.flock fd,operation fcntl.flock
143143

@@ -149,17 +149,28 @@ The module defines the following functions:
149149
method are accepted as well) of the file to lock or unlock, and *cmd*
150150
is one of the following values:
151151

152-
* :const:`LOCK_UN` -- unlock
153-
* :const:`LOCK_SH` -- acquire a shared lock
154-
* :const:`LOCK_EX` -- acquire an exclusive lock
152+
.. data:: LOCK_UN
155153

156-
When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
157-
bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
158-
If :const:`LOCK_NB` is used and the lock cannot be acquired, an
154+
Release an existing lock.
155+
156+
.. data:: LOCK_SH
157+
158+
Acquire a shared lock.
159+
160+
.. data:: LOCK_EX
161+
162+
Acquire an exclusive lock.
163+
164+
.. data:: LOCK_NB
165+
166+
Bitwise OR with any of the other three ``LOCK_*`` constants to make
167+
the request non-blocking.
168+
169+
If :const:`!LOCK_NB` is used and the lock cannot be acquired, an
159170
:exc:`OSError` will be raised and the exception will have an *errno*
160-
attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
171+
attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending on the
161172
operating system; for portability, check for both values). On at least some
162-
systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
173+
systems, :const:`!LOCK_EX` can only be used if the file descriptor refers to a
163174
file opened for writing.
164175

165176
*len* is the number of bytes to lock, *start* is the byte offset at

Doc/tools/.nitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ Doc/library/email.parser.rst
3333
Doc/library/email.policy.rst
3434
Doc/library/exceptions.rst
3535
Doc/library/faulthandler.rst
36-
Doc/library/fcntl.rst
3736
Doc/library/functools.rst
3837
Doc/library/http.cookiejar.rst
3938
Doc/library/http.server.rst

0 commit comments

Comments
 (0)
0