n | .. % 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. |
n | :deprecated: |
| .. moduleauthor:: Jaap Vermeulen |
| .. sectionauthor:: Jaap Vermeulen |
| |
| |
| .. index:: pair: POSIX; file object |
| |
| .. deprecated:: 1.5 |
n | .. 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. |
n | |
| .. % |
| |
| 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: |
| |
| |
| .. 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: |
| |
| |
n | .. function:: lock(fmt, [len[, start[, whence]]]) |
n | .. 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. |
| |
| |
n | .. function:: flags([flags]) |
n | .. 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. |
| |
| |
n | .. function:: dup() |
n | .. 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. |
| |
| |
n | .. function:: dup2(fd) |
n | .. 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. |
| |
| |
t | .. function:: file() |
t | .. 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: |
| |