[Python-checkins] CVS: python/dist/src/Doc/lib libfcntl.tex,1.25,1.26

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv24908/Doc/lib

Modified Files:
	libfcntl.tex 
Log Message:

Update the fcntl module documentation.


Index: libfcntl.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libfcntl.tex,v
retrieving revision 1.25
retrieving revision 1.26
diff -C2 -r1.25 -r1.26
*** libfcntl.tex	2001/04/11 21:33:47	1.25
--- libfcntl.tex	2001/05/09 21:09:57	1.26
***************
*** 12,18 ****
  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
! \method{fileno()} method of a file or socket object.
  
  The module defines the following functions:
  
--- 12,22 ----
  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.
  
+ 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:
  
***************
*** 21,40 ****
    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
!   module \module{FCNTL}\refstmodindex{FCNTL}. The argument \var{arg}
!   is optional, and defaults to the integer value \code{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 \cfunction{fcntl()}
!   call.  When the argument is a string it represents a binary
!   structure, e.g.\ created by \function{struct.pack()}. The binary
!   data is copied to a buffer whose address is passed to the C
!   \cfunction{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 \var{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 \cfunction{fcntl()} fails, an \exception{IOError} is
--- 25,44 ----
    Perform the requested operation on file descriptor \var{fd}.
    The operation is defined by \var{op} and is operating system
!   dependent.  These codes are also found in the \module{fcntl}
!   module. The argument \var{arg} is optional, and defaults to the
!   integer value \code{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 \cfunction{fcntl()} call.  When the argument is a string it
!   represents a binary structure, e.g.\ created by
!   \function{struct.pack()}. The binary data is copied to a buffer
!   whose address is passed to the C \cfunction{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 \var{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 \cfunction{fcntl()} fails, an \exception{IOError} is
***************
*** 91,114 ****
  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
  
  file = open(...)
! rv = fcntl(file.fileno(), FCNTL.F_SETFL, FCNTL.O_NDELAY)
  
! lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
! rv = fcntl.fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
  \end{verbatim}
  
--- 95,110 ----
  to lock to the end of the file.  The default for \var{whence} is also
  0.
  \end{funcdesc}
  
  Examples (all on a SVR4 compliant system):
  
  \begin{verbatim}
! import struct, fcntl
  
  file = open(...)
! rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY)
  
! lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
! rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata)
  \end{verbatim}