README: correct typo (lib.index)

lib.tex: include libfcntl, libposixfile
myformat.sty: add tableii environment
libfcntl.tex, libposixfile.tex: docs contributed by Jaap V

4 files changed, 424 insertions, 0 deletions

diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
new file mode 100644
index 0000000..dd5212b
--- /dev/null
+++ b/Doc/lib/libfcntl.tex
@@ -0,0 +1,58 @@
+% Manual text by Jaap Vermeulen
+\section{Built-in module \sectcode{fcntl}}
+\bimodindex{fcntl}
+\indexii{UNIX}{file control}
+\indexii{UNIX}{IO control}
+
+This module performs file control and IO control on file descriptors.
+It is an interface to the \dfn{fcntl()} and \dfn{ioctl()} \UNIX routines.
+File descriptors can be obtained with the \dfn{fileno()} method of a
+file or socket object.
+
+The module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module struct)}
+
+\begin{funcdesc}{fcntl}{fd\, op\, arg}
+  Perform the requested operation on file descriptor \code{\var{fd}}.
+  The operation is defined by \code{\var{op}} and is operating system
+  dependent.  Typically these codes can be retrieved from the library
+  module \code{FCNTL}. The argument \code{\var{arg}} is optional.  When
+  it is missing it is interpreted as the integer value \code{0}. When
+  it is present, it can either be an integer value, or a string.  With
+  the argument missing or an integer value, the return value of this
+  function is the integer return value of the real \code{fcntl()}
+  call.  When the argument is a string it represents a binary
+  structure, e.g.  created by \code{struct.pack()}. The binary data is
+  copied to a buffer whose address is passed to the real \code{fcntl()}
+  call.  The return value after a successful call is the contents of
+  the buffer, converted to a string object.  In the case the
+  \code{fcntl()} fails, an \code{IOError} will be raised.
+\end{funcdesc}
+
+\begin{funcdesc}{ioctl}{fd\, op\, arg}
+  This function is identical to the \code{fcntl()} function, except
+  that the operations are typically defined in the library module
+  \code{IOCTL}.
+\end{funcdesc}
+
+If the library modules \code{FCNTL} or \code{IOCTL} are missing, you
+can find the opcodes in the C include files \code{sys/fcntl} and
+\code{sys/ioctl}. You can create the modules yourself with the h2py
+script, found in the \code{Demo/scripts} directory.
+
+Examples (all on a SVR4 compliant system):
+
+\bcode\begin{verbatim}
+import struct, FCNTL
+
+file = open(...)
+rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)
+
+lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
+rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
+\end{verbatim}\ecode
+
+Note that in the first example the return value variable \code{rv} will
+hold an integer value; in the second example it will hold a string
+value.
diff --git a/Doc/lib/libposixfile.tex b/Doc/lib/libposixfile.tex
new file mode 100644
index 0000000..673ed6f
--- /dev/null
+++ b/Doc/lib/libposixfile.tex
@@ -0,0 +1,154 @@
+% Manual text and implementation by Jaap Vermeulen
+\section{Standard Module \sectcode{posixfile}}
+\bimodindex{posixfile}
+\indexii{posix}{file object}
+
+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
+inherits all the standard file object methods and adds the methods
+described below.
+
+To instantiate a posixfile object, use the \code{open()} function in
+the posixfile module.  The resulting object looks and feels the same as
+a standard file object.
+
+The posixfile module defines the following constants:
+
+\renewcommand{\indexsubitem}{(in module posixfile)}
+\begin{datadesc}{SEEK_SET}
+offset is calculated from the start of the file
+\end{datadesc}
+
+\begin{datadesc}{SEEK_CUR}
+offset is calculated from the current position in the file
+\end{datadesc}
+
+\begin{datadesc}{SEEK_END}
+offset is calculated from the end of the file
+\end{datadesc}
+
+The posixfile module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module posixfile)}
+\begin{funcdesc}{open}{filename\, mode}
+ Create a new posixfile object with the given filename and mode.  The
+ filename and mode are interpreted the same way as the \code{open()}
+ builtin function.
+\end{funcdesc}
+
+\begin{funcdesc}{openfile}{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.
+\end{funcdesc}
+
+The posixfile object defines the following additional methods:
+
+\renewcommand{\indexsubitem}{(posixfile method)}
+\begin{funcdesc}{lock}{fmt\, len\, start\, whence}
+ Lock the specified section of the file that the file object is
+ referring to.  The arguments \code{\var{len}}, \code{\var{start}}
+ and \code{\var{whence}} are optional with the understanding that
+ if \code{\var{start}} is used \code{\var{len}} becomes mandatory,
+ and if \code{\var{whence}} is used \code{\var{len}} and
+ \code{\var{start}} become mandatory.  The format is explained
+ below in a table. The length argument specifies the length of the
+ section that should be locked. The default is \code{0}. The start
+ specifies the starting offset of the section. The default is
+ \code{0}.  The whence argument specifies where the offset is
+ relative to. It accepts one of the constants \code{SEEK_SET},
+ \code{SEEK_CUR} or \code{SEEK_END}.  The default is \code{SEEK_SET}.
+ For more information about the arguments refer to the fcntl
+ manual page on your system.
+\end{funcdesc}
+
+\begin{funcdesc}{flags}{fmt}
+ 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
+ arguments a string indicating the current flags is returned (this is
+ the same as the '?'modifier).  For more information about the flags
+ refer to the fcntl manual page on your system.
+\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}
+
+All methods return \code{IOError} when the request fails.
+
+Format characters for the \code{lock()} method have the following meaning:
+
+\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}
+
+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}{}
+  \lineiii{?}{return the first lock conflicting with the requested lock,
+  or \code{None} if there is no conflict.}{(1)}
+\end{tableiii}
+
+Note:
+
+(1) The lock returned is in the format \code{(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 character for the \code{flags()} method have the following meaning:
+
+\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}
+
+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:
+
+(1) The \code{!} and \code{=} modifiers are mutually exclusive.
+
+(2) This string represents the flag after they may have been altered
+by the same call.
+
+Examples:
+
+\bcode\begin{verbatim}
+from posixfile import *
+
+file = open('/tmp/test', 'w')
+file.lock('w|')
+...
+file.lock('u')
+file.close()
+\end{verbatim}\ecode
diff --git a/Doc/libfcntl.tex b/Doc/libfcntl.tex
new file mode 100644
index 0000000..dd5212b
--- /dev/null
+++ b/Doc/libfcntl.tex
@@ -0,0 +1,58 @@
+% Manual text by Jaap Vermeulen
+\section{Built-in module \sectcode{fcntl}}
+\bimodindex{fcntl}
+\indexii{UNIX}{file control}
+\indexii{UNIX}{IO control}
+
+This module performs file control and IO control on file descriptors.
+It is an interface to the \dfn{fcntl()} and \dfn{ioctl()} \UNIX routines.
+File descriptors can be obtained with the \dfn{fileno()} method of a
+file or socket object.
+
+The module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module struct)}
+
+\begin{funcdesc}{fcntl}{fd\, op\, arg}
+  Perform the requested operation on file descriptor \code{\var{fd}}.
+  The operation is defined by \code{\var{op}} and is operating system
+  dependent.  Typically these codes can be retrieved from the library
+  module \code{FCNTL}. The argument \code{\var{arg}} is optional.  When
+  it is missing it is interpreted as the integer value \code{0}. When
+  it is present, it can either be an integer value, or a string.  With
+  the argument missing or an integer value, the return value of this
+  function is the integer return value of the real \code{fcntl()}
+  call.  When the argument is a string it represents a binary
+  structure, e.g.  created by \code{struct.pack()}. The binary data is
+  copied to a buffer whose address is passed to the real \code{fcntl()}
+  call.  The return value after a successful call is the contents of
+  the buffer, converted to a string object.  In the case the
+  \code{fcntl()} fails, an \code{IOError} will be raised.
+\end{funcdesc}
+
+\begin{funcdesc}{ioctl}{fd\, op\, arg}
+  This function is identical to the \code{fcntl()} function, except
+  that the operations are typically defined in the library module
+  \code{IOCTL}.
+\end{funcdesc}
+
+If the library modules \code{FCNTL} or \code{IOCTL} are missing, you
+can find the opcodes in the C include files \code{sys/fcntl} and
+\code{sys/ioctl}. You can create the modules yourself with the h2py
+script, found in the \code{Demo/scripts} directory.
+
+Examples (all on a SVR4 compliant system):
+
+\bcode\begin{verbatim}
+import struct, FCNTL
+
+file = open(...)
+rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)
+
+lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
+rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
+\end{verbatim}\ecode
+
+Note that in the first example the return value variable \code{rv} will
+hold an integer value; in the second example it will hold a string
+value.
diff --git a/Doc/libposixfile.tex b/Doc/libposixfile.tex
new file mode 100644
index 0000000..673ed6f
--- /dev/null
+++ b/Doc/libposixfile.tex
@@ -0,0 +1,154 @@
+% Manual text and implementation by Jaap Vermeulen
+\section{Standard Module \sectcode{posixfile}}
+\bimodindex{posixfile}
+\indexii{posix}{file object}
+
+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
+inherits all the standard file object methods and adds the methods
+described below.
+
+To instantiate a posixfile object, use the \code{open()} function in
+the posixfile module.  The resulting object looks and feels the same as
+a standard file object.
+
+The posixfile module defines the following constants:
+
+\renewcommand{\indexsubitem}{(in module posixfile)}
+\begin{datadesc}{SEEK_SET}
+offset is calculated from the start of the file
+\end{datadesc}
+
+\begin{datadesc}{SEEK_CUR}
+offset is calculated from the current position in the file
+\end{datadesc}
+
+\begin{datadesc}{SEEK_END}
+offset is calculated from the end of the file
+\end{datadesc}
+
+The posixfile module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module posixfile)}
+\begin{funcdesc}{open}{filename\, mode}
+ Create a new posixfile object with the given filename and mode.  The
+ filename and mode are interpreted the same way as the \code{open()}
+ builtin function.
+\end{funcdesc}
+
+\begin{funcdesc}{openfile}{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.
+\end{funcdesc}
+
+The posixfile object defines the following additional methods:
+
+\renewcommand{\indexsubitem}{(posixfile method)}
+\begin{funcdesc}{lock}{fmt\, len\, start\, whence}
+ Lock the specified section of the file that the file object is
+ referring to.  The arguments \code{\var{len}}, \code{\var{start}}
+ and \code{\var{whence}} are optional with the understanding that
+ if \code{\var{start}} is used \code{\var{len}} becomes mandatory,
+ and if \code{\var{whence}} is used \code{\var{len}} and
+ \code{\var{start}} become mandatory.  The format is explained
+ below in a table. The length argument specifies the length of the
+ section that should be locked. The default is \code{0}. The start
+ specifies the starting offset of the section. The default is
+ \code{0}.  The whence argument specifies where the offset is
+ relative to. It accepts one of the constants \code{SEEK_SET},
+ \code{SEEK_CUR} or \code{SEEK_END}.  The default is \code{SEEK_SET}.
+ For more information about the arguments refer to the fcntl
+ manual page on your system.
+\end{funcdesc}
+
+\begin{funcdesc}{flags}{fmt}
+ 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
+ arguments a string indicating the current flags is returned (this is
+ the same as the '?'modifier).  For more information about the flags
+ refer to the fcntl manual page on your system.
+\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}
+
+All methods return \code{IOError} when the request fails.
+
+Format characters for the \code{lock()} method have the following meaning:
+
+\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}
+
+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}{}
+  \lineiii{?}{return the first lock conflicting with the requested lock,
+  or \code{None} if there is no conflict.}{(1)}
+\end{tableiii}
+
+Note:
+
+(1) The lock returned is in the format \code{(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 character for the \code{flags()} method have the following meaning:
+
+\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}
+
+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:
+
+(1) The \code{!} and \code{=} modifiers are mutually exclusive.
+
+(2) This string represents the flag after they may have been altered
+by the same call.
+
+Examples:
+
+\bcode\begin{verbatim}
+from posixfile import *
+
+file = open('/tmp/test', 'w')
+file.lock('w|')
+...
+file.lock('u')
+file.close()
+\end{verbatim}\ecode