Doc/lib/libfcntl.tex

   1 \section{\module{fcntl} ---
   2          The \function{fcntl()} and \function{ioctl()} system calls}
   3
   4 \declaremodule{builtin}{fcntl}
   5   \platform{Unix}
   6 \modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.}
   7 \sectionauthor{Jaap Vermeulen}{}
   8
   9 \indexii{UNIX@\UNIX}{file control}
  10 \indexii{UNIX@\UNIX}{I/O control}
  11
  12 This module performs file control and I/O control on file descriptors.
  13 It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()}
  14 \UNIX{} routines.
  15
  16 All functions in this module take a file descriptor \var{fd} as their
  17 first argument.  This can be an integer file descriptor, such as
  18 returned by \code{sys.stdin.fileno()}, or a file object, such as
  19 \code{sys.stdin} itself, which provides a \method{fileno()} which
  20 returns a genuine file descriptor.
  21
  22 The module defines the following functions:
  23
  24
  25 \begin{funcdesc}{fcntl}{fd, op\optional{, arg}}
  26   Perform the requested operation on file descriptor \var{fd} (file
  27   objects providing a \method{fileno()} method are accepted as well).
  28   The operation is defined by \var{op} and is operating system
  29   dependent.  These codes are also found in the \module{fcntl}
  30   module. The argument \var{arg} is optional, and defaults to the
  31   integer value \code{0}.  When present, it can either be an integer
  32   value, or a string.  With the argument missing or an integer value,
  33   the return value of this function is the integer return value of the
  34   C \cfunction{fcntl()} call.  When the argument is a string it
  35   represents a binary structure, e.g.\ created by
  36   \function{struct.pack()}. The binary data is copied to a buffer
  37   whose address is passed to the C \cfunction{fcntl()} call.  The
  38   return value after a successful call is the contents of the buffer,
  39   converted to a string object.  The length of the returned string
  40   will be the same as the length of the \var{arg} argument.  This is
  41   limited to 1024 bytes.  If the information returned in the buffer by
  42   the operating system is larger than 1024 bytes, this is most likely
  43   to result in a segmentation violation or a more subtle data
  44   corruption.
  45
  46   If the \cfunction{fcntl()} fails, an \exception{IOError} is
  47   raised.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{ioctl}{fd, op, arg}
  51   This function is identical to the \function{fcntl()} function, except
  52   that the operations are typically defined in the library module
  53   \refmodule{termios}.
  54 \end{funcdesc}
  55
  56 \begin{funcdesc}{flock}{fd, op}
  57 Perform the lock operation \var{op} on file descriptor \var{fd} (file
  58   objects providing a \method{fileno()} method are accepted as well).
  59 See the \UNIX{} manual \manpage{flock}{3} for details.  (On some
  60 systems, this function is emulated using \cfunction{fcntl()}.)
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{lockf}{fd, operation,
  64     \optional{len, \optional{start, \optional{whence}}}}
  65 This is essentially a wrapper around the \function{fcntl()} locking
  66 calls.  \var{fd} is the file descriptor of the file to lock or unlock,
  67 and \var{operation} is one of the following values:
  68
  69 \begin{itemize}
  70 \item \constant{LOCK_UN} -- unlock
  71 \item \constant{LOCK_SH} -- acquire a shared lock
  72 \item \constant{LOCK_EX} -- acquire an exclusive lock
  73 \end{itemize}
  74
  75 When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it
  76 can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on
  77 lock acquisition.  If \constant{LOCK_NB} is used and the lock cannot
  78 be acquired, an \exception{IOError} will be raised and the exception
  79 will have an \var{errno} attribute set to \constant{EACCES} or
  80 \constant{EAGAIN} (depending on the operating system; for portability,
  81 check for both values).  On at least some systems, \constant{LOCK_EX}
  82 can only be used if the file descriptor refers to a file opened for
  83 writing.
  84
  85 \var{length} is the number of bytes to lock, \var{start} is the byte
  86 offset at which the lock starts, relative to \var{whence}, and
  87 \var{whence} is as with \function{fileobj.seek()}, specifically:
  88
  89 \begin{itemize}
  90 \item \constant{0} -- relative to the start of the file
  91       (\constant{SEEK_SET})
  92 \item \constant{1} -- relative to the current buffer position
  93       (\constant{SEEK_CUR})
  94 \item \constant{2} -- relative to the end of the file
  95       (\constant{SEEK_END})
  96 \end{itemize}
  97
  98 The default for \var{start} is 0, which means to start at the
  99 beginning of the file.  The default for \var{length} is 0 which means
 100 to lock to the end of the file.  The default for \var{whence} is also
 101 0.
 102 \end{funcdesc}
 103
 104 Examples (all on a SVR4 compliant system):
 105
 106 \begin{verbatim}
 107 import struct, fcntl
 108
 109 file = open(...)
 110 rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY)
 111
 112 lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
 113 rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata)
 114 \end{verbatim}
 115
 116 Note that in the first example the return value variable \var{rv} will
 117 hold an integer value; in the second example it will hold a string
 118 value.  The structure lay-out for the \var{lockdata} variable is
 119 system dependent --- therefore using the \function{flock()} call may be
 120 better.