diff options
| -rw-r--r-- | Doc/library/fcntl.rst | 64 | ||||
| -rw-r--r-- | Modules/clinic/fcntlmodule.c.h | 35 | ||||
| -rw-r--r-- | Modules/fcntlmodule.c | 49 |
3 files changed, 73 insertions, 75 deletions
diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 8e932fb..432140f 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -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:: diff --git a/Modules/clinic/fcntlmodule.c.h b/Modules/clinic/fcntlmodule.c.h index 377e55d..d2c36ba 100644 --- a/Modules/clinic/fcntlmodule.c.h +++ b/Modules/clinic/fcntlmodule.c.h @@ -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]*/ diff --git a/Modules/fcntlmodule.c b/Modules/fcntlmodule.c index 780e222..3cea151 100644 --- a/Modules/fcntlmodule.c +++ b/Modules/fcntlmodule.c @@ -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; |