diff options
| -rw-r--r-- | Doc/lib/libfcntl.tex | 58 | ||||
| -rw-r--r-- | Doc/lib/libposixfile.tex | 154 | ||||
| -rw-r--r-- | Doc/libfcntl.tex | 58 | ||||
| -rw-r--r-- | Doc/libposixfile.tex | 154 |
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 |