Update the fcntl module documentation.

Doc/lib/libfcntl.tex

@@ -11,8 +11,12 @@
 
 This module performs file control and I/O control on file descriptors.
 It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()}
-\UNIX{} routines.  File descriptors can be obtained with the
+\UNIX{} routines.
-\method{fileno()} method of a file or socket object.
+
+All functions in this module take a file descriptor \var{fd} as their
+first argument.  This can be an integer file descriptor, such as
+returned by \code{sys.stdin.fileno()}, or a file object, such as
+\code{sys.stdin} itself.
 
 The module defines the following functions:
 
@@ -20,22 +24,22 @@ The module defines the following functions:
 \begin{funcdesc}{fcntl}{fd, op\optional{, arg}}
   Perform the requested operation on file descriptor \var{fd}.
   The operation is defined by \var{op} and is operating system
-  dependent.  Typically these codes can be retrieved from the library
+  dependent.  These codes are also found in the \module{fcntl}
-  module \module{FCNTL}\refstmodindex{FCNTL}. The argument \var{arg}
+  module. The argument \var{arg} is optional, and defaults to the
-  is optional, and defaults to the integer value \code{0}.  When
+  integer value \code{0}.  When present, it can either be an integer
-  present, it can either be an integer value, or a string.  With
+  value, or a string.  With the argument missing or an integer value,
-  the argument missing or an integer value, the return value of this
+  the return value of this function is the integer return value of the
-  function is the integer return value of the C \cfunction{fcntl()}
+  C \cfunction{fcntl()} call.  When the argument is a string it
-  call.  When the argument is a string it represents a binary
+  represents a binary structure, e.g.\ created by
-  structure, e.g.\ created by \function{struct.pack()}. The binary
+  \function{struct.pack()}. The binary data is copied to a buffer
-  data is copied to a buffer whose address is passed to the C
+  whose address is passed to the C \cfunction{fcntl()} call.  The
-  \cfunction{fcntl()} call.  The return value after a successful call
+  return value after a successful call is the contents of the buffer,
-  is the contents of the buffer, converted to a string object.  The length
+  converted to a string object.  The length of the returned string
-  of the returned string will be the same as the length of the \var{arg} 
+  will be the same as the length of the \var{arg} argument.  This is
-  argument.  This is limited to 1024 bytes.  If the information returned
+  limited to 1024 bytes.  If the information returned in the buffer by
-  in the buffer by the operating system is larger than 1024 bytes, 
+  the operating system is larger than 1024 bytes, this is most likely
-  this is most likely to result in a segmentation violation or a more
+  to result in a segmentation violation or a more subtle data
-  subtle data corruption.
+  corruption.
 
   If the \cfunction{fcntl()} fails, an \exception{IOError} is
   raised.
@@ -90,26 +94,18 @@ The default for \var{start} is 0, which means to start at the
 beginning of the file.  The default for \var{length} is 0 which means
 to lock to the end of the file.  The default for \var{whence} is also
 0.
-
 \end{funcdesc}
 
-If the library modules \module{FCNTL}\refstmodindex{FCNTL} or
-\module{IOCTL}\refstmodindex{IOCTL} are missing, you can find the
-opcodes in the C include files \code{<sys/fcntl.h>} and
-\code{<sys/ioctl.h>}.  You can create the modules yourself with the
-\program{h2py} script, found in the \file{Tools/scripts/} directory.
-
-
 Examples (all on a SVR4 compliant system):
 
 \begin{verbatim}
-import struct, fcntl, FCNTL
+import struct, fcntl
 
 file = open(...)
-rv = fcntl(file.fileno(), FCNTL.F_SETFL, FCNTL.O_NDELAY)
+rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY)
 
-lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
+lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
-rv = fcntl.fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
+rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata)
 \end{verbatim}
 
 Note that in the first example the return value variable \var{rv} will