From d5a2f0b3a13974e4a62d088aee6f920262c37add Mon Sep 17 00:00:00 2001 From: R David Murray Date: Thu, 7 Nov 2013 10:51:07 -0500 Subject: #18985: Improve fcntl documentation. Original patch by Vajrasky Kok, further improved (I hope) by me. --- Doc/library/fcntl.rst | 13 ++++++++----- Modules/fcntlmodule.c | 24 +++++++++++++----------- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index cc77340..8e932fb 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -30,11 +30,11 @@ The module defines the following functions: .. function:: fcntl(fd, op[, arg]) - Perform the requested operation on file descriptor *fd* (file objects providing - a :meth:`~io.IOBase.fileno` method are accepted as well). The operation is - defined by *op* - and is operating system dependent. These codes are also found in the - :mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer + Perform the operation *op* 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 + 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 @@ -56,6 +56,9 @@ The module defines the following functions: 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 + 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 diff --git a/Modules/fcntlmodule.c b/Modules/fcntlmodule.c index de1e0da..6769098 100644 --- a/Modules/fcntlmodule.c +++ b/Modules/fcntlmodule.c @@ -27,7 +27,7 @@ conv_descriptor(PyObject *object, int *target) } -/* fcntl(fd, opt, [arg]) */ +/* fcntl(fd, op, [arg]) */ static PyObject * fcntl_fcntl(PyObject *self, PyObject *args) @@ -77,11 +77,12 @@ fcntl_fcntl(PyObject *self, PyObject *args) } PyDoc_STRVAR(fcntl_doc, -"fcntl(fd, opt, [arg])\n\ +"fcntl(fd, op, [arg])\n\ \n\ -Perform the requested operation on file descriptor fd. The operation\n\ -is defined by op and is operating system dependent. These constants are\n\ -available from the fcntl module. The argument arg is optional, and\n\ +Perform the operation op on file descriptor fd. The values used\n\ +for op 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\ the return value of fcntl is a string of that length, containing the\n\ resulting value put in the arg buffer by the operating system. The length\n\ @@ -90,7 +91,7 @@ is an integer or if none is specified, the result value is an integer\n\ corresponding to the return value of the fcntl call in the C code."); -/* ioctl(fd, opt, [arg]) */ +/* ioctl(fd, op, [arg]) */ static PyObject * fcntl_ioctl(PyObject *self, PyObject *args) @@ -104,7 +105,7 @@ fcntl_ioctl(PyObject *self, PyObject *args) whereas the system expects it to be a 32bit bit field value regardless of it being passed as an int or unsigned long on various platforms. See the termios.TIOCSWINSZ constant across - platforms for an example of thise. + platforms for an example of this. If any of the 64bit platforms ever decide to use more than 32bits in their unsigned long ioctl codes this will break and need @@ -222,11 +223,12 @@ fcntl_ioctl(PyObject *self, PyObject *args) } PyDoc_STRVAR(ioctl_doc, -"ioctl(fd, opt[, arg[, mutate_flag]])\n\ +"ioctl(fd, op[, arg[, mutate_flag]])\n\ \n\ -Perform the requested operation on file descriptor fd. The operation is\n\ -defined by opt and is operating system dependent. Typically these codes are\n\ -retrieved from the fcntl or termios library modules.\n\ +Perform the operation op on file descriptor fd. The values used for op\n\ +are operating system dependent, and are available as constants in the\n\ +fcntl or termios library modules, using the same names as used in the\n\ +relevant C header files.\n\ \n\ The argument arg is optional, and defaults to 0; it may be an int or a\n\ buffer containing character data (most likely a string or an array). \n\ -- cgit v0.12