Move the 2.6 reST doc tree in place.

1 files changed, 196 insertions, 0 deletions

diff --git a/Doc/library/posixfile.rst b/Doc/library/posixfile.rst
new file mode 100644
index 0000000..ec58b94
--- /dev/null
+++ b/Doc/library/posixfile.rst
@@ -0,0 +1,196 @@
+.. % Manual text and implementation by Jaap Vermeulen
+
+
+:mod:`posixfile` --- File-like objects with locking support
+===========================================================
+
+.. module:: posixfile
+   :platform: Unix
+   :synopsis: A file-like object with support for locking.
+.. moduleauthor:: Jaap Vermeulen
+.. sectionauthor:: Jaap Vermeulen
+
+
+.. index:: pair: POSIX; file object
+
+.. deprecated:: 1.5
+   .. index:: single: lockf() (in module fcntl)
+
+   The locking operation that this module provides is done better and more portably
+   by the :func:`fcntl.lockf` call.
+
+.. index:: single: fcntl() (in module fcntl)
+
+This module implements some additional functionality over the built-in file
+objects.  In particular, it implements file locking, control over the file
+flags, and an easy interface to duplicate the file object. The module defines a
+new file object, the posixfile object.  It has all the standard file object
+methods and adds the methods described below.  This module only works for
+certain flavors of Unix, since it uses :func:`fcntl.fcntl` for file locking.
+
+.. % 
+
+To instantiate a posixfile object, use the :func:`open` function in the
+:mod:`posixfile` module.  The resulting object looks and feels roughly the same
+as a standard file object.
+
+The :mod:`posixfile` module defines the following constants:
+
+
+.. data:: SEEK_SET
+
+   Offset is calculated from the start of the file.
+
+
+.. data:: SEEK_CUR
+
+   Offset is calculated from the current position in the file.
+
+
+.. data:: SEEK_END
+
+   Offset is calculated from the end of the file.
+
+The :mod:`posixfile` module defines the following functions:
+
+
+.. function:: open(filename[, mode[, bufsize]])
+
+   Create a new posixfile object with the given filename and mode.  The *filename*,
+   *mode* and *bufsize* arguments are interpreted the same way as by the built-in
+   :func:`open` function.
+
+
+.. function:: fileopen(fileobject)
+
+   Create a new posixfile object with the given standard file object. The resulting
+   object has the same filename and mode as the original file object.
+
+The posixfile object defines the following additional methods:
+
+
+.. method:: posixfile.lock(fmt, [len[, start[, whence]]])
+
+   Lock the specified section of the file that the file object is referring to.
+   The format is explained below in a table.  The *len* argument specifies the
+   length of the section that should be locked. The default is ``0``. *start*
+   specifies the starting offset of the section, where the default is ``0``.  The
+   *whence* argument specifies where the offset is relative to. It accepts one of
+   the constants :const:`SEEK_SET`, :const:`SEEK_CUR` or :const:`SEEK_END`.  The
+   default is :const:`SEEK_SET`.  For more information about the arguments refer to
+   the :manpage:`fcntl(2)` manual page on your system.
+
+
+.. method:: posixfile.flags([flags])
+
+   Set the specified flags for the file that the file object is referring to.  The
+   new flags are ORed with the old flags, unless specified otherwise.  The format
+   is explained below in a table.  Without the *flags* argument a string indicating
+   the current flags is returned (this is the same as the ``?`` modifier).  For
+   more information about the flags refer to the :manpage:`fcntl(2)` manual page on
+   your system.
+
+
+.. method:: posixfile.dup()
+
+   Duplicate the file object and the underlying file pointer and file descriptor.
+   The resulting object behaves as if it were newly opened.
+
+
+.. method:: posixfile.dup2(fd)
+
+   Duplicate the file object and the underlying file pointer and file descriptor.
+   The new object will have the given file descriptor. Otherwise the resulting
+   object behaves as if it were newly opened.
+
+
+.. method:: posixfile.file()
+
+   Return the standard file object that the posixfile object is based on.  This is
+   sometimes necessary for functions that insist on a standard file object.
+
+All methods raise :exc:`IOError` when the request fails.
+
+Format characters for the :meth:`lock` method have the following meaning:
+
++--------+-----------------------------------------------+
+| Format | Meaning                                       |
++========+===============================================+
+| ``u``  | unlock the specified region                   |
++--------+-----------------------------------------------+
+| ``r``  | request a read lock for the specified section |
++--------+-----------------------------------------------+
+| ``w``  | request a write lock for the specified        |
+|        | section                                       |
++--------+-----------------------------------------------+
+
+In addition the following modifiers can be added to the format:
+
++----------+--------------------------------+-------+
+| Modifier | Meaning                        | Notes |
++==========+================================+=======+
+| ``|``    | wait until the lock has been   |       |
+|          | granted                        |       |
++----------+--------------------------------+-------+
+| ``?``    | return the first lock          | \(1)  |
+|          | conflicting with the requested |       |
+|          | lock, or ``None`` if there is  |       |
+|          | no conflict.                   |       |
++----------+--------------------------------+-------+
+
+Note:
+
+(1)
+   The lock returned is in the format ``(mode, len, start, whence, pid)`` where
+   *mode* is a character representing the type of lock ('r' or 'w').  This modifier
+   prevents a request from being granted; it is for query purposes only.
+
+Format characters for the :meth:`flags` method have the following meanings:
+
++--------+-----------------------------------------------+
+| Format | Meaning                                       |
++========+===============================================+
+| ``a``  | append only flag                              |
++--------+-----------------------------------------------+
+| ``c``  | close on exec flag                            |
++--------+-----------------------------------------------+
+| ``n``  | no delay flag (also called non-blocking flag) |
++--------+-----------------------------------------------+
+| ``s``  | synchronization flag                          |
++--------+-----------------------------------------------+
+
+In addition the following modifiers can be added to the format:
+
++----------+---------------------------------+-------+
+| Modifier | Meaning                         | Notes |
++==========+=================================+=======+
+| ``!``    | turn the specified flags 'off', | \(1)  |
+|          | instead of the default 'on'     |       |
++----------+---------------------------------+-------+
+| ``=``    | replace the flags, instead of   | \(1)  |
+|          | the default 'OR' operation      |       |
++----------+---------------------------------+-------+
+| ``?``    | return a string in which the    | \(2)  |
+|          | characters represent the flags  |       |
+|          | that are set.                   |       |
++----------+---------------------------------+-------+
+
+Notes:
+
+(1)
+   The ``!`` and ``=`` modifiers are mutually exclusive.
+
+(2)
+   This string represents the flags after they may have been altered by the same
+   call.
+
+Examples::
+
+   import posixfile
+
+   file = posixfile.open('/tmp/test', 'w')
+   file.lock('w|')
+   ...
+   file.lock('u')
+   file.close()
+