Doc/lib/libfcntl.tex

   1 % Manual text by Jaap Vermeulen
   2 \section{Built-in Module \sectcode{fcntl}}
   3 \bimodindex{fcntl}
   4 \indexii{\UNIX{}}{file control}
   5 \indexii{\UNIX{}}{I/O control}
   6
   7 This module performs file control and I/O control on file descriptors.
   8 It is an interface to the \dfn{fcntl()} and \dfn{ioctl()} \UNIX{} routines.
   9 File descriptors can be obtained with the \dfn{fileno()} method of a
  10 file or socket object.
  11
  12 The module defines the following functions:
  13
  14 \renewcommand{\indexsubitem}{(in module struct)}
  15
  16 \begin{funcdesc}{fcntl}{fd\, op\optional{\, arg}}
  17   Perform the requested operation on file descriptor \code{\var{fd}}.
  18   The operation is defined by \code{\var{op}} and is operating system
  19   dependent.  Typically these codes can be retrieved from the library
  20   module \code{FCNTL}. The argument \code{\var{arg}} is optional, and
  21   defaults to the integer value \code{0}.  When
  22   it is present, it can either be an integer value, or a string.  With
  23   the argument missing or an integer value, the return value of this
  24   function is the integer return value of the real \code{fcntl()}
  25   call.  When the argument is a string it represents a binary
  26   structure, e.g.\ created by \code{struct.pack()}. The binary data is
  27   copied to a buffer whose address is passed to the real \code{fcntl()}
  28   call.  The return value after a successful call is the contents of
  29   the buffer, converted to a string object.  In case the
  30   \code{fcntl()} fails, an \code{IOError} will be raised.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{ioctl}{fd\, op\, arg}
  34   This function is identical to the \code{fcntl()} function, except
  35   that the operations are typically defined in the library module
  36   \code{IOCTL}.
  37 \end{funcdesc}
  38
  39 If the library modules \code{FCNTL} or \code{IOCTL} are missing, you
  40 can find the opcodes in the C include files \code{sys/fcntl} and
  41 \code{sys/ioctl}. You can create the modules yourself with the h2py
  42 script, found in the \code{Tools/scripts} directory.
  43 \stmodindex{FCNTL}
  44 \stmodindex{IOCTL}
  45
  46 Examples (all on a SVR4 compliant system):
  47
  48 \bcode\begin{verbatim}
  49 import struct, FCNTL
  50
  51 file = open(...)
  52 rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)
  53
  54 lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
  55 rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
  56 \end{verbatim}\ecode
  57
  58 Note that in the first example the return value variable \code{rv} will
  59 hold an integer value; in the second example it will hold a string
  60 value.