Issue #22832: Tweaked parameter names for fcntl module to better match
official POSIX documentation. Updated the documenttion for Python 3. Patch by Alex Shkop.
This commit is contained in:
Serhiy Storchaka
parent
6faa62445f
commit
17d3a58e39
|
|
@ -28,41 +28,41 @@ descriptor.
|
|||
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
|
||||
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
|
||||
header files. The argument *arg* is optional, and defaults to the integer
|
||||
value ``0``. When present, it can either be an integer value, or a string.
|
||||
With the argument missing or an integer value, the return value of this function
|
||||
is the integer return value of the C :c:func:`fcntl` call. When the argument is
|
||||
a string it represents a binary structure, e.g. created by :func:`struct.pack`.
|
||||
The binary data is copied to a buffer whose address is passed to the C
|
||||
:c:func:`fcntl` call. The return value after a successful call is the contents
|
||||
of the buffer, converted to a string object. The length of the returned string
|
||||
will be the same as the length of the *arg* argument. This is limited to 1024
|
||||
bytes. If the information returned in the buffer by the operating system is
|
||||
larger than 1024 bytes, this is most likely to result in a segmentation
|
||||
violation or a more subtle data corruption.
|
||||
header files. The argument *arg* can either be an integer value, or a
|
||||
:class:`bytes` object. With an integer value, the return value of this
|
||||
function is the integer return value of the C :c:func:`fcntl` call. When
|
||||
the argument is bytes it represents a binary structure, e.g. created by
|
||||
:func:`struct.pack`. The binary data is copied to a buffer whose address is
|
||||
passed to the C :c:func:`fcntl` call. The return value after a successful
|
||||
call is the contents of the buffer, converted to a :class:`bytes` object.
|
||||
The length of the returned object will be the same as the length of the
|
||||
*arg* argument. This is limited to 1024 bytes. If the information returned
|
||||
in the buffer by the operating system is larger than 1024 bytes, this is
|
||||
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.
|
||||
|
||||
|
||||
.. 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
|
||||
that the argument handling is even more complicated.
|
||||
|
||||
The op parameter is limited to values that can fit in 32-bits.
|
||||
Additional constants of interest for use as the *op* argument can be
|
||||
The *request* parameter is limited to values that can fit in 32-bits.
|
||||
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
|
||||
the relevant C header files.
|
||||
|
||||
The parameter *arg* can be one of an integer, absent (treated identically to the
|
||||
integer ``0``), an object supporting the read-only buffer interface (most likely
|
||||
a plain Python string) or an object supporting the read-write buffer interface.
|
||||
The parameter *arg* can be one of an integer, an object supporting the
|
||||
read-only buffer interface (like :class:`bytes`) or an object supporting
|
||||
the read-write buffer interface (like :class:`bytearray`).
|
||||
|
||||
In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
|
||||
function.
|
||||
|
|
@ -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
|
||||
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.
|
||||
|
||||
If *mutate_flag* is true (the default), then the buffer is (in effect) passed
|
||||
|
|
@ -97,25 +97,25 @@ The module defines the following functions:
|
|||
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
|
||||
:manpage:`flock(2)` for details. (On some systems, this function is emulated
|
||||
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.
|
||||
*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:
|
||||
|
||||
* :const:`LOCK_UN` -- unlock
|
||||
* :const:`LOCK_SH` -- acquire a shared 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.
|
||||
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*
|
||||
|
|
@ -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
|
||||
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
|
||||
:func:`io.IOBase.seek`, specifically:
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ The module defines the following functions:
|
|||
* :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 *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.
|
||||
|
||||
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)
|
||||
|
||||
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
|
||||
lay-out for the *lockdata* variable is system dependent --- therefore using the
|
||||
:func:`flock` call may be better.
|
||||
integer value; in the second example it will hold a :class:`bytes` object. The
|
||||
structure lay-out for the *lockdata* variable is system dependent --- therefore
|
||||
using the :func:`flock` call may be better.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
|
|
|||
|
|
@ -3,12 +3,12 @@ preserve
|
|||
[clinic start generated code]*/
|
||||
|
||||
PyDoc_STRVAR(fcntl_fcntl__doc__,
|
||||
"fcntl($module, fd, code, arg=None, /)\n"
|
||||
"fcntl($module, fd, cmd, arg=0, /)\n"
|
||||
"--\n"
|
||||
"\n"
|
||||
"Perform the operation `code` on file descriptor fd.\n"
|
||||
"Perform the operation `cmd` on file descriptor fd.\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"
|
||||
"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"
|
||||
|
|
@ -43,13 +43,13 @@ exit:
|
|||
}
|
||||
|
||||
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"
|
||||
"Perform the operation op on file descriptor fd.\n"
|
||||
"Perform the operation `request` on file descriptor `fd`.\n"
|
||||
"\n"
|
||||
"The values used for op are operating system dependent, and are available as\n"
|
||||
"constants in the fcntl or termios library modules, using the same names as\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"
|
||||
"\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__,
|
|||
"returned. The return value is the integer returned by the ioctl system\n"
|
||||
"call.\n"
|
||||
"\n"
|
||||
"If the argument is a mutable buffer and the mutable_flag argument is not\n"
|
||||
"passed or is false, the behavior is as if a string had been passed. This\n"
|
||||
"behavior will change in future releases of Python.\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"
|
||||
"\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"
|
||||
|
|
@ -102,10 +101,10 @@ exit:
|
|||
}
|
||||
|
||||
PyDoc_STRVAR(fcntl_flock__doc__,
|
||||
"flock($module, fd, code, /)\n"
|
||||
"flock($module, fd, operation, /)\n"
|
||||
"--\n"
|
||||
"\n"
|
||||
"Perform the lock operation op on file descriptor fd.\n"
|
||||
"Perform the lock operation `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()).");
|
||||
|
|
@ -134,12 +133,12 @@ exit:
|
|||
}
|
||||
|
||||
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"
|
||||
"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"
|
||||
"`fd` is the file descriptor of the file to lock or unlock, and operation is one\n"
|
||||
"of the following values:\n"
|
||||
"\n"
|
||||
" LOCK_UN - unlock\n"
|
||||
|
|
@ -152,9 +151,9 @@ PyDoc_STRVAR(fcntl_lockf__doc__,
|
|||
"have an errno attribute set to EACCES or EAGAIN (depending on the operating\n"
|
||||
"system -- for portability, check for either value).\n"
|
||||
"\n"
|
||||
"length 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"
|
||||
|
|
@ -185,4 +184,4 @@ fcntl_lockf(PyModuleDef *module, PyObject *args)
|
|||
exit:
|
||||
return return_value;
|
||||
}
|
||||
/*[clinic end generated code: output=84bdde73a92f7c61 input=a9049054013a1b77]*/
|
||||
/*[clinic end generated code: output=ec482672292aab0c input=a9049054013a1b77]*/
|
||||
|
|
|
|||
|
|
@ -39,13 +39,13 @@ conv_descriptor(PyObject *object, int *target)
|
|||
fcntl.fcntl
|
||||
|
||||
fd: object(type='int', converter='conv_descriptor')
|
||||
code: int
|
||||
arg: object = NULL
|
||||
cmd as code: int
|
||||
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
|
||||
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,
|
||||
|
|
@ -58,7 +58,7 @@ corresponding to the return value of the fcntl call in the C code.
|
|||
|
||||
static PyObject *
|
||||
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;
|
||||
int ret;
|
||||
|
|
@ -111,15 +111,15 @@ fcntl_fcntl_impl(PyModuleDef *module, int fd, int code, PyObject *arg)
|
|||
fcntl.ioctl
|
||||
|
||||
fd: object(type='int', converter='conv_descriptor')
|
||||
op as code: unsigned_int(bitwise=True)
|
||||
arg as ob_arg: object = NULL
|
||||
request as code: unsigned_int(bitwise=True)
|
||||
arg as ob_arg: object(c_default='NULL') = 0
|
||||
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
|
||||
constants in the fcntl or termios library modules, using the same names as
|
||||
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
|
||||
|
|
@ -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
|
||||
call.
|
||||
|
||||
If the argument is a mutable buffer and the mutable_flag argument is not
|
||||
passed or is false, the behavior is as if a string had been passed. This
|
||||
behavior will change in future releases of Python.
|
||||
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 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
|
||||
|
|
@ -149,7 +148,7 @@ code.
|
|||
|
||||
static PyObject *
|
||||
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
|
||||
/* 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
|
|||
fcntl.flock
|
||||
|
||||
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
|
||||
function is emulated using fcntl()).
|
||||
|
|
@ -281,7 +280,7 @@ function is emulated using fcntl()).
|
|||
|
||||
static PyObject *
|
||||
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;
|
||||
|
||||
|
|
@ -328,15 +327,15 @@ fcntl_flock_impl(PyModuleDef *module, int fd, int code)
|
|||
fcntl.lockf
|
||||
|
||||
fd: object(type='int', converter='conv_descriptor')
|
||||
code: int
|
||||
lenobj: object = NULL
|
||||
startobj: object = NULL
|
||||
cmd as code: int
|
||||
len as lenobj: object(c_default='NULL') = 0
|
||||
start as startobj: object(c_default='NULL') = 0
|
||||
whence: int = 0
|
||||
/
|
||||
|
||||
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:
|
||||
|
||||
LOCK_UN - unlock
|
||||
|
|
@ -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
|
||||
system -- for portability, check for either value).
|
||||
|
||||
length 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)
|
||||
|
|
@ -360,7 +359,7 @@ starts. whence is as with fileobj.seek(), specifically:
|
|||
|
||||
static PyObject *
|
||||
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;
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue