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

Skip to content

Commit 84a275c

Browse files
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>
1 parent 4827968 commit 84a275c

File tree

3 files changed

+28
-16
lines changed

3 files changed

+28
-16
lines changed

Doc/conf.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,11 +101,13 @@
101101
('c:func', 'dlopen'),
102102
('c:func', 'exec'),
103103
('c:func', 'fcntl'),
104+
('c:func', 'flock'),
104105
('c:func', 'fork'),
105106
('c:func', 'free'),
106107
('c:func', 'gettimeofday'),
107108
('c:func', 'gmtime'),
108109
('c:func', 'grantpt'),
110+
('c:func', 'ioctl'),
109111
('c:func', 'localeconv'),
110112
('c:func', 'localtime'),
111113
('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

@@ -101,7 +101,7 @@ The module defines the following functions:
101101
most likely to result in a segmentation violation or a more subtle data
102102
corruption.
103103

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

106106
.. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
107107

@@ -139,7 +139,7 @@ The module defines the following functions:
139139
buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
140140
into the supplied buffer.
141141

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

144144
An example::
145145

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

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

169169
.. audit-event:: fcntl.flock fd,operation fcntl.flock
170170

@@ -176,17 +176,28 @@ The module defines the following functions:
176176
method are accepted as well) of the file to lock or unlock, and *cmd*
177177
is one of the following values:
178178

179-
* :const:`LOCK_UN` -- unlock
180-
* :const:`LOCK_SH` -- acquire a shared lock
181-
* :const:`LOCK_EX` -- acquire an exclusive lock
179+
.. data:: LOCK_UN
182180

183-
When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
184-
bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
185-
If :const:`LOCK_NB` is used and the lock cannot be acquired, an
181+
Release an existing lock.
182+
183+
.. data:: LOCK_SH
184+
185+
Acquire a shared lock.
186+
187+
.. data:: LOCK_EX
188+
189+
Acquire an exclusive lock.
190+
191+
.. data:: LOCK_NB
192+
193+
Bitwise OR with any of the other three ``LOCK_*`` constants to make
194+
the request non-blocking.
195+
196+
If :const:`!LOCK_NB` is used and the lock cannot be acquired, an
186197
:exc:`OSError` will be raised and the exception will have an *errno*
187-
attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
198+
attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending on the
188199
operating system; for portability, check for both values). On at least some
189-
systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
200+
systems, :const:`!LOCK_EX` can only be used if the file descriptor refers to a
190201
file opened for writing.
191202

192203
*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
@@ -29,7 +29,6 @@ Doc/library/email.parser.rst
2929
Doc/library/email.policy.rst
3030
Doc/library/exceptions.rst
3131
Doc/library/faulthandler.rst
32-
Doc/library/fcntl.rst
3332
Doc/library/functools.rst
3433
Doc/library/http.cookiejar.rst
3534
Doc/library/http.server.rst

0 commit comments

Comments
 (0)
0