gh-140615: Update docstrings in the fcntl module (GH-140619)
* Refer to bytes objects or bytes-like objects instead of strings. * Remove backticks -- they do not have effect on formatting. * Re-wrap lines to ensure the pydoc output fits in 80 coluimns. * Remove references to the 1024 bytes limit.
This commit is contained in:
Serhiy Storchaka
GitHub
90
Modules/clinic/fcntlmodule.c.h
generated
90
Modules/clinic/fcntlmodule.c.h
generated
@@ -8,17 +8,22 @@ PyDoc_STRVAR(fcntl_fcntl__doc__,
|
||||
"fcntl($module, fd, cmd, arg=0, /)\n"
|
||||
"--\n"
|
||||
"\n"
|
||||
"Perform the operation `cmd` on file descriptor fd.\n"
|
||||
"Perform the operation cmd on file descriptor fd.\n"
|
||||
"\n"
|
||||
"The values used for `cmd` are operating system dependent, and are available\n"
|
||||
"as constants in the fcntl module, using the same names as used in\n"
|
||||
"the relevant C header files. The argument arg is optional, and\n"
|
||||
"defaults to 0; it may be an int or a string. If arg is given as a string,\n"
|
||||
"the return value of fcntl is a string of that length, containing the\n"
|
||||
"resulting value put in the arg buffer by the operating system. The length\n"
|
||||
"of the arg string is not allowed to exceed 1024 bytes. If the arg given\n"
|
||||
"is an integer or if none is specified, the result value is an integer\n"
|
||||
"corresponding to the return value of the fcntl call in the C code.");
|
||||
"The values used for cmd are operating system dependent, and are\n"
|
||||
"available as constants in the fcntl module, using the same names as used\n"
|
||||
"in the relevant C header files. The argument arg is optional, and\n"
|
||||
"defaults to 0; it may be an integer, a bytes-like object or a string.\n"
|
||||
"If arg is given as a string, it will be encoded to binary using the\n"
|
||||
"UTF-8 encoding.\n"
|
||||
"\n"
|
||||
"If the arg given is an integer or if none is specified, the result value\n"
|
||||
"is an integer corresponding to the return value of the fcntl() call in\n"
|
||||
"the C code.\n"
|
||||
"\n"
|
||||
"If arg is given as a bytes-like object, the return value of fcntl() is a\n"
|
||||
"bytes object of that length, containing the resulting value put in the\n"
|
||||
"arg buffer by the operating system.");
|
||||
|
||||
#define FCNTL_FCNTL_METHODDEF \
|
||||
{"fcntl", _PyCFunction_CAST(fcntl_fcntl), METH_FASTCALL, fcntl_fcntl__doc__},
|
||||
@@ -60,34 +65,33 @@ PyDoc_STRVAR(fcntl_ioctl__doc__,
|
||||
"ioctl($module, fd, request, arg=0, mutate_flag=True, /)\n"
|
||||
"--\n"
|
||||
"\n"
|
||||
"Perform the operation `request` on file descriptor `fd`.\n"
|
||||
"Perform the operation request on file descriptor fd.\n"
|
||||
"\n"
|
||||
"The values used for `request` are operating system dependent, and are available\n"
|
||||
"as constants in the fcntl or termios library modules, using the same names as\n"
|
||||
"used in the relevant C header files.\n"
|
||||
"The values used for request are operating system dependent, and are\n"
|
||||
"available as constants in the fcntl or termios library modules, using\n"
|
||||
"the same names as used in the relevant C header files.\n"
|
||||
"\n"
|
||||
"The argument `arg` is optional, and defaults to 0; it may be an int or a\n"
|
||||
"buffer containing character data (most likely a string or an array).\n"
|
||||
"The argument arg is optional, and defaults to 0; it may be an integer, a\n"
|
||||
"bytes-like object or a string. If arg is given as a string, it will be\n"
|
||||
"encoded to binary using the UTF-8 encoding.\n"
|
||||
"\n"
|
||||
"If the argument is a mutable buffer (such as an array) and if the\n"
|
||||
"mutate_flag argument (which is only allowed in this case) is true then the\n"
|
||||
"buffer is (in effect) passed to the operating system and changes made by\n"
|
||||
"the OS will be reflected in the contents of the buffer after the call has\n"
|
||||
"returned. The return value is the integer returned by the ioctl system\n"
|
||||
"call.\n"
|
||||
"If the arg given is an integer or if none is specified, the result value\n"
|
||||
"is an integer corresponding to the return value of the ioctl() call in\n"
|
||||
"the C code.\n"
|
||||
"\n"
|
||||
"If the argument is a mutable buffer and the mutable_flag argument is false,\n"
|
||||
"the behavior is as if a string had been passed.\n"
|
||||
"If the argument is a mutable buffer (such as a bytearray) and the\n"
|
||||
"mutate_flag argument is true (default) then the buffer is (in effect)\n"
|
||||
"passed to the operating system and changes made by the OS will be\n"
|
||||
"reflected in the contents of the buffer after the call has returned.\n"
|
||||
"The return value is the integer returned by the ioctl() system call.\n"
|
||||
"\n"
|
||||
"If the argument is an immutable buffer (most likely a string) then a copy\n"
|
||||
"of the buffer is passed to the operating system and the return value is a\n"
|
||||
"string of the same length containing whatever the operating system put in\n"
|
||||
"the buffer. The length of the arg buffer in this case is not allowed to\n"
|
||||
"exceed 1024 bytes.\n"
|
||||
"If the argument is a mutable buffer and the mutable_flag argument is\n"
|
||||
"false, the behavior is as if an immutable buffer had been passed.\n"
|
||||
"\n"
|
||||
"If the arg given is an integer or if none is specified, the result value is\n"
|
||||
"an integer corresponding to the return value of the ioctl call in the C\n"
|
||||
"code.");
|
||||
"If the argument is an immutable buffer then a copy of the buffer is\n"
|
||||
"passed to the operating system and the return value is a bytes object of\n"
|
||||
"the same length containing whatever the operating system put in the\n"
|
||||
"buffer.");
|
||||
|
||||
#define FCNTL_IOCTL_METHODDEF \
|
||||
{"ioctl", _PyCFunction_CAST(fcntl_ioctl), METH_FASTCALL, fcntl_ioctl__doc__},
|
||||
@@ -154,7 +158,7 @@ PyDoc_STRVAR(fcntl_flock__doc__,
|
||||
"flock($module, fd, operation, /)\n"
|
||||
"--\n"
|
||||
"\n"
|
||||
"Perform the lock operation `operation` on file descriptor `fd`.\n"
|
||||
"Perform the lock operation on file descriptor fd.\n"
|
||||
"\n"
|
||||
"See the Unix manual page for flock(2) for details (On some systems, this\n"
|
||||
"function is emulated using fcntl()).");
|
||||
@@ -195,22 +199,22 @@ PyDoc_STRVAR(fcntl_lockf__doc__,
|
||||
"\n"
|
||||
"A wrapper around the fcntl() locking calls.\n"
|
||||
"\n"
|
||||
"`fd` is the file descriptor of the file to lock or unlock, and operation is one\n"
|
||||
"of the following values:\n"
|
||||
"fd is the file descriptor of the file to lock or unlock, and operation\n"
|
||||
"is one of the following values:\n"
|
||||
"\n"
|
||||
" LOCK_UN - unlock\n"
|
||||
" LOCK_SH - acquire a shared lock\n"
|
||||
" LOCK_EX - acquire an exclusive lock\n"
|
||||
"\n"
|
||||
"When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with\n"
|
||||
"LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and the\n"
|
||||
"lock cannot be acquired, an OSError will be raised and the exception will\n"
|
||||
"have an errno attribute set to EACCES or EAGAIN (depending on the operating\n"
|
||||
"system -- for portability, check for either value).\n"
|
||||
"LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and\n"
|
||||
"the lock cannot be acquired, an OSError will be raised and the exception\n"
|
||||
"will have an errno attribute set to EACCES or EAGAIN (depending on the\n"
|
||||
"operating system -- for portability, check for either value).\n"
|
||||
"\n"
|
||||
"`len` is the number of bytes to lock, with the default meaning to lock to\n"
|
||||
"EOF. `start` is the byte offset, relative to `whence`, to that the lock\n"
|
||||
"starts. `whence` is as with fileobj.seek(), specifically:\n"
|
||||
"len is the number of bytes to lock, with the default meaning to lock to\n"
|
||||
"EOF. start is the byte offset, relative to whence, to that the lock\n"
|
||||
"starts. whence is as with fileobj.seek(), specifically:\n"
|
||||
"\n"
|
||||
" 0 - relative to the start of the file (SEEK_SET)\n"
|
||||
" 1 - relative to the current buffer position (SEEK_CUR)\n"
|
||||
@@ -265,4 +269,4 @@ skip_optional:
|
||||
exit:
|
||||
return return_value;
|
||||
}
|
||||
/*[clinic end generated code: output=9773e44da302dc7c input=a9049054013a1b77]*/
|
||||
/*[clinic end generated code: output=c782fcf9dd6690e0 input=a9049054013a1b77]*/
|
||||
|
||||
@@ -40,22 +40,27 @@ fcntl.fcntl
|
||||
arg: object(c_default='NULL') = 0
|
||||
/
|
||||
|
||||
Perform the operation `cmd` on file descriptor fd.
|
||||
Perform the operation cmd on file descriptor fd.
|
||||
|
||||
The values used for `cmd` are operating system dependent, and are available
|
||||
as constants in the fcntl module, using the same names as used in
|
||||
the relevant C header files. The argument arg is optional, and
|
||||
defaults to 0; it may be an int or a string. If arg is given as a string,
|
||||
the return value of fcntl is a string of that length, containing the
|
||||
resulting value put in the arg buffer by the operating system. The length
|
||||
of the arg string is not allowed to exceed 1024 bytes. If the arg given
|
||||
is an integer or if none is specified, the result value is an integer
|
||||
corresponding to the return value of the fcntl call in the C code.
|
||||
The values used for cmd are operating system dependent, and are
|
||||
available as constants in the fcntl module, using the same names as used
|
||||
in the relevant C header files. The argument arg is optional, and
|
||||
defaults to 0; it may be an integer, a bytes-like object or a string.
|
||||
If arg is given as a string, it will be encoded to binary using the
|
||||
UTF-8 encoding.
|
||||
|
||||
If the arg given is an integer or if none is specified, the result value
|
||||
is an integer corresponding to the return value of the fcntl() call in
|
||||
the C code.
|
||||
|
||||
If arg is given as a bytes-like object, the return value of fcntl() is a
|
||||
bytes object of that length, containing the resulting value put in the
|
||||
arg buffer by the operating system.
|
||||
[clinic start generated code]*/
|
||||
|
||||
static PyObject *
|
||||
fcntl_fcntl_impl(PyObject *module, int fd, int code, PyObject *arg)
|
||||
/*[clinic end generated code: output=888fc93b51c295bd input=7955340198e5f334]*/
|
||||
/*[clinic end generated code: output=888fc93b51c295bd input=77340720f11665da]*/
|
||||
{
|
||||
int ret;
|
||||
int async_err = 0;
|
||||
@@ -151,7 +156,6 @@ fcntl_fcntl_impl(PyObject *module, int fd, int code, PyObject *arg)
|
||||
|
||||
|
||||
/*[clinic input]
|
||||
@permit_long_docstring_body
|
||||
fcntl.ioctl
|
||||
|
||||
fd: fildes
|
||||
@@ -160,40 +164,39 @@ fcntl.ioctl
|
||||
mutate_flag as mutate_arg: bool = True
|
||||
/
|
||||
|
||||
Perform the operation `request` on file descriptor `fd`.
|
||||
Perform the operation request on file descriptor fd.
|
||||
|
||||
The values used for `request` are operating system dependent, and are available
|
||||
as constants in the fcntl or termios library modules, using the same names as
|
||||
used in the relevant C header files.
|
||||
The values used for request are operating system dependent, and are
|
||||
available as constants in the fcntl or termios library modules, using
|
||||
the same names as used in the relevant C header files.
|
||||
|
||||
The argument `arg` is optional, and defaults to 0; it may be an int or a
|
||||
buffer containing character data (most likely a string or an array).
|
||||
The argument arg is optional, and defaults to 0; it may be an integer, a
|
||||
bytes-like object or a string. If arg is given as a string, it will be
|
||||
encoded to binary using the UTF-8 encoding.
|
||||
|
||||
If the argument is a mutable buffer (such as an array) and if the
|
||||
mutate_flag argument (which is only allowed in this case) is true then the
|
||||
buffer is (in effect) passed to the operating system and changes made by
|
||||
the OS will be reflected in the contents of the buffer after the call has
|
||||
returned. The return value is the integer returned by the ioctl system
|
||||
call.
|
||||
If the arg given is an integer or if none is specified, the result value
|
||||
is an integer corresponding to the return value of the ioctl() call in
|
||||
the C code.
|
||||
|
||||
If the argument is a mutable buffer and the mutable_flag argument is false,
|
||||
the behavior is as if a string had been passed.
|
||||
If the argument is a mutable buffer (such as a bytearray) and the
|
||||
mutate_flag argument is true (default) then the buffer is (in effect)
|
||||
passed to the operating system and changes made by the OS will be
|
||||
reflected in the contents of the buffer after the call has returned.
|
||||
The return value is the integer returned by the ioctl() system call.
|
||||
|
||||
If the argument is an immutable buffer (most likely a string) then a copy
|
||||
of the buffer is passed to the operating system and the return value is a
|
||||
string of the same length containing whatever the operating system put in
|
||||
the buffer. The length of the arg buffer in this case is not allowed to
|
||||
exceed 1024 bytes.
|
||||
If the argument is a mutable buffer and the mutable_flag argument is
|
||||
false, the behavior is as if an immutable buffer had been passed.
|
||||
|
||||
If the arg given is an integer or if none is specified, the result value is
|
||||
an integer corresponding to the return value of the ioctl call in the C
|
||||
code.
|
||||
If the argument is an immutable buffer then a copy of the buffer is
|
||||
passed to the operating system and the return value is a bytes object of
|
||||
the same length containing whatever the operating system put in the
|
||||
buffer.
|
||||
[clinic start generated code]*/
|
||||
|
||||
static PyObject *
|
||||
fcntl_ioctl_impl(PyObject *module, int fd, unsigned long code, PyObject *arg,
|
||||
int mutate_arg)
|
||||
/*[clinic end generated code: output=f72baba2454d7a62 input=d7fe504d335449e2]*/
|
||||
/*[clinic end generated code: output=f72baba2454d7a62 input=954fe75c208cc492]*/
|
||||
{
|
||||
/* We use the unsigned non-checked 'I' format for the 'code' parameter
|
||||
because the system expects it to be a 32bit bit field value
|
||||
@@ -340,7 +343,7 @@ fcntl.flock
|
||||
operation as code: int
|
||||
/
|
||||
|
||||
Perform the lock operation `operation` on file descriptor `fd`.
|
||||
Perform the lock operation on file descriptor fd.
|
||||
|
||||
See the Unix manual page for flock(2) for details (On some systems, this
|
||||
function is emulated using fcntl()).
|
||||
@@ -348,7 +351,7 @@ function is emulated using fcntl()).
|
||||
|
||||
static PyObject *
|
||||
fcntl_flock_impl(PyObject *module, int fd, int code)
|
||||
/*[clinic end generated code: output=84059e2b37d2fc64 input=0bfc00f795953452]*/
|
||||
/*[clinic end generated code: output=84059e2b37d2fc64 input=ade68943e8599f0a]*/
|
||||
{
|
||||
int ret;
|
||||
int async_err = 0;
|
||||
@@ -400,7 +403,6 @@ fcntl_flock_impl(PyObject *module, int fd, int code)
|
||||
|
||||
|
||||
/*[clinic input]
|
||||
@permit_long_docstring_body
|
||||
fcntl.lockf
|
||||
|
||||
fd: fildes
|
||||
@@ -412,22 +414,22 @@ fcntl.lockf
|
||||
|
||||
A wrapper around the fcntl() locking calls.
|
||||
|
||||
`fd` is the file descriptor of the file to lock or unlock, and operation is one
|
||||
of the following values:
|
||||
fd is the file descriptor of the file to lock or unlock, and operation
|
||||
is one of the following values:
|
||||
|
||||
LOCK_UN - unlock
|
||||
LOCK_SH - acquire a shared lock
|
||||
LOCK_EX - acquire an exclusive lock
|
||||
|
||||
When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with
|
||||
LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and the
|
||||
lock cannot be acquired, an OSError will be raised and the exception will
|
||||
have an errno attribute set to EACCES or EAGAIN (depending on the operating
|
||||
system -- for portability, check for either value).
|
||||
LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and
|
||||
the lock cannot be acquired, an OSError will be raised and the exception
|
||||
will have an errno attribute set to EACCES or EAGAIN (depending on the
|
||||
operating system -- for portability, check for either value).
|
||||
|
||||
`len` is the number of bytes to lock, with the default meaning to lock to
|
||||
EOF. `start` is the byte offset, relative to `whence`, to that the lock
|
||||
starts. `whence` is as with fileobj.seek(), specifically:
|
||||
len is the number of bytes to lock, with the default meaning to lock to
|
||||
EOF. start is the byte offset, relative to whence, to that the lock
|
||||
starts. whence is as with fileobj.seek(), specifically:
|
||||
|
||||
0 - relative to the start of the file (SEEK_SET)
|
||||
1 - relative to the current buffer position (SEEK_CUR)
|
||||
@@ -437,7 +439,7 @@ starts. `whence` is as with fileobj.seek(), specifically:
|
||||
static PyObject *
|
||||
fcntl_lockf_impl(PyObject *module, int fd, int code, PyObject *lenobj,
|
||||
PyObject *startobj, int whence)
|
||||
/*[clinic end generated code: output=4985e7a172e7461a input=f666662ec2edd775]*/
|
||||
/*[clinic end generated code: output=4985e7a172e7461a input=369bef4d7a1c5ff4]*/
|
||||
{
|
||||
int ret;
|
||||
int async_err = 0;
|
||||
|
||||
Reference in New Issue
Block a user