diff -r 8545624309f5 Doc/library/fcntl.rst --- a/Doc/library/fcntl.rst Wed Feb 25 20:48:01 2015 -0800 +++ b/Doc/library/fcntl.rst Fri Feb 27 10:48:23 2015 +0200 @@ -28,11 +28,11 @@ The module defines the following functions: -.. function:: fcntl(fd, op[, arg]) +.. function:: fcntl(fd, cmd[, arg]) - 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. @@ -50,13 +50,13 @@ If the :c:func:`fcntl` fails, an :exc:`OSError` is raised. -.. function:: ioctl(fd, op[, arg[, mutate_flag]]) +.. function:: ioctl(fd, request[, arg[, mutate_flag]]) 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 + 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. @@ -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, [start, [whence]]]) 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):: diff -r 8545624309f5 Modules/clinic/fcntlmodule.c.h --- a/Modules/clinic/fcntlmodule.c.h Wed Feb 25 20:48:01 2015 -0800 +++ b/Modules/clinic/fcntlmodule.c.h Fri Feb 27 10:48:23 2015 +0200 @@ -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=None, /)\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=None, 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" @@ -102,10 +102,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 +134,12 @@ } PyDoc_STRVAR(fcntl_lockf__doc__, -"lockf($module, fd, code, lenobj=None, startobj=None, whence=0, /)\n" +"lockf($module, fd, cmd, len=None, start=None, 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 +152,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 +185,4 @@ exit: return return_value; } -/*[clinic end generated code: output=84bdde73a92f7c61 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=f9f4ee34fab0e3ba input=a9049054013a1b77]*/ diff -r 8545624309f5 Modules/fcntlmodule.c --- a/Modules/fcntlmodule.c Wed Feb 25 20:48:01 2015 -0800 +++ b/Modules/fcntlmodule.c Fri Feb 27 10:48:23 2015 +0200 @@ -39,13 +39,13 @@ fcntl.fcntl fd: object(type='int', converter='conv_descriptor') - code: int + cmd as code: int arg: object = NULL / -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=8c75114d221393db]*/ { 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) + request as code: unsigned_int(bitwise=True) arg as ob_arg: object = NULL 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 @@ -149,7 +149,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=b3f194825739bf90]*/ { #define IOCTL_BUFSZ 1024 /* We use the unsigned non-checked 'I' format for the 'code' parameter @@ -270,10 +270,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 +281,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 +328,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 = NULL + start as startobj: object = NULL 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 +349,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 +360,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=009d26928eb5602d]*/ { int ret;