#18985: Improve fcntl documentation.

bitdancer · bitdancer · commit d5a2f0b3a139 · 2013-11-07T10:51:07.000-05:00
Original patch by Vajrasky Kok, further improved (I hope) by me.
diff --git 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
@@ -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\
