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