/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
 15This module performs file control and I/O control on file descriptors. It is an
 16interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
 17
 18All functions in this module take a file descriptor *fd* as their first
 19argument.  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
 21provides a :meth:`fileno` which returns a genuine file descriptor.
 22
 23The 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
134Examples (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
144Note that in the first example the return value variable *rv* will hold an
145integer value; in the second example it will hold a string value.  The structure
146lay-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