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\optional{, arg\optional{, mutate_flag}}}
  51   This function is identical to the \function{fcntl()} function,
  52   except that the operations are typically defined in the library
  53   module \refmodule{termios} and the argument handling is even more
  54   complicated.
  55
  56   The parameter \var{arg} can be one of an integer, absent (treated
  57   identically to the integer \code{0}), an object supporting the
  58   read-only buffer interface (most likely a plain Python string) or an
  59   object supporting the read-write buffer interface.
  60
  61   In all but the last case, behaviour is as for the \function{fcntl()}
  62   function.
  63
  64   If a mutable buffer is passed, then the behaviour is determined by
  65   the value of the \var{mutate_flag} parameter.
  66
  67   If it is false, the buffer's mutability is ignored and behaviour is
  68   as for a read-only buffer, except that the 1024 byte limit mentioned
  69   above is avoided -- so long as the buffer you pass is longer than
  70   what the operating system wants to put there, things should work.
  71
  72   If \var{mutate_flag} is true, then the buffer is (in effect) passed
  73   to the underlying \function{ioctl()} system call, the latter's
  74   return code is passed back to the calling Python, and the buffer's
  75   new contents reflect the action of the \function{ioctl}.  This is a
  76   slight simplification, because if the supplied buffer is less than
  77   1024 bytes long it is first copied into a static buffer 1024 bytes
  78   long which is then passed to \function{ioctl} and copied back into
  79   the supplied buffer.
  80
  81   If \var{mutate_flag} is not supplied, then in 2.3 it defaults to
  82   false.  This is planned to change over the next few Python versions:
  83   in 2.4 failing to supply \var{mutate_flag} will get a warning but
  84   the same behavior and in versions later than 2.5 it will default to
  85   true.
  86
  87   An example:
  88
  89 \begin{verbatim}
  90 >>> import array, fnctl, struct, termios, os
  91 >>> os.getpgrp()
  92 13341
  93 >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
  94 13341
  95 >>> buf = array.array('h', [0])
  96 >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
  97 0
  98 >>> buf
  99 array('h', [13341])
 100 \end{verbatim}
 101 \end{funcdesc}
 102
 103 \begin{funcdesc}{flock}{fd, op}
 104 Perform the lock operation \var{op} on file descriptor \var{fd} (file
 105   objects providing a \method{fileno()} method are accepted as well).
 106 See the \UNIX{} manual \manpage{flock}{3} for details.  (On some
 107 systems, this function is emulated using \cfunction{fcntl()}.)
 108 \end{funcdesc}
 109
 110 \begin{funcdesc}{lockf}{fd, operation,
 111     \optional{len, \optional{start, \optional{whence}}}}
 112 This is essentially a wrapper around the \function{fcntl()} locking
 113 calls.  \var{fd} is the file descriptor of the file to lock or unlock,
 114 and \var{operation} is one of the following values:
 115
 116 \begin{itemize}
 117 \item \constant{LOCK_UN} -- unlock
 118 \item \constant{LOCK_SH} -- acquire a shared lock
 119 \item \constant{LOCK_EX} -- acquire an exclusive lock
 120 \end{itemize}
 121
 122 When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it
 123 can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on
 124 lock acquisition.  If \constant{LOCK_NB} is used and the lock cannot
 125 be acquired, an \exception{IOError} will be raised and the exception
 126 will have an \var{errno} attribute set to \constant{EACCES} or
 127 \constant{EAGAIN} (depending on the operating system; for portability,
 128 check for both values).  On at least some systems, \constant{LOCK_EX}
 129 can only be used if the file descriptor refers to a file opened for
 130 writing.
 131
 132 \var{length} is the number of bytes to lock, \var{start} is the byte
 133 offset at which the lock starts, relative to \var{whence}, and
 134 \var{whence} is as with \function{fileobj.seek()}, specifically:
 135
 136 \begin{itemize}
 137 \item \constant{0} -- relative to the start of the file
 138       (\constant{SEEK_SET})
 139 \item \constant{1} -- relative to the current buffer position
 140       (\constant{SEEK_CUR})
 141 \item \constant{2} -- relative to the end of the file
 142       (\constant{SEEK_END})
 143 \end{itemize}
 144
 145 The default for \var{start} is 0, which means to start at the
 146 beginning of the file.  The default for \var{length} is 0 which means
 147 to lock to the end of the file.  The default for \var{whence} is also
 148 0.
 149 \end{funcdesc}
 150
 151 Examples (all on a SVR4 compliant system):
 152
 153 \begin{verbatim}
 154 import struct, fcntl
 155
 156 file = open(...)
 157 rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY)
 158
 159 lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
 160 rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata)
 161 \end{verbatim}
 162
 163 Note that in the first example the return value variable \var{rv} will
 164 hold an integer value; in the second example it will hold a string
 165 value.  The structure lay-out for the \var{lockdata} variable is
 166 system dependent --- therefore using the \function{flock()} call may be
 167 better.
 168
 169 \begin{seealso}
 170   \seemodule{os}{The \function{os.open} function supports locking flags
 171                  and is available on a wider variety of platforms than
 172                  the \function{fcntl.lockf} and \function{fcntl.flock}
 173                  functions, providing a more platform-independent file
 174                  locking facility.}
 175 \end{seealso}