Doc/lib/libposixfile.tex

   1 % Manual text and implementation by Jaap Vermeulen
   2 \section{\module{posixfile} ---
   3          File-like objects with locking support}
   4
   5 \declaremodule{builtin}{posixfile}
   6   \platform{Unix}
   7 \modulesynopsis{A file-like object with support for locking.}
   8 \moduleauthor{Jaap Vermeulen}{}
   9 \sectionauthor{Jaap Vermeulen}{}
  10
  11
  12 \indexii{\POSIX}{file object}
  13
  14 \deprecated{1.5}{The locking operation that this module provides is
  15 done better and more portably by the
  16 \function{\refmodule{fcntl}.lockf()} call.
  17 \withsubitem{(in module fcntl)}{\ttindex{lockf()}}}
  18
  19 This module implements some additional functionality over the built-in
  20 file objects.  In particular, it implements file locking, control over
  21 the file flags, and an easy interface to duplicate the file object.
  22 The module defines a new file object, the posixfile object.  It
  23 has all the standard file object methods and adds the methods
  24 described below.  This module only works for certain flavors of
  25 \UNIX, since it uses \function{fcntl.fcntl()} for file locking.%
  26 \withsubitem{(in module fcntl)}{\ttindex{fcntl()}}
  27
  28 To instantiate a posixfile object, use the \function{open()} function
  29 in the \module{posixfile} module.  The resulting object looks and
  30 feels roughly the same as a standard file object.
  31
  32 The \module{posixfile} module defines the following constants:
  33
  34
  35 \begin{datadesc}{SEEK_SET}
  36 Offset is calculated from the start of the file.
  37 \end{datadesc}
  38
  39 \begin{datadesc}{SEEK_CUR}
  40 Offset is calculated from the current position in the file.
  41 \end{datadesc}
  42
  43 \begin{datadesc}{SEEK_END}
  44 Offset is calculated from the end of the file.
  45 \end{datadesc}
  46
  47 The \module{posixfile} module defines the following functions:
  48
  49
  50 \begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
  51  Create a new posixfile object with the given filename and mode.  The
  52  \var{filename}, \var{mode} and \var{bufsize} arguments are
  53  interpreted the same way as by the built-in \function{open()}
  54  function.
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{fileopen}{fileobject}
  58  Create a new posixfile object with the given standard file object.
  59  The resulting object has the same filename and mode as the original
  60  file object.
  61 \end{funcdesc}
  62
  63 The posixfile object defines the following additional methods:
  64
  65 \setindexsubitem{(posixfile method)}
  66 \begin{funcdesc}{lock}{fmt, \optional{len\optional{, start\optional{, whence}}}}
  67  Lock the specified section of the file that the file object is
  68  referring to.  The format is explained
  69  below in a table.  The \var{len} argument specifies the length of the
  70  section that should be locked. The default is \code{0}. \var{start}
  71  specifies the starting offset of the section, where the default is
  72  \code{0}.  The \var{whence} argument specifies where the offset is
  73  relative to. It accepts one of the constants \constant{SEEK_SET},
  74  \constant{SEEK_CUR} or \constant{SEEK_END}.  The default is
  75  \constant{SEEK_SET}.  For more information about the arguments refer
  76  to the \manpage{fcntl}{2} manual page on your system.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{flags}{\optional{flags}}
  80  Set the specified flags for the file that the file object is referring
  81  to.  The new flags are ORed with the old flags, unless specified
  82  otherwise.  The format is explained below in a table.  Without
  83  the \var{flags} argument
  84  a string indicating the current flags is returned (this is
  85  the same as the \samp{?} modifier).  For more information about the
  86  flags refer to the \manpage{fcntl}{2} manual page on your system.
  87 \end{funcdesc}
  88
  89 \begin{funcdesc}{dup}{}
  90  Duplicate the file object and the underlying file pointer and file
  91  descriptor.  The resulting object behaves as if it were newly
  92  opened.
  93 \end{funcdesc}
  94
  95 \begin{funcdesc}{dup2}{fd}
  96  Duplicate the file object and the underlying file pointer and file
  97  descriptor.  The new object will have the given file descriptor.
  98  Otherwise the resulting object behaves as if it were newly opened.
  99 \end{funcdesc}
 100
 101 \begin{funcdesc}{file}{}
 102  Return the standard file object that the posixfile object is based
 103  on.  This is sometimes necessary for functions that insist on a
 104  standard file object.
 105 \end{funcdesc}
 106
 107 All methods raise \exception{IOError} when the request fails.
 108
 109 Format characters for the \method{lock()} method have the following
 110 meaning:
 111
 112 \begin{tableii}{c|l}{samp}{Format}{Meaning}
 113   \lineii{u}{unlock the specified region}
 114   \lineii{r}{request a read lock for the specified section}
 115   \lineii{w}{request a write lock for the specified section}
 116 \end{tableii}
 117
 118 In addition the following modifiers can be added to the format:
 119
 120 \begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes}
 121   \lineiii{|}{wait until the lock has been granted}{}
 122   \lineiii{?}{return the first lock conflicting with the requested lock, or
 123               \code{None} if there is no conflict.}{(1)}
 124 \end{tableiii}
 125
 126 \noindent
 127 Note:
 128
 129 \begin{description}
 130 \item[(1)] The lock returned is in the format \code{(\var{mode}, \var{len},
 131 \var{start}, \var{whence}, \var{pid})} where \var{mode} is a character
 132 representing the type of lock ('r' or 'w').  This modifier prevents a
 133 request from being granted; it is for query purposes only.
 134 \end{description}
 135
 136 Format characters for the \method{flags()} method have the following
 137 meanings:
 138
 139 \begin{tableii}{c|l}{samp}{Format}{Meaning}
 140   \lineii{a}{append only flag}
 141   \lineii{c}{close on exec flag}
 142   \lineii{n}{no delay flag (also called non-blocking flag)}
 143   \lineii{s}{synchronization flag}
 144 \end{tableii}
 145
 146 In addition the following modifiers can be added to the format:
 147
 148 \begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes}
 149   \lineiii{!}{turn the specified flags 'off', instead of the default 'on'}{(1)}
 150   \lineiii{=}{replace the flags, instead of the default 'OR' operation}{(1)}
 151   \lineiii{?}{return a string in which the characters represent the flags that
 152   are set.}{(2)}
 153 \end{tableiii}
 154
 155 \noindent
 156 Notes:
 157
 158 \begin{description}
 159 \item[(1)] The \samp{!} and \samp{=} modifiers are mutually exclusive.
 160
 161 \item[(2)] This string represents the flags after they may have been altered
 162 by the same call.
 163 \end{description}
 164
 165 Examples:
 166
 167 \begin{verbatim}
 168 import posixfile
 169
 170 file = posixfile.open('/tmp/test', 'w')
 171 file.lock('w|')
 172 ...
 173 file.lock('u')
 174 file.close()
 175 \end{verbatim}