[Python-checkins] cpython: Issue #22832: Tweaked parameter names for fcntl module to better match
serhiy.storchaka
python-checkins at python.org
Fri Mar 20 19:18:35 CET 2015
https://hg.python.org/cpython/rev/a3c9c2c92b87
changeset: 95105:a3c9c2c92b87
user: Serhiy Storchaka <storchaka at gmail.com>
date: Fri Mar 20 20:04:21 2015 +0200
summary:
Issue #22832: Tweaked parameter names for fcntl module to better match
official POSIX documentation. Updated the documenttion for Python 3.
Patch by Alex Shkop.
files:
Doc/library/fcntl.rst | 64 +++++++++++-----------
Modules/clinic/fcntlmodule.c.h | 35 +++++------
Modules/fcntlmodule.c | 49 ++++++++--------
3 files changed, 73 insertions(+), 75 deletions(-)
diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -28,41 +28,41 @@
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 @@
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 @@
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 @@
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 @@
* :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 @@
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::
diff --git a/Modules/clinic/fcntlmodule.c.h b/Modules/clinic/fcntlmodule.c.h
--- a/Modules/clinic/fcntlmodule.c.h
+++ b/Modules/clinic/fcntlmodule.c.h
@@ -3,12 +3,12 @@
[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 @@
}
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 @@
"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 @@
}
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 @@
}
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 @@
"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 @@
exit:
return return_value;
}
-/*[clinic end generated code: output=84bdde73a92f7c61 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=ec482672292aab0c input=a9049054013a1b77]*/
diff --git a/Modules/fcntlmodule.c b/Modules/fcntlmodule.c
--- a/Modules/fcntlmodule.c
+++ b/Modules/fcntlmodule.c
@@ -39,13 +39,13 @@
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 @@
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.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 @@
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 @@
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.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 @@
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.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 @@
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 @@
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;
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list