Skip to content

C
cpython
Commit 17d3a58e authored by Serhiy Storchaka's avatar Serhiy Storchaka
Browse files
Options

Issue #22832: Tweaked parameter names for fcntl module to better match 

official POSIX documentation.  Updated the documenttion for Python 3.
Patch by Alex Shkop.
parent 6faa6244
Hide whitespace changes
Inline Side-by-side
Showing with 73 additions and 75 deletions
Doc/library/fcntl.rst
View file @ 17d3a58e
...@@ -28,41 +28,41 @@ descriptor. ...@@ -28,41 +28,41 @@ descriptor.
The module defines the following functions: The module defines the following functions:
.. function:: fcntl(fd, op[, arg]) .. function:: fcntl(fd, cmd, arg=0)
Perform the operation *op* on file descriptor *fd* (file objects providing Perform the operation *cmd* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). The values used a :meth:`~io.IOBase.fileno` method are accepted as well). The values used
for *op* are operating system dependent, and are available as constants for *cmd* are operating system dependent, and are available as constants
in the :mod:`fcntl` module, using the same names as used in the relevant C in the :mod:`fcntl` module, using the same names as used in the relevant C
header files. The argument *arg* is optional, and defaults to the integer header files. The argument *arg* can either be an integer value, or a
value ``0``. When present, it can either be an integer value, or a string. :class:`bytes` object. With an integer value, the return value of this
With the argument missing or an integer value, the return value of this function function is the integer return value of the C :c:func:`fcntl` call. When
is the integer return value of the C :c:func:`fcntl` call. When the argument is the argument is bytes it represents a binary structure, e.g. created by
a string it represents a binary structure, e.g. created by :func:`struct.pack`. :func:`struct.pack`. The binary data is copied to a buffer whose address is
The binary data is copied to a buffer whose address is passed to the C passed to the C :c:func:`fcntl` call. The return value after a successful
:c:func:`fcntl` call. The return value after a successful call is the contents call is the contents of the buffer, converted to a :class:`bytes` object.
of the buffer, converted to a string object. The length of the returned string The length of the returned object will be the same as the length of the
will be the same as the length of the *arg* argument. This is limited to 1024 *arg* argument. This is limited to 1024 bytes. If the information returned
bytes. If the information returned in the buffer by the operating system is in the buffer by the operating system is larger than 1024 bytes, this is
larger than 1024 bytes, this is most likely to result in a segmentation most likely to result in a segmentation violation or a more subtle data
violation or a more subtle data corruption. corruption.
If the :c:func:`fcntl` fails, an :exc:`OSError` is raised. If the :c:func:`fcntl` fails, an :exc:`OSError` is raised.
.. function:: ioctl(fd, op[, arg[, mutate_flag]]) .. function:: ioctl(fd, request, arg=0, mutate_flag=True)
This function is identical to the :func:`~fcntl.fcntl` function, except This function is identical to the :func:`~fcntl.fcntl` function, except
that the argument handling is even more complicated. that the argument handling is even more complicated.
The op parameter is limited to values that can fit in 32-bits. The *request* parameter is limited to values that can fit in 32-bits.
Additional constants of interest for use as the *op* argument can be Additional constants of interest for use as the *request* argument can be
found in the :mod:`termios` module, under the same names as used in found in the :mod:`termios` module, under the same names as used in
the relevant C header files. the relevant C header files.
The parameter *arg* can be one of an integer, absent (treated identically to the The parameter *arg* can be one of an integer, an object supporting the
integer ``0``), an object supporting the read-only buffer interface (most likely read-only buffer interface (like :class:`bytes`) or an object supporting
a plain Python string) or an object supporting the read-write buffer interface. the read-write buffer interface (like :class:`bytearray`).
In all but the last case, behaviour is as for the :func:`~fcntl.fcntl` In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
function. function.
...@@ -72,7 +72,7 @@ The module defines the following functions: ...@@ -72,7 +72,7 @@ The module defines the following functions:
If it is false, the buffer's mutability is ignored and behaviour is as for a If it is false, the buffer's mutability is ignored and behaviour is as for a
read-only buffer, except that the 1024 byte limit mentioned above is avoided -- read-only buffer, except that the 1024 byte limit mentioned above is avoided --
so long as the buffer you pass is as least as long as what the operating system so long as the buffer you pass is at least as long as what the operating system
wants to put there, things should work. wants to put there, things should work.
If *mutate_flag* is true (the default), then the buffer is (in effect) passed If *mutate_flag* is true (the default), then the buffer is (in effect) passed
...@@ -97,25 +97,25 @@ The module defines the following functions: ...@@ -97,25 +97,25 @@ The module defines the following functions:
array('h', [13341]) array('h', [13341])
.. function:: flock(fd, op) .. function:: flock(fd, operation)
Perform the lock operation *op* on file descriptor *fd* (file objects providing Perform the lock operation *operation* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual
:manpage:`flock(2)` for details. (On some systems, this function is emulated :manpage:`flock(2)` for details. (On some systems, this function is emulated
using :c:func:`fcntl`.) using :c:func:`fcntl`.)
.. function:: lockf(fd, operation, [length, [start, [whence]]]) .. function:: lockf(fd, cmd, len=0, start=0, whence=0)
This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls.
*fd* is the file descriptor of the file to lock or unlock, and *operation* *fd* is the file descriptor of the file to lock or unlock, and *cmd*
is one of the following values: is one of the following values:
* :const:`LOCK_UN` -- unlock * :const:`LOCK_UN` -- unlock
* :const:`LOCK_SH` -- acquire a shared lock * :const:`LOCK_SH` -- acquire a shared lock
* :const:`LOCK_EX` -- acquire an exclusive lock * :const:`LOCK_EX` -- acquire an exclusive lock
When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be 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. 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 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* :exc:`OSError` will be raised and the exception will have an *errno*
...@@ -124,7 +124,7 @@ The module defines the following functions: ...@@ -124,7 +124,7 @@ The module defines the following functions:
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. file opened for writing.
*length* is the number of bytes to lock, *start* is the byte offset at *len* is the number of bytes to lock, *start* is the byte offset at
which the lock starts, relative to *whence*, and *whence* is as with which the lock starts, relative to *whence*, and *whence* is as with
:func:`io.IOBase.seek`, specifically: :func:`io.IOBase.seek`, specifically:
...@@ -133,7 +133,7 @@ The module defines the following functions: ...@@ -133,7 +133,7 @@ The module defines the following functions:
* :const:`2` -- relative to the end of the file (:data:`os.SEEK_END`) * :const:`2` -- relative to the end of the file (:data:`os.SEEK_END`)
The default for *start* is 0, which means to start at the beginning of the file. The default for *start* is 0, which means to start at the beginning of the file.
The default for *length* is 0 which means to lock to the end of the file. The The default for *len* is 0 which means to lock to the end of the file. The
default for *whence* is also 0. default for *whence* is also 0.
Examples (all on a SVR4 compliant system):: Examples (all on a SVR4 compliant system)::
...@@ -147,9 +147,9 @@ Examples (all on a SVR4 compliant system):: ...@@ -147,9 +147,9 @@ Examples (all on a SVR4 compliant system)::
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
Note that in the first example the return value variable *rv* will hold an Note that in the first example the return value variable *rv* will hold an
integer value; in the second example it will hold a string value. The structure integer value; in the second example it will hold a :class:`bytes` object. The
lay-out for the *lockdata* variable is system dependent --- therefore using the structure lay-out for the *lockdata* variable is system dependent --- therefore
:func:`flock` call may be better. using the :func:`flock` call may be better.
.. seealso:: .. seealso::
......
Modules/clinic/fcntlmodule.c.h
View file @ 17d3a58e
...@@ -3,12 +3,12 @@ preserve ...@@ -3,12 +3,12 @@ preserve
[clinic start generated code]*/ [clinic start generated code]*/
PyDoc_STRVAR(fcntl_fcntl__doc__, PyDoc_STRVAR(fcntl_fcntl__doc__,
"fcntl($module, fd, code, arg=None, /)\n" "fcntl($module, fd, cmd, arg=0, /)\n"
"--\n" "--\n"
"\n" "\n"
"Perform the operation `code` on file descriptor fd.\n" "Perform the operation `cmd` on file descriptor fd.\n"
"\n" "\n"
"The values used for `code` are operating system dependent, and are available\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" "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" "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" "defaults to 0; it may be an int or a string. If arg is given as a string,\n"
...@@ -43,13 +43,13 @@ exit: ...@@ -43,13 +43,13 @@ exit:
} }
PyDoc_STRVAR(fcntl_ioctl__doc__, PyDoc_STRVAR(fcntl_ioctl__doc__,
"ioctl($module, fd, op, arg=None, mutate_flag=True, /)\n" "ioctl($module, fd, request, arg=0, mutate_flag=True, /)\n"
"--\n" "--\n"
"\n" "\n"
"Perform the operation op on file descriptor fd.\n" "Perform the operation `request` on file descriptor `fd`.\n"
"\n" "\n"
"The values used for op are operating system dependent, and are available as\n" "The values used for `request` are operating system dependent, and are available\n"
"constants in the fcntl or termios library modules, using the same names as\n" "as constants in the fcntl or termios library modules, using the same names as\n"
"used in the relevant C header files.\n" "used in the relevant C header files.\n"
"\n" "\n"
"The argument `arg` is optional, and defaults to 0; it may be an int or a\n" "The argument `arg` is optional, and defaults to 0; it may be an int or a\n"
...@@ -62,9 +62,8 @@ PyDoc_STRVAR(fcntl_ioctl__doc__, ...@@ -62,9 +62,8 @@ PyDoc_STRVAR(fcntl_ioctl__doc__,
"returned. The return value is the integer returned by the ioctl system\n" "returned. The return value is the integer returned by the ioctl system\n"
"call.\n" "call.\n"
"\n" "\n"
"If the argument is a mutable buffer and the mutable_flag argument is not\n" "If the argument is a mutable buffer and the mutable_flag argument is false,\n"
"passed or is false, the behavior is as if a string had been passed. This\n" "the behavior is as if a string had been passed.\n"
"behavior will change in future releases of Python.\n"
"\n" "\n"
"If the argument is an immutable buffer (most likely a string) then a copy\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" "of the buffer is passed to the operating system and the return value is a\n"
...@@ -102,10 +101,10 @@ exit: ...@@ -102,10 +101,10 @@ exit:
} }
PyDoc_STRVAR(fcntl_flock__doc__, PyDoc_STRVAR(fcntl_flock__doc__,
"flock($module, fd, code, /)\n" "flock($module, fd, operation, /)\n"
"--\n" "--\n"
"\n" "\n"
"Perform the lock operation op on file descriptor fd.\n" "Perform the lock operation `operation` on file descriptor `fd`.\n"
"\n" "\n"
"See the Unix manual page for flock(2) for details (On some systems, this\n" "See the Unix manual page for flock(2) for details (On some systems, this\n"
"function is emulated using fcntl())."); "function is emulated using fcntl()).");
...@@ -134,12 +133,12 @@ exit: ...@@ -134,12 +133,12 @@ exit:
} }
PyDoc_STRVAR(fcntl_lockf__doc__, PyDoc_STRVAR(fcntl_lockf__doc__,
"lockf($module, fd, code, lenobj=None, startobj=None, whence=0, /)\n" "lockf($module, fd, cmd, len=0, start=0, whence=0, /)\n"
"--\n" "--\n"
"\n" "\n"
"A wrapper around the fcntl() locking calls.\n" "A wrapper around the fcntl() locking calls.\n"
"\n" "\n"
"fd is the file descriptor of the file to lock or unlock, and operation is one\n" "`fd` is the file descriptor of the file to lock or unlock, and operation is one\n"
"of the following values:\n" "of the following values:\n"
"\n" "\n"
" LOCK_UN - unlock\n" " LOCK_UN - unlock\n"
...@@ -152,9 +151,9 @@ PyDoc_STRVAR(fcntl_lockf__doc__, ...@@ -152,9 +151,9 @@ PyDoc_STRVAR(fcntl_lockf__doc__,
"have an errno attribute set to EACCES or EAGAIN (depending on the operating\n" "have an errno attribute set to EACCES or EAGAIN (depending on the operating\n"
"system -- for portability, check for either value).\n" "system -- for portability, check for either value).\n"
"\n" "\n"
"length is the number of bytes to lock, with the default meaning to lock to\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" "EOF. `start` is the byte offset, relative to `whence`, to that the lock\n"
"starts. whence is as with fileobj.seek(), specifically:\n" "starts. `whence` is as with fileobj.seek(), specifically:\n"
"\n" "\n"
" 0 - relative to the start of the file (SEEK_SET)\n" " 0 - relative to the start of the file (SEEK_SET)\n"
" 1 - relative to the current buffer position (SEEK_CUR)\n" " 1 - relative to the current buffer position (SEEK_CUR)\n"
...@@ -185,4 +184,4 @@ fcntl_lockf(PyModuleDef *module, PyObject *args) ...@@ -185,4 +184,4 @@ fcntl_lockf(PyModuleDef *module, PyObject *args)
exit: exit:
return return_value; return return_value;
} }
/*[clinic end generated code: output=84bdde73a92f7c61 input=a9049054013a1b77]*/ /*[clinic end generated code: output=ec482672292aab0c input=a9049054013a1b77]*/
Modules/fcntlmodule.c
View file @ 17d3a58e
...@@ -39,13 +39,13 @@ conv_descriptor(PyObject *object, int *target) ...@@ -39,13 +39,13 @@ conv_descriptor(PyObject *object, int *target)
fcntl.fcntl fcntl.fcntl
fd: object(type='int', converter='conv_descriptor') fd: object(type='int', converter='conv_descriptor')
code: int cmd as code: int
arg: object = NULL arg: object(c_default='NULL') = 0
/ /
Perform the operation `code` on file descriptor fd. Perform the operation `cmd` on file descriptor fd.
The values used for `code` are operating system dependent, and are available 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 as constants in the fcntl module, using the same names as used in
the relevant C header files. The argument arg is optional, and 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, defaults to 0; it may be an int or a string. If arg is given as a string,
...@@ -58,7 +58,7 @@ corresponding to the return value of the fcntl call in the C code. ...@@ -58,7 +58,7 @@ corresponding to the return value of the fcntl call in the C code.
static PyObject * static PyObject *
fcntl_fcntl_impl(PyModuleDef *module, int fd, int code, PyObject *arg) fcntl_fcntl_impl(PyModuleDef *module, int fd, int code, PyObject *arg)
/*[clinic end generated code: output=afc5bfa74a03ef0d input=4850c13a41e86930]*/ /*[clinic end generated code: output=afc5bfa74a03ef0d input=8cefbe59b29efbe2]*/
{ {
unsigned int int_arg = 0; unsigned int int_arg = 0;
int ret; int ret;
...@@ -111,15 +111,15 @@ fcntl_fcntl_impl(PyModuleDef *module, int fd, int code, PyObject *arg) ...@@ -111,15 +111,15 @@ fcntl_fcntl_impl(PyModuleDef *module, int fd, int code, PyObject *arg)
fcntl.ioctl fcntl.ioctl
fd: object(type='int', converter='conv_descriptor') fd: object(type='int', converter='conv_descriptor')
op as code: unsigned_int(bitwise=True) request as code: unsigned_int(bitwise=True)
arg as ob_arg: object = NULL arg as ob_arg: object(c_default='NULL') = 0
mutate_flag as mutate_arg: bool = True mutate_flag as mutate_arg: bool = True
/ /
Perform the operation op on file descriptor fd. Perform the operation `request` on file descriptor `fd`.
The values used for op are operating system dependent, and are available as The values used for `request` are operating system dependent, and are available
constants in the fcntl or termios library modules, using the same names as as constants in the fcntl or termios library modules, using the same names as
used in the relevant C header files. used in the relevant C header files.
The argument `arg` is optional, and defaults to 0; it may be an int or a The argument `arg` is optional, and defaults to 0; it may be an int or a
...@@ -132,9 +132,8 @@ the OS will be reflected in the contents of the buffer after the call has ...@@ -132,9 +132,8 @@ 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 returned. The return value is the integer returned by the ioctl system
call. call.
If the argument is a mutable buffer and the mutable_flag argument is not If the argument is a mutable buffer and the mutable_flag argument is false,
passed or is false, the behavior is as if a string had been passed. This the behavior is as if a string had been passed.
behavior will change in future releases of Python.
If the argument is an immutable buffer (most likely a string) then a copy 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 of the buffer is passed to the operating system and the return value is a
...@@ -149,7 +148,7 @@ code. ...@@ -149,7 +148,7 @@ code.
static PyObject * static PyObject *
fcntl_ioctl_impl(PyModuleDef *module, int fd, unsigned int code, PyObject *ob_arg, int mutate_arg) fcntl_ioctl_impl(PyModuleDef *module, int fd, unsigned int code, PyObject *ob_arg, int mutate_arg)
/*[clinic end generated code: output=ad47738c118622bf input=a55a6ee8e494c449]*/ /*[clinic end generated code: output=ad47738c118622bf input=ede70c433cccbbb2]*/
{ {
#define IOCTL_BUFSZ 1024 #define IOCTL_BUFSZ 1024
/* We use the unsigned non-checked 'I' format for the 'code' parameter /* We use the unsigned non-checked 'I' format for the 'code' parameter
...@@ -270,10 +269,10 @@ fcntl_ioctl_impl(PyModuleDef *module, int fd, unsigned int code, PyObject *ob_ar ...@@ -270,10 +269,10 @@ fcntl_ioctl_impl(PyModuleDef *module, int fd, unsigned int code, PyObject *ob_ar
fcntl.flock fcntl.flock
fd: object(type='int', converter='conv_descriptor') fd: object(type='int', converter='conv_descriptor')
code: int operation as code: int
/ /
Perform the lock operation op on file descriptor fd. Perform the lock operation `operation` on file descriptor `fd`.
See the Unix manual page for flock(2) for details (On some systems, this See the Unix manual page for flock(2) for details (On some systems, this
function is emulated using fcntl()). function is emulated using fcntl()).
...@@ -281,7 +280,7 @@ function is emulated using fcntl()). ...@@ -281,7 +280,7 @@ function is emulated using fcntl()).
static PyObject * static PyObject *
fcntl_flock_impl(PyModuleDef *module, int fd, int code) fcntl_flock_impl(PyModuleDef *module, int fd, int code)
/*[clinic end generated code: output=c9035133a7dbfc96 input=b762aa9448d05e43]*/ /*[clinic end generated code: output=c9035133a7dbfc96 input=b70a0a41ca22a8a0]*/
{ {
int ret; int ret;
...@@ -328,15 +327,15 @@ fcntl_flock_impl(PyModuleDef *module, int fd, int code) ...@@ -328,15 +327,15 @@ fcntl_flock_impl(PyModuleDef *module, int fd, int code)
fcntl.lockf fcntl.lockf
fd: object(type='int', converter='conv_descriptor') fd: object(type='int', converter='conv_descriptor')
code: int cmd as code: int
lenobj: object = NULL len as lenobj: object(c_default='NULL') = 0
startobj: object = NULL start as startobj: object(c_default='NULL') = 0
whence: int = 0 whence: int = 0
/ /
A wrapper around the fcntl() locking calls. A wrapper around the fcntl() locking calls.
fd is the file descriptor of the file to lock or unlock, and operation is one `fd` is the file descriptor of the file to lock or unlock, and operation is one
of the following values: of the following values:
LOCK_UN - unlock LOCK_UN - unlock
...@@ -349,9 +348,9 @@ lock cannot be acquired, an IOError will be raised and the exception will ...@@ -349,9 +348,9 @@ lock cannot be acquired, an IOError will be raised and the exception will
have an errno attribute set to EACCES or EAGAIN (depending on the operating have an errno attribute set to EACCES or EAGAIN (depending on the operating
system -- for portability, check for either value). system -- for portability, check for either value).
length is the number of bytes to lock, with the default meaning to lock to `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 EOF. `start` is the byte offset, relative to `whence`, to that the lock
starts. whence is as with fileobj.seek(), specifically: starts. `whence` is as with fileobj.seek(), specifically:
0 - relative to the start of the file (SEEK_SET) 0 - relative to the start of the file (SEEK_SET)
1 - relative to the current buffer position (SEEK_CUR) 1 - relative to the current buffer position (SEEK_CUR)
...@@ -360,7 +359,7 @@ starts. whence is as with fileobj.seek(), specifically: ...@@ -360,7 +359,7 @@ starts. whence is as with fileobj.seek(), specifically:
static PyObject * static PyObject *
fcntl_lockf_impl(PyModuleDef *module, int fd, int code, PyObject *lenobj, PyObject *startobj, int whence) fcntl_lockf_impl(PyModuleDef *module, int fd, int code, PyObject *lenobj, PyObject *startobj, int whence)
/*[clinic end generated code: output=5536df2892bf3ce9 input=44856fa06db36184]*/ /*[clinic end generated code: output=5536df2892bf3ce9 input=9c594391de821f24]*/
{ {
int ret; int ret;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7