README: correct typo (lib.index)
lib.tex: include libfcntl, libposixfile myformat.sty: add tableii environment libfcntl.tex, libposixfile.tex: docs contributed by Jaap V
This commit is contained in:
Guido van Rossum
parent
c762becaf5
commit
7f61b3511c
|
|
@ -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.
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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
|
||||||
Loading…
Reference in New Issue