% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\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{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}


\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}


\usepackage[
            pdftex=true,
            bookmarks=true,        
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone}, 
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% 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,}}
%% were never documented, give conflicts with some additional packages

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

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}





%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}


\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{ IO \\
\mbox{}}}\\
\vfill

\hypersetup{pdftitle={ IO }}
\markright{\scriptsize \mbox{}\hfill  IO  \hfill\mbox{}}
{\Huge \textbf{ Bindings for low level C library I/O routines \\
\mbox{}}}\\
\vfill

{\Huge  4.10.0 \mbox{}}\\[1cm]
{ 14 July 2026 \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{\strut  Max Neunh{\"o}ffer   \strut\mbox{}}}\\
\hypersetup{pdfauthor={ Max Neunh{\"o}ffer  }}
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Max Neunh{\"o}ffer  }  Email: \href{mailto://max@9hoeffer.de} {\texttt{max@9hoeffer.de}}}\\
\end{titlepage}

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

 This package may be distributed under the terms and conditions of the GNU
Public License Version 3 or later (at your convenience). \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\texttt{\symbol{45}}level
I/O functions in the C\texttt{\symbol{45}}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.

 For bug reports, feature requests and suggestions, please use our \href{https://github.com/gap-packages/io/issues} {issue tracker}. }

 
\chapter{\textcolor{Chapter }{Installation of the \textsf{IO}\texttt{\symbol{45}}package}}\label{Chap-Install}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X8203E34B78787118}{}
{
  To get the newest version of this \textsf{GAP} 4 package download one of the archive files 
\begin{itemize}
\item  \texttt{io\texttt{\symbol{45}}x.x.tar.gz} 
\item  \texttt{io\texttt{\symbol{45}}x.x.tar.bz2} 
\item  \texttt{io\texttt{\symbol{45}}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}
 or 
\begin{verbatim}  
  bzip2 -d io-x.x.tar.bz2; tar xvf io-x.x.tar
\end{verbatim}
 or 
\begin{verbatim}  
  unzip -x io-x.x.zip
\end{verbatim}
 respectively. 

 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}''.

 The package will not work without the following compilation step.

 To compile the C part of the package do (in the \texttt{pkg} directory) 
\begin{verbatim}  
      cd io
      ./configure
      make
\end{verbatim}
 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 do two things. Firstly during compilation you
have to use the option \texttt{\texttt{\symbol{45}}\texttt{\symbol{45}}with\texttt{\symbol{45}}gaproot=PATH} of the \texttt{configure} script where ``PATH'' is a path to the main \textsf{GAP} root directory (if not given the default ``\texttt{../..}'' is assumed). 

 Secondly you have to specify 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{\texttt{\symbol{45}}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 }{Recompiling the documentation}}\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7FB00ED2787027A3}{}
{
  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{getcwd}, \texttt{getenv}, \texttt{gethostbyname}, \texttt{gethostname}, \texttt{getpid}, \texttt{getppid}, \texttt{getsockname}, \texttt{getsockopt}, \texttt{gettimeofday}, \texttt{gmtime}, \texttt{kill}, \texttt{lchown}, \texttt{link}, \texttt{listen}, \texttt{localtime}, \texttt{lseek}, \texttt{lstat}, \texttt{mkdir}, \texttt{mkfifo}, \texttt{mknod}, \texttt{mkstemp}, \texttt{mkdtemp}, \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{setenv}, \texttt{setsockopt}, \texttt{socket}, \texttt{stat}, \texttt{symlink}, \texttt{telldir}, \texttt{unlink}, \texttt{unsetenv}, \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 \texttt{\symbol{45}}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 \texttt{\symbol{45}} an overview}}\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X85D3551379BA32FC}{}
{
  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{\mdseries\slshape fd}} is an integer file descriptor, \mbox{\texttt{\mdseries\slshape st}} is a \textsf{GAP} string, \mbox{\texttt{\mdseries\slshape offset}} is an offset within this string (zero based), and \mbox{\texttt{\mdseries\slshape count}} is the maximal number of bytes to read. The data is read and stored into the
string \mbox{\texttt{\mdseries\slshape st}}, starting at position $\mbox{\texttt{\mdseries\slshape offset}}+1$. The string \mbox{\texttt{\mdseries\slshape st}} is made long enough, such that \mbox{\texttt{\mdseries\slshape count}} bytes would fit into it, beginning at position $\mbox{\texttt{\mdseries\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{\mdseries\slshape fd}} is an integer file descriptor, \mbox{\texttt{\mdseries\slshape st}} is a \textsf{GAP} string, \mbox{\texttt{\mdseries\slshape offset}} is an offset within this string (zero based), and \mbox{\texttt{\mdseries\slshape count}} is the number of bytes to write, starting from position $\mbox{\texttt{\mdseries\slshape offset}}+1$ in the string \mbox{\texttt{\mdseries\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{IOuScoremakeuScoresockaddruScorein}) and \texttt{IO{\textunderscore}MakeIPAddressPort} (\ref{IOuScoreMakeIPAddressPort}) to create such addresses. The first takes two arguments \mbox{\texttt{\mdseries\slshape addr}} and \mbox{\texttt{\mdseries\slshape port}}, where \mbox{\texttt{\mdseries\slshape addr}} is a string of length 4, containing the 4 bytes of the IP address and \mbox{\texttt{\mdseries\slshape port}} is a port number as \textsf{GAP} integer. The function \texttt{IO{\textunderscore}MakeIPAddressPort} (\ref{IOuScoreMakeIPAddressPort}) takes the same arguments, but the first can be a string containing an IP
address in dot notation like ``137.226.152.77'' or a hostname to be looked up.

 The \texttt{setsockopt} function has no argument \mbox{\texttt{\mdseries\slshape optlen}}. The length of the string \mbox{\texttt{\mdseries\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\texttt{\symbol{45}}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\texttt{\symbol{45}}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}{X7E474E9787012FE4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}accept({\mdseries\slshape fd, addr})\index{IO{\textunderscore}accept@\texttt{IO{\textunderscore}accept}}
\label{IOuScoreaccept}
}\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{\mdseries\slshape addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOuScoremakeuScoresockaddruScorein}) and contains its length such that no third argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}bind}}
\logpage{[ 3, 2, 2 ]}\nobreak
\hyperdef{L}{X791A6341852001F8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}bind({\mdseries\slshape fd, my{\textunderscore}addr})\index{IO{\textunderscore}bind@\texttt{IO{\textunderscore}bind}}
\label{IOuScorebind}
}\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{\mdseries\slshape my{\textunderscore}addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOuScoremakeuScoresockaddruScorein}) and contains its length such that no third argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}chdir}}
\logpage{[ 3, 2, 3 ]}\nobreak
\hyperdef{L}{X790139B37E87FA61}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}chdir({\mdseries\slshape path})\index{IO{\textunderscore}chdir@\texttt{IO{\textunderscore}chdir}}
\label{IOuScorechdir}
}\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}chmod({\mdseries\slshape pathname, mode})\index{IO{\textunderscore}chmod@\texttt{IO{\textunderscore}chmod}}
\label{IOuScorechmod}
}\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}{X85C0617479E4D952}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}chown({\mdseries\slshape path, owner, group})\index{IO{\textunderscore}chown@\texttt{IO{\textunderscore}chown}}
\label{IOuScorechown}
}\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}{X820DA9C97C2E80BA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}close({\mdseries\slshape fd})\index{IO{\textunderscore}close@\texttt{IO{\textunderscore}close}}
\label{IOuScoreclose}
}\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}closedir({\mdseries\slshape })\index{IO{\textunderscore}closedir@\texttt{IO{\textunderscore}closedir}}
\label{IOuScoreclosedir}
}\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}{X7DE9D8B387D3A3D5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}connect({\mdseries\slshape fd, serv{\textunderscore}addr})\index{IO{\textunderscore}connect@\texttt{IO{\textunderscore}connect}}
\label{IOuScoreconnect}
}\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{\mdseries\slshape serv{\textunderscore}addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOuScoremakeuScoresockaddruScorein}) and contains its length such that no third argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}creat}}
\logpage{[ 3, 2, 9 ]}\nobreak
\hyperdef{L}{X78FCF69C7FCF3BD7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}creat({\mdseries\slshape pathname, mode})\index{IO{\textunderscore}creat@\texttt{IO{\textunderscore}creat}}
\label{IOuScorecreat}
}\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}{X7DAAD93A80F76681}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}dup({\mdseries\slshape oldfd})\index{IO{\textunderscore}dup@\texttt{IO{\textunderscore}dup}}
\label{IOuScoredup}
}\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}{X7F7B8FAC7ABA285B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}dup2({\mdseries\slshape oldfd, newfd})\index{IO{\textunderscore}dup2@\texttt{IO{\textunderscore}dup2}}
\label{IOuScoredup2}
}\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}{X7B30A7FA84692EC5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}execv({\mdseries\slshape path, argv})\index{IO{\textunderscore}execv@\texttt{IO{\textunderscore}execv}}
\label{IOuScoreexecv}
}\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{\mdseries\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}execve({\mdseries\slshape path, argv, envp})\index{IO{\textunderscore}execve@\texttt{IO{\textunderscore}execve}}
\label{IOuScoreexecve}
}\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{\mdseries\slshape argv}} and \mbox{\texttt{\mdseries\slshape envp}} are both lists of strings. The called program does not have to be the first
argument in \mbox{\texttt{\mdseries\slshape argv}}. The list \mbox{\texttt{\mdseries\slshape envp}} can be made with \texttt{IO{\textunderscore}MakeEnvList} (\ref{IOuScoreMakeEnvList}) from a record acquired from \texttt{IO{\textunderscore}Environment} (\ref{IOuScoreEnvironment}) and modified later. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}execvp}}
\logpage{[ 3, 2, 14 ]}\nobreak
\hyperdef{L}{X818044D07C64A412}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}execvp({\mdseries\slshape path, argv})\index{IO{\textunderscore}execvp@\texttt{IO{\textunderscore}execvp}}
\label{IOuScoreexecvp}
}\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{\mdseries\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}{X843634347E88C357}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}exit({\mdseries\slshape status})\index{IO{\textunderscore}exit@\texttt{IO{\textunderscore}exit}}
\label{IOuScoreexit}
}\hfill{\scriptsize (function)}}\\


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

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}fchmod}}
\logpage{[ 3, 2, 16 ]}\nobreak
\hyperdef{L}{X7F08E1187BDB619A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}fchmod({\mdseries\slshape fd, mode})\index{IO{\textunderscore}fchmod@\texttt{IO{\textunderscore}fchmod}}
\label{IOuScorefchmod}
}\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}{X791C4B4A81059A88}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}fchown({\mdseries\slshape fd, owner, group})\index{IO{\textunderscore}fchown@\texttt{IO{\textunderscore}fchown}}
\label{IOuScorefchown}
}\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}{X7870647E866D29A4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}fcntl({\mdseries\slshape fd, cmd, arg})\index{IO{\textunderscore}fcntl@\texttt{IO{\textunderscore}fcntl}}
\label{IOuScorefcntl}
}\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}{X86C819F37D07ECF7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}fork({\mdseries\slshape })\index{IO{\textunderscore}fork@\texttt{IO{\textunderscore}fork}}
\label{IOuScorefork}
}\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 \texttt{IO{\textunderscore}fork} activates our SIGCHLD handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOuScoreInstallSIGCHLDHandler})). Note that you must use the \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) function to wait or check for the termination of child processes, or call \texttt{IO{\textunderscore}IgnorePid} (\ref{IOuScoreIgnorePid}) to ignore the child. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}fstat}}
\logpage{[ 3, 2, 20 ]}\nobreak
\hyperdef{L}{X7E27748983EC7B5C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}fstat({\mdseries\slshape fd})\index{IO{\textunderscore}fstat@\texttt{IO{\textunderscore}fstat}}
\label{IOuScorefstat}
}\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}getcwd}}
\logpage{[ 3, 2, 21 ]}\nobreak
\hyperdef{L}{X826D86AF8013F184}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}getcwd({\mdseries\slshape })\index{IO{\textunderscore}getcwd@\texttt{IO{\textunderscore}getcwd}}
\label{IOuScoregetcwd}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Returns the current working directory. For details see ``\texttt{man 3 getcwd}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}getenv}}
\logpage{[ 3, 2, 22 ]}\nobreak
\hyperdef{L}{X84AECCE17832D6D8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}getenv({\mdseries\slshape name})\index{IO{\textunderscore}getenv@\texttt{IO{\textunderscore}getenv}}
\label{IOuScoregetenv}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Return the current value of the environment variable \mbox{\texttt{\mdseries\slshape name}}. If the variable is not in the current environment, \texttt{fail} is returned. For details see ``\texttt{man 3 getenv}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}gethostbyname}}
\logpage{[ 3, 2, 23 ]}\nobreak
\hyperdef{L}{X7DD25BDC79EE65AD}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}gethostbyname({\mdseries\slshape name})\index{IO{\textunderscore}gethostbyname@\texttt{IO{\textunderscore}gethostbyname}}
\label{IOuScoregethostbyname}
}\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}gethostname}}
\logpage{[ 3, 2, 24 ]}\nobreak
\hyperdef{L}{X7B7164EF8307D26B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}gethostname({\mdseries\slshape })\index{IO{\textunderscore}gethostname@\texttt{IO{\textunderscore}gethostname}}
\label{IOuScoregethostname}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Return host name. For details see ``\texttt{man 3 gethostname}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}getpid}}
\logpage{[ 3, 2, 25 ]}\nobreak
\hyperdef{L}{X7ECF948083E38BD0}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}getpid({\mdseries\slshape })\index{IO{\textunderscore}getpid@\texttt{IO{\textunderscore}getpid}}
\label{IOuScoregetpid}
}\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, 26 ]}\nobreak
\hyperdef{L}{X7EC6ABAB7AB9F40F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}getppid({\mdseries\slshape })\index{IO{\textunderscore}getppid@\texttt{IO{\textunderscore}getppid}}
\label{IOuScoregetppid}
}\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}getsockname}}
\logpage{[ 3, 2, 27 ]}\nobreak
\hyperdef{L}{X877A161482FC1769}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}getsockname({\mdseries\slshape fd})\index{IO{\textunderscore}getsockname@\texttt{IO{\textunderscore}getsockname}}
\label{IOuScoregetsockname}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Get a socket name. For details see ``\texttt{man 2 getsockname}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}getsockopt}}
\logpage{[ 3, 2, 28 ]}\nobreak
\hyperdef{L}{X790213D885BAB495}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}getsockopt({\mdseries\slshape fd, level, optname, optval})\index{IO{\textunderscore}getsockopt@\texttt{IO{\textunderscore}getsockopt}}
\label{IOuScoregetsockopt}
}\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{\mdseries\slshape optval}} carries its length around, such that no 5th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}gettimeofday}}
\logpage{[ 3, 2, 29 ]}\nobreak
\hyperdef{L}{X7BC965198011083B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}gettimeofday({\mdseries\slshape })\index{IO{\textunderscore}gettimeofday@\texttt{IO{\textunderscore}gettimeofday}}
\label{IOuScoregettimeofday}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 A record with components \texttt{tv{\textunderscore}sec} and \texttt{tv{\textunderscore}usec} 



 This returns the time elapsed since 1.1.1970, 0:00 GMT. The component \texttt{tv{\textunderscore}sec} contains the number of full seconds and the number \texttt{tv{\textunderscore}usec} the additional microseconds. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}gmtime}}
\logpage{[ 3, 2, 30 ]}\nobreak
\hyperdef{L}{X7DC156EA86F3F356}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}gmtime({\mdseries\slshape seconds})\index{IO{\textunderscore}gmtime@\texttt{IO{\textunderscore}gmtime}}
\label{IOuScoregmtime}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 A record 



 The argument is the number of seconds that have elapsed since 1.1.1970, 0:00
GMT. The result is a record with the current Greenwich mean time broken down
into date and time as in the C\texttt{\symbol{45}}library function \texttt{gmtime}. }

 

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



 Sends the signal \mbox{\texttt{\mdseries\slshape sig}} to the process with process ID \mbox{\texttt{\mdseries\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, 32 ]}\nobreak
\hyperdef{L}{X8305F97C87FE448E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}lchown({\mdseries\slshape path, owner, group})\index{IO{\textunderscore}lchown@\texttt{IO{\textunderscore}lchown}}
\label{IOuScorelchown}
}\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, 33 ]}\nobreak
\hyperdef{L}{X7E1C65EB84497185}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}link({\mdseries\slshape oldpath, newpath})\index{IO{\textunderscore}link@\texttt{IO{\textunderscore}link}}
\label{IOuScorelink}
}\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, 34 ]}\nobreak
\hyperdef{L}{X7957063B807025C7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}listen({\mdseries\slshape fd, backlog})\index{IO{\textunderscore}listen@\texttt{IO{\textunderscore}listen}}
\label{IOuScorelisten}
}\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}localtime}}
\logpage{[ 3, 2, 35 ]}\nobreak
\hyperdef{L}{X7B7D3D64805F335F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}localtime({\mdseries\slshape seconds})\index{IO{\textunderscore}localtime@\texttt{IO{\textunderscore}localtime}}
\label{IOuScorelocaltime}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 A record 



 The argument is the number of seconds that have elapsed since 1.1.1970, 0:00
GMT. The result is a record with the current local time broken down into date
and time as in the C\texttt{\symbol{45}}library function \texttt{localtime}. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}lseek}}
\logpage{[ 3, 2, 36 ]}\nobreak
\hyperdef{L}{X85C475187C824830}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}lseek({\mdseries\slshape fd, offset, whence})\index{IO{\textunderscore}lseek@\texttt{IO{\textunderscore}lseek}}
\label{IOuScorelseek}
}\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, 37 ]}\nobreak
\hyperdef{L}{X7A8C75038517A55A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}lstat({\mdseries\slshape name})\index{IO{\textunderscore}lstat@\texttt{IO{\textunderscore}lstat}}
\label{IOuScorelstat}
}\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, 38 ]}\nobreak
\hyperdef{L}{X83D968AB84F00ABF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}mkdir({\mdseries\slshape pathname, mode})\index{IO{\textunderscore}mkdir@\texttt{IO{\textunderscore}mkdir}}
\label{IOuScoremkdir}
}\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, 39 ]}\nobreak
\hyperdef{L}{X80BFF17A8099815F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}mkfifo({\mdseries\slshape pathname, mode})\index{IO{\textunderscore}mkfifo@\texttt{IO{\textunderscore}mkfifo}}
\label{IOuScoremkfifo}
}\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, 40 ]}\nobreak
\hyperdef{L}{X7928F1DB8379F850}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}mknod({\mdseries\slshape pathname, mode, dev})\index{IO{\textunderscore}mknod@\texttt{IO{\textunderscore}mknod}}
\label{IOuScoremknod}
}\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}mkstemp}}
\logpage{[ 3, 2, 41 ]}\nobreak
\hyperdef{L}{X82B09BF27D5AA458}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}mkstemp({\mdseries\slshape template})\index{IO{\textunderscore}mkstemp@\texttt{IO{\textunderscore}mkstemp}}
\label{IOuScoremkstemp}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



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

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}mkdtemp}}
\logpage{[ 3, 2, 42 ]}\nobreak
\hyperdef{L}{X7F9C9F4B7CB7977A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}mkdtemp({\mdseries\slshape template})\index{IO{\textunderscore}mkdtemp@\texttt{IO{\textunderscore}mkdtemp}}
\label{IOuScoremkdtemp}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Create a temporary directory. For details see ``\texttt{man 3 mkdtemp}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}open}}
\logpage{[ 3, 2, 43 ]}\nobreak
\hyperdef{L}{X8731A44E8032D9D2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}open({\mdseries\slshape pathname, flags, mode})\index{IO{\textunderscore}open@\texttt{IO{\textunderscore}open}}
\label{IOuScoreopen}
}\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, 44 ]}\nobreak
\hyperdef{L}{X78E234797EB01883}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}opendir({\mdseries\slshape name})\index{IO{\textunderscore}opendir@\texttt{IO{\textunderscore}opendir}}
\label{IOuScoreopendir}
}\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, 45 ]}\nobreak
\hyperdef{L}{X7C8F0A44837BBE8C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}pipe({\mdseries\slshape })\index{IO{\textunderscore}pipe@\texttt{IO{\textunderscore}pipe}}
\label{IOuScorepipe}
}\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, 46 ]}\nobreak
\hyperdef{L}{X84F3D862836BF17C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}read({\mdseries\slshape fd, st, offset, count})\index{IO{\textunderscore}read@\texttt{IO{\textunderscore}read}}
\label{IOuScoreread}
}\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{\mdseries\slshape offset}} to specify at which position in the string \mbox{\texttt{\mdseries\slshape st}} the read data should be stored. Note that \mbox{\texttt{\mdseries\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, 47 ]}\nobreak
\hyperdef{L}{X8410C6F17DE9302D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}readdir({\mdseries\slshape })\index{IO{\textunderscore}readdir@\texttt{IO{\textunderscore}readdir}}
\label{IOuScorereaddir}
}\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, 48 ]}\nobreak
\hyperdef{L}{X7943F25E7EBA9A6B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}readlink({\mdseries\slshape path, buf, bufsize})\index{IO{\textunderscore}readlink@\texttt{IO{\textunderscore}readlink}}
\label{IOuScorereadlink}
}\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{\mdseries\slshape buf}} is modified. The new length of \mbox{\texttt{\mdseries\slshape buf}} is returned or \texttt{fail} in case of an error. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}recv}}
\logpage{[ 3, 2, 49 ]}\nobreak
\hyperdef{L}{X78EB295E78B363B2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}recv({\mdseries\slshape fd, st, offset, len, flags})\index{IO{\textunderscore}recv@\texttt{IO{\textunderscore}recv}}
\label{IOuScorerecv}
}\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{\mdseries\slshape offset}} which plays the same role as for the \texttt{IO{\textunderscore}read} (\ref{IOuScoreread}) function. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}recvfrom}}
\logpage{[ 3, 2, 50 ]}\nobreak
\hyperdef{L}{X84C617887EE02EB4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}recvfrom({\mdseries\slshape fd, st, offset, len, flags, addr})\index{IO{\textunderscore}recvfrom@\texttt{IO{\textunderscore}recvfrom}}
\label{IOuScorerecvfrom}
}\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{\mdseries\slshape offset}} which plays the same role as for the \texttt{IO{\textunderscore}read} (\ref{IOuScoreread}) function. The argument \mbox{\texttt{\mdseries\slshape addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOuScoremakeuScoresockaddruScorein}) and contains its length such that no 7th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}rename}}
\logpage{[ 3, 2, 51 ]}\nobreak
\hyperdef{L}{X78EC95007A92AB69}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}rename({\mdseries\slshape oldpath, newpath})\index{IO{\textunderscore}rename@\texttt{IO{\textunderscore}rename}}
\label{IOuScorerename}
}\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, 52 ]}\nobreak
\hyperdef{L}{X7F86DBEB7876FBA5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}rewinddir({\mdseries\slshape })\index{IO{\textunderscore}rewinddir@\texttt{IO{\textunderscore}rewinddir}}
\label{IOuScorerewinddir}
}\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{IOuScoreopendir}) command has been called. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}rmdir}}
\logpage{[ 3, 2, 53 ]}\nobreak
\hyperdef{L}{X7FA4DD537C83A199}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}rmdir({\mdseries\slshape name})\index{IO{\textunderscore}rmdir@\texttt{IO{\textunderscore}rmdir}}
\label{IOuScorermdir}
}\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, 54 ]}\nobreak
\hyperdef{L}{X84A98D2380BF6574}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}seekdir({\mdseries\slshape offset})\index{IO{\textunderscore}seekdir@\texttt{IO{\textunderscore}seekdir}}
\label{IOuScoreseekdir}
}\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, 55 ]}\nobreak
\hyperdef{L}{X81CA6EE88062010E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}select({\mdseries\slshape inlist, outlist, exclist, timeoutsec, timeoutusec})\index{IO{\textunderscore}select@\texttt{IO{\textunderscore}select}}
\label{IOuScoreselect}
}\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{\mdseries\slshape inlist}}, \mbox{\texttt{\mdseries\slshape outlist}} and \mbox{\texttt{\mdseries\slshape exclist}} are lists of filedescriptors, which are modified. If the corresponding file
descriptor is not yet ready, it is replaced by \texttt{fail}. The timeout values \mbox{\texttt{\mdseries\slshape timeoutsec}} and \mbox{\texttt{\mdseries\slshape timeoutusec}} correspond to the usual arguments of \texttt{select}, if both are immediate integers, they are set, otherwise \texttt{select} is called with no timeout value. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}send}}
\logpage{[ 3, 2, 56 ]}\nobreak
\hyperdef{L}{X87019FD887F55C27}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}send({\mdseries\slshape fd, st, offset, len, flags})\index{IO{\textunderscore}send@\texttt{IO{\textunderscore}send}}
\label{IOuScoresend}
}\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{\mdseries\slshape offset}} specifies the position of the data to send within the string \mbox{\texttt{\mdseries\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, 57 ]}\nobreak
\hyperdef{L}{X8388B0147B5745EC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}sendto({\mdseries\slshape fd, st, offset, len, flags, addr})\index{IO{\textunderscore}sendto@\texttt{IO{\textunderscore}sendto}}
\label{IOuScoresendto}
}\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{\mdseries\slshape offset}} specifies the position of the data to send within the string \mbox{\texttt{\mdseries\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{\mdseries\slshape addr}} can be made with \texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in} (\ref{IOuScoremakeuScoresockaddruScorein}) and contains its length such that no 7th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}setenv}}
\logpage{[ 3, 2, 58 ]}\nobreak
\hyperdef{L}{X7D2AB8E985C56AD4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}setenv({\mdseries\slshape name, value, overvwrite})\index{IO{\textunderscore}setenv@\texttt{IO{\textunderscore}setenv}}
\label{IOuScoresetenv}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Set the current value of the environment variable \mbox{\texttt{\mdseries\slshape name}} to \mbox{\texttt{\mdseries\slshape value}} if it has either not been set before, or \mbox{\texttt{\mdseries\slshape overwrite}} is \texttt{true}. For details see ``\texttt{man 3 setenv}''. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}setsockopt}}
\logpage{[ 3, 2, 59 ]}\nobreak
\hyperdef{L}{X7BE641C1784D0899}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}setsockopt({\mdseries\slshape fd, level, optname, optval})\index{IO{\textunderscore}setsockopt@\texttt{IO{\textunderscore}setsockopt}}
\label{IOuScoresetsockopt}
}\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{\mdseries\slshape optval}} carries its length around, such that no 5th argument is necessary. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}socket}}
\logpage{[ 3, 2, 60 ]}\nobreak
\hyperdef{L}{X852B16CF82B96C84}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}socket({\mdseries\slshape domain, type, protocol})\index{IO{\textunderscore}socket@\texttt{IO{\textunderscore}socket}}
\label{IOuScoresocket}
}\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{\mdseries\slshape protocol}} which is automatically looked up by \texttt{getprotobyname}. }

 

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



 Returns the file metadata for the file \mbox{\texttt{\mdseries\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, 62 ]}\nobreak
\hyperdef{L}{X7B0D9CEF7A3CD431}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}symlink({\mdseries\slshape oldpath, newpath})\index{IO{\textunderscore}symlink@\texttt{IO{\textunderscore}symlink}}
\label{IOuScoresymlink}
}\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, 63 ]}\nobreak
\hyperdef{L}{X81FF8B678748900B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}telldir({\mdseries\slshape })\index{IO{\textunderscore}telldir@\texttt{IO{\textunderscore}telldir}}
\label{IOuScoretelldir}
}\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, 64 ]}\nobreak
\hyperdef{L}{X78C93B6587B478C2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}unlink({\mdseries\slshape pathname})\index{IO{\textunderscore}unlink@\texttt{IO{\textunderscore}unlink}}
\label{IOuScoreunlink}
}\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}unsetenv}}
\logpage{[ 3, 2, 65 ]}\nobreak
\hyperdef{L}{X8103218E7C5CF577}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}unsetenv({\mdseries\slshape name})\index{IO{\textunderscore}unsetenv@\texttt{IO{\textunderscore}unsetenv}}
\label{IOuScoreunsetenv}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 Remove the environment variable \mbox{\texttt{\mdseries\slshape name}}. For details see ``\texttt{man 3 unsetenv}''. }

 

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



 Waits for the termination of a child process. For details see ``\texttt{man 2 waitpid}''. The first argument must be a process id, otherwise the function immediately
exits with \texttt{fail} as return value. 

 The second argument \mbox{\texttt{\mdseries\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. If the child process has not yet terminated,
returns \texttt{false}; otherwise, returns a \textsf{GAP} record describing the PID, the return value of waitpid, if the process exited
normally and the exit status of the process. 

 See \texttt{IO{\textunderscore}fork} (\ref{IOuScorefork}). If you do not care about the return value of the process, call \texttt{IO{\textunderscore}IgnorePid} (\ref{IOuScoreIgnorePid}). }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}IgnorePid}}
\logpage{[ 3, 2, 67 ]}\nobreak
\hyperdef{L}{X84295FC77CCB1066}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}IgnorePid({\mdseries\slshape pid})\index{IO{\textunderscore}IgnorePid@\texttt{IO{\textunderscore}IgnorePid}}
\label{IOuScoreIgnorePid}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing 



 Disowns a child process. This means there is no need to call \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}). Calling \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) on a pid which was previously passed to \texttt{IO{\textunderscore}IgnorePid} may cause an infinite loop.F }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}write}}
\logpage{[ 3, 2, 68 ]}\nobreak
\hyperdef{L}{X84EB06707D1BD3F1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}write({\mdseries\slshape fd, st, offset, count})\index{IO{\textunderscore}write@\texttt{IO{\textunderscore}write}}
\label{IOuScorewrite}
}\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{\mdseries\slshape offset}} specifies the position of the data to send within the string \mbox{\texttt{\mdseries\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}{X878007A67E806CEF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in({\mdseries\slshape ip, port})\index{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in@\texttt{IO{\textunderscore}make{\textunderscore}sockaddr{\textunderscore}in}}
\label{IOuScoremakeuScoresockaddruScorein}
}\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}{X7F3E88AD7EFD52F4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}environ({\mdseries\slshape })\index{IO{\textunderscore}environ@\texttt{IO{\textunderscore}environ}}
\label{IOuScoreenviron}
}\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}InstallSIGCHLDHandler({\mdseries\slshape })\index{IO{\textunderscore}InstallSIGCHLDHandler@\texttt{IO{\textunderscore}}\-\texttt{Install}\-\texttt{S}\-\texttt{I}\-\texttt{G}\-\texttt{C}\-\texttt{H}\-\texttt{L}\-\texttt{D}\-\texttt{Handler}}
\label{IOuScoreInstallSIGCHLDHandler}
}\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. This function is automatically called
by any function which creates new processes, so never needs to be called
unless the handler was explictly disabled with \texttt{IO{\textunderscore}RestoreSIGCHLDHandler} (\ref{IOuScoreRestoreSIGCHLDHandler}) See \texttt{IO{\textunderscore}fork} (\ref{IOuScorefork}). }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}RestoreSIGCHLDHandler}}
\logpage{[ 3, 3, 4 ]}\nobreak
\hyperdef{L}{X7EEB7471816B64DF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}RestoreSIGCHLDHandler({\mdseries\slshape })\index{IO{\textunderscore}RestoreSIGCHLDHandler@\texttt{IO{\textunderscore}}\-\texttt{Restore}\-\texttt{S}\-\texttt{I}\-\texttt{G}\-\texttt{C}\-\texttt{H}\-\texttt{L}\-\texttt{D}\-\texttt{Handler}}
\label{IOuScoreRestoreSIGCHLDHandler}
}\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{IOuScoreInstallSIGCHLDHandler}). See \texttt{IO{\textunderscore}fork} (\ref{IOuScorefork}). }

 }

 }

 
\chapter{\textcolor{Chapter }{High level functions for buffered I/O}}\label{bufio}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7D6A3F7178CB6169}{}
{
  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\texttt{\symbol{45}}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\texttt{\symbol{45}}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}{X83C42F7778B704C7}{}
{
  The wrapped file objects are in the following category: 

\subsection{\textcolor{Chapter }{IsFile}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X80C9B80A80E3A555}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsFile({\mdseries\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}{X7DDB0BA6836DA208}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}WrapFD({\mdseries\slshape fd, rbufsize, wbufsize})\index{IO{\textunderscore}WrapFD@\texttt{IO{\textunderscore}WrapFD}}
\label{IOuScoreWrapFD}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object 



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

 \mbox{\texttt{\mdseries\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{\mdseries\slshape fd}} must be \texttt{\symbol{45}}1 and a \texttt{File} object that reads from that string is created.

 \mbox{\texttt{\mdseries\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{\mdseries\slshape fd}} must be \texttt{\symbol{45}}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}{X7EC160D07E815DBB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}File({\mdseries\slshape filename[, mode]})\index{IO{\textunderscore}File@\texttt{IO{\textunderscore}File}!mode}
\label{IOuScoreFile:mode}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}File({\mdseries\slshape filename[, bufsize]})\index{IO{\textunderscore}File@\texttt{IO{\textunderscore}File}!bufsize}
\label{IOuScoreFile:bufsize}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}File({\mdseries\slshape filename, mode, bufsize})\index{IO{\textunderscore}File@\texttt{IO{\textunderscore}File}!mode and bufsize}
\label{IOuScoreFile:mode and bufsize}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object or \texttt{fail} 



 The argument \mbox{\texttt{\mdseries\slshape filename}} must be a string specifying the path name of the file to work on. \mbox{\texttt{\mdseries\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{\mdseries\slshape mode}} is omitted, it defaults to ``r''. \mbox{\texttt{\mdseries\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{IOuScoreopen}) function is used and the result file descriptor is wrapped using \texttt{IO{\textunderscore}WrapFD} (\ref{IOuScoreWrapFD}) with \mbox{\texttt{\mdseries\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{IOuScoreFilteredFile}) 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\texttt{\symbol{45}}level functionality to acquire
open file descriptors. These can be wrapped into \texttt{File} objects using \texttt{IO{\textunderscore}WrapFD} (\ref{IOuScoreWrapFD}). }

 
\section{\textcolor{Chapter }{Reading and writing}}\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X818FA8A37C8BBB95}{}
{
  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}{X865A873E78C822B7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}ReadUntilEOF({\mdseries\slshape f})\index{IO{\textunderscore}ReadUntilEOF@\texttt{IO{\textunderscore}ReadUntilEOF}}
\label{IOuScoreReadUntilEOF}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 This function reads all data from the file \mbox{\texttt{\mdseries\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{IOuScoreClose}) on the \texttt{File} object to properly close the file later. }

 

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



 This function gets two arguments, the first argument \mbox{\texttt{\mdseries\slshape f}} must be a \texttt{File} object and the second argument \mbox{\texttt{\mdseries\slshape len}} must be a positive integer. The function tries to read \mbox{\texttt{\mdseries\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{\mdseries\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}{X8738708E7B9DF8DB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}ReadLine({\mdseries\slshape f})\index{IO{\textunderscore}ReadLine@\texttt{IO{\textunderscore}ReadLine}}
\label{IOuScoreReadLine}
}\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{\mdseries\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{\mdseries\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}ReadLines({\mdseries\slshape f[, max]})\index{IO{\textunderscore}ReadLines@\texttt{IO{\textunderscore}ReadLines}}
\label{IOuScoreReadLines}
}\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{\mdseries\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{\mdseries\slshape max}} lines (with a second argument \mbox{\texttt{\mdseries\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{\mdseries\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}{X87E0AC547835F21D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}HasData({\mdseries\slshape f})\index{IO{\textunderscore}HasData@\texttt{IO{\textunderscore}HasData}}
\label{IOuScoreHasData}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 This function takes one argument \mbox{\texttt{\mdseries\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{\mdseries\slshape f}}. A return value of \texttt{true} guarantees that the next call to \texttt{IO{\textunderscore}Read} (\ref{IOuScoreRead}) 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}{$\triangleright$\enspace\texttt{IO{\textunderscore}Read({\mdseries\slshape f, len})\index{IO{\textunderscore}Read@\texttt{IO{\textunderscore}Read}}
\label{IOuScoreRead}
}\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{\mdseries\slshape f}}. The second argument must be a positive integer. The function reads data up
to \mbox{\texttt{\mdseries\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{\mdseries\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{IOuScoreHasData}) or to \texttt{IO{\textunderscore}Select} (\ref{IOuScoreSelect}) indicated that there is data available to read, then it is guaranteed that the
function \texttt{IO{\textunderscore}Read} 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}{X84EB06707D1BD3F1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Write({\mdseries\slshape f[, things, ...]})\index{IO{\textunderscore}Write@\texttt{IO{\textunderscore}Write}}
\label{IOuScoreWrite}
}\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{\mdseries\slshape f}}. All the other arguments are just written to \mbox{\texttt{\mdseries\slshape f}} if they are strings. Otherwise, the \texttt{String} function is called on them and the result is written out to \mbox{\texttt{\mdseries\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{IOuScoreFlush}) on \mbox{\texttt{\mdseries\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}WriteLine({\mdseries\slshape f, line})\index{IO{\textunderscore}WriteLine@\texttt{IO{\textunderscore}WriteLine}}
\label{IOuScoreWriteLine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Behaves like \texttt{IO{\textunderscore}Write} (\ref{IOuScoreWrite}) but works on a single string \mbox{\texttt{\mdseries\slshape line}} and sends an (operating system dependent) end of line string afterwards. Also \texttt{IO{\textunderscore}Flush} (\ref{IOuScoreFlush}) 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}{X87CE6EC17C1573AC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}WriteLines({\mdseries\slshape f, list})\index{IO{\textunderscore}WriteLines@\texttt{IO{\textunderscore}WriteLines}}
\label{IOuScoreWriteLines}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 Behaves like \texttt{IO{\textunderscore}Write} (\ref{IOuScoreWrite}) but works on a list of strings \mbox{\texttt{\mdseries\slshape list}} and sends an (operating system dependent) end of line string after each string
in the list. Also \texttt{IO{\textunderscore}Flush} (\ref{IOuScoreFlush}) 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}{X7873A49F7CC7ECFB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Flush({\mdseries\slshape f})\index{IO{\textunderscore}Flush@\texttt{IO{\textunderscore}Flush}}
\label{IOuScoreFlush}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 This function gets one argument \mbox{\texttt{\mdseries\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{IOuScoreClose}), since that function calls \texttt{IO{\textunderscore}Flush} automatically. However, it is necessary to call \texttt{IO{\textunderscore}Flush} after calls to \texttt{IO{\textunderscore}Write} (\ref{IOuScoreWrite}) 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{IOuScoreWriteLine}) and \texttt{IO{\textunderscore}WriteLines} (\ref{IOuScoreWriteLines}) implicitly call \texttt{IO{\textunderscore}Flush} 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}{X7870634278F6C69F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}WriteFlush({\mdseries\slshape f[, things]})\index{IO{\textunderscore}WriteFlush@\texttt{IO{\textunderscore}WriteFlush}}
\label{IOuScoreWriteFlush}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 This function behaves like \texttt{IO{\textunderscore}Write} (\ref{IOuScoreWrite}) followed by a call to \texttt{IO{\textunderscore}Flush} (\ref{IOuScoreFlush}). 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}{X80CF240F78664DF4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}ReadyForWrite({\mdseries\slshape f})\index{IO{\textunderscore}ReadyForWrite@\texttt{IO{\textunderscore}ReadyForWrite}}
\label{IOuScoreReadyForWrite}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 This function takes one argument \mbox{\texttt{\mdseries\slshape f}} which must be a \texttt{File} object. It returns \texttt{true} or \texttt{false} according to whether the file \mbox{\texttt{\mdseries\slshape f}} is ready to write. A return value of \texttt{true} guarantees that the next call to \texttt{IO{\textunderscore}WriteNonBlocking} (\ref{IOuScoreWriteNonBlocking}) 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}{$\triangleright$\enspace\texttt{IO{\textunderscore}WriteNonBlocking({\mdseries\slshape f, st, pos, len})\index{IO{\textunderscore}WriteNonBlocking@\texttt{IO{\textunderscore}WriteNonBlocking}}
\label{IOuScoreWriteNonBlocking}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 This function takes four arguments. The first one \mbox{\texttt{\mdseries\slshape f}} must be a \texttt{File} object, the second \mbox{\texttt{\mdseries\slshape st}} a string, and the arguments \mbox{\texttt{\mdseries\slshape pos}} and \mbox{\texttt{\mdseries\slshape len}} must be integers, such that positions $\mbox{\texttt{\mdseries\slshape pos}}+1$ until $\mbox{\texttt{\mdseries\slshape pos}}+\mbox{\texttt{\mdseries\slshape len}}$ are bound in \mbox{\texttt{\mdseries\slshape st}}. The function tries to write up to \mbox{\texttt{\mdseries\slshape len}} bytes from \mbox{\texttt{\mdseries\slshape st}} from position $\mbox{\texttt{\mdseries\slshape pos}}+1$ to the file \mbox{\texttt{\mdseries\slshape f}}. If a previous call to \texttt{IO{\textunderscore}ReadyForWrite} (\ref{IOuScoreReadyForWrite}) or to \texttt{IO{\textunderscore}Select} (\ref{IOuScoreSelect}) indicates that \mbox{\texttt{\mdseries\slshape f}} is writable, then it is guaranteed that the following call to \texttt{IO{\textunderscore}WriteNonBlocking} will not block and accept at least one byte of data. Note that it is not
guaranteed that all \mbox{\texttt{\mdseries\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}{X7C5786E07813434B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}ReadyForFlush({\mdseries\slshape f})\index{IO{\textunderscore}ReadyForFlush@\texttt{IO{\textunderscore}ReadyForFlush}}
\label{IOuScoreReadyForFlush}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 This function takes one argument \mbox{\texttt{\mdseries\slshape f}} which must be a \texttt{File} object. It returns \texttt{true} or \texttt{false} according to whether the file \mbox{\texttt{\mdseries\slshape f}} is ready to flush. A return value of \texttt{true} guarantees that the next call to \texttt{IO{\textunderscore}FlushNonBlocking} (\ref{IOuScoreFlushNonBlocking}) 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}{$\triangleright$\enspace\texttt{IO{\textunderscore}FlushNonBlocking({\mdseries\slshape f})\index{IO{\textunderscore}FlushNonBlocking@\texttt{IO{\textunderscore}FlushNonBlocking}}
\label{IOuScoreFlushNonBlocking}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true}, \texttt{false}, or \texttt{fail} 



 This function takes one argument \mbox{\texttt{\mdseries\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{IOuScoreReadyForFlush}) or \texttt{IO{\textunderscore}Select} (\ref{IOuScoreSelect}) indicated that \mbox{\texttt{\mdseries\slshape f}} is flushable, then it is guaranteed that the following call to \texttt{IO{\textunderscore}FlushNonBlocking} 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}{X820DA9C97C2E80BA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Close({\mdseries\slshape f})\index{IO{\textunderscore}Close@\texttt{IO{\textunderscore}Close}}
\label{IOuScoreClose}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 This function closes the \texttt{File} object \mbox{\texttt{\mdseries\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{IOuScoreWaitPid}). }

 }

 
\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}{X7F893EFC7D0C7BF2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}GetFD({\mdseries\slshape f})\index{IO{\textunderscore}GetFD@\texttt{IO{\textunderscore}GetFD}}
\label{IOuScoreGetFD}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer 



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

 

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



 This function gets one argument \mbox{\texttt{\mdseries\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}Select({\mdseries\slshape r, w, f, e, t1, t2})\index{IO{\textunderscore}Select@\texttt{IO{\textunderscore}Select}}
\label{IOuScoreSelect}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an integer or \texttt{fail} 



 This function is the corresponding function to \texttt{IO{\textunderscore}select} (\ref{IOuScoreselect}) for buffered file access. It behaves similarly to that function. The
differences are the following: There are four lists of files \mbox{\texttt{\mdseries\slshape r}}, \mbox{\texttt{\mdseries\slshape w}}, \mbox{\texttt{\mdseries\slshape f}}, and \mbox{\texttt{\mdseries\slshape e}}. They all can contain either integers (standing for file descriptors) or \texttt{File} objects. The list \mbox{\texttt{\mdseries\slshape r}} is for checking, whether files or file descriptors are ready to read, the list \mbox{\texttt{\mdseries\slshape w}} is for checking whether they are ready to write, the list \mbox{\texttt{\mdseries\slshape f}} is for checking whether they are ready to flush, and the list \mbox{\texttt{\mdseries\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{IOuScoreselect}) is called to get an overview about readiness. The timeout values \mbox{\texttt{\mdseries\slshape t1}} and \mbox{\texttt{\mdseries\slshape t2}} are set to zero for immediate returning if one of the requested buffers were
ready.

 \texttt{IO{\textunderscore}Select} 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}{X84B16DB878265F02}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}ListDir({\mdseries\slshape pathname})\index{IO{\textunderscore}ListDir@\texttt{IO{\textunderscore}ListDir}}
\label{IOuScoreListDir}
}\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. }

 

\subsection{\textcolor{Chapter }{ChangeDirectoryCurrent}}
\logpage{[ 4, 3, 5 ]}\nobreak
\hyperdef{L}{X81DDD2E87F68E086}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ChangeDirectoryCurrent({\mdseries\slshape pathname})\index{ChangeDirectoryCurrent@\texttt{ChangeDirectoryCurrent}}
\label{ChangeDirectoryCurrent}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} on success and \texttt{fail} on failure 



 Changes the current directory. Returns \texttt{true} on success and \texttt{fail} on failure. }

 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, 6 ]}\nobreak
\hyperdef{L}{X8568CE6684C90CE5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}MakeIPAddressPort({\mdseries\slshape ipstring, portnr})\index{IO{\textunderscore}MakeIPAddressPort@\texttt{IO{\textunderscore}}\-\texttt{Make}\-\texttt{I}\-\texttt{P}\-\texttt{Address}\-\texttt{Port}}
\label{IOuScoreMakeIPAddressPort}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string 



 This function gets a string \mbox{\texttt{\mdseries\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{\mdseries\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. The string \mbox{\texttt{\mdseries\slshape ipstring}} can also be a host name, which is then looked up using \texttt{IO{\textunderscore}gethostbyname} (\ref{IOuScoregethostbyname}) to find the IP address. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Environment}}
\logpage{[ 4, 3, 7 ]}\nobreak
\hyperdef{L}{X7F9AAE018474E1D8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Environment({\mdseries\slshape })\index{IO{\textunderscore}Environment@\texttt{IO{\textunderscore}Environment}}
\label{IOuScoreEnvironment}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Takes no arguments, uses \texttt{IO{\textunderscore}environ} (\ref{IOuScoreenviron}) 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{IOuScoreMakeEnvList}) to produce again a list which can be used for \texttt{IO{\textunderscore}execve} (\ref{IOuScoreexecve}) as third argument. }

 

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



 Takes a record as returned by \texttt{IO{\textunderscore}Environment} (\ref{IOuScoreEnvironment}) and turns it into a list of strings as needed by \texttt{IO{\textunderscore}execve} (\ref{IOuScoreexecve}) 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}{X84E91FE27A7860F3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}FindExecutable({\mdseries\slshape path})\index{IO{\textunderscore}FindExecutable@\texttt{IO{\textunderscore}FindExecutable}}
\label{IOuScoreFindExecutable}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{fail} or the path to an executable 



 If the path name \mbox{\texttt{\mdseries\slshape path}} contains a slash, this function simply checks whether the string \mbox{\texttt{\mdseries\slshape path}} refers to an executable file. If so, \mbox{\texttt{\mdseries\slshape path}} is returned as is. Otherwise, \texttt{fail} is returned. If the path name \mbox{\texttt{\mdseries\slshape path}} does not contain a slash, all directories in the environment variable \texttt{PATH} are searched for an executable with name \mbox{\texttt{\mdseries\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}{X7C43017E7AC5973A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}CloseAllFDs({\mdseries\slshape exceptions})\index{IO{\textunderscore}CloseAllFDs@\texttt{IO{\textunderscore}CloseAllFDs}}
\label{IOuScoreCloseAllFDs}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



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

 

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



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

 Starts a child process using the executable in \mbox{\texttt{\mdseries\slshape path}} with either stdout or stdin being a pipe. The argument \mbox{\texttt{\mdseries\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 as in
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 as in
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{IOuScoreClose}) function then calls \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) for it to acquire information about the terminated process. 

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

 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}{X7E05CF6481CBC0A1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Popen2({\mdseries\slshape path, argv})\index{IO{\textunderscore}Popen2@\texttt{IO{\textunderscore}Popen2}}
\label{IOuScorePopen2}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



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

 A new child process is started using the executable in \mbox{\texttt{\mdseries\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{IOuScoreClose}) for the \texttt{stdout} object will call \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) for it to acquire information about the terminated process. 

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

 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}{X7975BC6D80BC71E5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Popen3({\mdseries\slshape path, argv})\index{IO{\textunderscore}Popen3@\texttt{IO{\textunderscore}Popen3}}
\label{IOuScorePopen3}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



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

 A new child process is started using the executable in \mbox{\texttt{\mdseries\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{IOuScoreClose}) function for the \texttt{stdout} object will call \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) for it to acquire information about the terminated child process. 

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

 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}{X813219C17FB54731}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}StartPipeline({\mdseries\slshape progs, infd, outfd, switcherror})\index{IO{\textunderscore}StartPipeline@\texttt{IO{\textunderscore}StartPipeline}}
\label{IOuScoreStartPipeline}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 The argument \mbox{\texttt{\mdseries\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{IOuScoreFindExecutable})), the second an argument list, the argument \mbox{\texttt{\mdseries\slshape infd}} is an open file descriptor for reading, \mbox{\texttt{\mdseries\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{\mdseries\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{\mdseries\slshape infd}} and the output of the last to \mbox{\texttt{\mdseries\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{\mdseries\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{\mdseries\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{IOuScoreInstallSIGCHLDHandler})) and that it lies in the responsibility of the caller to use \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) to ask for the status information of all child processes after their
termination, or call \texttt{IO{\textunderscore}IgnorePid} (\ref{IOuScoreIgnorePid}) to ignore the return value of a process. }

 

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



 Reads the file with the name \mbox{\texttt{\mdseries\slshape filename}}, however, a pipeline is created by the processes described by \mbox{\texttt{\mdseries\slshape progs}} (see \texttt{IO{\textunderscore}StartPipeline} (\ref{IOuScoreStartPipeline})) 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}FileFilterString (append)}}
\logpage{[ 4, 4, 8 ]}\nobreak
\hyperdef{L}{X83E765D783531845}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}FileFilterString({\mdseries\slshape filename, progs, st[, append]})\index{IO{\textunderscore}FileFilterString@\texttt{IO{\textunderscore}FileFilterString}!append}
\label{IOuScoreFileFilterString:append}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Writes the content of the string \mbox{\texttt{\mdseries\slshape st}} to the file with the name \mbox{\texttt{\mdseries\slshape filename}}, however, a pipeline is created by the processes described by \mbox{\texttt{\mdseries\slshape progs}} (see \texttt{IO{\textunderscore}StartPipeline} (\ref{IOuScoreStartPipeline})) to filter the content of the string through the pipeline. The result is put
into the file. If the boolean value \mbox{\texttt{\mdseries\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}FilteredFile({\mdseries\slshape progs, filename[, mode][, bufsize]})\index{IO{\textunderscore}FilteredFile@\texttt{IO{\textunderscore}FilteredFile}}
\label{IOuScoreFilteredFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object or \texttt{fail} 



 This function is similar to \texttt{IO{\textunderscore}File} (\ref{IOuScoreFile: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{IOuScoreClose}) automatically uses the \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) 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{IOuScoreWaitPid}) any more after the call to \texttt{IO{\textunderscore}Close} (\ref{IOuScoreClose}).

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

 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}CompressedFile}}
\logpage{[ 4, 4, 10 ]}\nobreak
\hyperdef{L}{X7B425F3B7A68C2FB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}CompressedFile({\mdseries\slshape filename[, mode][, bufsize]})\index{IO{\textunderscore}CompressedFile@\texttt{IO{\textunderscore}CompressedFile}}
\label{IOuScoreCompressedFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a \texttt{File} object or \texttt{fail} 



 This function is a convenience wrapper around \texttt{IO{\textunderscore}FilteredFile} (\ref{IOuScoreFilteredFile}) which handles a number of common compressed file formats transparently, by
calling an external program. The arguments to this function are identical to \texttt{IO{\textunderscore}File} (\ref{IOuScoreFile:mode}). If the extension to \mbox{\texttt{\mdseries\slshape filename}} is one of gz, bz2 or xz, then the file is transparently
compressed/uncompressed using gzip, bzip2 or xz respectively. If the extension
is none of these, then the command behaves identically to \texttt{IO{\textunderscore}File} (\ref{IOuScoreFile:mode}).

 Note that as this function calls \texttt{IO{\textunderscore}FilteredFile} (\ref{IOuScoreFilteredFile}), it will activate our SIGCHLD handler (see \texttt{IO{\textunderscore}InstallSIGCHLDHandler} (\ref{IOuScoreInstallSIGCHLDHandler})).

 When compression / decompression is active, 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, 11 ]}\nobreak
\hyperdef{L}{X7D62E9C57F1F96FB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}SendStringBackground({\mdseries\slshape f, st})\index{IO{\textunderscore}SendStringBackground@\texttt{IO{\textunderscore}}\-\texttt{Send}\-\texttt{String}\-\texttt{Background}}
\label{IOuScoreSendStringBackground}
}\hfill{\scriptsize (function)}}\\


 This functions uses \texttt{IO{\textunderscore}Write} (\ref{IOuScoreWrite}) to write the whole string \mbox{\texttt{\mdseries\slshape st}} to the \texttt{File} object \mbox{\texttt{\mdseries\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{IOuScorePopen2}) or \texttt{IO{\textunderscore}Popen3} (\ref{IOuScorePopen3}) 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} 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, 12 ]}\nobreak
\hyperdef{L}{X8484B0CD7836A19E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}PipeThrough({\mdseries\slshape cmd, args, input})\index{IO{\textunderscore}PipeThrough@\texttt{IO{\textunderscore}PipeThrough}}
\label{IOuScorePipeThrough}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a string or \texttt{fail} 



 Starts the process with the executable given by the file name \mbox{\texttt{\mdseries\slshape cmd}} (in the sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOuScoreFindExecutable})) with arguments in the argument list \mbox{\texttt{\mdseries\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{\mdseries\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\texttt{\symbol{45}}blocking I/O to
avoid deadlocks is done in this function. 

 This function properly does \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) 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{IOuScoreInstallSIGCHLDHandler})). }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}PipeThroughWithError}}
\logpage{[ 4, 4, 13 ]}\nobreak
\hyperdef{L}{X7A9ACA3979635506}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}PipeThroughWithError({\mdseries\slshape cmd, args, input})\index{IO{\textunderscore}PipeThroughWithError@\texttt{IO{\textunderscore}}\-\texttt{Pipe}\-\texttt{Through}\-\texttt{With}\-\texttt{Error}}
\label{IOuScorePipeThroughWithError}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record or \texttt{fail} 



 Starts the process with the executable given by the file name \mbox{\texttt{\mdseries\slshape cmd}} (in the sense of \texttt{IO{\textunderscore}FindExecutable} (\ref{IOuScoreFindExecutable})) with arguments in the argument list \mbox{\texttt{\mdseries\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{\mdseries\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\texttt{\symbol{45}}blocking I/O to
avoid deadlocks is done in this function. 

 This function properly does \texttt{IO{\textunderscore}WaitPid} (\ref{IOuScoreWaitPid}) 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{IOuScoreInstallSIGCHLDHandler})). 

 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, and \texttt{status} which is the status returned from the exiting 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\texttt{\symbol{45}}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\texttt{\symbol{45}}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}{X7E504814811605B7}{}
{
  The following static objects are used to report about success or failure of
the (un\texttt{\symbol{45}})pickling operations: 

\subsection{\textcolor{Chapter }{IO{\textunderscore}Error}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X86E06A128511BA25}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Error\index{IO{\textunderscore}Error@\texttt{IO{\textunderscore}Error}}
\label{IOuScoreError}
}\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}{X7887BFCF824B439B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}Nothing\index{IO{\textunderscore}Nothing@\texttt{IO{\textunderscore}Nothing}}
\label{IOuScoreNothing}
}\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{IOuScoreUnpickle})) encounters the end of a file. }

 

\subsection{\textcolor{Chapter }{IO{\textunderscore}OK}}
\logpage{[ 5, 1, 3 ]}\nobreak
\hyperdef{L}{X7D4D092B8401EA0F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}OK\index{IO{\textunderscore}OK@\texttt{IO{\textunderscore}OK}}
\label{IOuScoreOK}
}\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}{X7F68A8F47F87B243}{}
{
  

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



 The argument \mbox{\texttt{\mdseries\slshape f}} must be an open, writable \texttt{File} object. The object \mbox{\texttt{\mdseries\slshape ob}} can be an arbitrary \textsf{GAP} object. The operation ``pickles'' or ``serialises'' the object \mbox{\texttt{\mdseries\slshape ob}} and writes the result into the \texttt{File} object \mbox{\texttt{\mdseries\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{IOuScoreUnpickle}) and is platform\texttt{\symbol{45}} 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\texttt{\symbol{45}}referential objects built from records and lists are
handled correctly and are restored completely with the same
self\texttt{\symbol{45}}references during unpickling. }

 

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



 The argument \mbox{\texttt{\mdseries\slshape f}} must be an open, readable \texttt{File} object. The operation reads from \mbox{\texttt{\mdseries\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}{$\triangleright$\enspace\texttt{IO{\textunderscore}ClearPickleCache({\mdseries\slshape })\index{IO{\textunderscore}ClearPickleCache@\texttt{IO{\textunderscore}ClearPickleCache}}
\label{IOuScoreClearPickleCache}
}\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{IOuScorePickle}) and is necessary to handle self\texttt{\symbol{45}}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{IOuScorePickle}) and \texttt{IO{\textunderscore}Unpickle} (\ref{IOuScoreUnpickle}) to work! }

 }

 
\section{\textcolor{Chapter }{Extending the pickling framework}}\label{ExtPickFrame}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X7B1C9A9C7D3C0312}{}
{
  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{IOuScorePickle}) 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\texttt{\symbol{45}}references. Arbitrary subobjects can then be
pickled using recursive calls to the operation \texttt{IO{\textunderscore}Pickle} (\ref{IOuScorePickle}) 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\texttt{\symbol{45}} 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{IOuScoreClearPickleCache}) 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{IOuScoreUnpickle}) 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\texttt{\symbol{45}}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{IOuScoreUnpickle}) 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{IOuScoreClearPickleCache}) 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}{X78A8811F7BD55ABA}{}
{
  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}{X8173135A7D187358}{}
{
  

\subsection{\textcolor{Chapter }{RandomSource}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X7CB0B5BC82F8FD8F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RandomSource({\mdseries\slshape r, dev})\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{\mdseries\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/urandom} always provides random numbers of not guaranteed ``quality'', the device \texttt{/dev/random} 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}{X79DA05BB7CCC1749}{}
{
  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}{X7E8B5F0A87F2C1F7}{}
{
  

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



 The first argument \mbox{\texttt{\mdseries\slshape hostname}} must be a string containing the hostname of the server to connect. The second
argument \mbox{\texttt{\mdseries\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{IOuScoregethostbyname})) 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}{X80FF9E307BDA0659}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HTTPRequest({\mdseries\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{\mdseries\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{\mdseries\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{\mdseries\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{\mdseries\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\texttt{\symbol{45}}Length} is automatically created from the length of the string \mbox{\texttt{\mdseries\slshape body}}. Finally, the argument \mbox{\texttt{\mdseries\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{\mdseries\slshape target}}. The \texttt{body} component of the result will be the file name in this case. If \mbox{\texttt{\mdseries\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{\mdseries\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\texttt{\symbol{45}}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}{X83526BF378B3D8F2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\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{IOuScoreSelect}) 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}{X81702FA07F2AF472}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CloseHTTPConnection({\mdseries\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{\mdseries\slshape conn}}. No error can possibly occur. }

 

\subsection{\textcolor{Chapter }{SingleHTTPRequest}}
\logpage{[ 7, 1, 5 ]}\nobreak
\hyperdef{L}{X7DBCB0B4801E4D6D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SingleHTTPRequest({\mdseries\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}{X78BAF7A77F6BE631}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CheckForUpdates({\mdseries\slshape })\index{CheckForUpdates@\texttt{CheckForUpdates}}
\label{CheckForUpdates}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This function has been removed, as it only worked over the insecure HTTP
protocol, but not over HTTPS; and the relevant webservice these days only
works over HTTPS. If you relied on this functionality, please take a look at
the \textsf{PackageManager} package, see \href{https://gap-packages.github.io/PackageManager/} {\texttt{https://gap\texttt{\symbol{45}}packages.github.io/PackageManager/}}. }

 

\subsection{\textcolor{Chapter }{ReadWeb}}
\logpage{[ 7, 1, 7 ]}\nobreak
\hyperdef{L}{X872B174F7FFD345B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ReadWeb({\mdseries\slshape URL})\index{ReadWeb@\texttt{ReadWeb}}
\label{ReadWeb}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This function downloads the file from the given uniform resource locator \mbox{\texttt{\mdseries\slshape URL}} using the HTTP protocol and reads the contents into \textsf{GAP} using \texttt{Read} (\textbf{Reference: Read}). 

 Note that this can execute arbitrary code on your machine with the privileges
of the \textsf{GAP} job running, so you should be very careful what files you download and
execute. You have been warned! }

 }

 }

 
\chapter{\textcolor{Chapter }{Background jobs using fork}}\logpage{[ 8, 0, 0 ]}
\hyperdef{L}{X7E9E9B3F7B585BA7}{}
{
  This chapter describes a way to use multi\texttt{\symbol{45}}processor or
multi\texttt{\symbol{45}}core machines from within \textsf{GAP}. In its current version the \textsf{GAP} system is a single threaded and single process system. However, modern
operating systems allow, via the \texttt{fork} system call, to replicate a complete process on the same machine relatively
efficiently. That is, at first after a \texttt{fork} the two processes actually use the same physical memory such that not much
copying needs to be done. The child process is in exactly the same state as
the parent process, sharing open files, network connections and the complete
status of the workspace. However, whenever a page of memory is written, it is
then automatically copied using new, additional physical memory, such that it
behaves like a completely separate process. This method is called ``copy\texttt{\symbol{45}}on\texttt{\symbol{45}}write''. 

 Thus this is a method to parallelise certain computations. Note however, that
from the point of time when the \texttt{fork} has occurred, all further communication between the two processes has to be
realised via pipes or even files. 

 The operations and methods described in this chapter help to use \textsf{GAP} in this way and implement certain ``skeletons'' of parallel programming to make these readily available in \textsf{GAP}. Note that this implementation has its severe limitations and should probably
eventually be replaced by a proper multi\texttt{\symbol{45}}threaded version
of \textsf{GAP}. 
\section{\textcolor{Chapter }{Background jobs}}\logpage{[ 8, 1, 0 ]}
\hyperdef{L}{X7CCAF66D7E7E098E}{}
{
  One creates a background job with the following operation: 

\subsection{\textcolor{Chapter }{BackgroundJobByFork}}
\logpage{[ 8, 1, 1 ]}\nobreak
\hyperdef{L}{X7FE0061F8484814B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{BackgroundJobByFork({\mdseries\slshape fun, args[, opt]})\index{BackgroundJobByFork@\texttt{BackgroundJobByFork}}
\label{BackgroundJobByFork}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a background job object or \texttt{fail}



 This operation creates a background job using \texttt{IO{\textunderscore}fork} (\ref{IOuScorefork}) which starts up as an identical copy of the currently running \textsf{GAP} process. In this child process the function \mbox{\texttt{\mdseries\slshape fun}} is called with the argument list \mbox{\texttt{\mdseries\slshape args}}. The third argument \mbox{\texttt{\mdseries\slshape opt}} must be a record for options. The operation returns either an object
representing the background job or \texttt{fail} if the startup did not work. 

 This operation automatically sets up two pipes for communication with the
child process. This is in particular used to report the result of the function
call to \mbox{\texttt{\mdseries\slshape fun}} back to the parent. However, if called without the option \texttt{TerminateImmediately} (see below) the child process stays alive even after the completion of \mbox{\texttt{\mdseries\slshape fun}} and one can submit further argument lists for subsequent calls to \mbox{\texttt{\mdseries\slshape fun}}. Of course, these additional argument lists will have to be sent over a pipe
to the child process. A special case is if the argument \mbox{\texttt{\mdseries\slshape args}} is equal to \texttt{fail}, in this case the child process is started but does not automatically call \mbox{\texttt{\mdseries\slshape fun}} but rather waits in an idle state until an argument list is submitted via the
pipe using the \texttt{Submit} (\ref{Submit:bgjob}) operation described below. 

 There are two components defined which can be bound in the options record \mbox{\texttt{\mdseries\slshape opt}}. One is \texttt{TerminateImmediately}, if this is bound to \texttt{true} then the child process immediately terminates after the function \mbox{\texttt{\mdseries\slshape fun}} returns its result. In this case, no pipe for communication from parent to
child is created since it would never be used. Note that in this case one can
still get the result of the function \mbox{\texttt{\mdseries\slshape fun}} using the \texttt{Pickup} (\ref{Pickup:bgjob}) operation described below, even when the child has already terminated, since
the result is first transmitted back to the parent before termination. }

 The following operations are available to deal with background job objects: 

\subsection{\textcolor{Chapter }{IsIdle (bgjob)}}
\logpage{[ 8, 1, 2 ]}\nobreak
\hyperdef{L}{X7B7D934583257B9A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsIdle({\mdseries\slshape job})\index{IsIdle@\texttt{IsIdle}!bgjob}
\label{IsIdle:bgjob}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true}, \texttt{false} or \texttt{fail}



 This operation checks whether or not the background job represented by the
object \mbox{\texttt{\mdseries\slshape job}} has already finished the function call to its worker function and is now idle.
If so, \texttt{true} is returned. If it is still running and working on the worker function, \texttt{false} is returned. If the background job has already terminated altogether, this
operation returns \texttt{fail}. Note that if a child process terminates automatically after the first
completion of its worker function and sending the result, then the first call
to \texttt{IsIdle} after completion will return \texttt{true} to indicate successful completion and all subsequent calls will return \texttt{fail}. }

 

\subsection{\textcolor{Chapter }{HasTerminated}}
\logpage{[ 8, 1, 3 ]}\nobreak
\hyperdef{L}{X86E1283D7AD05169}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HasTerminated({\mdseries\slshape job})\index{HasTerminated@\texttt{HasTerminated}}
\label{HasTerminated}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 This operation checks whether or not the background job represented by the
object \mbox{\texttt{\mdseries\slshape job}} has already terminated. If so, \texttt{true} is returned, if not, \texttt{false} is returned. }

 

\subsection{\textcolor{Chapter }{WaitUntilIdle}}
\logpage{[ 8, 1, 4 ]}\nobreak
\hyperdef{L}{X7C139805804E6FE1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WaitUntilIdle({\mdseries\slshape job})\index{WaitUntilIdle@\texttt{WaitUntilIdle}}
\label{WaitUntilIdle}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
the result of the worker function or \texttt{fail}



 This operation waits until the worker function of the background job \mbox{\texttt{\mdseries\slshape job}} has finished and the job is idle. It then returns the result of the worker
function, which has automatically been transmitted to the parent process. If
the child process has died before completion \texttt{fail} is returned. }

 

\subsection{\textcolor{Chapter }{Pickup (bgjob)}}
\logpage{[ 8, 1, 5 ]}\nobreak
\hyperdef{L}{X7F4B8B9078D0E18E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Pickup({\mdseries\slshape job})\index{Pickup@\texttt{Pickup}!bgjob}
\label{Pickup:bgjob}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
the result of the worker function or \texttt{fail}



 This operation does the same as \texttt{WaitUntilIdle} (\ref{WaitUntilIdle}). }

 

\subsection{\textcolor{Chapter }{Submit (bgjob)}}
\logpage{[ 8, 1, 6 ]}\nobreak
\hyperdef{L}{X864492F37E858197}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Submit({\mdseries\slshape job, args})\index{Submit@\texttt{Submit}!bgjob}
\label{Submit:bgjob}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{fail}



 This submits another argument list \mbox{\texttt{\mdseries\slshape args}} for another call to the worker function in the background job \mbox{\texttt{\mdseries\slshape job}}. It is an error if either the background job has already terminated or if it
is still busy working on the previous argument list. That is, one must only
submit another argument in a situation when \texttt{IsIdle} (\ref{IsIdle:bgjob}) would return \texttt{true}. This is for example the case directly after a successful call to \texttt{Pickup} (\ref{Pickup:bgjob}) or i \texttt{WaitUntilIdle} (\ref{WaitUntilIdle}) which did not return \texttt{fail}, unless the background job was created with the \texttt{TerminateImmediately} option set to \texttt{true}. 

 This operation returns immediately after submission, when the new argument
list has been sent to the child process through a pipe. In particular, it does
not await completion of the worker function for the new argument list. }

 

\subsection{\textcolor{Chapter }{Kill (bgjob)}}
\logpage{[ 8, 1, 7 ]}\nobreak
\hyperdef{L}{X841B3A1A7967DEA4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Kill({\mdseries\slshape job})\index{Kill@\texttt{Kill}!bgjob}
\label{Kill:bgjob}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
nothing



 This kills the background job represented by the object \mbox{\texttt{\mdseries\slshape job}} with immediate effect. No more results can be expected from it. Note that
unless one has created the background job with the \texttt{TerminateImmediately} option set to \texttt{true} one always has to call \texttt{Kill} on a background job eventually for cleanup purposes. Otherwise, the background
job and the connecting pipes remain alive until the parent \textsf{GAP} process terminates. }

 }

 
\section{\textcolor{Chapter }{Parallel programming skeletons}}\logpage{[ 8, 2, 0 ]}
\hyperdef{L}{X7AF7D78B7F6F1212}{}
{
  In this section we document the operations for the available skeletons. For a
general description of these ideas see other sources. 

\subsection{\textcolor{Chapter }{ParTakeFirstResultByFork}}
\logpage{[ 8, 2, 1 ]}\nobreak
\hyperdef{L}{X78A59A628449960F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParTakeFirstResultByFork({\mdseries\slshape jobs, args[, opt]})\index{ParTakeFirstResultByFork@\texttt{ParTakeFirstResultByFork}}
\label{ParTakeFirstResultByFork}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a list of results or \texttt{fail}



 The argument \mbox{\texttt{\mdseries\slshape jobs}} must be a list of \textsf{GAP} functions and the argument \mbox{\texttt{\mdseries\slshape args}} a list of the same length containing argument lists with which the job
functions can be called. This operation starts up a background job using \texttt{fork} for each of the functions in \mbox{\texttt{\mdseries\slshape jobs}}, calls it with the corresponding argument list in \mbox{\texttt{\mdseries\slshape args}}. As soon as any of the background jobs finishes with a result, \texttt{ParTakeFirstResultByFork} terminates all other jobs and reports the results found so far. Note that it
can happen that two jobs finish ``at the same time'' in the sense that both results are received before all other jobs could be
terminated. Therefore the result of \texttt{ParTakeFirstResultByFork} is a list, in which position $i$ is bound if and only if job number $i$ returned a result. So in the result at least one entry is bound but it is
possible that more than one entry is bound. 

 You can specify an overall timeout to give up the whole computation if no job
finishes by setting the \texttt{TimeOut} component of the options record \mbox{\texttt{\mdseries\slshape opt}}. In this case you have to set it to a record with two components \texttt{tv{\textunderscore}sec} and \texttt{tv{\textunderscore}usec} which are seconds and microseconds respectively, exactly as returned by the \texttt{IO{\textunderscore}gettimeofday} (\ref{IOuScoregettimeofday}) function. In the case of timeout an empty list is returned. }

 

\subsection{\textcolor{Chapter }{ParDoByFork}}
\logpage{[ 8, 2, 2 ]}\nobreak
\hyperdef{L}{X7A1F40D1841C36D2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParDoByFork({\mdseries\slshape jobs, args[, opt]})\index{ParDoByFork@\texttt{ParDoByFork}}
\label{ParDoByFork}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a list of results or \texttt{fail}



 The argument \mbox{\texttt{\mdseries\slshape jobs}} must be a list of \textsf{GAP} functions and the argument \mbox{\texttt{\mdseries\slshape args}} a list of the same length containing argument lists with which the job
functions can be called. This operation starts up a background job using \texttt{fork} for each of the functions in \mbox{\texttt{\mdseries\slshape jobs}}, calls it with the corresponding argument list in \mbox{\texttt{\mdseries\slshape args}}. As soon as all of the background jobs finish with a result, \texttt{ParDoByFork} reports the results found. Therefore the result of \texttt{ParDoByFork} is a list, in which position $i$ is bound to the result that job number $i$ returned. 

 You can specify an overall timeout to stop the whole computation if not all
jobs finish in time by setting the \texttt{TimeOut} component of the options record \mbox{\texttt{\mdseries\slshape opt}}. In this case you have to set it to a record with two components \texttt{tv{\textunderscore}sec} and \texttt{tv{\textunderscore}usec} which are seconds and microseconds respectively, exactly as returned by the \texttt{IO{\textunderscore}gettimeofday} (\ref{IOuScoregettimeofday}) function. In the case of timeout a list is returned in which the positions
corresponding to those jobs that have already finished are bound to the
respective results and the other positions are unbound. }

 

\subsection{\textcolor{Chapter }{ParListByFork}}
\logpage{[ 8, 2, 3 ]}\nobreak
\hyperdef{L}{X80DA6945873DCC66}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParListByFork({\mdseries\slshape l, worker[, opt]})\index{ParListByFork@\texttt{ParListByFork}}
\label{ParListByFork}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a list of results or \texttt{fail}



 This is a parallel version of the \texttt{List} (\textbf{Reference: list and non\texttt{\symbol{45}}list difference}) function. It applies the function \mbox{\texttt{\mdseries\slshape worker}} to all elements of the list \mbox{\texttt{\mdseries\slshape l}} and returns a list containing the results in corresponding positions. You have
to specify the component \texttt{NumberJobs} in the options record \mbox{\texttt{\mdseries\slshape opt}} which indicates how many background processes to start. You can optionally use
the \texttt{TimeOut} option exactly as for \texttt{ParDoByFork} (\ref{ParDoByFork}), however, if a timeout occurs, \texttt{ParListByFork} returns \texttt{fail}. 

 Note that the usefulness of this operation is relatively limited, since every
individual result has to be sent back over a pipe from the child process to
the parent process. Therefore this only makes sense if the computation time
for the worker function dominates the communication time. }

 

\subsection{\textcolor{Chapter }{ParMapReduceByFork}}
\logpage{[ 8, 2, 4 ]}\nobreak
\hyperdef{L}{X7AD5D85283BC41AC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParMapReduceByFork({\mdseries\slshape l, map, reduce[, opt]})\index{ParMapReduceByFork@\texttt{ParMapReduceByFork}}
\label{ParMapReduceByFork}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a value or \texttt{fail}



 This is a parallel version implementation of the classical \texttt{MapReduce} pattern. It applies the function \mbox{\texttt{\mdseries\slshape map}} to all elements of the list \mbox{\texttt{\mdseries\slshape l}} and then reduces the result using the \mbox{\texttt{\mdseries\slshape reduce}} function which accepts two return values of \mbox{\texttt{\mdseries\slshape map}} and returns one of them. Thus, the final result is one return value or \texttt{fail} if the startup of the jobs fails. You have to specify the component \texttt{NumberJobs} in the options record \mbox{\texttt{\mdseries\slshape opt}} which indicates how many background processes to start. You can optionally use
the \texttt{TimeOut} option exactly as for \texttt{ParDoByFork} (\ref{ParDoByFork}), however, if a timeout occurs, \texttt{ParMapReduceByFork} returns \texttt{fail}. 

 Note that this can be very useful because quite often the cumulated
computation time for all the worker function calls dominates the communication
time for a single result. }

 \index{Timeouts} 

\subsection{\textcolor{Chapter }{IO{\textunderscore}CallWithTimeout}}
\logpage{[ 8, 2, 5 ]}\nobreak
\hyperdef{L}{X7A5CCA557B7F8660}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}CallWithTimeout({\mdseries\slshape timeout, func, ...})\index{IO{\textunderscore}CallWithTimeout@\texttt{IO{\textunderscore}CallWithTimeout}}
\label{IOuScoreCallWithTimeout}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IO{\textunderscore}CallWithTimeoutList({\mdseries\slshape timeout, func, arglist})\index{IO{\textunderscore}CallWithTimeoutList@\texttt{IO{\textunderscore}}\-\texttt{Call}\-\texttt{With}\-\texttt{Timeout}\-\texttt{List}}
\label{IOuScoreCallWithTimeoutList}
}\hfill{\scriptsize (function)}}\\


 \texttt{IO{\textunderscore}CallWithTimeout} and \texttt{IO{\textunderscore}CallWithTimeoutList} allow calling a function with a limit on length of time it will run. The
function is run inside a copy of the current GAP session, so any changes it
makes to global variables are thrown away when the function finishes or times
out. The return value of \mbox{\texttt{\mdseries\slshape func}} is passed back to the current GAP session via \texttt{IO{\textunderscore}Pickle}. Note that \texttt{IO{\textunderscore}Pickle} may not be available for all objects.

 \texttt{IO{\textunderscore}CallWithTimeout} is variadic. Any arguments to it beyond the first two are passed as arguments
to \mbox{\texttt{\mdseries\slshape func}}. \texttt{IO{\textunderscore}CallWithTimeoutList} in contrast takes exactly three arguments, of which the third is a list
(possibly empty) of arguments to pass to \mbox{\texttt{\mdseries\slshape func}}. 

 If the call completes within the allotted time and returns a value \texttt{res}, the result of \texttt{IO{\textunderscore}CallWithTimeout[List]} is a list of the form \texttt{[ true, res ]}. 

 If the call completes within the allotted time and returns no value, the
result of \texttt{IO{\textunderscore}CallWithTimeout[List]} is the list \texttt{[ true ]}.

 If the call does not complete within the timeout, the result of \texttt{IO{\textunderscore}CallWithTimeout[List]} is the list \texttt{[ false ]}. If the call causes GAP to crash or exit, the result is the list \texttt{[ fail ]}. 

 The timer is suspended during execution of a break loop and abandoned when you
quit from a break loop.

 The limit \mbox{\texttt{\mdseries\slshape timeout}} is specified as a record. At present the following components are recognised \texttt{nanoseconds}, \texttt{microseconds}, \texttt{milliseconds}, \texttt{seconds}, \texttt{minutes}, \texttt{hours}, \texttt{days} and \texttt{weeks}. Any of these components which is present should be bound to a positive
integer, rational or float and the times represented are totalled to give the
actual timeout. As a shorthand, a single positive integers may be supplied,
and is taken as a number of microseconds. Further components are permitted and
ignored, to allow for future functionality.

 The precision of the timeouts is not guaranteed, and there is a system
dependent upper limit on the timeout which is typically about 8 years on 32
bit systems and about 30 billion years on 64 bit systems. Timeouts longer than
this will be reduced to this limit.

 }

 Note that the next parallel skeleton is a worker farm which is described in
the following section. }

 
\section{\textcolor{Chapter }{Worker farms}}\logpage{[ 8, 3, 0 ]}
\hyperdef{L}{X7D18519B879047B3}{}
{
  The parallel skeleton of a worker farm is basically nothing but a bunch of
background jobs all with the same worker function and all eagerly waiting for
work. The only additional concepts needed are an input and an output queue.
The input queue contains argument lists and the output queue pairs of argument
lists and results. 

 One creates a worker farm with the following operation: 

\subsection{\textcolor{Chapter }{ParWorkerFarmByFork}}
\logpage{[ 8, 3, 1 ]}\nobreak
\hyperdef{L}{X87896E477DCB9C55}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParWorkerFarmByFork({\mdseries\slshape fun, opt})\index{ParWorkerFarmByFork@\texttt{ParWorkerFarmByFork}}
\label{ParWorkerFarmByFork}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
an object representing the worker farm or \texttt{fail}



 This operation creates a worker farm with the worker function \mbox{\texttt{\mdseries\slshape fun}} and sets up its input and output queue. An object representing the farm is
returned unless not all jobs could be started up in which case \texttt{fail} is returned. After startup all background jobs in the farm are idle. The only
valid option in the options record \mbox{\texttt{\mdseries\slshape opt}} is \texttt{NumberJobs} and it must be bound to the number of worker jobs in the farm, a positive
integer. }

 The following operations are for worker farm objects: 

\subsection{\textcolor{Chapter }{DoQueues}}
\logpage{[ 8, 3, 2 ]}\nobreak
\hyperdef{L}{X7ED2CE687EA7FC66}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoQueues({\mdseries\slshape wf, block})\index{DoQueues@\texttt{DoQueues}}
\label{DoQueues}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This operation called on a worker farm object \mbox{\texttt{\mdseries\slshape wf}} administrates the input and output queues of the worker farm. In particular it
checks whether new results are available from the workers and if so it appends
them to the output queue. If jobs are idle and the input queue is
non\texttt{\symbol{45}}empty, argument lists from the input queue are sent to
the idle jobs and removed from the input queue. 

 This operation must be called regularly to keep up the communication with the
clients. It uses \texttt{select} and so does not block if the boolean argument \mbox{\texttt{\mdseries\slshape block}} is set to \texttt{false}. However, if larger chunks of data has to be sent or received this operation
might need some time to return. 

 If the boolean argument \mbox{\texttt{\mdseries\slshape block}} is set to true then the \texttt{DoQueues} blocks until at least one job has returned a result. This can be used to wait
for the termination of all tasks without burning CPU cycles in the parent job.
One would repeatedly call \texttt{DoQueues} with \mbox{\texttt{\mdseries\slshape block}} set to \texttt{true} and after each such call check with \texttt{IsIdle} (\ref{IsIdle:wfarm}) whether all tasks are done. Note that one should no longer call \texttt{DoQueues} with \mbox{\texttt{\mdseries\slshape block}} set to \texttt{true} once this is the case since then it would block forever. 

 This operation is called automatically by most of the following operations. }

 

\subsection{\textcolor{Chapter }{Kill (wfarm)}}
\logpage{[ 8, 3, 3 ]}\nobreak
\hyperdef{L}{X83289405792FF902}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Kill({\mdseries\slshape wf})\index{Kill@\texttt{Kill}!wfarm}
\label{Kill:wfarm}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This operation terminates all background jobs in the farm \mbox{\texttt{\mdseries\slshape wf}}, which cannot be used subsequently. One should always call this operation
when the worker farm is no longer needed to free resources. }

 

\subsection{\textcolor{Chapter }{IsIdle (wfarm)}}
\logpage{[ 8, 3, 4 ]}\nobreak
\hyperdef{L}{X7C4E3D5A7FE617FE}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsIdle({\mdseries\slshape wf})\index{IsIdle@\texttt{IsIdle}!wfarm}
\label{IsIdle:wfarm}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} 



 This operation returns \texttt{true} if all background jobs in the worker farm \mbox{\texttt{\mdseries\slshape wf}} are idle. This means, that all tasks which have previously been submitted
using \texttt{Submit} (\ref{Submit:wfarm}) have been completed and their result been appended to the output queue. The
operation \texttt{DoQueues} (\ref{DoQueues}) is automatically called before the execution of \texttt{IsIdle}. }

 

\subsection{\textcolor{Chapter }{Submit (wfarm)}}
\logpage{[ 8, 3, 5 ]}\nobreak
\hyperdef{L}{X81773CEC8246EDF3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Submit({\mdseries\slshape wg, arglist})\index{Submit@\texttt{Submit}!wfarm}
\label{Submit:wfarm}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This operation submits a task in the form of an argument list for the worker
function to the worker farm. It is appended at the end of the input queue. The
operation \texttt{DoQueues} (\ref{DoQueues}) is automatically called after the execution of \texttt{Submit}, giving the farm a chance to actually send the work out to the worker
background jobs. }

 

\subsection{\textcolor{Chapter }{Pickup (wfarm)}}
\logpage{[ 8, 3, 6 ]}\nobreak
\hyperdef{L}{X7878258F84138DEA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Pickup({\mdseries\slshape wg, arglist})\index{Pickup@\texttt{Pickup}!wfarm}
\label{Pickup:wfarm}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 nothing 



 This operation collects all results from the output queue of the worker farm.
The output queue is empty after this function returns. The results are
reported as a list of pairs, each pair has the input argument list as first
component and the output object as second component. 

 The operation \texttt{DoQueues} (\ref{DoQueues}) is automatically called before the execution of \texttt{Pickup}, giving the farm a chance to actually receive some more results from the
worker background jobs. }

 }

 }

 
\chapter{\textcolor{Chapter }{I/O multiplexing}}\logpage{[ 9, 0, 0 ]}
\hyperdef{L}{X7A466B907B882CA0}{}
{
  
\section{\textcolor{Chapter }{Introduction}}\logpage{[ 9, 1, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  Whenever one needs to do input/output on more than one connection (file
descriptor) at a time, some code is needed to organise the I/O multiplexing.
Due to the single\texttt{\symbol{45}}threaded nature of the current \textsf{GAP} language one has to use \texttt{IO{\textunderscore}select} (\ref{IOuScoreselect}) and some buffering and queueing to organise this. This chapter describes a
relative generic implementation of I/O\texttt{\symbol{45}}multiplexing using
so\texttt{\symbol{45}}called \texttt{IOHub} (\ref{IOHub}) objects. The basic idea is that an \texttt{IOHub} (\ref{IOHub}) object handles lots of I/O connections at the same time and maintains a buffer
for each of them. There is a very simple protocol that marks chunks of data
(called ``messages'') and whenever a message has been received completely it is collected in the
input queue of the \texttt{IOHub} (\ref{IOHub}), marked with the number of the connection it came from. Rather than sending a
message away in one go, one would always schedule it for sending by appending
it to the output queue. The operation \texttt{DoIO} (\ref{DoIO}), when called often enough, will then make sure that the message is sent away
eventually. }

 
\section{\textcolor{Chapter }{The operations for \texttt{IOHub} objects}}\logpage{[ 9, 2, 0 ]}
\hyperdef{L}{X81EC9A3186F1DCDE}{}
{
  In this section, we simply describe the functions and operations to create,
use and destroy \texttt{IOHub} (\ref{IOHub}) objects. 

\subsection{\textcolor{Chapter }{IOHub}}
\logpage{[ 9, 2, 1 ]}\nobreak
\hyperdef{L}{X83C0523D8538E866}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IOHub({\mdseries\slshape })\index{IOHub@\texttt{IOHub}}
\label{IOHub}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 an \texttt{IOHub} object 



 This creates a new \texttt{IOHub} object at first without any open connections. }

 

\subsection{\textcolor{Chapter }{NewConnection}}
\logpage{[ 9, 2, 2 ]}\nobreak
\hyperdef{L}{X7D1D9A8D837ECCEB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NewConnection({\mdseries\slshape h, i, o})\index{NewConnection@\texttt{NewConnection}}
\label{NewConnection}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a positive integer 



 This operation adds a new connection to the \texttt{IOHub} (\ref{IOHub}) object \mbox{\texttt{\mdseries\slshape h}}. The arguments \mbox{\texttt{\mdseries\slshape i}} and \mbox{\texttt{\mdseries\slshape o}} must be Unix file descriptors or $0$ and \mbox{\texttt{\mdseries\slshape i}} must be open for reading if it is positive and \mbox{\texttt{\mdseries\slshape o}} must be open for writing if it is positive. It is allowed that both file
descriptors are equal, but they may not both be equal to $0$. The operation returns a positive integer which is the number under which
this new connection will be administrated in the \texttt{IOHub} (\ref{IOHub}) object. Note that this number is specific to the object \mbox{\texttt{\mdseries\slshape h}}. 

 From the moment these file descriptors are registered with the \texttt{IOHub} (\ref{IOHub}) object, every subsequent call to \texttt{DoIO} (\ref{DoIO}) will try to do input and output on them. This means in particular that the
other side of this connection should be in the same initial state of the
protocol. Usually this will be achieved by them being added as a new
connection to a corresponding \texttt{IOHub} (\ref{IOHub}) object on the other side at the same time. 

 See also \texttt{NewTCPConnection} (\ref{NewTCPConnection}) below. }

 

\subsection{\textcolor{Chapter }{CloseConnection}}
\logpage{[ 9, 2, 3 ]}\nobreak
\hyperdef{L}{X8553D2E47C05797F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CloseConnection({\mdseries\slshape h, nr})\index{CloseConnection@\texttt{CloseConnection}}
\label{CloseConnection}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 nothing 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object and \mbox{\texttt{\mdseries\slshape nr}} the number of a connection which was previously returned by \texttt{NewConnection} (\ref{NewConnection}). The corresponding connection is closed and removed from the \texttt{IOHub} (\ref{IOHub}). }

 

\subsection{\textcolor{Chapter }{AttachServingSocket}}
\logpage{[ 9, 2, 4 ]}\nobreak
\hyperdef{L}{X7F7FD824866CB582}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AttachServingSocket({\mdseries\slshape h, addr, port})\index{AttachServingSocket@\texttt{AttachServingSocket}}
\label{AttachServingSocket}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a Unix file descriptor or \texttt{fail} 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object, \mbox{\texttt{\mdseries\slshape addr}} an IP address or host name as a string and \mbox{\texttt{\mdseries\slshape port}} a port number (see also \texttt{IO{\textunderscore}MakeIPAddressPort} (\ref{IOuScoreMakeIPAddressPort})). This operation creates a new socket, binds it to the IP address and port
and attaches it to the \texttt{IOHub} (\ref{IOHub}) object. From this moment on the operation \texttt{DoIO} (\ref{DoIO}) will accept new bidirectional TCP/IP connections on that socket and add them
to \mbox{\texttt{\mdseries\slshape h}}. The operation returns either the file descriptor of the new socket or \texttt{fail} if an error occurred. }

 

\subsection{\textcolor{Chapter }{ShutdownServingSocket}}
\logpage{[ 9, 2, 5 ]}\nobreak
\hyperdef{L}{X7866F9DA8358968C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShutdownServingSocket({\mdseries\slshape h})\index{ShutdownServingSocket@\texttt{ShutdownServingSocket}}
\label{ShutdownServingSocket}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 nothing 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object. Any server socket which was attached to \mbox{\texttt{\mdseries\slshape h}} is shut down, so no new connections will be accepted. }

 

\subsection{\textcolor{Chapter }{Shutdown}}
\logpage{[ 9, 2, 6 ]}\nobreak
\hyperdef{L}{X84AFBD658118ABB8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Shutdown({\mdseries\slshape h})\index{Shutdown@\texttt{Shutdown}}
\label{Shutdown}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 nothing 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object. All connections of \mbox{\texttt{\mdseries\slshape h}} will be closed using \texttt{CloseConnection} (\ref{CloseConnection}) and any serving socket will be shut down using \texttt{ShutdownServingSocket} (\ref{ShutdownServingSocket}). The \texttt{IOHub} (\ref{IOHub}) object will not be usable any more after this call. }

 

\subsection{\textcolor{Chapter }{AcceptNewConnection}}
\logpage{[ 9, 2, 7 ]}\nobreak
\hyperdef{L}{X7BE1B9FD82C9B8E0}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AcceptNewConnection({\mdseries\slshape h})\index{AcceptNewConnection@\texttt{AcceptNewConnection}}
\label{AcceptNewConnection}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a positive integer or \texttt{fail}



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object. The object \mbox{\texttt{\mdseries\slshape h}} must have a serving socket attached to it via \texttt{AttachServingSocket} (\ref{AttachServingSocket}), otherwise \texttt{fail} is returned and nothing happens. One more connection is accepted through the
serving socket. It is added as a new bidirectional TCP/IP connection to the \texttt{IOHub} (\ref{IOHub}) object and the new connection number is returned. Note first that this
operation blocks until a new connection comes in. Note furthermore that this
operation is usually called automatically in \texttt{DoIO} (\ref{DoIO}) whenever a new connection has come in, which is reported in the internal \texttt{IO{\textunderscore}select} (\ref{IOuScoreselect}) call. So usually, the client code does not have to call this operation at all. }

 

\subsection{\textcolor{Chapter }{SubmitOutput}}
\logpage{[ 9, 2, 8 ]}\nobreak
\hyperdef{L}{X85F634D4826D89F1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubmitOutput({\mdseries\slshape h, nr, st})\index{SubmitOutput@\texttt{SubmitOutput}}
\label{SubmitOutput}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{fail} 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object, \mbox{\texttt{\mdseries\slshape nr}} must be a positive integer which is the number of an open connection of \mbox{\texttt{\mdseries\slshape h}} which can be used for output. The argument \mbox{\texttt{\mdseries\slshape st}} must be a \textsf{GAP} string. This operation appends the message \mbox{\texttt{\mdseries\slshape st}} to the end of the output queue for the connection \mbox{\texttt{\mdseries\slshape nr}}. Note that at this stage no output is actually performed automatically. One
has to call \texttt{DoIO} (\ref{DoIO}) subsequently to actually send the message away. }

 

\subsection{\textcolor{Chapter }{GetInput}}
\logpage{[ 9, 2, 9 ]}\nobreak
\hyperdef{L}{X837629707DF9B60E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GetInput({\mdseries\slshape h, nr})\index{GetInput@\texttt{GetInput}}
\label{GetInput}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a list of length $2$ 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object, \mbox{\texttt{\mdseries\slshape nr}} must be an integer. If \mbox{\texttt{\mdseries\slshape nr}} is positive, this operation returns the earliest message which has come in
from connection number \mbox{\texttt{\mdseries\slshape nr}} and has not yet been returned by \texttt{GetInput} before. This message is then removed from the input queue. If there is no such
message, then \texttt{false} is returned. A message is returned as a plain list of length $2$ where the first entry is the connection number it came from and the second
entry is a string containing the message itself. If \mbox{\texttt{\mdseries\slshape nr}} is equal to $0$ then the first message in the input queue from any connection is returned or \texttt{false} if there is no message in the input queue. }

 

\subsection{\textcolor{Chapter }{NewTCPConnection}}
\logpage{[ 9, 2, 10 ]}\nobreak
\hyperdef{L}{X79031BC687502CB6}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NewTCPConnection({\mdseries\slshape h, addr, port})\index{NewTCPConnection@\texttt{NewTCPConnection}}
\label{NewTCPConnection}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a connection number or \texttt{fail} 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object, the arguments \mbox{\texttt{\mdseries\slshape addr}} and \mbox{\texttt{\mdseries\slshape port}} must be an address/port pair as used in \texttt{IO{\textunderscore}MakeIPAddressPort} (\ref{IOuScoreMakeIPAddressPort}), so \mbox{\texttt{\mdseries\slshape address}} can either be a host name or an IP address and \mbox{\texttt{\mdseries\slshape port}} is a port number. This operation opens a new TCP connection to the address and
port specified, adds a new bidirectional connection to the \texttt{IOHub} (\ref{IOHub}) \mbox{\texttt{\mdseries\slshape h}} using \texttt{NewConnection} (\ref{NewConnection}) and returns the connection number specific to the object \mbox{\texttt{\mdseries\slshape h}}. If anything goes wrong, \texttt{fail} is returned. }

 

\subsection{\textcolor{Chapter }{OutputQueue}}
\logpage{[ 9, 2, 11 ]}\nobreak
\hyperdef{L}{X7F8C7F5782213A71}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{OutputQueue({\mdseries\slshape h})\index{OutputQueue@\texttt{OutputQueue}}
\label{OutputQueue}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a list 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object. This returns the internal object for the output queue. Its elements
are pairs where the first entry is the connection number where it is going to
be sent and the second entry is the message as a string. Only modify this list
if you really know what you are doing. }

 

\subsection{\textcolor{Chapter }{InputQueue}}
\logpage{[ 9, 2, 12 ]}\nobreak
\hyperdef{L}{X7972FF1C7B59D0A4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InputQueue({\mdseries\slshape h})\index{InputQueue@\texttt{InputQueue}}
\label{InputQueue}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a list 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object. This returns the internal object for the input queue. Its elements are
pairs where the first entry is the connection number from where the message
was received and the second entry is the message as a string. Only modify this
list if you really know what you are doing. }

 

\subsection{\textcolor{Chapter }{DoIO}}
\logpage{[ 9, 2, 13 ]}\nobreak
\hyperdef{L}{X810D418A802D09D1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoIO({\mdseries\slshape h[, block]})\index{DoIO@\texttt{DoIO}}
\label{DoIO}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} or \texttt{false} or \texttt{fail} 



 The argument \mbox{\texttt{\mdseries\slshape h}} must be an \texttt{IOHub} (\ref{IOHub}) object, and the optional second argument \mbox{\texttt{\mdseries\slshape block}} must be \texttt{true} or \texttt{false}. This operation uses \texttt{IO{\textunderscore}select} (\ref{IOuScoreselect}) to decide which of the file descriptors belonging to the connections of \mbox{\texttt{\mdseries\slshape h}} are ready to read or write. All file descriptors which are ready are served,
possibly updating the input and output queues. A possible serving socket is
also served accepting a new connection if there is one. The operation \texttt{DoIO} loops until no more file descriptors are ready. It returns \texttt{true} if some I/O was performed and \texttt{false} if not. It returns \texttt{fail} if the \texttt{IOHub} (\ref{IOHub}) is already shut down. The second argument \mbox{\texttt{\mdseries\slshape block}} indicates whether or not \texttt{DoIO} should block until some I/O has taken place. If this argument is omitted then \texttt{false} (non\texttt{\symbol{45}}blocking operation) is the default.

 Note that broken connections are silently closed. }

 }

 
\section{\textcolor{Chapter }{ Examples }}\logpage{[ 9, 3, 0 ]}
\hyperdef{L}{X7A489A5D79DA9E5C}{}
{
  There is an example hash server in the file \texttt{examples/hashserver.g}. }

 }

 
\chapter{\textcolor{Chapter }{Examples of usage}}\logpage{[ 10, 0, 0 ]}
\hyperdef{L}{X7EADF566874177D8}{}
{
  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{IOuScorePopen2}). 

 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{[ 10, 1, 0 ]}
\hyperdef{L}{X7EC25CA68794860A}{}
{
  The following sequence of commands opens a file with name \texttt{guck} and writes some things to it: 
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  @gapprompt|gap>A @gapinput|f := IO_File("guck","w");A
  <file fd=3 wbufsize=65536 wdata=0>
  @gapprompt|gap>A @gapinput|IO_Write(f,"Hello world\n");A
  12
  @gapprompt|gap>A @gapinput|IO_WriteLine(f,"Hello world2!");A
  14
  @gapprompt|gap>A @gapinput|IO_Write(f,12345);A
  5
  @gapprompt|gap>A @gapinput|IO_Flush(f);A
  true
  @gapprompt|gap>A @gapinput|IO_Close(f);A
  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{IOuScoreFlush}) 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{IOuScoreFlush}) call here would not have been necessary, since the \texttt{IO{\textunderscore}Close} (\ref{IOuScoreClose}) call flushes the buffer anyway.

 The file can again be read with the following sequence of commands: 
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  @gapprompt|gap>A @gapinput|f := IO_File("guck","r");A
  <file fd=3 rbufsize=65536 rpos=1 rdata=0>
  @gapprompt|gap>A @gapinput|IO_Read(f,10);A
  "Hello worl"
  @gapprompt|gap>A @gapinput|IO_ReadLine(f);A
  "d\n"
  @gapprompt|gap>A @gapinput|IO_ReadLine(f);A
  "Hello world2!\n"
  @gapprompt|gap>A @gapinput|IO_ReadLine(f);A
  "12345"
  @gapprompt|gap>A @gapinput|IO_ReadLine(f);A
  ""
  @gapprompt|gap>A @gapinput|IO_Close(f);A
  true
\end{Verbatim}
 Note here that reading line\texttt{\symbol{45}}wise can only be done
efficiently by using buffered I/O. You can mix calls to \texttt{IO{\textunderscore}Read} (\ref{IOuScoreRead}) and to \texttt{IO{\textunderscore}ReadLine} (\ref{IOuScoreReadLine}). 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{[ 10, 2, 0 ]}
\hyperdef{L}{X7AECE665813D6E4D}{}
{
  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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@s := "";; for i in [1..10000] do Append(s,String(i)); od;;|
  !gapprompt@gap>| !gapinput@Length(s);|
  38894
  !gapprompt@gap>| !gapinput@IO_FileFilterString("guck.gz",[["gzip",["-9c"]]],s);|
  true
  !gapprompt@gap>| !gapinput@sgz := StringFile("guck.gz");;|
  !gapprompt@gap>| !gapinput@Length(sgz);|
  18541
  !gapprompt@gap>| !gapinput@ss := IO_StringFilterFile([["gzip",["-dc"]]],"guck.gz");;|
  !gapprompt@gap>| !gapinput@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{[ 10, 3, 0 ]}
\hyperdef{L}{X7A8A180D7B335151}{}
{
  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}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  @gapprompt|gap>A @gapinput|f := IO_FilteredFile([["gzip",["-9c"]]],"guck.gz","w");A
  <file fd=5 wbufsize=65536 wdata=0>
  @gapprompt|gap>A @gapinput|IO_Write(f,"Hello world!\n");A
  13
  @gapprompt|gap>A @gapinput|IO_Write(f,Elements(SymmetricGroup(5)),"\n");A
  1359
  @gapprompt|gap>A @gapinput|IO_Close(f);A
  true
  @gapprompt|gap>A @gapinput|f := IO_FilteredFile([["gzip",["-dc"]]],"guck.gz","r");A
  <file fd=4 rbufsize=65536 rpos=1 rdata=0>
  @gapprompt|gap>A @gapinput|IO_ReadLine(f);A
  "Hello world!\n"
  @gapprompt|gap>A @gapinput|s := IO_ReadLine(f);; Length(s);A
  1359
  @gapprompt|gap>A @gapinput|IO_Read(f,10);A
  ""
  @gapprompt|gap>A @gapinput|IO_Close(f);A
  true
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Accessing a web page}}\logpage{[ 10, 4, 0 ]}
\hyperdef{L}{X7BD2BF7F87573C69}{}
{
  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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@r := SingleHTTPRequest("www.math.rwth-aachen.de",80,"GET",|
  !gapprompt@>| !gapinput@             "/~Max.Neunhoeffer/index.html",rec(),false,false);;|
  !gapprompt@gap>| !gapinput@RecNames(r);|
  [ "protoversion", "statuscode", "status", "header", "body", "closed" ]
  !gapprompt@gap>| !gapinput@r.status;|
  "OK"
  !gapprompt@gap>| !gapinput@r.statuscode;|
  200
  !gapprompt@gap>| !gapinput@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" )
  !gapprompt@gap>| !gapinput@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\texttt{\symbol{45}})Pickling}}\logpage{[ 10, 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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@r := rec( a := 1, b := "Max", c := [1,2,3] );|
  rec( a := 1, b := "Max", c := [ 1, 2, 3 ] )
  !gapprompt@gap>| !gapinput@r.c[4] := r;|
  rec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )
  !gapprompt@gap>| !gapinput@f := IO_File("guck","w");|
  <file fd=3 wbufsize=65536 wdata=0>
  !gapprompt@gap>| !gapinput@IO_Pickle(f,r);|
  IO_OK
  !gapprompt@gap>| !gapinput@IO_Pickle(f,[(1,2,3,4),(3,4)]);|
  IO_OK
  !gapprompt@gap>| !gapinput@IO_Close(f);|
  true
\end{Verbatim}
 Then, to read it in again, just do: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@f := IO_File("guck");|
  <file fd=3 rbufsize=65536 rpos=1 rdata=0>
  !gapprompt@gap>| !gapinput@IO_Unpickle(f);|
  rec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )
  !gapprompt@gap>| !gapinput@IO_Unpickle(f);|
  [ (1,2,3,4), (3,4) ]
  !gapprompt@gap>| !gapinput@IO_Unpickle(f);|
  IO_Nothing
  !gapprompt@gap>| !gapinput@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\texttt{\symbol{45}}referential. }

 }

 
\chapter{\textcolor{Chapter }{License}}\logpage{[ 11, 0, 0 ]}
\hyperdef{L}{X861E5DF986F89AE2}{}
{
  This program 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, either version 3 of the License, or (at your option) any later
version.

 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, see https://www.gnu.org/licenses/. }

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

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

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