% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage[pdftex=true,
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        pdfcreator={LaTeX with hyperref package / GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\F}{\mathbb{F}}

\newcommand{\GAP}{\textsf{GAP}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{GAP 4 Package \textsf{IO}\mbox{}}}\\[1cm]
\hypersetup{pdftitle=GAP 4 Package \textsf{IO}}
\markright{\scriptsize \mbox{}\hfill GAP 4 Package \textsf{IO} \hfill\mbox{}}
{\Large \textbf{Bindings for low level C library I/O routines\mbox{}}}\\[1cm]
{ Version 2.3 \mbox{}}\\[1cm]
{October 2007\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Max Neunh{\"o}ffer    \mbox{}}}\\
\hypersetup{pdfauthor=Max Neunh{\"o}ffer    }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Max Neunh{\"o}ffer    } --- Email: \href{mailto://neunhoef@mcs.st-and.ac.uk} {\texttt{neunhoef@mcs.st-and.ac.uk}}\\
 --- Homepage: \href{http://www-groups.mcs.st-and.ac.uk/~neunhoef} {\texttt{http://www-groups.mcs.st-and.ac.uk/\texttt{\symbol{126}}neunhoef}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 School of Mathematics and Statistics Mathematical Institute University of St
Andrews North Haugh St Andrews, Fife KY16 9SS Scotland, UK \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2005-2007 by Max Neunh{\"o}ffer

 This package may be distributed under the terms and conditions of the GNU
Public License Version 2 or later. \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}}

\tableofcontents
\newpage

  
\chapter{\textcolor{Chapter }{Preface}}\label{Chap-Preface}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X874E1D45845007FE}{}
{
  \index{\textsf{IO}} The purpose of this package is to allow efficient and flexible input/output
operations from \textsf{GAP}. This is achieved by providing bindings to the low-level I/O functions in the
C-library. On top of this an implementation of buffered I/O in the \textsf{GAP} language is provided. Further, a framework for serialisation of arbitrary \textsf{GAP} objects is implemented. Finally, an implementation of the client side of the
HTTP protocol is included in the package.

 This package allows to use file based I/O, access to links and file systems,
pipes, sockets, and the UDP and TCP/IP protocols.

 By default the \textsf{IO} package is not automatically loaded by \textsf{GAP} when it is installed. You must load the package with \texttt{LoadPackage("IO");} before its functions become available.

 Please, send me an e-mail (\href{mailto://neunhoef@mcs.st-and.ac.uk} {\texttt{neunhoef@mcs.st-and.ac.uk}}) if you have any questions, remarks, suggestions, etc. concerning this
package. Also, I would like to hear about applications of this package.

 Max Neunh{\"o}ffer }

 
\chapter{\textcolor{Chapter }{Installation of the \textsf{IO}-package}}\label{Chap-Install}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X8203E34B178787118}{}
{
  To get the newest version of this \textsf{GAP} 4 package download one of the archive files 
\begin{itemize}
\item  \texttt{io-x.x.tar.gz} 
\item  \texttt{io-x.x.zoo} 
\item  \texttt{io-x.x.tar.bz2} 
\item  \texttt{io-x.x.zip} 
\end{itemize}
 and unpack it using 
\begin{verbatim}  
      gunzip io-x.x.tar.gz; tar xvf io-x.x.tar
\end{verbatim}
 respectively 
\begin{verbatim}  
      unzoo -x io-x.x.zoo
\end{verbatim}
 and so on. 

 Do this in a directory called ``\texttt{pkg}'', preferably (but not necessarily) in the ``\texttt{pkg}'' subdirectory of your \textsf{GAP} 4 installation. It creates a subdirectory called ``\texttt{io}''.

 To install this package do 
\begin{verbatim}  
      cd io
      ./configure [path]
\end{verbatim}
 where ``path'' is a path to the main \textsf{GAP} root directory (if not given the default ``\texttt{../..}'' is assumed).

 Afterwards call ``\texttt{make}'' to compile a binary file.

 If you installed \textsf{GAP} on several architectures, you must execute this configure/make step on each of
the architectures immediately after configuring \textsf{GAP} itself on this architecture.

 The package will not work without this step.

 If you installed the package in another ``\texttt{pkg}'' directory than the standard ``\texttt{pkg}'' directory in your \textsf{GAP} 4 installation, then you have to add the path to the directory containing your ``\texttt{pkg}'' directory to \textsf{GAP}'s list of directories. This can be done by starting \textsf{GAP} with the ``\texttt{-l}'' command line option followed by the name of the directory and a semicolon.
Then your directory is prepended to the list of directories searched.
Otherwise the package is not found by \textsf{GAP}. Of course, you can add this option to your \textsf{GAP} startup script. 
\section{\textcolor{Chapter }{Static linking}}\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X17F7AFC7E808A56C7}{}
{
  This might be interesting for M\$ Windows users, as dynamic loading of binary
modules does not work there.

 You can also create a new statically linked ``\texttt{gap}'' binary as follows: Go into the main \textsf{GAP} directory and then into \texttt{bin/BINDIR}. Here \texttt{BINDIR} means the directory containing the ``\texttt{gap}'' executable after compiling ``\texttt{gap}''. This directory also contains the \textsf{GAP} compiler script ``\texttt{gac}''. Assuming IO in the standard location you can then say 
\begin{verbatim}  
     ./gac -o gap-static -p "-DIOSTATIC" -P "-static" ../../pkg/io/src/io.c
\end{verbatim}
 Then copy your ``\texttt{gap}'' start script to, say, ``\texttt{gapbig}'' and change the references to the \textsf{GAP} binary to ``\texttt{gap-static}''.

 If you want to install more than one package with a C-part like this package,
you can still create a statically linked \textsf{GAP} executable by combining all the compile and link options and all the .c files
as in the ./gac command above. For the IO package, you have to add 
\begin{verbatim}  
    -DIOSTATIC
\end{verbatim}
 to the string of the -p option and the file 
\begin{verbatim}  
    ../../pkg/io/src/io.c
\end{verbatim}
 somewhere on the command line. }

 
\section{\textcolor{Chapter }{Recompiling the documentation}}\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X17FB00ED21787027A3}{}
{
  Recompiling the documentation is possible by the command ``\texttt{gap makedoc.g}'' in the \texttt{io} directory. But this should not be necessary. }

 }

  
\chapter{\textcolor{Chapter }{Functions directly available from the C library}}\label{Chap-CLibFuncs}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X85DE7F82801DDA50}{}
{
  The following functions from the C library are made available as \textsf{GAP} functions: 

 \texttt{accept}, \texttt{bind}, \texttt{chdir}, \texttt{chmod}, \texttt{chown}, \texttt{close}, \texttt{closedir}, \texttt{connect}, \texttt{creat}, \texttt{dup}, \texttt{dup2}, \texttt{execv}, \texttt{execve}, \texttt{execvp}, \texttt{exit}, \texttt{fchmod}, \texttt{fchown}, \texttt{fcntl}, \texttt{fork}, \texttt{fstat}, \texttt{gethostbyname}, \texttt{getpid}, \texttt{getppid}, \texttt{getsockopt}, \texttt{kill}, \texttt{lchown}, \texttt{link}, \texttt{listen}, \texttt{lseek}, \texttt{lstat}, \texttt{mkdir}, \texttt{mkfifo}, \texttt{mknod}, \texttt{open}, \texttt{opendir}, \texttt{pipe}, \texttt{read}, \texttt{readdir}, \texttt{readlink}, \texttt{recv}, \texttt{recvfrom}, \texttt{rename}, \texttt{rewinddir}, \texttt{rmdir}, \texttt{seekdir}, \texttt{select}, \texttt{send}, \texttt{sendto}, \texttt{setsockopt}, \texttt{socket}, \texttt{stat}, \texttt{symlink}, \texttt{telldir}, \texttt{unlink}, \texttt{write}. 

 Use the \texttt{man} command in your shell to get information about these functions.

 For each of these functions there is a corresponding \textsf{GAP} global function with the prefix \texttt{IO{\textunderscore}} before its name. Apart from minor differences (see below) they take exactly
the same arguments as their C counterparts. Strings must be specified as \textsf{GAP} strings and integers as \textsf{GAP} immediate integers. Return values are in general the same as for the C
counterparts. However, an error condition is indicated by the value \texttt{fail} instead of -1, and if the result can only be success or failure, \texttt{true} indicates success. 

 All errors are reported via the \texttt{LastSystemError} (\textbf{Reference: LastSystemError}) function.

 In the C library a lot of integers are defined as macros in header files. All
the necessary values for the above functions are bound to their name in the
global \texttt{IO} record. 

 \emph{Warning:} Existence of many of these functions and constants is platform dependent. The
compilation process checks existence and this leads to the situation that on
the \textsf{GAP} levels the functions and constants are there or not. If you want to develop
platform independent \textsf{GAP} code using this package, then you have to check for existence of the functions
and constants you need. 
\section{\textcolor{Chapter }{Differences in arguments - an overview}}\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X85D35513179BA32FC}{}
{
  The \texttt{open} function has to be called with three arguments. The version with two arguments
is not available on the \textsf{GAP} level. 

 The \texttt{read} function takes four arguments: \mbox{\texttt{\slshape fd}} is an integer file descriptor, \mbox{\texttt{\slshape st}} is a \textsf{GAP} string, \mbox{\texttt{\slshape offset}} is an offset within this string (zero based), and \mbox{\texttt{\slshape count}} is the maximal number of bytes to read. The data is read and stored into the
string \mbox{\texttt{\slshape st}}, starting at position $\mbox{\texttt{\slshape offset}}+1$. The string \mbox{\texttt{\slshape st}} is made long enough, such that \mbox{\texttt{\slshape count}} bytes would fit into it, beginning at position $\mbox{\texttt{\slshape offset}}+1$. The number of bytes read is returned or \texttt{fail} in case of an error. 

 The \texttt{write} function is similar, it also takes four arguments: \mbox{\texttt{\slshape fd}} is an integer file descriptor, \mbox{\texttt{\slshape st}} is a \textsf{GAP} string, \mbox{\texttt{\slshape offset}} is an offset within this string (zero based), and \mbox{\texttt{\slshape count}} is the number of bytes to write, starting from position $\mbox{\texttt{\slshape offset}}+1$ in the string \mbox{\texttt{\slshape st}}. The number of bytes written is returned, or a \texttt{fail} in case of an error. 

 The \texttt{opendir} function only returns \texttt{true} or \texttt{fail}. 

 The \texttt{readdir} function takes no argument. It reads the directory that was specified in the
last call to \texttt{opendir}. It just returns a string, which is the name of a file or subdirectory in the
corresponding directory. It returns \texttt{false} after the last file name in the directory or \texttt{fail} in case of an error. 

 The \texttt{closedir} function takes no argument. It should be called after \texttt{readdir} returned \texttt{false} or \texttt{fail} to avoid excessive use of file descriptors. 

 The functions \texttt{stat}, \texttt{fstat}, and \texttt{lstat} only take one argument and return a \textsf{GAP} record that has the same entries as a \texttt{struct stat}.

 The function \texttt{socket} can optionally take a string as third argument. In that case it automatically
calls \texttt{getprotobyname} to look up the protocol name.

 The functions \texttt{bind} and \texttt{connect} take only one string argument as address field, because the string already
encodes the length.

 There are two convenience functions \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOmakesockaddrin}) and \texttt{IO{\textunderscore}MakeIPAddressPort} (\ref{IOMakeIPAddressPort}) to create such addresses. The first takes two arguments \mbox{\texttt{\slshape addr}} and \mbox{\texttt{\slshape port}}, where \mbox{\texttt{\slshape addr}} is a string of length 4, containing the 4 bytes of the IP address and \mbox{\texttt{\slshape port}} is a port number as \textsf{GAP} integer. The function \texttt{IO{\textunderscore}MakeIPAddressPort} (\ref{IOMakeIPAddressPort}) takes the same arguments, but the first can be a string containing an IP
address in dot notation like ``137.226.152.77''.

 The \texttt{setsockopt} function has no argument \mbox{\texttt{\slshape optlen}}. The length of the string \mbox{\texttt{\slshape optval}} is taken.

 The \texttt{select} function works as the function \texttt{UNIXSelect} in the \textsf{GAP} library.

 As of now, the file locking mechanisms of \texttt{fcntl} using \texttt{struct flock} are not yet implemented on the \textsf{GAP} level. }

 
\section{\textcolor{Chapter }{The low-level functions in detail}}\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X800F9F3E810A7228}{}
{
  Nearly all of this functions return an integer result in the C library. On the \textsf{GAP} level this is either returned as a non-negative integer in case of success or
as \texttt{fail} in case of an error (where on the C level $-1$ would be returned). If the integer can only be $0$ for ``no error'' this is changed to \texttt{true} on the \textsf{GAP} level. 

\subsection{\textcolor{Chapter }{IO{\textunderscore}accept}}
\logpage{[ 3, 2, 1 ]}\nobreak
\hyperdef{L}{X17E474E9787012FE4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}accept({\slshape fd, addr})\index{IOaccept@\texttt{IO{\textunderscore}accept}}
\label{IOaccept}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Accepts an incoming network connection. For details see ``\texttt{man 2 accept}''. The argument \mbox{\texttt{\slshape addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOmakesockaddrin}) and contains its length such that no third argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}bind}}
\logpage{[ 3, 2, 2 ]}\nobreak
\hyperdef{L}{X1791A6341852001F8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}bind({\slshape fd, my{\textunderscore}addr})\index{IObind@\texttt{IO{\textunderscore}bind}}
\label{IObind}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Binds a local address to a socket. For details see ``\texttt{man 2 bind}''. The argument \mbox{\texttt{\slshape my{\textunderscore}addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOmakesockaddrin}) and contains its length such that no third argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}chdir}}
\logpage{[ 3, 2, 3 ]}\nobreak
\hyperdef{L}{X1790139B317E87FA61}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}chdir({\slshape path})\index{IOchdir@\texttt{IO{\textunderscore}chdir}}
\label{IOchdir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Changes the current working directory. For details see ``\texttt{man 2 chdir}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}chmod}}
\logpage{[ 3, 2, 4 ]}\nobreak
\hyperdef{L}{X83D4CB2681674FA4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}chmod({\slshape pathname, mode})\index{IOchmod@\texttt{IO{\textunderscore}chmod}}
\label{IOchmod}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Changes the mode of a file. For details see ``\texttt{man 2 chmod}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}chown}}
\logpage{[ 3, 2, 5 ]}\nobreak
\hyperdef{L}{X85C06174179E4D952}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}chown({\slshape path, owner, group})\index{IOchown@\texttt{IO{\textunderscore}chown}}
\label{IOchown}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Sets owner and/or group of file. For details see ``\texttt{man 2 chown}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}close}}
\logpage{[ 3, 2, 6 ]}\nobreak
\hyperdef{L}{X820DA9C917C2E80BA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}close({\slshape fd})\index{IOclose@\texttt{IO{\textunderscore}close}}
\label{IOclose}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Closes a file descriptor. For details see ``\texttt{man 2 close}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}closedir}}
\logpage{[ 3, 2, 7 ]}\nobreak
\hyperdef{L}{X8078699B84F082A4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}closedir({\slshape })\index{IOclosedir@\texttt{IO{\textunderscore}closedir}}
\label{IOclosedir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Closes a directory. For details see ``\texttt{man 3 closedir}''. Has no arguments, because we only have one \texttt{DIR} struct in the C part. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}connect}}
\logpage{[ 3, 2, 8 ]}\nobreak
\hyperdef{L}{X17DE9D8B387D3A3D5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}connect({\slshape fd, serv{\textunderscore}addr})\index{IOconnect@\texttt{IO{\textunderscore}connect}}
\label{IOconnect}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Connects to a remote socket. For details see ``\texttt{man 2 connect}''. The argument \mbox{\texttt{\slshape serv{\textunderscore}addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOmakesockaddrin}) and contains its length such that no third argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}creat}}
\logpage{[ 3, 2, 9 ]}\nobreak
\hyperdef{L}{X178FCF69C17FCF3BD7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}creat({\slshape pathname, mode})\index{IOcreat@\texttt{IO{\textunderscore}creat}}
\label{IOcreat}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Creates a new file. For details see ``\texttt{man 2 creat}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}dup}}
\logpage{[ 3, 2, 10 ]}\nobreak
\hyperdef{L}{X17DAAD93A80F76681}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}dup({\slshape oldfd})\index{IOdup@\texttt{IO{\textunderscore}dup}}
\label{IOdup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Duplicates a file descriptor. For details see ``\texttt{man 2 dup}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}dup2}}
\logpage{[ 3, 2, 11 ]}\nobreak
\hyperdef{L}{X17F7B8FAC17ABA285B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}dup2({\slshape oldfd, newfd})\index{IOdup2@\texttt{IO{\textunderscore}dup2}}
\label{IOdup2}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Duplicates a file descriptor to a new one. For details see ``\texttt{man 2 dup2}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}execv}}
\logpage{[ 3, 2, 12 ]}\nobreak
\hyperdef{L}{X17B30A7FA84692EC5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}execv({\slshape path, argv})\index{IOexecv@\texttt{IO{\textunderscore}execv}}
\label{IOexecv}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{fail} or does not return 



 Replaces the process with another process. For details see ``\texttt{man 3 execv}''. The argument \mbox{\texttt{\slshape argv}} is a list of strings. The called program does not have to be the first
argument in this list. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}execve}}
\logpage{[ 3, 2, 13 ]}\nobreak
\hyperdef{L}{X875D9A9E8201D461}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}execve({\slshape path, argv, envp})\index{IOexecve@\texttt{IO{\textunderscore}execve}}
\label{IOexecve}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{fail} or does not return 



 Replaces the process with another process. For details see ``\texttt{man 3 execve}''. The arguments \mbox{\texttt{\slshape argv}} and \mbox{\texttt{\slshape envp}} are both lists of strings. The called program does not have to be the first
argument in \mbox{\texttt{\slshape argv}}. The list \mbox{\texttt{\slshape envp}} can be made with \texttt{IO{\textunderscore}MakeEnvList} (\ref{IOMakeEnvList}) from a record acquired from \texttt{IO{\textunderscore}Environment} (\ref{IOEnvironment}) and modified later. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}execvp}}
\logpage{[ 3, 2, 14 ]}\nobreak
\hyperdef{L}{X818044D017C64A412}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}execvp({\slshape path, argv})\index{IOexecvp@\texttt{IO{\textunderscore}execvp}}
\label{IOexecvp}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{fail} or does not return 



 Replaces the process with another process. For details see ``\texttt{man 3 execvp}''. The argument \mbox{\texttt{\slshape argv}} is a list of strings. The called program does not have to be the first
argument in this list. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}exit}}
\logpage{[ 3, 2, 15 ]}\nobreak
\hyperdef{L}{X8436343417E88C357}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}exit({\slshape status})\index{IOexit@\texttt{IO{\textunderscore}exit}}
\label{IOexit}
}\hfill{\scriptsize (function)}}\\


 Stops process immediately with return code \mbox{\texttt{\slshape status}}. For details see ``\texttt{man 2 exit}''. The argument \mbox{\texttt{\slshape status}} must be an integer. Does not return. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}fchmod}}
\logpage{[ 3, 2, 16 ]}\nobreak
\hyperdef{L}{X17F08E11817BDB619A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}fchmod({\slshape fd, mode})\index{IOfchmod@\texttt{IO{\textunderscore}fchmod}}
\label{IOfchmod}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Changes mode of an opened file. For details see ``\texttt{man 2 fchmod}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}fchown}}
\logpage{[ 3, 2, 17 ]}\nobreak
\hyperdef{L}{X1791C4B4A81059A88}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}fchown({\slshape fd, owner, group})\index{IOfchown@\texttt{IO{\textunderscore}fchown}}
\label{IOfchown}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Changes owner and/or group of an opened file. For details see ``\texttt{man 2 fchown}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}fcntl}}
\logpage{[ 3, 2, 18 ]}\nobreak
\hyperdef{L}{X17870647E866D29A4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}fcntl({\slshape fd, cmd, arg})\index{IOfcntl@\texttt{IO{\textunderscore}fcntl}}
\label{IOfcntl}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Does various things to control the behaviour of a file descriptor. For details
see ``\texttt{man 2 fcntl}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}fork}}
\logpage{[ 3, 2, 19 ]}\nobreak
\hyperdef{L}{X86C819F317D07ECF7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}fork({\slshape })\index{IOfork@\texttt{IO{\textunderscore}fork}}
\label{IOfork}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Forks off a child process, which is an identical copy. For details see ``\texttt{man 2 fork}''. Note that if you want to use the \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) function to wait or check for the termination of child processes, you have to
activate the SIGCHLD handler for this package beforehand by using the function \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler}). Note further that after that you cannot use the function \texttt{InputOutputLocalProcess} (\textbf{Reference: InputOutputLocalProcess}) any more, since its SIGCHLD handler does not work any more. To switch back to
that functionality use the function \texttt{IO{\textunderscore}RestoreSIGCHLDHandler} (\ref{IORestoreSIGCHLDHandler}). }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}fstat}}
\logpage{[ 3, 2, 20 ]}\nobreak
\hyperdef{L}{X17E27748983EC7B5C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}fstat({\slshape fd})\index{IOfstat@\texttt{IO{\textunderscore}fstat}}
\label{IOfstat}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Returns the file meta data for an opened file. For details see ``\texttt{man 2 fstat}''. A \textsf{GAP} record is returned with the same entries than a \texttt{struct stat}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}gethostbyname}}
\logpage{[ 3, 2, 21 ]}\nobreak
\hyperdef{L}{X17DD25BDC179EE65AD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}gethostbyname({\slshape name})\index{IOgethostbyname@\texttt{IO{\textunderscore}gethostbyname}}
\label{IOgethostbyname}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Return host information by name. For details see ``\texttt{man 3 gethostbyname}''. A \textsf{GAP} record is returned with all the relevant information about the host. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}getpid}}
\logpage{[ 3, 2, 22 ]}\nobreak
\hyperdef{L}{X17ECF948083E38BD0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}getpid({\slshape })\index{IOgetpid@\texttt{IO{\textunderscore}getpid}}
\label{IOgetpid}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer 



 Returns the process ID of the current process as an integer. For details see ``\texttt{man 2 getpid}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}getppid}}
\logpage{[ 3, 2, 23 ]}\nobreak
\hyperdef{L}{X17EC6ABAB17AB9F40F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}getppid({\slshape })\index{IOgetppid@\texttt{IO{\textunderscore}getppid}}
\label{IOgetppid}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer 



 Returns the process ID of the parent of the current process as an integer. For
details see ``\texttt{man 2 getppid}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}getsockopt}}
\logpage{[ 3, 2, 24 ]}\nobreak
\hyperdef{L}{X1790213D885BAB495}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}getsockopt({\slshape fd, level, optname, optval})\index{IOgetsockopt@\texttt{IO{\textunderscore}getsockopt}}
\label{IOgetsockopt}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Get a socket option. For details see ``\texttt{man 2 getsockopt}''. Note that the argument \mbox{\texttt{\slshape optval}} carries its length around, such that no 5th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}kill}}
\logpage{[ 3, 2, 25 ]}\nobreak
\hyperdef{L}{X17D0439128512FBF6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}kill({\slshape pid, sig})\index{IOkill@\texttt{IO{\textunderscore}kill}}
\label{IOkill}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Sends the signal \mbox{\texttt{\slshape sig}} to the process with process ID \mbox{\texttt{\slshape pid}}. For details see ``\texttt{man 2 kill}''. The signal numbers available can be found in the global \texttt{IO} record with names like \texttt{SIGTERM}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}lchown}}
\logpage{[ 3, 2, 26 ]}\nobreak
\hyperdef{L}{X8305F97C87FE448E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}lchown({\slshape path, owner, group})\index{IOlchown@\texttt{IO{\textunderscore}lchown}}
\label{IOlchown}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Changes owner and/or group of a file not following links. For details see ``\texttt{man 2 lchown}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}link}}
\logpage{[ 3, 2, 27 ]}\nobreak
\hyperdef{L}{X17E1C65EB84497185}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}link({\slshape oldpath, newpath})\index{IOlink@\texttt{IO{\textunderscore}link}}
\label{IOlink}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Create a hard link. For details see ``\texttt{man 2 link}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}listen}}
\logpage{[ 3, 2, 28 ]}\nobreak
\hyperdef{L}{X17957063B807025C7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}listen({\slshape fd, backlog})\index{IOlisten@\texttt{IO{\textunderscore}listen}}
\label{IOlisten}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Switch a socket to listening. For details see ``\texttt{man 2 listen}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}lseek}}
\logpage{[ 3, 2, 29 ]}\nobreak
\hyperdef{L}{X85C4751817C824830}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}lseek({\slshape fd, offset, whence})\index{IOlseek@\texttt{IO{\textunderscore}lseek}}
\label{IOlseek}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Seeks within an open file. For details see ``\texttt{man 2 lseek}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}lstat}}
\logpage{[ 3, 2, 30 ]}\nobreak
\hyperdef{L}{X17A8C75038517A55A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}lstat({\slshape name})\index{IOlstat@\texttt{IO{\textunderscore}lstat}}
\label{IOlstat}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Returns the file meta data for a file not following links. For details see ``\texttt{man 2 lstat}''. A \textsf{GAP} record is returned with the same entries than a \texttt{struct stat}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}mkdir}}
\logpage{[ 3, 2, 31 ]}\nobreak
\hyperdef{L}{X83D968AB84F00ABF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}mkdir({\slshape pathname, mode})\index{IOmkdir@\texttt{IO{\textunderscore}mkdir}}
\label{IOmkdir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Creates a directory. For details see ``\texttt{man 2 mkdir}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}mkfifo}}
\logpage{[ 3, 2, 32 ]}\nobreak
\hyperdef{L}{X80BFF17A8099815F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}mkfifo({\slshape pathname, mode})\index{IOmkfifo@\texttt{IO{\textunderscore}mkfifo}}
\label{IOmkfifo}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Creates a FIFO special file (a named pipe). For details see ``\texttt{man 3 mkfifo}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}mknod}}
\logpage{[ 3, 2, 33 ]}\nobreak
\hyperdef{L}{X17928F1DB8379F850}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}mknod({\slshape pathname, mode, dev})\index{IOmknod@\texttt{IO{\textunderscore}mknod}}
\label{IOmknod}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Create a special or ordinary file. For details see ``\texttt{man 2 mknod}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}open}}
\logpage{[ 3, 2, 34 ]}\nobreak
\hyperdef{L}{X8731A44E8032D9D2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}open({\slshape pathname, flags, mode})\index{IOopen@\texttt{IO{\textunderscore}open}}
\label{IOopen}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Open and possibly create a file or device. For details see ``\texttt{man 2 open}''. Only the variant with 3 arguments can be used. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}opendir}}
\logpage{[ 3, 2, 35 ]}\nobreak
\hyperdef{L}{X178E2347917EB01883}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}opendir({\slshape name})\index{IOopendir@\texttt{IO{\textunderscore}opendir}}
\label{IOopendir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Opens a directory. For details see ``\texttt{man 3 opendir}''. Note that only \texttt{true} is returned if everything is OK, since only one \texttt{DIR} struct is stored on the C level and thus only one directory can be open at any
time. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}pipe}}
\logpage{[ 3, 2, 36 ]}\nobreak
\hyperdef{L}{X17C8F0A44837BBE8C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}pipe({\slshape })\index{IOpipe@\texttt{IO{\textunderscore}pipe}}
\label{IOpipe}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Create a pair of file descriptors with a pipe between them. For details see ``\texttt{man 2 pipe}''. Note that no arguments are needed. The result is either \texttt{fail} in case of an error or a record with two components \texttt{toread} and \texttt{towrite} bound to the two filedescriptors for reading and writing respectively. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}read}}
\logpage{[ 3, 2, 37 ]}\nobreak
\hyperdef{L}{X84F3D862836BF17C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}read({\slshape fd, st, offset, count})\index{IOread@\texttt{IO{\textunderscore}read}}
\label{IOread}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Reads from file descriptor. For details see ``\texttt{man 2 read}''. Note that there is one more argument \mbox{\texttt{\slshape offset}} to specify at which position in the string \mbox{\texttt{\slshape st}} the read data should be stored. Note that \mbox{\texttt{\slshape offset}} zero means at the beginning of the string, which is position 1 in \textsf{GAP}. The number of bytes read or \texttt{fail} in case of an error is returned. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}readdir}}
\logpage{[ 3, 2, 38 ]}\nobreak
\hyperdef{L}{X8410C6F117DE9302D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}readdir({\slshape })\index{IOreaddir@\texttt{IO{\textunderscore}readdir}}
\label{IOreaddir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} or \texttt{false} 



 Reads from a directory. For details see ``\texttt{man 2 readdir}''. Note that no argument is required as we have only one \texttt{DIR} struct on the C level. If the directory is read completely \texttt{false} is returned, and otherwise a string. An error is indicated by \texttt{fail}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}readlink}}
\logpage{[ 3, 2, 39 ]}\nobreak
\hyperdef{L}{X17943F25E17EBA9A6B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}readlink({\slshape path, buf, bufsize})\index{IOreadlink@\texttt{IO{\textunderscore}readlink}}
\label{IOreadlink}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Reads the value of a symbolic link. For details see ``\texttt{man 2 readlink}''. \mbox{\texttt{\slshape buf}} is modified. The new length of \mbox{\texttt{\slshape buf}} is returned or \texttt{fail} in case of an error. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}recv}}
\logpage{[ 3, 2, 40 ]}\nobreak
\hyperdef{L}{X178EB295E178B363B2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}recv({\slshape fd, st, offset, len, flags})\index{IOrecv@\texttt{IO{\textunderscore}recv}}
\label{IOrecv}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Receives data from a socket. For details see ``\texttt{man 2 recv}''. Note the additional argument \mbox{\texttt{\slshape offset}} which plays the same role as for the \texttt{IO{\textunderscore}read} (\ref{IOread}) function. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}recvfrom}}
\logpage{[ 3, 2, 41 ]}\nobreak
\hyperdef{L}{X84C6178817EE02EB4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}recvfrom({\slshape fd, st, offset, len, flags, addr})\index{IOrecvfrom@\texttt{IO{\textunderscore}recvfrom}}
\label{IOrecvfrom}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Receives data from a socket with given address. For details see ``\texttt{man 2 recvfrom}''. Note the additional argument \mbox{\texttt{\slshape offset}} which plays the same role as for the \texttt{IO{\textunderscore}read} (\ref{IOread}) function. The argument \mbox{\texttt{\slshape addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOmakesockaddrin}) and contains its length such that no 7th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}rename}}
\logpage{[ 3, 2, 42 ]}\nobreak
\hyperdef{L}{X178EC950017A92AB69}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}rename({\slshape oldpath, newpath})\index{IOrename@\texttt{IO{\textunderscore}rename}}
\label{IOrename}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Renames a file or moves it. For details see ``\texttt{man 2 rename}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}rewinddir}}
\logpage{[ 3, 2, 43 ]}\nobreak
\hyperdef{L}{X17F86DBEB17876FBA5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}rewinddir({\slshape })\index{IOrewinddir@\texttt{IO{\textunderscore}rewinddir}}
\label{IOrewinddir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Rewinds a directory. For details see ``\texttt{man 2 rewinddir}''. Note that no argument is required as we have only one \texttt{DIR} struct on the C level. Returns \texttt{fail} only, if no prior \texttt{IO{\textunderscore}opendir} (\ref{IOopendir}) command has been called. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}rmdir}}
\logpage{[ 3, 2, 44 ]}\nobreak
\hyperdef{L}{X17FA4DD5317C83A199}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}rmdir({\slshape name})\index{IOrmdir@\texttt{IO{\textunderscore}rmdir}}
\label{IOrmdir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Removes an empty directory. For details see ``\texttt{man 2 rmdir}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}seekdir}}
\logpage{[ 3, 2, 45 ]}\nobreak
\hyperdef{L}{X84A98D2380BF6574}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}seekdir({\slshape offset})\index{IOseekdir@\texttt{IO{\textunderscore}seekdir}}
\label{IOseekdir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Sets the position of the next readdir call. For details see ``\texttt{man 3 seekdir}''. Note that no second argument is required as we have only one \texttt{DIR} struct on the C level. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}select}}
\logpage{[ 3, 2, 46 ]}\nobreak
\hyperdef{L}{X81CA6EE88062010E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}select({\slshape inlist, outlist, exclist, timeoutsec, timeoutusec})\index{IOselect@\texttt{IO{\textunderscore}select}}
\label{IOselect}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Used for I/O multiplexing. For details see ``\texttt{man 2 select}''. \mbox{\texttt{\slshape inlist}}, \mbox{\texttt{\slshape outlist}} and \mbox{\texttt{\slshape exclist}} are lists of filedescriptors, which are modified. If the corresponding file
descriptor is not yet ready, it is replaced by \texttt{fail}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}send}}
\logpage{[ 3, 2, 47 ]}\nobreak
\hyperdef{L}{X87019FD887F55C27}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}send({\slshape fd, st, offset, len, flags})\index{IOsend@\texttt{IO{\textunderscore}send}}
\label{IOsend}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Sends data to a socket. For details see ``\texttt{man 2 send}''. Note that the additional argument \mbox{\texttt{\slshape offset}} specifies the position of the data to send within the string \mbox{\texttt{\slshape st}}. It is zero based, meaning that zero indicates the start of the string, which
is position 1 in \textsf{GAP}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}sendto}}
\logpage{[ 3, 2, 48 ]}\nobreak
\hyperdef{L}{X8388B01417B5745EC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}sendto({\slshape fd, st, offset, len, flags, addr})\index{IOsendto@\texttt{IO{\textunderscore}sendto}}
\label{IOsendto}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Sends data to a socket. For details see ``\texttt{man 2 sendto}''. Note that the additional argument \mbox{\texttt{\slshape offset}} specifies the position of the data to send within the string \mbox{\texttt{\slshape st}}. It is zero based, meaning that zero indicates the start of the string, which
is position 1 in \textsf{GAP}. The argument \mbox{\texttt{\slshape addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOmakesockaddrin}) and contains its length such that no 7th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}setsockopt}}
\logpage{[ 3, 2, 49 ]}\nobreak
\hyperdef{L}{X17BE641C11784D0899}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}setsockopt({\slshape fd, level, optname, optval})\index{IOsetsockopt@\texttt{IO{\textunderscore}setsockopt}}
\label{IOsetsockopt}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Sets a socket option. For details see ``\texttt{man 2 setsockopt}''. Note that the argument \mbox{\texttt{\slshape optval}} carries its length around, such that no 5th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}socket}}
\logpage{[ 3, 2, 50 ]}\nobreak
\hyperdef{L}{X852B16CF82B96C84}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}socket({\slshape domain, type, protocol})\index{IOsocket@\texttt{IO{\textunderscore}socket}}
\label{IOsocket}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Creates a socket, an endpoint for communication. For details see ``\texttt{man 2 socket}''. There is one little special: On systems that have \texttt{getprotobyname} you can pass a string as third argument \mbox{\texttt{\slshape protocol}} which is automatically looked up by \texttt{getprotobyname}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}stat}}
\logpage{[ 3, 2, 51 ]}\nobreak
\hyperdef{L}{X17F7D238617B45D525}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}stat({\slshape pathname})\index{IOstat@\texttt{IO{\textunderscore}stat}}
\label{IOstat}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Returns the file metadata for the file \mbox{\texttt{\slshape pathname}}. For details see ``\texttt{man 2 stat}''. A \textsf{GAP} record is returned with the same entries than a \texttt{struct stat}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}symlink}}
\logpage{[ 3, 2, 52 ]}\nobreak
\hyperdef{L}{X17B0D9CEF17A3CD431}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}symlink({\slshape oldpath, newpath})\index{IOsymlink@\texttt{IO{\textunderscore}symlink}}
\label{IOsymlink}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Creates a symbolic link. For details see ``\texttt{man 2 symlink}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}telldir}}
\logpage{[ 3, 2, 53 ]}\nobreak
\hyperdef{L}{X81FF8B678748900B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}telldir({\slshape })\index{IOtelldir@\texttt{IO{\textunderscore}telldir}}
\label{IOtelldir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Return current location in directory. For details see ``\texttt{man 3 telldir}''. Note that no second argument is required as we have only one \texttt{DIR} struct on the C level. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}unlink}}
\logpage{[ 3, 2, 54 ]}\nobreak
\hyperdef{L}{X178C93B6587B478C2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}unlink({\slshape pathname})\index{IOunlink@\texttt{IO{\textunderscore}unlink}}
\label{IOunlink}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Delete a name and possibly the file it refers to. For details see ``\texttt{man 2 unlink}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}WaitPid}}
\logpage{[ 3, 2, 55 ]}\nobreak
\hyperdef{L}{X80737A008450184F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}WaitPid({\slshape pid, wait})\index{IOWaitPid@\texttt{IO{\textunderscore}WaitPid}}
\label{IOWaitPid}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Waits for the termination of a child process. For details see ``\texttt{man 2 waitpid}''. Returns a \textsf{GAP} record describing PID and exit status. The second argument \mbox{\texttt{\slshape wait}} must be either \texttt{true} or \texttt{false}. In the first case, the call blocks until new information about a terminated
child process is available. In the second case no such waiting is performed,
the call returns immediately. See \texttt{IO{\textunderscore}fork} (\ref{IOfork}). }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}write}}
\logpage{[ 3, 2, 56 ]}\nobreak
\hyperdef{L}{X84EB067017D1BD3F1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}write({\slshape fd, st, offset, count})\index{IOwrite@\texttt{IO{\textunderscore}write}}
\label{IOwrite}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Writes to a file descriptor. For details see ``\texttt{man 2 write}''. Note that the additional argument \mbox{\texttt{\slshape offset}} specifies the position of the data to send within the string \mbox{\texttt{\slshape st}}. It is zero based, meaning that zero indicates the start of the string, which
is position 1 in \textsf{GAP}. }

 }

 
\section{\textcolor{Chapter }{Further C level functions}}\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X85065AD381BD8E0F}{}
{
  The following functions do not correspond to functions in the C library, but
are there to provide convenience to use other functions: 

\subsection{\textcolor{Chapter }{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in}}
\logpage{[ 3, 3, 1 ]}\nobreak
\hyperdef{L}{X878007A617E806CEF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in({\slshape ip, port})\index{IOmakesockaddrin@\texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in}}
\label{IOmakesockaddrin}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Makes a struct \texttt{sockaddr{\textunderscore}in} from IP address and port. The IP address must be given as a string of length
four, containing the four bytes of an IPv4 address in natural order. The port
must be a port number. Returns a string containing the struct, which can be
given to all functions above having an address argument. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}environ}}
\logpage{[ 3, 3, 2 ]}\nobreak
\hyperdef{L}{X17F3E88AD17EFD52F4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}environ({\slshape })\index{IOenviron@\texttt{IO{\textunderscore}environ}}
\label{IOenviron}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a list of strings 



 For details see ``\texttt{man environ}''. Returns the current environment as a list of strings of the form ``key=value''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}InstallSIGCHLDHandler}}
\logpage{[ 3, 3, 3 ]}\nobreak
\hyperdef{L}{X8383E62D86BE30C6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}InstallSIGCHLDHandler({\slshape })\index{IOInstallSIGCHLDHandler@\texttt{IO{\textunderscore}InstallSIGCHLDHandler}}
\label{IOInstallSIGCHLDHandler}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 Installs our SIGCHLD handler. This functions works as an idempotent. That is,
calling it twice does exactly the same as calling it once. It returns \texttt{true} when it is called for the first time since then a pointer to the old signal
handler is stored in a global variable. See \texttt{IO{\textunderscore}fork} (\ref{IOfork}). }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}RestoreSIGCHLDHandler}}
\logpage{[ 3, 3, 4 ]}\nobreak
\hyperdef{L}{X17EEB7471816B64DF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}RestoreSIGCHLDHandler({\slshape })\index{IORestoreSIGCHLDHandler@\texttt{IO{\textunderscore}RestoreSIGCHLDHandler}}
\label{IORestoreSIGCHLDHandler}
}\hfill{\scriptsize (function)}}\\


 Restores the original SIGCHLD handler. This function works as an idempotent.
That is, calling it twice does exactly the same as calling it once. It returns \texttt{true} when it is called for the first time after calling \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler}). See \texttt{IO{\textunderscore}fork} (\ref{IOfork}). }

 }

 }

 
\chapter{\textcolor{Chapter }{High level functions for buffered I/O}}\label{bufio}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X8513BEBD17A0A684D}{}
{
  The functions in the previous sections are intended to be a possibility for
direct access to the low level I/O functions in the C library. Thus, the
calling conventions are strictly as in the original.

 The functionality described in this section is implemented completely in the \textsf{GAP} language and is intended to provide a good interface for programming in \textsf{GAP}. The fundamental object for I/O on the C library level is the file
descriptor, which is just a non-negative integer representing an open file of
the process. The basic idea is to wrap up file descriptors in \textsf{GAP} objects that do the buffering.

 Note that considerable care has been taken to ensure that one can do I/O
multiplexing with buffered I/O. That is, one always has the possibility to
make sure before a read or write operation, that this read or write operation
will not block. This is crucial when one wants to serve more than one I/O
channel from the same (single-threaded) \textsf{GAP} process. This design principle sometimes made it necessary to have more than
one function for a certain operation. Those functions usually differ in a
subtle way with respect to their blocking behaviour.

 One remark applies again to nearly all functions presented here: If an error
is indicated by the returned value \texttt{fail} one can use the library function \texttt{LastSystemError} (\textbf{Reference: LastSystemError}) to find out more about the cause of the error. This fact is not mentioned with
every single function. 
\section{\textcolor{Chapter }{Types and the creation of \texttt{File} objects}}\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X83C42F77178B704C7}{}
{
  The wrapped file objects are in the following category: 

\subsection{\textcolor{Chapter }{IsFile}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X80C9B80A80E3A555}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFile({\slshape o})\index{IsFile@\texttt{IsFile}}
\label{IsFile}
}\hfill{\scriptsize (Category)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 The category of \texttt{File} objects. }

 To create objects in this category, one uses the following function: 

\subsection{\textcolor{Chapter }{IO{\textunderscore}WrapFD}}
\logpage{[ 4, 1, 2 ]}\nobreak
\hyperdef{L}{X17DDB0BA6836DA208}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}WrapFD({\slshape fd, rbufsize, wbufsize})\index{IOWrapFD@\texttt{IO{\textunderscore}WrapFD}}
\label{IOWrapFD}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object 



 The argument \mbox{\texttt{\slshape fd}} must be a file descriptor (i.e. an integer) or -1 (see below). 

 \mbox{\texttt{\slshape rbufsize}} can either be \texttt{false} for unbuffered reading or an integer buffer size or a string. If it is an
integer, a read buffer of that size is used. If it is a string, then \mbox{\texttt{\slshape fd}} must be -1 and a \texttt{File} object that reads from that string is created.

 \mbox{\texttt{\slshape wbufsize}} can either be \texttt{false} for unbuffered writing or an integer buffer size or a string. If it is an
integer, a write buffer of that size is used. If it is a string, then \mbox{\texttt{\slshape fd}} must be -1 and a \texttt{File} object that appends to that string is created.

 The result of this function is a new \texttt{File} object. }

 A convenient way to do this for reading or writing of files on disk is the
following function: 

\subsection{\textcolor{Chapter }{IO{\textunderscore}File (mode)}}
\logpage{[ 4, 1, 3 ]}\nobreak
\hyperdef{L}{X17EC160D017E815DBB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}File({\slshape filename[, mode]})\index{IOFile@\texttt{IO{\textunderscore}File}!mode}
\label{IOFile:mode}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}File({\slshape filename[, bufsize]})\index{IOFile@\texttt{IO{\textunderscore}File}!bufsize}
\label{IOFile:bufsize}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}File({\slshape filenamemodebufsize})\index{IOFile@\texttt{IO{\textunderscore}File}!mode and bufsize}
\label{IOFile:mode and bufsize}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object or \texttt{fail} 



 The argument \mbox{\texttt{\slshape filename}} must be a string specifying the path name of the file to work on. \mbox{\texttt{\slshape mode}} must also be a string with possible values ``r'', ``w'', or ``a'', meaning read access, write access (with creating and truncating), and append
access respectively. If \mbox{\texttt{\slshape mode}} is omitted, it defaults to ``r''. \mbox{\texttt{\slshape bufsize}}, if given, must be a positive integer or \texttt{false}, otherwise it defaults to \texttt{IO.DefaultBufSize}. Internally, the \texttt{IO{\textunderscore}open} (\ref{IOopen}) function is used and the result file descriptor is wrapped using \texttt{IO{\textunderscore}WrapFD} (\ref{IOWrapFD}) with \mbox{\texttt{\slshape bufsize}} as the buffer size. 

 The result is either \texttt{fail} in case of an error or a \texttt{File} object in case of success. }

 Note that there is a similar function \texttt{IO{\textunderscore}FilteredFile} (\ref{IOFilteredFile}) which also creates a \texttt{File} object but with additional functionality with respect to a pipeline for
filtering. It is described in its section in Section \ref{ipc}. There is some more low-level functionality to acquire open file descriptors.
These can be wrapped into \texttt{File} objects using \texttt{IO{\textunderscore}WrapFD} (\ref{IOWrapFD}). }

 
\section{\textcolor{Chapter }{Reading and writing}}\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X818FA8A317C8BBB95}{}
{
  Once a \texttt{File} object is created, one can use the following functions on it: 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ReadUntilEOF}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X865A873E178C822B7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ReadUntilEOF({\slshape f})\index{IOReadUntilEOF@\texttt{IO{\textunderscore}ReadUntilEOF}}
\label{IOReadUntilEOF}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 This function reads all data from the file \mbox{\texttt{\slshape f}} until the end of file. The data is returned as a \textsf{GAP} string. If the file is already at end of file, an empty string is returned. If
an error occurs, then \texttt{fail} is returned. Note that you still have to call \texttt{IO{\textunderscore}Close} (\ref{IOClose}) on the \texttt{File} object to properly close the file later. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ReadBlock}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X17D2686ED854BEF95}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ReadBlock({\slshape f, len})\index{IOReadBlock@\texttt{IO{\textunderscore}ReadBlock}}
\label{IOReadBlock}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 This function gets two arguments, the first argument \mbox{\texttt{\slshape f}} must be a \texttt{File} object and the second argument \mbox{\texttt{\slshape len}} must be a positive integer. The function tries to read \mbox{\texttt{\slshape len}} bytes and returns a string of that length. If and only if the end of file is
reached earlier, fewer bytes are returned. If an error occurs, \texttt{fail} is returned. Note that this function blocks until either \mbox{\texttt{\slshape len}} bytes are read, or the end of file is reached, or an error occurs. For the
case of pipes or internet connections it is possible that currently no more
data is available, however, by definition the end of file is only reached
after the connection has been closed by the other side! }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ReadLine}}
\logpage{[ 4, 2, 3 ]}\nobreak
\hyperdef{L}{X8738708E17B9DF8DB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ReadLine({\slshape f})\index{IOReadLine@\texttt{IO{\textunderscore}ReadLine}}
\label{IOReadLine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 This function gets exactly one argument, which must be a \texttt{File} object \mbox{\texttt{\slshape f}}. It reads one line of data, where the definition of line is operating system
dependent. The line end character(s) are included in the result. The function
returns a string with the line in case of success and \texttt{fail} in case of an error. In the latter case, one can query the error with \texttt{LastSystemError} (\textbf{Reference: LastSystemError}).

 Note that the reading is done via the buffer of \mbox{\texttt{\slshape f}}, such that this function will be quite fast also for large amounts of data.

 If the end of file is hit without a line end, the rest of the file is
returned. If the file is already at end of file before the call, then a string
of length 0 is returned. Note that this is not an error but the standard end
of file convention! }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ReadLines}}
\logpage{[ 4, 2, 4 ]}\nobreak
\hyperdef{L}{X81E72756806C0945}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ReadLines({\slshape f[, max]})\index{IOReadLines@\texttt{IO{\textunderscore}ReadLines}}
\label{IOReadLines}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a list of strings or \texttt{fail} 



 This function gets one or two arguments, the first of which must always be a \texttt{File} object \mbox{\texttt{\slshape f}}. It reads lines of data (where the definition of line is operating system
dependent) either until end of file (without a second argument) or up to \mbox{\texttt{\slshape max}} lines (with a second argument \mbox{\texttt{\slshape max}}. A list of strings with the result is returned, if everything went well and \texttt{fail} oterwise. In the latter case, one can query the error with \texttt{LastSystemError} (\textbf{Reference: LastSystemError}).

 Note that the reading is done via the buffer of \mbox{\texttt{\slshape f}}, such that this function will be quite fast also for large amounts of data.

 If the file is already at the end of file, the function returns a list of
length 0. Note that this is not an error but the standard end of file
convention! }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}HasData}}
\logpage{[ 4, 2, 5 ]}\nobreak
\hyperdef{L}{X87E0AC5417835F21D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}HasData({\slshape f})\index{IOHasData@\texttt{IO{\textunderscore}HasData}}
\label{IOHasData}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 This function takes one argument \mbox{\texttt{\slshape f}} which must be a \texttt{File} object. It returns \texttt{true} or \texttt{false} according to whether there is data to read available in the file \mbox{\texttt{\slshape f}}. A return value of \texttt{true} guarantees that the next call to \texttt{IO{\textunderscore}Read} (\ref{IORead}) on that file will succeed without blocking and return at least one byte or an
empty string to indicate the end of file. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Read}}
\logpage{[ 4, 2, 6 ]}\nobreak
\hyperdef{L}{X84F3D862836BF17C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Read({\slshape f, len})\index{IORead@\texttt{IO{\textunderscore}Read}}
\label{IORead}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 The function gets two arguments, the first of which must be a \texttt{File} object \mbox{\texttt{\slshape f}}. The second argument must be a positive integer. The function reads data up
to \mbox{\texttt{\slshape len}} bytes. A string with the result is returned, if everything went well and \texttt{fail} otherwise. In the latter case, one can query the error with \texttt{LastSystemError} (\textbf{Reference: LastSystemError}).

 Note that the reading is done via the buffer of \mbox{\texttt{\slshape f}}, such that this function will be quite fast also for large amounts of data.

 If the file is already at the end of the file, the function returns a string
of length 0. Note that this is not an error!

 If a previous call to \texttt{IO{\textunderscore}HasData} (\ref{IOHasData}) or to \texttt{IO{\textunderscore}Select} (\ref{IOSelect}) indicated that there is data available to read, then it is guaranteed that the
function \texttt{IO{\textunderscore}Read} (\ref{IORead}) does not block and returns at least one byte if the file is not yet at end of
file and an empty string otherwise. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Write}}
\logpage{[ 4, 2, 7 ]}\nobreak
\hyperdef{L}{X84EB067017D1BD3F1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Write({\slshape f[, things, ...]})\index{IOWrite@\texttt{IO{\textunderscore}Write}}
\label{IOWrite}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 This function can get an arbitrary number of arguments, the first of which
must be a \texttt{File} object \mbox{\texttt{\slshape f}}. All the other arguments are just written to \mbox{\texttt{\slshape f}} if they are strings. Otherwise, the \texttt{String} function is called on them and the result is written out to \mbox{\texttt{\slshape f}}.

 Note that the writing is done buffered. That is, the data is first written to
the buffer and only really written out after the buffer is full or after the
user explicitly calls \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) on \mbox{\texttt{\slshape f}}.

 The result is either the number of bytes written in case of success or \texttt{fail} in case of an error. In the latter case the error can be queried with \texttt{LastSystemError} (\textbf{Reference: LastSystemError}).

 Note that this function blocks until all data is at least written into the
buffer and might block until data can be sent again if the buffer is full. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}WriteLine}}
\logpage{[ 4, 2, 8 ]}\nobreak
\hyperdef{L}{X83A03ACB81F53BB1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}WriteLine({\slshape f, line})\index{IOWriteLine@\texttt{IO{\textunderscore}WriteLine}}
\label{IOWriteLine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Behaves like \texttt{IO{\textunderscore}Write} (\ref{IOWrite}) but works on a single string \mbox{\texttt{\slshape line}} and sends an (operating system dependent) end of line string afterwards. Also \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) is called automatically after the operation, such that one can be sure, that
the data is actually written out after the function has completed. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}WriteLines}}
\logpage{[ 4, 2, 9 ]}\nobreak
\hyperdef{L}{X87CE6EC117C1573AC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}WriteLines({\slshape f, list})\index{IOWriteLines@\texttt{IO{\textunderscore}WriteLines}}
\label{IOWriteLines}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Behaves like \texttt{IO{\textunderscore}Write} (\ref{IOWrite}) but works on a list of strings \mbox{\texttt{\slshape list}} and sends an (operating system dependent) end of line string after each string
in the list. Also \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) is called automatically after the operation, such that one can be sure, that
the data is actually written out after the function has completed. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Flush}}
\logpage{[ 4, 2, 10 ]}\nobreak
\hyperdef{L}{X17873A49F17CC7ECFB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Flush({\slshape f})\index{IOFlush@\texttt{IO{\textunderscore}Flush}}
\label{IOFlush}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 This function gets one argument \mbox{\texttt{\slshape f}}, which must be a \texttt{File} object. It writes out all the data that is in the write buffer. This is not
necessary before the call to the function \texttt{IO{\textunderscore}Close} (\ref{IOClose}), since that function calls \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) automatically. However, it is necessary to call \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) after calls to \texttt{IO{\textunderscore}Write} (\ref{IOWrite}) to be sure that the data is really sent out. The function returns \texttt{true} if everything goes well and \texttt{fail} if an error occurs.

 Remember that the functions \texttt{IO{\textunderscore}WriteLine} (\ref{IOWriteLine}) and \texttt{IO{\textunderscore}WriteLines} (\ref{IOWriteLines}) implicitly call \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) after they are done.

 Note that this function might block until all data is actually written to the
file descriptor. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}WriteFlush}}
\logpage{[ 4, 2, 11 ]}\nobreak
\hyperdef{L}{X178706342178F6C69F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}WriteFlush({\slshape f[, things]})\index{IOWriteFlush@\texttt{IO{\textunderscore}WriteFlush}}
\label{IOWriteFlush}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 This function behaves like \texttt{IO{\textunderscore}Write} (\ref{IOWrite}) followed by a call to \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}). It returns either the number of bytes written or \texttt{fail} if an error occurs. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ReadyForWrite}}
\logpage{[ 4, 2, 12 ]}\nobreak
\hyperdef{L}{X80CF240F178664DF4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ReadyForWrite({\slshape f})\index{IOReadyForWrite@\texttt{IO{\textunderscore}ReadyForWrite}}
\label{IOReadyForWrite}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 This function takes one argument \mbox{\texttt{\slshape f}} which must be a \texttt{File} object. It returns \texttt{true} or \texttt{false} according to whether the file \mbox{\texttt{\slshape f}} is ready to write. A return value of \texttt{true} guarantees that the next call to \texttt{IO{\textunderscore}WriteNonBlocking} (\ref{IOWriteNonBlocking}) on that file will succeed without blocking and accept at least one byte. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}WriteNonBlocking}}
\logpage{[ 4, 2, 13 ]}\nobreak
\hyperdef{L}{X84052F9886ADED0D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}WriteNonBlocking({\slshape f, st, pos, len})\index{IOWriteNonBlocking@\texttt{IO{\textunderscore}WriteNonBlocking}}
\label{IOWriteNonBlocking}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 This function takes four arguments. The first one \mbox{\texttt{\slshape f}} must be a \texttt{File} object, the second \mbox{\texttt{\slshape st}} a string, and the arguments \mbox{\texttt{\slshape pos}} and \mbox{\texttt{\slshape len}} must be integers, such that positions $\mbox{\texttt{\slshape pos}}+1$ until $\mbox{\texttt{\slshape pos}}+\mbox{\texttt{\slshape len}}$ are bound in \mbox{\texttt{\slshape st}}. The function tries to write up to \mbox{\texttt{\slshape len}} bytes from \mbox{\texttt{\slshape st}} from position $\mbox{\texttt{\slshape pos}}+1$ to the file \mbox{\texttt{\slshape f}}. If a previous call to \texttt{IO{\textunderscore}ReadyForWrite} (\ref{IOReadyForWrite}) or to \texttt{IO{\textunderscore}Select} (\ref{IOSelect}) indicates that \mbox{\texttt{\slshape f}} is writable, then it is guaranteed that the following call to \texttt{IO{\textunderscore}WriteNonBlocking} (\ref{IOWriteNonBlocking}) will not block and accept at least one byte of data. Note that it is not
guaranteed that all \mbox{\texttt{\slshape len}} bytes are written. The function returns the number of bytes written or \texttt{fail} if an error occurs. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ReadyForFlush}}
\logpage{[ 4, 2, 14 ]}\nobreak
\hyperdef{L}{X17C5786E017813434B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ReadyForFlush({\slshape f})\index{IOReadyForFlush@\texttt{IO{\textunderscore}ReadyForFlush}}
\label{IOReadyForFlush}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 This function takes one argument \mbox{\texttt{\slshape f}} which must be a \texttt{File} object. It returns \texttt{true} or \texttt{false} according to whether the file \mbox{\texttt{\slshape f}} is ready to flush. A return value of \texttt{true} guarantees that the next call to \texttt{IO{\textunderscore}FlushNonBlocking} (\ref{IOFlushNonBlocking}) on that file will succeed without blocking and flush out at least one byte.
Note that this does not guarantee, that this call succeeds to flush out the
whole content of the buffer! }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}FlushNonBlocking}}
\logpage{[ 4, 2, 15 ]}\nobreak
\hyperdef{L}{X80E977B48771D207}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}FlushNonBlocking({\slshape f})\index{IOFlushNonBlocking@\texttt{IO{\textunderscore}FlushNonBlocking}}
\label{IOFlushNonBlocking}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true}, \texttt{false}, or \texttt{fail} 



 This function takes one argument \mbox{\texttt{\slshape f}} which must be a \texttt{File} object. It tries to write all data in the writing buffer to the file
descriptor. If this succeeds, the function returns \texttt{true} and \texttt{false} otherwise. If an error occurs, \texttt{fail} is returned. If a previous call to \texttt{IO{\textunderscore}ReadyForFlush} (\ref{IOReadyForFlush}) or \texttt{IO{\textunderscore}Select} (\ref{IOSelect}) indicated that \mbox{\texttt{\slshape f}} is flushable, then it is guaranteed that the following call to \texttt{IO{\textunderscore}FlushNonBlocking} (\ref{IOFlushNonBlocking}) does not block. However, it is not guaranteed that \texttt{true} is returned from that call. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Close}}
\logpage{[ 4, 2, 16 ]}\nobreak
\hyperdef{L}{X820DA9C917C2E80BA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Close({\slshape f})\index{IOClose@\texttt{IO{\textunderscore}Close}}
\label{IOClose}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 This function closes the \texttt{File} object \mbox{\texttt{\slshape f}} after writing all data in the write buffer out and closing the file
descriptor. All buffers are freed. In case of an error, the function returns \texttt{fail} and otherwise \texttt{true}. Note that for pipes to other processes this function collects data about the
terminated processes using \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}). }

 }

 
\section{\textcolor{Chapter }{Other functions}}\logpage{[ 4, 3, 0 ]}
\hyperdef{L}{X87C3D1B984960984}{}
{
  

\subsection{\textcolor{Chapter }{IO{\textunderscore}GetFD}}
\logpage{[ 4, 3, 1 ]}\nobreak
\hyperdef{L}{X17F893EFC17D0C7BF2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}GetFD({\slshape f})\index{IOGetFD@\texttt{IO{\textunderscore}GetFD}}
\label{IOGetFD}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer 



 This function returns the real file descriptor that is behind the \texttt{File} object \mbox{\texttt{\slshape f}}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}GetWBuf}}
\logpage{[ 4, 3, 2 ]}\nobreak
\hyperdef{L}{X86666C9681EA7297}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}GetWBuf({\slshape f})\index{IOGetWBuf@\texttt{IO{\textunderscore}GetWBuf}}
\label{IOGetWBuf}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{false} 



 This function gets one argument \mbox{\texttt{\slshape f}} which must be a \texttt{File} object and returns the writing buffer of that \texttt{File} object. This is necessary for \texttt{File} objects, that are not associated to a real file descriptor but just collect
everything that was written in their writing buffer. Remember to use this
function before closing the \texttt{File} object. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Select}}
\logpage{[ 4, 3, 3 ]}\nobreak
\hyperdef{L}{X81CA6EE88062010E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Select({\slshape r, w, f, e, t1, t2})\index{IOSelect@\texttt{IO{\textunderscore}Select}}
\label{IOSelect}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 This function is the corresponding function to \texttt{IO{\textunderscore}select} (\ref{IOselect}) for buffered file access. It behaves similarly to that function. The
differences are the following: There are four lists of files \mbox{\texttt{\slshape r}}, \mbox{\texttt{\slshape w}}, \mbox{\texttt{\slshape f}}, and \mbox{\texttt{\slshape e}}. They all can contain either integers (standing for file descriptors) or \texttt{File} objects. The list \mbox{\texttt{\slshape r}} is for checking, whether files or file descriptors are ready to read, the list \mbox{\texttt{\slshape w}} is for checking whether they are ready to write, the list \mbox{\texttt{\slshape f}} is for checking whether they are ready to flush, and the list \mbox{\texttt{\slshape e}} is for checking whether they have exceptions.

 For \texttt{File} objects it is always first checked, whether there is either data available in
a reading buffer or space in a writing buffer. If so, they are immediately
reported to be ready (this feature makes the list of \texttt{File} objects to test for flushability necessary). For the remaining files and for
all specified file descriptors, the function \texttt{IO{\textunderscore}select} (\ref{IOselect}) is called to get an overview about readiness. The timeout values \mbox{\texttt{\slshape t1}} and \mbox{\texttt{\slshape t2}} are set to zero for immediate returning if one of the requested buffers were
ready.

 \texttt{IO{\textunderscore}Select} (\ref{IOSelect}) returns the number of files or file descriptors that are ready to serve or \texttt{fail} if an error occurs. }

 The following function is a convenience function for directory access: 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ListDir}}
\logpage{[ 4, 3, 4 ]}\nobreak
\hyperdef{L}{X84B16DB8178265F02}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ListDir({\slshape pathname})\index{IOListDir@\texttt{IO{\textunderscore}ListDir}}
\label{IOListDir}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a list of strings or \texttt{fail} 



 This function gets a string containing a path name as single argument and
returns a list of strings that are the names of the files in that directory,
or \texttt{fail}, if an error occurred. }

 The following function is used to create strings describing a pair of an IP
address and a port number in a binary way. These strings can be used in
connection with the C library functions \texttt{connect}, \texttt{bind}, \texttt{recvfrom}, and \texttt{sendto} for the arguments needing such address pairs. 

\subsection{\textcolor{Chapter }{IO{\textunderscore}MakeIPAddressPort}}
\logpage{[ 4, 3, 5 ]}\nobreak
\hyperdef{L}{X8568CE6684C90CE5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}MakeIPAddressPort({\slshape ipstring, portnr})\index{IOMakeIPAddressPort@\texttt{IO{\textunderscore}MakeIPAddressPort}}
\label{IOMakeIPAddressPort}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string 



 This function gets a string \mbox{\texttt{\slshape ipstring}} containing an IP address in dot notation, i.e. four numbers in the range from
0 to 255 separated by dots ``.'', and an integer \mbox{\texttt{\slshape portnr}}, which is a port number. The result is a string of the correct length to be
used for the low level C library functions, wherever IP address port number
pairs are needed. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Environment}}
\logpage{[ 4, 3, 6 ]}\nobreak
\hyperdef{L}{X17F9AAE018474E1D8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Environment({\slshape })\index{IOEnvironment@\texttt{IO{\textunderscore}Environment}}
\label{IOEnvironment}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Takes no arguments, uses \texttt{IO{\textunderscore}environ} (\ref{IOenviron}) to get the environment and returns a record in which the component names are
the names of the environment variables and the values are the values. This can
then be changed and the changed record can be given to \texttt{IO{\textunderscore}MakeEnvList} (\ref{IOMakeEnvList}) to produce again a list which can be used for \texttt{IO{\textunderscore}execve} (\ref{IOexecve}) as third argument. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}MakeEnvList}}
\logpage{[ 4, 3, 7 ]}\nobreak
\hyperdef{L}{X17CF3DB5081A91600}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}MakeEnvList({\slshape r})\index{IOMakeEnvList@\texttt{IO{\textunderscore}MakeEnvList}}
\label{IOMakeEnvList}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a list of strings 



 Takes a record as returned by \texttt{IO{\textunderscore}Environment} (\ref{IOEnvironment}) and turns it into a list of strings as needed by \texttt{IO{\textunderscore}execve} (\ref{IOexecve}) as third argument. }

 }

 
\section{\textcolor{Chapter }{Inter process communication}}\label{ipc}
\logpage{[ 4, 4, 0 ]}
\hyperdef{L}{X85BB2BA684485CD6}{}
{
  

\subsection{\textcolor{Chapter }{IO{\textunderscore}FindExecutable}}
\logpage{[ 4, 4, 1 ]}\nobreak
\hyperdef{L}{X84E91FE217A7860F3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}FindExecutable({\slshape path})\index{IOFindExecutable@\texttt{IO{\textunderscore}FindExecutable}}
\label{IOFindExecutable}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{fail} or the path to an executable 



 If the path name \mbox{\texttt{\slshape path}} contains a slash, this function simply checks whether the string \mbox{\texttt{\slshape path}} refers to an executable file. If so, \mbox{\texttt{\slshape path}} is returned as is. Otherwise, \texttt{fail} is returned. If the path name \mbox{\texttt{\slshape path}} does not contain a slash, all directories in the environment variable \texttt{PATH} are searched for an executable with name \mbox{\texttt{\slshape path}}. If so, the full path to that executable is returned, otherwise \texttt{fail}.

 This function is used whenever one of the following functions gets an argument
that should refer to an executable. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}CloseAllFDs}}
\logpage{[ 4, 4, 2 ]}\nobreak
\hyperdef{L}{X17C43017E17AC5973A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}CloseAllFDs({\slshape exceptions})\index{IOCloseAllFDs@\texttt{IO{\textunderscore}CloseAllFDs}}
\label{IOCloseAllFDs}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 Closes all file descriptors except those listed in \mbox{\texttt{\slshape exceptions}}, which must be a list of integers. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Popen}}
\logpage{[ 4, 4, 3 ]}\nobreak
\hyperdef{L}{X17891F56386C008CE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Popen({\slshape path, argv, mode})\index{IOPopen@\texttt{IO{\textunderscore}Popen}}
\label{IOPopen}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object or \texttt{fail} 



 The argument \mbox{\texttt{\slshape path}} must refer to an executable file in the sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOFindExecutable}). 

 Starts a child process using the executable in \mbox{\texttt{\slshape path}} with either stdout or stdin being a pipe. The argument \mbox{\texttt{\slshape mode}} must be either the string ``\texttt{r}'' or the string ``\texttt{w}''. 

 In the first case, the standard output of the child process will be the
writing end of a pipe. A \texttt{File} object for reading connected to the reading end of the pipe is returned. The
standard input and standard error of the child process will be the same than
the calling \textsf{GAP} process. 

 In the second case, the standard input of the child process will be the
reading end of a pipe. A \texttt{File} object for writing connected to the writing end of the pipe is returned. The
standard output and standard error of the child process will be the same than
the calling \textsf{GAP} process. 

 In case of an error, \texttt{fail} is returned. 

 The process will usually die, when the pipe is closed, but can also do so
without that. The \texttt{File} object remembers the process ID of the started process and the \texttt{IO{\textunderscore}Close} (\ref{IOClose}) function then calls \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) for it to acquire information about the terminated process. 

 Note that \texttt{IO{\textunderscore}Popen} (\ref{IOPopen}) activates our SIGCHLD handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler})). 

 In either case the \texttt{File} object will have the attribute ``\texttt{ProcessID}'' set to the process ID of the child process. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Popen2}}
\logpage{[ 4, 4, 4 ]}\nobreak
\hyperdef{L}{X17E05CF6481CBC0A1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Popen2({\slshape path, argv})\index{IOPopen2@\texttt{IO{\textunderscore}Popen2}}
\label{IOPopen2}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 The argument \mbox{\texttt{\slshape path}} must refer to an executable file in the sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOFindExecutable}). 

 A new child process is started using the executable in \mbox{\texttt{\slshape path}} The standard input and standard output of it are pipes. The writing end of the
input pipe and the reading end of the output pipe are returned as \texttt{File} objects bound to two components ``\texttt{stdin}'' and ``\texttt{stdout}'' (resp.) of the returned record. This means, you have to \emph{write} to ``\texttt{stdin}'' and \emph{read} from ``\texttt{stdout}'' in the calling \textsf{GAP} process. The standard error of the child process will be the same as the one
of the calling \textsf{GAP} process. 

 Returns \texttt{fail} if an error occurred. 

 The process will usually die, when one of the pipes is closed. The \texttt{File} objects remember the process ID of the called process and the function call to \texttt{IO{\textunderscore}Close} (\ref{IOClose}) for the \texttt{stdout} object will call \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) for it to acquire information about the terminated process. 

 Note that \texttt{IO{\textunderscore}Popen2} (\ref{IOPopen2}) activates our SIGCHLD handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler})). 

 Both \texttt{File} objects will have the attribute ``\texttt{ProcessID}'' set to the process ID of the child process, which will also be bound to the ``\texttt{pid}'' component of the returned record. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Popen3}}
\logpage{[ 4, 4, 5 ]}\nobreak
\hyperdef{L}{X17975BC6D80BC71E5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Popen3({\slshape path, argv})\index{IOPopen3@\texttt{IO{\textunderscore}Popen3}}
\label{IOPopen3}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 The argument \mbox{\texttt{\slshape path}} must refer to an executable file in the sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOFindExecutable}). 

 A new child process is started using the executable in \mbox{\texttt{\slshape path}} The standard input, standard output, and standard error of it are pipes. The
writing end of the input pipe, the reading end of the output pipe and the
reading end of the error pipe are returned as \texttt{File} objects bound to two components ``\texttt{stdin}'', ``\texttt{stdout}'', and ``\texttt{stderr}'' (resp.) of the returned record. This means, you have to \emph{write} to ``\texttt{stdin}'' and \emph{read} from ``\texttt{stdout}'' and ``\texttt{stderr}'' in the calling \textsf{GAP} process.

 Returns \texttt{fail} if an error occurred. 

 The process will usually die, when one of the pipes is closed. All three \texttt{File} objects will remember the process ID of the newly created process and the call
to the \texttt{IO{\textunderscore}Close} (\ref{IOClose}) function for the \texttt{stdout} object will call \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) for it to acquire information about the terminated child process. 

 Note that \texttt{IO{\textunderscore}Popen3} (\ref{IOPopen3}) activates our SIGCHLD handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler})). 

 All three \texttt{File} objects will have the attribute ``\texttt{ProcessID}'' set to the process ID of the child process, which will also be bound to the ``\texttt{pid}'' component of the returned record. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}StartPipeline}}
\logpage{[ 4, 4, 6 ]}\nobreak
\hyperdef{L}{X813219C117FB54731}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}StartPipeline({\slshape progs, infd, outfd, switcherror})\index{IOStartPipeline@\texttt{IO{\textunderscore}StartPipeline}}
\label{IOStartPipeline}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 The argument \mbox{\texttt{\slshape progs}} is a list of pairs, the first entry being a path to an executable (in the
sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOFindExecutable})), the second an argument list, the argument \mbox{\texttt{\slshape infd}} is an open file descriptor for reading, \mbox{\texttt{\slshape outfd}} is an open file descriptor for writing, both can be replaced by the string ``\texttt{open}'' in which case a new pipe will be opened. The argument \mbox{\texttt{\slshape switcherror}} is a boolean indicating whether standard error channels are also switched to
the corresponding output channels. 

 This function starts up all processes and connects them with pipes. The input
of the first is switched to \mbox{\texttt{\slshape infd}} and the output of the last to \mbox{\texttt{\slshape outfd}}. 

 Returns a record with the following components: \texttt{pids} is a list of process ids if everything worked. For each process for which some
error occurred the corresponding pid is replaced by \texttt{fail}. The \texttt{stdin} component is equal to \texttt{false}, or to the file descriptor of the writing end of the newly created pipe which
is connected to the standard input of the first of the new processes if \mbox{\texttt{\slshape infd}} was ``\texttt{open}''. The \texttt{stdout} component is equal to \texttt{false} or to the file descriptor of the reading end of the newly created pipe which
is connected to the standard output of the last of the new processes if \mbox{\texttt{\slshape outfd}} was ``\texttt{open}''. 

 Note that the SIGCHLD handler of the \textsf{IO} package is installed by this function (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler})) and that it lies in the responsibility of the caller to use \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) to ask for the status information of all child processes after their
termination. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}StringFilterFile}}
\logpage{[ 4, 4, 7 ]}\nobreak
\hyperdef{L}{X86D61FAE871B23E8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}StringFilterFile({\slshape progs, filename})\index{IOStringFilterFile@\texttt{IO{\textunderscore}StringFilterFile}}
\label{IOStringFilterFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Reads the file with the name \mbox{\texttt{\slshape filename}}, however, a pipeline is created by the processes described by \mbox{\texttt{\slshape progs}} (see \texttt{IO{\textunderscore}StartPipeline} (\ref{IOStartPipeline})) to filter the content of the file through the pipeline. The result is put
into a \textsf{GAP} string and returned. If something goes wrong, \texttt{fail} is returned. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}StringFilterFile (append)}}
\logpage{[ 4, 4, 8 ]}\nobreak
\hyperdef{L}{X87E559C5179F2DF97}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}StringFilterFile({\slshape filename, progs, st[, append]})\index{IOStringFilterFile@\texttt{IO{\textunderscore}StringFilterFile}!append}
\label{IOStringFilterFile:append}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Writes the content of the string \mbox{\texttt{\slshape st}} to the file with the name \mbox{\texttt{\slshape filename}}, however, a pipeline is created by the processes described by \mbox{\texttt{\slshape progs}} (see \texttt{IO{\textunderscore}StartPipeline} (\ref{IOStartPipeline})) to filter the content of the string through the pipeline. The result is put
into the file. If the boolean value \mbox{\texttt{\slshape append}} is given and equal to \texttt{true}, then the data will be appended to the already existing file. If something
goes wrong, \texttt{fail} is returned. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}FilteredFile}}
\logpage{[ 4, 4, 9 ]}\nobreak
\hyperdef{L}{X801CE3708656FB00}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}FilteredFile({\slshape progs, filename[, mode][, bufsize]})\index{IOFilteredFile@\texttt{IO{\textunderscore}FilteredFile}}
\label{IOFilteredFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object or \texttt{fail} 



 This function is similar to \texttt{IO{\textunderscore}File} (\ref{IOFile:mode}) and behaves nearly identically. The only difference is that a filtering
pipeline is switched between the file and the \texttt{File} object such that all things read or written respectively are filtered through
this pipeline of processes. 

 The \texttt{File} object remembers the started processes and upon the final call to \texttt{IO{\textunderscore}Close} (\ref{IOClose}) automatically uses the \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) function to acquire information from the terminated processes in the pipeline
after their termination. This means that you do not have to call \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) any more after the call to \texttt{IO{\textunderscore}Close} (\ref{IOClose}).

 Note that \texttt{IO{\textunderscore}FilteredFile} (\ref{IOFilteredFile}) activates our SIGCHLD handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler})).

 The \texttt{File} object will have the attribute ``\texttt{ProcessID}'' set to the list of process IDs of the child processes. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}SendStringBackground}}
\logpage{[ 4, 4, 10 ]}\nobreak
\hyperdef{L}{X17D62E9C517F1F96FB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}SendStringBackground({\slshape f, st})\index{IOSendStringBackground@\texttt{IO{\textunderscore}SendStringBackground}}
\label{IOSendStringBackground}
}\hfill{\scriptsize (function)}}\\


 This functions uses \texttt{IO{\textunderscore}Write} (\ref{IOWrite}) to write the whole string \mbox{\texttt{\slshape st}} to the \texttt{File} object \mbox{\texttt{\slshape f}}. However, this is done by forking off a child process identical to the
calling \textsf{GAP} process that does the sending. The calling \textsf{GAP} process returns immediately, even before anything has been sent away with the
result \texttt{true}. The forked off sender process terminates itself immediately after it has
sent all data away.

 The reason for having this function available is the following: If one uses \texttt{IO{\textunderscore}Popen2} (\ref{IOPopen2}) or \texttt{IO{\textunderscore}Popen3} (\ref{IOPopen3}) to start up a child process with standard input and standard output being a
pipe, then one usually has the problem, that the child process starts reading
some data, but then wants to write data, before it received all data coming.
If the calling \textsf{GAP} process would first try to write all data and only start to read the output of
the child process after sending away all data, a deadlock situation would
occur. This is avoided with the forking and backgrounding approach.

 Remember to close the writing end of the standard input pipe in the calling \textsf{GAP} process directly after \texttt{IO{\textunderscore}SendStringBackground} (\ref{IOSendStringBackground}) has returned, because otherwise the child process might not notice that all
data has arrived, because the pipe persists! See the file \texttt{popen2.g} in the \texttt{example} directory for an example.

 Note that with most modern operating systems the forking off of an identical
child process does in fact \emph{not} mean a duplication of the total main memory used by both processes, because
the operating system kernel will use ``copy on write''. However, if a garbage collection happens to become necessary during the
sending of the data in the forked off sending process, this might trigger
doubled memory usage. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}PipeThrough}}
\logpage{[ 4, 4, 11 ]}\nobreak
\hyperdef{L}{X8484B0CD17836A19E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}PipeThrough({\slshape cmd, args, input})\index{IOPipeThrough@\texttt{IO{\textunderscore}PipeThrough}}
\label{IOPipeThrough}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Starts the process with the executable given by the file name \mbox{\texttt{\slshape cmd}} (in the sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOFindExecutable})) with arguments in the argument list \mbox{\texttt{\slshape args}} (a list of strings). The standard input and output of the started process are
connected via pipes to the calling process. The content of the string \mbox{\texttt{\slshape input}} is written to the standard input of the called process and its standard output
is read and returned as a string.

 All the necessary I/O multiplexing and non-blocking I/O to avoid deadlocks is
done in this function. 

 This function properly does \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) to wait for the termination of the child process but does not restore the
original \textsf{GAP} SIGCHLD signal handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler})). }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}PipeThroughWithError}}
\logpage{[ 4, 4, 12 ]}\nobreak
\hyperdef{L}{X17A9ACA39179635506}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}PipeThroughWithError({\slshape cmd, args, input})\index{IOPipeThroughWithError@\texttt{IO{\textunderscore}PipeThroughWithError}}
\label{IOPipeThroughWithError}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Starts the process with the executable given by the file name \mbox{\texttt{\slshape cmd}} (in the sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOFindExecutable})) with arguments in the argument list \mbox{\texttt{\slshape args}} (a list of strings). The standard input, output and error of the started
process are connected via pipes to the calling process. The content of the
string \mbox{\texttt{\slshape input}} is written to the standard input of the called process and its standard output
and error are read and returned as a record with components \texttt{out} and \texttt{err}, which are strings.

 All the necessary I/O multiplexing and non-blocking I/O to avoid deadlocks is
done in this function. 

 This function properly does \texttt{IO{\textunderscore}WaitPid} (\ref{IOWaitPid}) to wait for the termination of the child process but does not restore the
original \textsf{GAP} SIGCHLD signal handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOInstallSIGCHLDHandler})). 

 The functions returns either \texttt{fail} if an error occurred, or otherwise a record with components \texttt{out} and \texttt{err} which are bound to strings containing the full standard output and standard
error of the called process. }

 }

 }

 
\chapter{\textcolor{Chapter }{Object serialisation (Pickling)}}\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X81BBA46880EBFC7D}{}
{
  The idea of ``object serialisation'' is that one wants to store nearly arbitrary \textsf{GAP} objects to disk or transfer them over the network. To this end, one wants to
convert them to a byte stream that is platform independent and can later be
converted back to a copy of the same object in memory, be it in the same \textsf{GAP} process or another one maybe even on another machine. The main problem here
are the vast amount of different types occurring in \textsf{GAP} and the possibly highly self-referential structure of \textsf{GAP} objects. 

 The \textsf{IO} package contains a framework to implement object serialisation and
implementations for most of the basic data types in \textsf{GAP}. The framework is easily extendible to other types and takes complete care of
self-references and corresponding problems. It builds upon the buffered I/O
functions described in Section \ref{bufio}. We start by describing the user interface.

 
\section{\textcolor{Chapter }{Result objects}}\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X17E504814811605B7}{}
{
  The following static objects are used to report about success or failure of
the (un-)pickling operations: 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Error}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X86E06A128511BA25}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Error\index{IOError@\texttt{IO{\textunderscore}Error}}
\label{IOError}
}\hfill{\scriptsize (global variable)}}\\


 This object is returned if an error occurs. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Nothing}}
\logpage{[ 5, 1, 2 ]}\nobreak
\hyperdef{L}{X17887BFCF824B439B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Nothing\index{IONothing@\texttt{IO{\textunderscore}Nothing}}
\label{IONothing}
}\hfill{\scriptsize (global variable)}}\\


 This object is returned when there is nothing to return, for example if an
unpickler (see \texttt{IO{\textunderscore}Unpickle} (\ref{IOUnpickle})) encounters the end of a file. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}OK}}
\logpage{[ 5, 1, 3 ]}\nobreak
\hyperdef{L}{X17D4D092B8401EA0F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}OK\index{IOOK@\texttt{IO{\textunderscore}OK}}
\label{IOOK}
}\hfill{\scriptsize (global variable)}}\\


 This object is returned if everything went well and there is no other
canonical value to return to indicate this. }

 The only thing you can do with these special values is to compare them to each
other and to other objects.

 }

 
\section{\textcolor{Chapter }{Pickling and unpickling}}\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X17F68A8F417F87B243}{}
{
  

\subsection{\textcolor{Chapter }{IO{\textunderscore}Pickle}}
\logpage{[ 5, 2, 1 ]}\nobreak
\hyperdef{L}{X17E01770481297DF1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Pickle({\slshape f, ob})\index{IOPickle@\texttt{IO{\textunderscore}Pickle}}
\label{IOPickle}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 \texttt{IO{\textunderscore}OK} or \texttt{IO{\textunderscore}Error} 



 The argument \mbox{\texttt{\slshape f}} must be an open, writable \texttt{File} object. The object \mbox{\texttt{\slshape ob}} can be an arbitrary \textsf{GAP} object. The operation ``pickles'' or ``serialises'' the object \mbox{\texttt{\slshape ob}} and writes the result into the \texttt{File} object \mbox{\texttt{\slshape f}}. If everything is OK, the unique value \texttt{IO{\textunderscore}OK} is returned and otherwise the unique value \texttt{IO{\textunderscore}Error}. The resulting byte stream can be read again using the operation \texttt{IO{\textunderscore}Unpickle} (\ref{IOUnpickle}) and is platform- and architecture independent. Especially the question whether
a system has 32 bit or 64 bit wide words and the question of endianess does
not matter. 

 Note that not all of \textsf{GAP}'s object types are supported but it is relatively easy to extend the system.
This package supports in particular boolean values, integers, permutations,
rational numbers, finite field elements, cyclotomics, strings, polynomials,
rational functions, lists, records, compressed vectors and matrices over
finite fields (objects are uncompressed in the byte stream but recompressed
during unpickling), and straight line programs. 

 Self-referential objects built from records and lists are handled correctly
and are restored completely with the same self-references during unpickling. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Unpickle}}
\logpage{[ 5, 2, 2 ]}\nobreak
\hyperdef{L}{X8228EE63809A6DEF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}Unpickle({\slshape f})\index{IOUnpickle@\texttt{IO{\textunderscore}Unpickle}}
\label{IOUnpickle}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 \texttt{IO{\textunderscore}Error} or a \textsf{GAP} object 



 The argument \mbox{\texttt{\slshape f}} must be an open, readable \texttt{File} object. The operation reads from \mbox{\texttt{\slshape f}} and ``unpickles'' the next object. If an error occurs, the unique value \texttt{IO{\textunderscore}Error} is returned. If the \texttt{File} object is at end of file, the value \texttt{IO{\textunderscore}Nothing} is returned. Note that these two values are not picklable, because of their
special meaning as return values of this operation here. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}ClearPickleCache}}
\logpage{[ 5, 2, 3 ]}\nobreak
\hyperdef{L}{X844736FB80F6EE97}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IO{\textunderscore}ClearPickleCache({\slshape })\index{IOClearPickleCache@\texttt{IO{\textunderscore}ClearPickleCache}}
\label{IOClearPickleCache}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing 



 This function clears the ``pickle cache''. This cache stores all object pickled in the current recursive call to \texttt{IO{\textunderscore}Pickle} (\ref{IOPickle}) and is necessary to handle self-references. Usually it is not necessary to
call this function explicitly. Only in the rare case (that should not happen)
that a pickling or unpickling operation enters a break loop which is left by
the user, the pickle cache has to be cleared explicitly using this function
for later calls to \texttt{IO{\textunderscore}Pickle} (\ref{IOPickle}) and \texttt{IO{\textunderscore}Unpickle} (\ref{IOUnpickle}) to work! }

 }

 
\section{\textcolor{Chapter }{Extending the pickling framework}}\label{ExtPickFrame}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X17B1C9A9C17D3C0312}{}
{
  The framework can be extended for other \textsf{GAP} object types as follows: 

 For pickling, a method for the operation \texttt{IO{\textunderscore}Pickle} (\ref{IOPickle}) has to be installed which does the work. If the object to be pickled has
subobjects, then the first action of the method is to call the function \texttt{IO{\textunderscore}AddToPickled} with the object as argument. This will put it into the pickle cache and take
care of self-references. Arbitrary subobjects can then be pickled using
recursive calls to the operation \texttt{IO{\textunderscore}Pickle} (\ref{IOPickle}) handing down the same \texttt{File} object into the recursion. The method must either return \texttt{IO{\textunderscore}Error} in case of an error or \texttt{IO{\textunderscore}OK} if everything goes well. Before returning, a method that has called \texttt{IO{\textunderscore}AddToPickled} must call the function \texttt{IO{\textunderscore}FinalizePickled} without arguments \emph{under all circumstances}. If this call is missing, global data for the pickling procedure becomes
corrupt! 

 Every pickling method must first write a 4 byte magic value such that later
during unpickling of the byte stream the right unpickling method can be called
(see below). Then it can write arbitrary data, however, this data should be
platform- and architecture independent, and it must be possible to unpickle it
later without ``lookahead''. 

 Pickling methods should usually not go into a break loop, because after
leaving the user has to call \texttt{IO{\textunderscore}ClearPickleCache} (\ref{IOClearPickleCache}) explicitly! 

 Unpickling is implemented as follows: For every 4 byte magic value there must
be a function bound to that value in the record \texttt{IO{\textunderscore}Unpicklers}. If the unpickling operation \texttt{IO{\textunderscore}Unpickle} (\ref{IOUnpickle}) encounters that magic value, it calls the corresponding unpickling function.
This function just gets one \texttt{File} object as argument. Since the magic value is already read, it can immediately
start with reading and rebuilding the serialised object in memory. The method
has to take care to restore the object including its type completely. 

 If an object type has subobjects, the unpickling function has to first create
a skeleton of the object without its subobjects, then call \texttt{IO{\textunderscore}AddToUnpickled} on this skeleton, \emph{before} unpickling subobjects. If things are not done in this order, the handling of
self-references down in the recursion will not work! An unpickling function
that has called \texttt{IO{\textunderscore}AddToUnpickled} at the beginning has to call \texttt{IO{\textunderscore}FinalizeUnpickled} without arguments before returning \emph{under all circumstances}! If this call is missing, global data for the unpickling procedure becomes
corrupt! 

 Of course, unpickling functions can recursively call \texttt{IO{\textunderscore}Unpickle} (\ref{IOUnpickle}) to unpickle subobjects. Apart from this, unpickling functions can use
arbitrary reading functions on the \texttt{File} object. However, they should only read sequentially and never move the current
file position pointer otherwise. An unpickling function should return the
newly created object or the value \texttt{IO{\textunderscore}Error} if an error occurred. They should never go into a break loop, because after
leaving the user has to call \texttt{IO{\textunderscore}ClearPickleCache} (\ref{IOClearPickleCache}) explicitly! 

 Perhaps the best way to learn how to extend the framework is to study the code
for the basic \textsf{GAP} objects in the file \texttt{pkg/io/gap/pickle.gi}. }

 }

 
\chapter{\textcolor{Chapter }{Really random sources}}\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X178A8811F17BD55ABA}{}
{
  This section describes so called ``real random sources''. It is an extension to the library mechanism of random source objects that
uses the devices \texttt{/dev/random} and \texttt{/dev/urandom} available on \texttt{Linux} systems (and maybe on other operating systems) providing random numbers that
are impossible to predict. The idea is that such sources of random numbers are
useful to produce unpredictable secret keys for cryptographic applications. 
\section{\textcolor{Chapter }{The functions}}\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X8173135A17D187358}{}
{
  

\subsection{\textcolor{Chapter }{RandomSource}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X17CB0B5BC82F8FD8F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RandomSource({\slshape rdev})\index{RandomSource@\texttt{RandomSource}}
\label{RandomSource}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 a real random source object or \texttt{fail} 



 The first argument \mbox{\texttt{\slshape r}} must be the \textsf{GAP} filter \texttt{IsRealRandomSource} and the second either the string \texttt{random} or the string \texttt{urandom}. A real random source object is created that draws its random numbers from
the kernel devices \texttt{/dev/random} and \texttt{/dev/urandom} respectively. Whereas \texttt{/dev/random} always provides random numbers of not guaranteed ``quality'', the device \texttt{/dev/urandom} measures its entropy and produces guaranteed unpredictable numbers. However,
it might block until enough ``random'' events (like mouse movements) have been accumulated. }

 }

 }

 
\chapter{\textcolor{Chapter }{A client side implementation of the HTTP protocol}}\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X179DA05BB17CCC1749}{}
{
  The \textsf{IO} package contains an implementation of the client side of the HTTP protocol.
The basic purpose of this is of course to be able to download data from web
servers from the \textsf{GAP} language. However, the HTTP protocol can perform a much bigger variety of
tasks. 
\section{\textcolor{Chapter }{Functions for client side HTTP}}\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X17E8B5F0A87F2C1F7}{}
{
  

\subsection{\textcolor{Chapter }{OpenHTTPConnection}}
\logpage{[ 7, 1, 1 ]}\nobreak
\hyperdef{L}{X17B5588D5856BE6DD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OpenHTTPConnection({\slshape hostname, port})\index{OpenHTTPConnection@\texttt{OpenHTTPConnection}}
\label{OpenHTTPConnection}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record 



 The first argument \mbox{\texttt{\slshape hostname}} must be a string containing the hostname of the server to connect. The second
argument \mbox{\texttt{\slshape port}} must be an integer in the range from $1$ to $65535$ and describes the port to connect to on the server. 

 The function opens a TCP/IP connection to the server and returns a record \texttt{conn} with the following components: \texttt{conn.sock} is \texttt{fail} if an error occurs and otherwise a \texttt{File} object linked to the file descriptor of the socket. In case of an error, the
component \texttt{conn.errormsg} contains an error message, it is otherwise empty. If everything went well then
the component \texttt{conn.host} is the result from the host name lookup (see \texttt{IO{\textunderscore}gethostbyname} (\ref{IOgethostbyname})) and the component \texttt{conn.closed} is set to \texttt{false}. 

 No data is sent or received on the socket in this function. }

 

\subsection{\textcolor{Chapter }{HTTPRequest}}
\logpage{[ 7, 1, 2 ]}\nobreak
\hyperdef{L}{X80FF9E3017BDA0659}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HTTPRequest({\slshape conn, method, uri, header, body, target})\index{HTTPRequest@\texttt{HTTPRequest}}
\label{HTTPRequest}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record 



 This function performs a complete HTTP request. The first argument must be a
connection record as returned by a successful call to \texttt{OpenHTTPConnection} (\ref{OpenHTTPConnection}). The argument \mbox{\texttt{\slshape method}} must be a valid HTTP request ``method'' in form of a string. The most common will be \texttt{GET}, \texttt{POST}, or \texttt{HEAD}. The argument \mbox{\texttt{\slshape uri}} is a string containing the URI of the request, which is given in the first
line of the request. This will usually be a relative or absolute path name
given to the server. The argument \mbox{\texttt{\slshape header}} must be a \textsf{GAP} record. Each bound field of this record will we transformed into one header
line with the name of the component being the key and the value the value. All
bound values must be strings. The argument \mbox{\texttt{\slshape body}} must either be a string or \texttt{false}. If it is a string, this string is sent away as the body of the request. If
no string or an empty string is given, no body will be sent. The header field \texttt{Content-Length} is automatically created from the length of the string \mbox{\texttt{\slshape body}}. Finally, the argument \mbox{\texttt{\slshape target}} can either be \texttt{false} or a string. In the latter case, the body of the request answer is written to
the file with the name given in \mbox{\texttt{\slshape target}}. The \texttt{body} component of the result will be the file name in this case. If \mbox{\texttt{\slshape target}} is false, the full body of the answer is stored into the \texttt{body} component of the result. 

 The function sends away the request and awaits the answer. If anything goes
wrong during the transfer (for example if the connection is broken
prematurely), then the component \texttt{statuscode} of the resulting record is $0$ and the component \texttt{status} is a corresponding error message. In that case, all other fields may or may
not be bound to sensible values, according to when the error occurred. If
everything goes well, then \texttt{statuscode} and \texttt{status} are bound to the corresponding values coming from the request answer. \texttt{statuscode} is transformed into a \textsf{GAP} integer. The header of the answer is parsed, transformed into a \textsf{GAP} record, and stored into the component \texttt{header} of the result. The \texttt{body} component of the result record is set as described above. Finally, the \texttt{protoversion} component contains the HTTP protocol version number used by the server as a
string and the boolean value \texttt{closed} indicates, whether or not the function has detected, that the connection has
been closed by the server. Note that by default, the connection will stay
open, at least for a certain time after the end of the request.

 See the description of the global variable \texttt{HTTPTimeoutForSelect} (\ref{HTTPTimeoutForSelect}) for rules how timeouts are done in this function. 

 Note that if the \mbox{\texttt{\slshape method}} is \texttt{HEAD}, then no body is expected (none will be sent anyway) and the function returns
immediately with empty body. Of course, the \texttt{Content-Length} value in the header is as if it the request would be done with the \texttt{GET} method. }

 

\subsection{\textcolor{Chapter }{HTTPTimeoutForSelect}}
\logpage{[ 7, 1, 3 ]}\nobreak
\hyperdef{L}{X83526BF3178B3D8F2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HTTPTimeoutForSelect\index{HTTPTimeoutForSelect@\texttt{HTTPTimeoutForSelect}}
\label{HTTPTimeoutForSelect}
}\hfill{\scriptsize (global variable)}}\\


 This global variable holds a list of length two. By default, both entries are \texttt{fail} indicating that \texttt{HTTPRequest} (\ref{HTTPRequest}) should never timeout and wait forever for an answer. Actually, the two values
in this variable are given to the \texttt{IO{\textunderscore}Select} (\ref{IOSelect}) function call during I/O multiplexing. That is, the first number is in seconds
and the second in milliseconds. Together they lead to a timeout for the HTTP
request. If a timeout occurs, an error condition is triggered which returns a
record with status code $0$ and status being the timeout error message.

 You can change the timeout by accessing the two entries of this write
protected list variable directly. }

 

\subsection{\textcolor{Chapter }{CloseHTTPConnection}}
\logpage{[ 7, 1, 4 ]}\nobreak
\hyperdef{L}{X81702FA017F2AF472}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CloseHTTPConnection({\slshape conn})\index{CloseHTTPConnection@\texttt{CloseHTTPConnection}}
\label{CloseHTTPConnection}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 Closes the connection described by the connection record \mbox{\texttt{\slshape conn}}. No error can possibly occur. }

 

\subsection{\textcolor{Chapter }{SingleHTTPRequest}}
\logpage{[ 7, 1, 5 ]}\nobreak
\hyperdef{L}{X17DBCB0B4801E4D6D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SingleHTTPRequest({\slshape hostname, port, method, uri, header, body, target})\index{SingleHTTPRequest@\texttt{SingleHTTPRequest}}
\label{SingleHTTPRequest}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record 



 The arguments are as the corresponding ones in the functions \texttt{OpenHTTPConnection} (\ref{OpenHTTPConnection}) and \texttt{HTTPRequest} (\ref{HTTPRequest}) respectively. This function opens an HTTP connection, tries a single HTTP
request and immediately closes the connection again. The result is as for the \texttt{HTTPRequest} (\ref{HTTPRequest}) function. If an error occurs during the opening of the connection, the \texttt{statuscode} value of the result is $0$ and the error message is stored in the \texttt{status} component of the result. }

 The previous function allows for a very simple implementation of a function
that checks, whether your current \textsf{GAP} installation is up to date: 

\subsection{\textcolor{Chapter }{CheckForUpdates}}
\logpage{[ 7, 1, 6 ]}\nobreak
\hyperdef{L}{X178BAF7A717F6BE631}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CheckForUpdates({\slshape })\index{CheckForUpdates@\texttt{CheckForUpdates}}
\label{CheckForUpdates}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This function accesses a web page in St. Andrews and runs some \textsf{GAP} code from there. This code knows all the currently released versions of \textsf{GAP} and its packages. It prints out a summary and possibly suggests upgrades. If
you do not want to executed code downloaded from the internet, then do not
call this function. 

 More concretely, the page accessed is \href{http://www.gap-system.org/Download/upgrade.html} {\texttt{http://www.gap-system.org/Download/upgrade.html}} and the code executed is a single call to the function \texttt{SuggestUpgrades} function in the \textsf{GAP} library. }

 }

 }

 
\chapter{\textcolor{Chapter }{Examples of usage}}\logpage{[ 8, 0, 0 ]}
\hyperdef{L}{X17EADF566874177D8}{}
{
  For larger examples see the \texttt{example} directory of the package. You find there a small server using the TCP/IP
protocol and a corresponding client and another small server using the UDP
protocol and a corresponding client. 

 Further, there is an example for the usage of \texttt{File} objects, that read from or write to strings.

 Another example there shows starting up a child process and piping a few
megabytes through it using \texttt{IO{\textunderscore}Popen2} (\ref{IOPopen2}). 

 In the following, we present a few explicit, interactive short examples for
the usage of the functions in this package. Note that you have to load the \textsf{IO} package with the command \texttt{LoadPackage("IO");} before trying these examples. 
\section{\textcolor{Chapter }{Writing and reading a file}}\logpage{[ 8, 1, 0 ]}
\hyperdef{L}{X17EC25CA68794860A}{}
{
  The following sequence of commands opens a file with name \texttt{guck} and writes some things to it: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := IO_File("guck","w");
  <file fd=3 wbufsize=65536 wdata=0>
  gap> IO_Write(f,"Hello world\n");
  12
  gap> IO_WriteLine(f,"Hello world2!");
  14
  gap> IO_Write(f,12345);
  5
  gap> IO_Flush(f);
  true
  gap> IO_Close(f);
  true
\end{Verbatim}
 There is nothing special about this, the numbers are numbers of bytes written.
Note that only after the \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) command the data is actually written to disk. Before that, it resides in the
write buffer of the file. Note further, that the \texttt{IO{\textunderscore}Flush} (\ref{IOFlush}) call here would not have been necessary, since the \texttt{IO{\textunderscore}Close} (\ref{IOClose}) call flushes the buffer anyway.

 The file can again be read with the following sequence of commands: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := IO_File("guck","r");
  <file fd=3 rbufsize=65536 rpos=1 rdata=0>
  gap> IO_Read(f,10);
  "Hello worl"
  gap> IO_ReadLine(f);
  "d\n"
  gap> IO_ReadLine(f);
  "Hello world2!\n"
  gap> IO_ReadLine(f);
  "12345"
  gap> IO_ReadLine(f);
  ""
  gap> IO_Close(f);
  true
\end{Verbatim}
 Note here that reading line-wise can only be done efficiently by using
buffered I/O. You can mix calls to \texttt{IO{\textunderscore}Read} (\ref{IORead}) and to \texttt{IO{\textunderscore}ReadLine} (\ref{IOReadLine}). The end of file is indicated by an empty string returned by one of the read
functions. }

 
\section{\textcolor{Chapter }{Using filtering programs to read and write files}}\logpage{[ 8, 2, 0 ]}
\hyperdef{L}{X17AECE665813D6E4D}{}
{
  If you want to write a big amount of data to file you might want to compress
it on the fly without using much disk space. This can be achieved with the
following command: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> s := "";; for i in [1..10000] do Append(s,String(i)); od;;
  gap> Length(s);
  38894
  gap> IO_FileFilterString("guck.gz",[["gzip",["-9c"]]],s);
  true
  gap> sgz := StringFile("guck.gz");;
  gap> Length(sgz);
  18541
  gap> ss := IO_StringFilterFile([["gzip",["-dc"]]],"guck.gz");;
  gap> s=ss;
  true
\end{Verbatim}
 This sequence of commands needs that the program \texttt{gzip} is installed on your system. }

 
\section{\textcolor{Chapter }{Using filters when reading or writing files sequentially}}\logpage{[ 8, 3, 0 ]}
\hyperdef{L}{X17A8A180D17B335151}{}
{
  If you want to process bigger amounts of data you might not want to store all
of it in a single \textsf{GAP} string. In that case you might want to access a file on disk sequentially
through a filter: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := IO_FilteredFile([["gzip",["-9c"]]],"guck.gz","w");
  <file fd=5 wbufsize=65536 wdata=0>
  gap> IO_Write(f,"Hello world!\n");
  13
  gap> IO_Write(f,Elements(SymmetricGroup(5)),"\n");
  1359
  gap> IO_Close(f);
  true
  gap> f := IO_FilteredFile([["gzip",["-dc"]]],"guck.gz","r");
  <file fd=4 rbufsize=65536 rpos=1 rdata=0>
  gap> IO_ReadLine(f);
  "Hello world!\n"
  gap> s := IO_ReadLine(f);; Length(s);
  1359
  gap> IO_Read(f,10);                  
  ""
  gap> IO_Close(f);
  true
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Accessing a web page}}\logpage{[ 8, 4, 0 ]}
\hyperdef{L}{X17BD2BF7F87573C69}{}
{
  The \textsf{IO} package has an HTTP client implementation. Using this you can access web pages
and other web downloads from within \textsf{GAP}. Here is an example: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> r := SingleHTTPRequest("www.math.rwth-aachen.de",80,"GET",
  >              "/~Max.Neunhoeffer/index.html",rec(),false,false);;
  gap> RecFields(r);
  [ "protoversion", "statuscode", "status", "header", "body", "closed" ]
  gap> r.status;
  "OK"
  gap> r.statuscode;
  200
  gap> r.header;
  rec( date := "Thu, 07 Dec 2006 22:08:22 GMT", 
    server := "Apache/2.0.55 (Ubuntu)", 
    last-modified := "Thu, 16 Nov 2006 00:21:44 GMT", 
    etag := "\"2179cf-11a5-3c77f600\"", accept-ranges := "bytes", 
    content-length := "4517", content-type := "text/html; charset=ISO-8859-1" )
  gap> Length(r.body);
  4517
\end{Verbatim}
 Of course, the time stamps and exact sizes of the answer may differ when you
do this. }

 
\section{\textcolor{Chapter }{(Un-)Pickling}}\logpage{[ 8, 5, 0 ]}
\hyperdef{L}{X81BD8400832EE20B}{}
{
  Assume you have some \textsf{GAP} objects you want to archive to disk grouped together. Then you might do the
following: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> r := rec( a := 1, b := "Max", c := [1,2,3] );
  rec( a := 1, b := "Max", c := [ 1, 2, 3 ] )
  gap> r.c[4] := r;
  rec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )
  gap> f := IO_File("guck","w");
  <file fd=3 wbufsize=65536 wdata=0>
  gap> IO_Pickle(f,r);
  IO_OK
  gap> IO_Pickle(f,[(1,2,3,4),(3,4)]);
  IO_OK
  gap> IO_Close(f);
  true
\end{Verbatim}
 Then, to read it in again, just do: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := IO_File("guck");
  <file fd=3 rbufsize=65536 rpos=1 rdata=0>
  gap> IO_Unpickle(f);
  rec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )
  gap> IO_Unpickle(f);
  [ (1,2,3,4), (3,4) ]
  gap> IO_Unpickle(f);
  IO_Nothing
  gap> IO_Close(f);
  true
\end{Verbatim}
 Note that this works for a certain amount of builtin objects. If you want to
archive your own objects or more sophisticated objects you have to use extend
the functionality as explained in Section \ref{ExtPickFrame}. However, it works for lists and records and they may be arbitrarily
self-referential. }

 }

 
\chapter{\textcolor{Chapter }{License}}\logpage{[ 9, 0, 0 ]}
\hyperdef{L}{X861E5DF986F89AE2}{}
{
  This package is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; version 2 or greater of the License.

 This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

 You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place, Suite 330, Boston, MA 02111-1307 USA }

 \def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}