1994-05-19 06:09:50 -03:00
|
|
|
% Manual text and implementation by Jaap Vermeulen
|
1998-04-04 03:23:21 -04:00
|
|
|
\section{Standard Module \module{posixfile}}
|
1998-02-18 11:22:08 -04:00
|
|
|
\label{module-posixfile}
|
1994-05-19 06:09:50 -03:00
|
|
|
\bimodindex{posixfile}
|
1998-02-18 11:22:08 -04:00
|
|
|
\indexii{\POSIX{}}{file object}
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1996-10-11 14:43:34 -03:00
|
|
|
\emph{Note:} This module will become obsolete in a future release.
|
|
|
|
The locking operation that it provides is done better and more
|
1998-03-11 02:11:37 -04:00
|
|
|
portably by the \function{fcntl.lockf()} call.%
|
1998-03-12 02:46:16 -04:00
|
|
|
\withsubitem{(in module fcntl)}{\ttindex{lockf()}}
|
1996-10-11 14:43:34 -03:00
|
|
|
|
1994-05-19 06:09:50 -03:00
|
|
|
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
|
1995-03-17 12:07:09 -04:00
|
|
|
has all the standard file object methods and adds the methods
|
|
|
|
described below. This module only works for certain flavors of
|
1998-03-12 02:46:16 -04:00
|
|
|
\UNIX{}, since it uses \function{fcntl.fcntl()} for file locking.%
|
|
|
|
\withsubitem{(in module fcntl)}{\ttindex{fcntl()}}
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
To instantiate a posixfile object, use the \function{open()} function
|
|
|
|
in the \module{posixfile} module. The resulting object looks and
|
|
|
|
feels roughly the same as a standard file object.
|
|
|
|
|
|
|
|
The \module{posixfile} module defines the following constants:
|
1994-05-19 06:09:50 -03:00
|
|
|
|
|
|
|
|
|
|
|
\begin{datadesc}{SEEK_SET}
|
1998-02-13 17:57:33 -04:00
|
|
|
Offset is calculated from the start of the file.
|
1994-05-19 06:09:50 -03:00
|
|
|
\end{datadesc}
|
|
|
|
|
|
|
|
\begin{datadesc}{SEEK_CUR}
|
1998-02-13 17:57:33 -04:00
|
|
|
Offset is calculated from the current position in the file.
|
1994-05-19 06:09:50 -03:00
|
|
|
\end{datadesc}
|
|
|
|
|
|
|
|
\begin{datadesc}{SEEK_END}
|
1998-02-13 17:57:33 -04:00
|
|
|
Offset is calculated from the end of the file.
|
1994-05-19 06:09:50 -03:00
|
|
|
\end{datadesc}
|
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
The \module{posixfile} module defines the following functions:
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1995-03-17 12:07:09 -04:00
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
|
1994-05-19 06:09:50 -03:00
|
|
|
Create a new posixfile object with the given filename and mode. The
|
1995-03-17 12:07:09 -04:00
|
|
|
\var{filename}, \var{mode} and \var{bufsize} arguments are
|
1998-03-11 02:11:37 -04:00
|
|
|
interpreted the same way as by the built-in \function{open()}
|
|
|
|
function.
|
1994-05-19 06:09:50 -03:00
|
|
|
\end{funcdesc}
|
|
|
|
|
1995-01-04 15:17:34 -04:00
|
|
|
\begin{funcdesc}{fileopen}{fileobject}
|
1994-05-19 06:09:50 -03:00
|
|
|
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.
|
|
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
The posixfile object defines the following additional methods:
|
|
|
|
|
1998-02-13 02:58:54 -04:00
|
|
|
\setindexsubitem{(posixfile method)}
|
1998-03-11 02:11:37 -04:00
|
|
|
\begin{funcdesc}{lock}{fmt, \optional{len\optional{, start\optional{, whence}}}}
|
1994-05-19 06:09:50 -03:00
|
|
|
Lock the specified section of the file that the file object is
|
1994-08-08 09:30:22 -03:00
|
|
|
referring to. The format is explained
|
|
|
|
below in a table. The \var{len} argument specifies the length of the
|
|
|
|
section that should be locked. The default is \code{0}. \var{start}
|
|
|
|
specifies the starting offset of the section, where the default is
|
|
|
|
\code{0}. The \var{whence} argument specifies where the offset is
|
1998-03-11 02:11:37 -04:00
|
|
|
relative to. It accepts one of the constants \constant{SEEK_SET},
|
|
|
|
\constant{SEEK_CUR} or \constant{SEEK_END}. The default is
|
|
|
|
\constant{SEEK_SET}. For more information about the arguments refer
|
|
|
|
to the \manpage{fcntl}{2} manual page on your system.
|
1994-05-19 06:09:50 -03:00
|
|
|
\end{funcdesc}
|
|
|
|
|
1995-04-10 08:34:00 -03:00
|
|
|
\begin{funcdesc}{flags}{\optional{flags}}
|
1994-05-19 06:09:50 -03:00
|
|
|
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
|
1995-04-10 08:34:00 -03:00
|
|
|
the \var{flags} argument
|
|
|
|
a string indicating the current flags is returned (this is
|
1998-03-11 02:11:37 -04:00
|
|
|
the same as the \samp{?} modifier). For more information about the
|
|
|
|
flags refer to the \manpage{fcntl}{2} manual page on your system.
|
1994-05-19 06:09:50 -03:00
|
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
\begin{funcdesc}{dup}{}
|
|
|
|
Duplicate the file object and the underlying file pointer and file
|
|
|
|
descriptor. The resulting object behaves as if it were newly
|
|
|
|
opened.
|
|
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
\begin{funcdesc}{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.
|
|
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
\begin{funcdesc}{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.
|
|
|
|
\end{funcdesc}
|
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
All methods raise \exception{IOError} when the request fails.
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
Format characters for the \method{lock()} method have the following
|
|
|
|
meaning:
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1997-12-23 00:21:20 -04:00
|
|
|
\begin{tableii}{|c|l|}{samp}{Format}{Meaning}
|
|
|
|
\lineii{u}{unlock the specified region}
|
|
|
|
\lineii{r}{request a read lock for the specified section}
|
|
|
|
\lineii{w}{request a write lock for the specified section}
|
|
|
|
\end{tableii}
|
1994-05-19 06:09:50 -03:00
|
|
|
|
|
|
|
In addition the following modifiers can be added to the format:
|
|
|
|
|
|
|
|
\begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes}
|
|
|
|
\lineiii{|}{wait until the lock has been granted}{}
|
1995-03-17 12:07:09 -04:00
|
|
|
\lineiii{?}{return the first lock conflicting with the requested lock, or
|
|
|
|
\code{None} if there is no conflict.}{(1)}
|
1994-05-19 06:09:50 -03:00
|
|
|
\end{tableiii}
|
|
|
|
|
|
|
|
Note:
|
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
(1) The lock returned is in the format \code{(\var{mode}, \var{len},
|
|
|
|
\var{start}, \var{whence}, \var{pid})} where \var{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.
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
Format characters for the \method{flags()} method have the following
|
|
|
|
meanings:
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1997-12-23 00:21:20 -04:00
|
|
|
\begin{tableii}{|c|l|}{samp}{Format}{Meaning}
|
|
|
|
\lineii{a}{append only flag}
|
|
|
|
\lineii{c}{close on exec flag}
|
|
|
|
\lineii{n}{no delay flag (also called non-blocking flag)}
|
|
|
|
\lineii{s}{synchronization flag}
|
|
|
|
\end{tableii}
|
1994-05-19 06:09:50 -03:00
|
|
|
|
|
|
|
In addition the following modifiers can be added to the format:
|
|
|
|
|
|
|
|
\begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes}
|
|
|
|
\lineiii{!}{turn the specified flags 'off', instead of the default 'on'}{(1)}
|
|
|
|
\lineiii{=}{replace the flags, instead of the default 'OR' operation}{(1)}
|
|
|
|
\lineiii{?}{return a string in which the characters represent the flags that
|
|
|
|
are set.}{(2)}
|
|
|
|
\end{tableiii}
|
|
|
|
|
|
|
|
Note:
|
|
|
|
|
1998-04-07 16:17:27 -03:00
|
|
|
(1) The \samp{!} and \samp{=} modifiers are mutually exclusive.
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1994-08-08 09:30:22 -03:00
|
|
|
(2) This string represents the flags after they may have been altered
|
1994-05-19 06:09:50 -03:00
|
|
|
by the same call.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
1998-02-13 02:58:54 -04:00
|
|
|
\begin{verbatim}
|
1998-03-11 02:11:37 -04:00
|
|
|
import posixfile
|
1994-05-19 06:09:50 -03:00
|
|
|
|
1998-03-11 02:11:37 -04:00
|
|
|
file = posixfile.open('/tmp/test', 'w')
|
1994-05-19 06:09:50 -03:00
|
|
|
file.lock('w|')
|
|
|
|
...
|
|
|
|
file.lock('u')
|
|
|
|
file.close()
|
1998-02-13 02:58:54 -04:00
|
|
|
\end{verbatim}
|