#18985: Improve fcntl documentation.

Original patch by Vajrasky Kok, further improved (I hope) by me.
This commit is contained in:
R David Murray 2013-11-07 10:51:07 -05:00
parent 7c934da0ff
commit d5a2f0b3a1
2 changed files with 21 additions and 16 deletions

View File

@ -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

View File

@ -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\