Doc/library/fcntl.rst

   1
   2 :mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls
   3 =================================================================
   4
   5 .. module:: fcntl
   6    :platform: Unix
   7    :synopsis: The fcntl() and ioctl() system calls.
   8 .. sectionauthor:: Jaap Vermeulen
   9
  10
  11 .. index::
  12    pair: UNIX@Unix; file control
  13    pair: UNIX@Unix; I/O control
  14
  15 This module performs file control and I/O control on file descriptors. It is an
  16 interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
  17
  18 All functions in this module take a file descriptor *fd* as their first
  19 argument.  This can be an integer file descriptor, such as returned by
  20 ``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
  21 provides a :meth:`fileno` which returns a genuine file descriptor.
  22
  23 The module defines the following functions:
  24
  25
  26 .. function:: fcntl(fd, op[, arg])
  27
  28    Perform the requested operation on file descriptor *fd* (file objects providing
  29    a :meth:`fileno` method are accepted as well). The operation is defined by *op*
  30    and is operating system dependent.  These codes are also found in the
  31    :mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer
  32    value ``0``.  When present, it can either be an integer value, or a string.
  33    With the argument missing or an integer value, the return value of this function
  34    is the integer return value of the C :cfunc:`fcntl` call.  When the argument is
  35    a string it represents a binary structure, e.g. created by :func:`struct.pack`.
  36    The binary data is copied to a buffer whose address is passed to the C
  37    :cfunc:`fcntl` call.  The return value after a successful call is the contents
  38    of the buffer, converted to a string object.  The length of the returned string
  39    will be the same as the length of the *arg* argument.  This is limited to 1024
  40    bytes.  If the information returned in the buffer by the operating system is
  41    larger than 1024 bytes, this is most likely to result in a segmentation
  42    violation or a more subtle data corruption.
  43
  44    If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.
  45
  46
  47 .. function:: ioctl(fd, op[, arg[, mutate_flag]])
  48
  49    This function is identical to the :func:`fcntl` function, except that the
  50    operations are typically defined in the library module :mod:`termios` and the
  51    argument handling is even more complicated.
  52
  53    The op parameter is limited to values that can fit in 32-bits.
  54
  55    The parameter *arg* can be one of an integer, absent (treated identically to the
  56    integer ``0``), an object supporting the read-only buffer interface (most likely
  57    a plain Python string) or an object supporting the read-write buffer interface.
  58
  59    In all but the last case, behaviour is as for the :func:`fcntl` function.
  60
  61    If a mutable buffer is passed, then the behaviour is determined by the value of
  62    the *mutate_flag* parameter.
  63
  64    If it is false, the buffer's mutability is ignored and behaviour is as for a
  65    read-only buffer, except that the 1024 byte limit mentioned above is avoided --
  66    so long as the buffer you pass is as least as long as what the operating system
  67    wants to put there, things should work.
  68
  69    If *mutate_flag* is true, then the buffer is (in effect) passed to the
  70    underlying :func:`ioctl` system call, the latter's return code is passed back to
  71    the calling Python, and the buffer's new contents reflect the action of the
  72    :func:`ioctl`.  This is a slight simplification, because if the supplied buffer
  73    is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
  74    long which is then passed to :func:`ioctl` and copied back into the supplied
  75    buffer.
  76
  77    If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
  78    which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
  79    version portability is a priority.
  80
  81    An example::
  82
  83       >>> import array, fcntl, struct, termios, os
  84       >>> os.getpgrp()
  85       13341
  86       >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
  87       13341
  88       >>> buf = array.array('h', [0])
  89       >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
  90       0
  91       >>> buf
  92       array('h', [13341])
  93
  94
  95 .. function:: flock(fd, op)
  96
  97    Perform the lock operation *op* on file descriptor *fd* (file objects providing
  98    a :meth:`fileno` method are accepted as well). See the Unix manual
  99    :manpage:`flock(3)` for details.  (On some systems, this function is emulated
 100    using :cfunc:`fcntl`.)
 101
 102
 103 .. function:: lockf(fd, operation, [length, [start, [whence]]])
 104
 105    This is essentially a wrapper around the :func:`fcntl` locking calls.  *fd* is
 106    the file descriptor of the file to lock or unlock, and *operation* is one of the
 107    following values:
 108
 109    * :const:`LOCK_UN` -- unlock
 110    * :const:`LOCK_SH` -- acquire a shared lock
 111    * :const:`LOCK_EX` -- acquire an exclusive lock
 112
 113    When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
 114    bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
 115    If :const:`LOCK_NB` is used and the lock cannot be acquired, an
 116    :exc:`IOError` will be raised and the exception will have an *errno*
 117    attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
 118    operating system; for portability, check for both values).  On at least some
 119    systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
 120    file opened for writing.
 121
 122    *length* is the number of bytes to lock, *start* is the byte offset at which the
 123    lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`,
 124    specifically:
 125
 126    * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`)
 127    * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`)
 128    * :const:`2` -- relative to the end of the file (:const:`SEEK_END`)
 129
 130    The default for *start* is 0, which means to start at the beginning of the file.
 131    The default for *length* is 0 which means to lock to the end of the file.  The
 132    default for *whence* is also 0.
 133
 134 Examples (all on a SVR4 compliant system)::
 135
 136    import struct, fcntl, os
 137
 138    f = open(...)
 139    rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
 140
 141    lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
 142    rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
 143
 144 Note that in the first example the return value variable *rv* will hold an
 145 integer value; in the second example it will hold a string value.  The structure
 146 lay-out for the *lockdata* variable is system dependent --- therefore using the
 147 :func:`flock` call may be better.
 148
 149
 150 .. seealso::
 151
 152    Module :mod:`os`
 153       If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present
 154       in the :mod:`os` module, the :func:`os.open` function provides a more
 155       platform-independent alternative to the :func:`lockf` and :func:`flock`
 156       functions.
 157