Move the 3k reST doc tree in place.

1 files changed, 155 insertions, 0 deletions

diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
new file mode 100644
index 0000000..2d7bb9c
--- /dev/null
+++ b/Doc/library/fcntl.rst
@@ -0,0 +1,155 @@
+
+:mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls
+=================================================================
+
+.. module:: fcntl
+   :platform: Unix
+   :synopsis: The fcntl() and ioctl() system calls.
+.. sectionauthor:: Jaap Vermeulen
+
+
+.. index::
+   pair: UNIX@Unix; file control
+   pair: UNIX@Unix; I/O control
+
+This module performs file control and I/O control on file descriptors. It is an
+interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
+
+All functions in this module take a file descriptor *fd* as their first
+argument.  This can be an integer file descriptor, such as returned by
+``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
+provides a :meth:`fileno` which returns a genuine file descriptor.
+
+The module defines the following functions:
+
+
+.. function:: fcntl(fd, op[, arg])
+
+   Perform the requested operation on file descriptor *fd* (file objects providing
+   a :meth:`fileno` method are accepted as well). The operation is defined by *op*
+   and is operating system dependent.  These codes are also found in the
+   :mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer
+   value ``0``.  When present, it can either be an integer value, or a string.
+   With the argument missing or an integer value, the return value of this function
+   is the integer return value of the C :cfunc:`fcntl` call.  When the argument is
+   a string it represents a binary structure, e.g. created by :func:`struct.pack`.
+   The binary data is copied to a buffer whose address is passed to the C
+   :cfunc:`fcntl` call.  The return value after a successful call is the contents
+   of the buffer, converted to a string object.  The length of the returned string
+   will be the same as the length of the *arg* argument.  This is limited to 1024
+   bytes.  If the information returned in the buffer by the operating system is
+   larger than 1024 bytes, this is most likely to result in a segmentation
+   violation or a more subtle data corruption.
+
+   If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.
+
+
+.. function:: ioctl(fd, op[, arg[, mutate_flag]])
+
+   This function is identical to the :func:`fcntl` function, except that the
+   operations are typically defined in the library module :mod:`termios` and the
+   argument handling is even more complicated.
+
+   The parameter *arg* can be one of an integer, absent (treated identically to the
+   integer ``0``), an object supporting the read-only buffer interface (most likely
+   a plain Python string) or an object supporting the read-write buffer interface.
+
+   In all but the last case, behaviour is as for the :func:`fcntl` function.
+
+   If a mutable buffer is passed, then the behaviour is determined by the value of
+   the *mutate_flag* parameter.
+
+   If it is false, the buffer's mutability is ignored and behaviour is as for a
+   read-only buffer, except that the 1024 byte limit mentioned above is avoided --
+   so long as the buffer you pass is as least as long as what the operating system
+   wants to put there, things should work.
+
+   If *mutate_flag* is true, then the buffer is (in effect) passed to the
+   underlying :func:`ioctl` system call, the latter's return code is passed back to
+   the calling Python, and the buffer's new contents reflect the action of the
+   :func:`ioctl`.  This is a slight simplification, because if the supplied buffer
+   is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
+   long which is then passed to :func:`ioctl` and copied back into the supplied
+   buffer.
+
+   If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
+   which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
+   version portability is a priority.
+
+   An example::
+
+      >>> import array, fcntl, struct, termios, os
+      >>> os.getpgrp()
+      13341
+      >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
+      13341
+      >>> buf = array.array('h', [0])
+      >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
+      0
+      >>> buf
+      array('h', [13341])
+
+
+.. function:: flock(fd, op)
+
+   Perform the lock operation *op* on file descriptor *fd* (file objects providing
+   a :meth:`fileno` method are accepted as well). See the Unix manual
+   :manpage:`flock(3)` for details.  (On some systems, this function is emulated
+   using :cfunc:`fcntl`.)
+
+
+.. function:: lockf(fd, operation, [length, [start, [whence]]])
+
+   This is essentially a wrapper around the :func:`fcntl` locking calls.  *fd* is
+   the file descriptor of the file to lock or unlock, and *operation* is one of the
+   following values:
+
+   * :const:`LOCK_UN` -- unlock
+   * :const:`LOCK_SH` -- acquire a shared lock
+   * :const:`LOCK_EX` -- acquire an exclusive lock
+
+   When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
+   bit-wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition.
+   If :const:`LOCK_NB` is used and the lock cannot be acquired, an
+   :exc:`IOError` will be raised and the exception will have an *errno*
+   attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
+   operating system; for portability, check for both values).  On at least some
+   systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
+   file opened for writing.
+
+   *length* is the number of bytes to lock, *start* is the byte offset at which the
+   lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`,
+   specifically:
+
+   * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`)
+   * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`)
+   * :const:`2` -- relative to the end of the file (:const:`SEEK_END`)
+
+   The default for *start* is 0, which means to start at the beginning of the file.
+   The default for *length* is 0 which means to lock to the end of the file.  The
+   default for *whence* is also 0.
+
+Examples (all on a SVR4 compliant system)::
+
+   import struct, fcntl, os
+
+   f = open(...)
+   rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
+
+   lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
+   rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
+
+Note that in the first example the return value variable *rv* will hold an
+integer value; in the second example it will hold a string value.  The structure
+lay-out for the *lockdata* variable is system dependent --- therefore using the
+:func:`flock` call may be better.
+
+
+.. seealso::
+
+   Module :mod:`os`
+      If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present
+      in the :mod:`os` module, the :func:`os.open` function provides a more
+      platform-independent alternative to the :func:`lockf` and :func:`flock`
+      functions.
+