Doc/libposixfile.tex

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