SSL main.xml Sprache: XML

<Chapter Label="Chap-Preface">
<Heading>Preface</Heading>
<Index><Package>IO</Package></Index>

The purpose of this package is to allow efficient and flexible input/output
operations from &GAP;. This is achieved by providing bindings to the
low-level I/O functions in the C-library. On top of this an implementation
of buffered I/O in the &GAP; language is provided. Further, a framework
for serialisation of arbitrary &GAP; objects is implemented.
Finally, an implementation of the client side of the HTTP protocol is
included in the package.<P/>

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

By default the <Package>IO</Package> package  is  not automatically   loaded
by   &GAP;   when   it   is  installed.   You  must   load  the   package
with   <C>LoadPackage("IO");</C>   before  its   functions   become
available.<P/>

For bug reports, feature requests and suggestions, please use our
<URL Text="issue tracker">https://github.com/gap-packages/io/issues</URL>.

</Chapter>

<Chapter Label="Chap-Install">
<Heading>Installation of the <Package>IO</Package>-package</Heading>

To get the newest version of this &GAP; 4 package download one of the
archive files
<List>
<Item> <F>io-x.x.tar.gz</F> </Item>
<Item> <F>io-x.x.tar.bz2</F> </Item>
<Item> <F>io-x.x.zip</F> </Item>
</List>
and unpack it using
<Verb>
gunzip io-x.x.tar.gz; tar xvf io-x.x.tar
</Verb>
or
<Verb>
bzip2 -d io-x.x.tar.bz2; tar xvf io-x.x.tar
</Verb>
or
<Verb>
unzip -x io-x.x.zip
</Verb>
respectively.
<P/>

Do this in a directory called <Q><F>pkg</F></Q>, preferably (but not necessarily)
in the <Q><F>pkg</F></Q> subdirectory of your &GAP; 4 installation. It creates a
subdirectory called <Q><F>io</F></Q>.<P/>

The package  will not work without the following compilation step.<P/>

To compile the C part of the package do (in the <F>pkg</F> directory)

<Verb>
    cd io
    ./configure
    make
</Verb>

If you installed the package in another <Q><F>pkg</F></Q> directory than
the standard <Q><F>pkg</F></Q> directory in your &GAP; 4 installation,
then you have to do two things. Firstly during compilation
you have to use the option
<C>--with-gaproot=PATH</C> of the <F>configure</F> script
where <Q>PATH</Q> is a path to the main &GAP; root directory
(if not given the
default <Q><F>../..</F></Q> is assumed). <P/>
Secondly you have to
specify the path to the directory containing your
<Q><F>pkg</F></Q>
directory to &GAP;'s list of directories. This can be done by starting
&GAP; with the <Q><F>-l</F></Q> 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
&GAP;. Of course, you can add this option to your &GAP; startup script.
<P/>

<Section>
<Heading>Recompiling the documentation</Heading>

Recompiling the documentation is possible by the command <Q><F>gap
makedoc.g</F></Q>
in the <F>io</F> directory. But this should not be necessary.

</Section>

</Chapter>


<Chapter Label="Chap-CLibFuncs">
<Heading>Functions directly available from the C library</Heading>

The following functions from the C library are made available as
&GAP; functions: <P/>

<C>accept</C>,
<C>bind</C>,
<C>chdir</C>,
<C>chmod</C>,
<C>chown</C>,
<C>close</C>,
<C>closedir</C>,
<C>connect</C>,
<C>creat</C>,
<C>dup</C>,
<C>dup2</C>,
<C>execv</C>,
<C>execve</C>,
<C>execvp</C>,
<C>exit</C>,
<C>fchmod</C>,
<C>fchown</C>,
<C>fcntl</C>,
<C>fork</C>,
<C>fstat</C>,
<C>getcwd</C>,
<C>getenv</C>,
<C>gethostbyname</C>,
<C>gethostname</C>,
<C>getpid</C>,
<C>getppid</C>,
<C>getsockname</C>,
<C>getsockopt</C>,
<C>gettimeofday</C>,
<C>gmtime</C>,
<C>kill</C>,
<C>lchown</C>,
<C>link</C>,
<C>listen</C>,
<C>localtime</C>,
<C>lseek</C>,
<C>lstat</C>,
<C>mkdir</C>,
<C>mkfifo</C>,
<C>mknod</C>,
<C>mkstemp</C>,
<C>mkdtemp</C>,
<C>open</C>,
<C>opendir</C>,
<C>pipe</C>,
<C>read</C>,
<C>readdir</C>,
<C>readlink</C>,
<C>recv</C>,
<C>recvfrom</C>,
<C>rename</C>,
<C>rewinddir</C>,
<C>rmdir</C>,
<C>seekdir</C>,
<C>select</C>,
<C>send</C>,
<C>sendto</C>,
<C>setenv</C>,
<C>setsockopt</C>,
<C>socket</C>,
<C>stat</C>,
<C>symlink</C>,
<C>telldir</C>,
<C>unlink</C>,
<C>unsetenv</C>,
<C>write</C>. <P/>

Use the <C>man</C> command in your shell to get information about these
functions.<P/>

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

All errors are reported via the <Ref Func="LastSystemError"
BookName="ref"/> function.<P/>

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 <C>IO</C> record. <P/>

<E>Warning:</E> 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 &GAP; levels the functions
and constants are there or not. If you want to develop platform
independent &GAP; code using this package, then you have to check
for existence of the functions and constants you need.

<Section>
<Heading>Differences in arguments - an overview</Heading>

The <C>open</C> function has to be called with three arguments. The
version with two arguments is not available on the &GAP; level. <P/>

The <C>read</C> function takes four arguments: <A>fd</A> is an integer
file descriptor, <A>st</A> is a &GAP; string, <A>offset</A> is an offset
within this string (zero based), and <A>count</A> is the maximal number
of bytes to read. The data is read and stored into the string <A>st</A>,
starting at position <M><A>offset</A>+1</M>. The string <A>st</A> is
made long enough, such that <A>count</A> bytes would fit into it, beginning
at position <M><A>offset</A>+1</M>. The number of bytes read is returned
or <C>fail</C> in case of an error. <P/>

The <C>write</C> function is similar, it also takes four arguments:
<A>fd</A> is an integer file descriptor, <A>st</A> is a &GAP; string,
<A>offset</A> is an offset within this string (zero based), and
<A>count</A> is the number of bytes to write, starting from position
<M><A>offset</A>+1</M> in the string <A>st</A>. The number of bytes
written is returned, or a <C>fail</C> in case of an error. <P/>

The <C>opendir</C> function only returns <C>true</C> or <C>fail</C>. <P/>

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

The <C>closedir</C> function takes no argument. It should be called after
<C>readdir</C> returned <C>false</C> or <C>fail</C> to avoid excessive
use of file descriptors. <P/>

The functions <C>stat</C>, <C>fstat</C>, and <C>lstat</C> only take one
argument and return a &GAP; record that has the same entries as
a <C>struct stat</C>.<P/>

The function <C>socket</C> can optionally take a string as third argument.
In that case it automatically calls <C>getprotobyname</C> to look up the
protocol name.<P/>

The functions <C>bind</C> and <C>connect</C> take only one string argument
as address field, because the string already encodes the length.<P/>

There are two convenience functions <Ref Func="IO_make_sockaddr_in"/> and
<Ref Func="IO_MakeIPAddressPort"/> to create such addresses. The first takes
two arguments <A>addr</A> and <A>port</A>, where <A>addr</A> is
a string of length 4, containing the 4 bytes of the IP address and
<A>port</A> is a port number as &GAP; integer. The function
<Ref Func="IO_MakeIPAddressPort"/> takes the same arguments, but the first can
be a string containing an IP address in dot notation like
<Q>137.226.152.77</Q> or a hostname to be looked up.<P/>

The <C>setsockopt</C> function has no argument <A>optlen</A>. The length
of the string <A>optval</A> is taken.<P/>

The <C>select</C> function works as the function <C>UNIXSelect</C> in the
&GAP; library.<P/>

As of now, the file locking mechanisms of <C>fcntl</C> using
<C>struct flock</C> are not yet implemented on the &GAP; level.
</Section>

<Section>
    <Heading>The low-level functions in detail</Heading>

Nearly all of this functions return an integer result in the C library.
On the &GAP; level this is either returned as a non-negative integer
in case of success or as <K>fail</K> in case of an error (where on the
C level <M>-1</M> would be returned). If the integer can only be <M>0</M>
for <Q>no error</Q> this is changed to <K>true</K> on the &GAP; level.

<ManSection>
<Func Name="IO_accept" Arg="fd, addr"
      Comm="Accepts an incoming network connection"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Accepts an incoming network connection.
For details see <Q><C>man 2 accept</C></Q>. The argument <A>addr</A> can be
made with <Ref Func="IO_make_sockaddr_in"/> and contains its length such
that no third argument is necessary.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_bind" Arg="fd, my_addr"
      Comm="Binds a local address to a socket."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Binds a local address to a socket.
For details see <Q><C>man 2 bind</C></Q>. The argument
<A>my&uscore;addr</A> can be made with <Ref Func="IO_make_sockaddr_in"/>
and contains its length such that no third argument is necessary.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_chdir" Arg="path"
      Comm="Changes the current working directory."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Changes the current working directory.
For details see <Q><C>man 2 chdir</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_chmod" Arg="pathname, mode"
      Comm="Changes the mode of a file."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Changes the mode of a file.
For details see <Q><C>man 2 chmod</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_chown" Arg="path, owner, group"
      Comm="Sets owner and/or group of file."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Sets owner and/or group of file.
For details see <Q><C>man 2 chown</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_close" Arg="fd"
      Comm="Closes a file descriptor."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Closes a file descriptor.
For details see <Q><C>man 2 close</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_closedir" Arg=""
      Comm="Closes a directory."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Closes a directory.
For details see <Q><C>man 3 closedir</C></Q>. Has no arguments, because we only
have one <C>DIR</C> struct in the C part.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_connect" Arg="fd, serv_addr"
      Comm="Connects to a remote socket."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Connects to a remote socket.
For details see <Q><C>man 2 connect</C></Q>. The argument
<A>serv&uscore;addr</A> can be made with <Ref Func="IO_make_sockaddr_in"/>
and contains its length such that no third argument is necessary.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_creat" Arg="pathname, mode"
      Comm="Creates a new file."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Creates a new file. For details see <Q><C>man 2 creat</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_dup" Arg="oldfd"
      Comm="Duplicates a file descriptor."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Duplicates a file descriptor.
For details see <Q><C>man 2 dup</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_dup2" Arg="oldfd, newfd"
      Comm="Duplicates a file descriptor to a new one."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Duplicates a file descriptor to a new one.
For details see <Q><C>man 2 dup2</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_execv" Arg="path, argv"
      Comm="Replaces the process with another process."/>
<Returns> <K>fail</K> or does not return </Returns>
<Description>
Replaces the process with another process.
For details see <Q><C>man 3 execv</C></Q>. The argument <A>argv</A> is a list
of strings. The called program does not have to be the first argument
in this list.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_execve" Arg="path, argv, envp"
      Comm="Replaces the process with another process."/>
<Returns> <K>fail</K> or does not return </Returns>
<Description>
Replaces the process with another process.
For details see <Q><C>man 3 execve</C></Q>. The arguments <A>argv</A> and
<A>envp</A> are both lists of strings. The called program does not have to
be the first argument in <A>argv</A>. The list <A>envp</A> can be made
with <Ref Func="IO_MakeEnvList"/> from a record acquired from <Ref
Func="IO_Environment"/> and modified later.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_execvp" Arg="path, argv"
      Comm="Replaces the process with another process."/>
<Returns> <K>fail</K> or does not return </Returns>
<Description>
Replaces the process with another process.
For details see <Q><C>man 3 execvp</C></Q>. The argument <A>argv</A> is a list
of strings. The called program does not have to be the first argument
in this list.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_exit" Arg="status"
      Comm="Stops process immediately with return code status."/>
<Description>
Stops process immediately with return code <A>status</A>.
For details see <Q><C>man 2 exit</C></Q>. The argument <A>status</A> must
be an integer. Does not return.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_fchmod" Arg="fd, mode"
      Comm="Changes mode of an opened file."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Changes mode of an opened file.
For details see <Q><C>man 2 fchmod</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_fchown" Arg="fd, owner, group"
      Comm="Changes owner and/or group of an opened file."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Changes owner and/or group of an opened file.
For details see <Q><C>man 2 fchown</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_fcntl" Arg="fd, cmd, arg"
      Comm="file control"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
    Does various things to control the behaviour of a file descriptor.
    For details see <Q><C>man 2 fcntl</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_fork" Arg=""
      Comm="Forks off a child process, which is an identical copy."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Forks off a child process, which is an identical copy.
For details see <Q><C>man 2 fork</C></Q>.
Note that <Ref Func="IO_fork"/> activates our SIGCHLD handler (see <Ref
Func="IO_InstallSIGCHLDHandler"/>). Note that you must use the
<Ref Func="IO_WaitPid"/> function to wait or check for the termination of
child processes, or call <Ref Func="IO_IgnorePid"/> to ignore the child.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_fstat" Arg="fd"
      Comm="Returns the file meta data for an opened file."/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
Returns the file meta data for an opened file.
For details see <Q><C>man 2 fstat</C></Q>. A &GAP; record is returned with
the same entries than a <C>struct stat</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_getcwd" Arg=""
      Comm="Get the current working directory."/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
Returns the current working directory.
For details see <Q><C>man 3 getcwd</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_getenv" Arg="name"
      Comm="Return the value of an environment variable."/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
Return the current value of the environment variable <A>name</A>.
If the variable is not in the current environment, <C>fail</C> is returned.
For details see <Q><C>man 3 getenv</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_gethostbyname" Arg="name"
      Comm="Return host information by name."/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
Return host information by name.
For details see <Q><C>man 3 gethostbyname</C></Q>. A &GAP; record is returned
with all the relevant information about the host.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_gethostname" Arg=""
      Comm="Return host name."/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
Return host name.
For details see <Q><C>man 3 gethostname</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_getpid" Arg="" Comm="Get process ID."/>
<Returns> an integer </Returns>
<Description>
    Returns the process ID of the current process as an integer. For
    details see <Q><C>man 2 getpid</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_getppid" Arg="" Comm="Get parent process ID."/>
<Returns> an integer </Returns>
<Description>
    Returns the process ID of the parent of the current process as an
    integer. For details see <Q><C>man 2 getppid</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_getsockname" Arg="fd"
      Comm="Get a socket name."/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
Get a socket name. For details see <Q><C>man 2 getsockname</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_getsockopt" Arg="fd, level, optname, optval"
      Comm="Get a socket option."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Get a socket option. For details see <Q><C>man 2 getsockopt</C></Q>.
Note that the argument <A>optval</A> carries its length around, such that
no 5th argument is necessary.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_gettimeofday" Arg=""
      Comm="Get the current time."/>
<Returns> A record with components <C>tv_sec</C> and <C>tv_usec</C> </Returns>
<Description>
This returns the time elapsed since 1.1.1970, 0:00 GMT. The component
<C>tv_sec</C> contains the number of full seconds and the number
<C>tv_usec</C> the additional microseconds.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_gmtime" Arg="seconds"
      Comm="Computes broken down time."/>
<Returns> A record </Returns>
<Description>
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-library function
<C>gmtime</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_kill" Arg="pid, sig" Comm="Send signal."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
    Sends the signal <A>sig</A> to the process with process ID
    <A>pid</A>. For details see <Q><C>man 2 kill</C></Q>.
    The signal numbers available can be found in the global
    <C>IO</C> record with names like <C>SIGTERM</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_lchown" Arg="path, owner, group"
      Comm="Changes owner and/or group of a file not following links."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Changes owner and/or group of a file not following links.
For details see <Q><C>man 2 lchown</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_link" Arg="oldpath, newpath"
      Comm="Create a hard link."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Create a hard link.
For details see <Q><C>man 2 link</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_listen" Arg="fd, backlog"
      Comm="Switch a socket to listening."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Switch a socket to listening.
For details see <Q><C>man 2 listen</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_localtime" Arg="seconds"
      Comm="Computes broken down time."/>
<Returns> A record </Returns>
<Description>
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-library function
<C>localtime</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_lseek" Arg="fd, offset, whence"
      Comm="Seeks with in an open file."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Seeks within an open file.
For details see <Q><C>man 2 lseek</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_lstat" Arg="name"
      Comm="Returns the file meta data for a file not following links."/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
Returns the file meta data for a file not following links.
For details see <Q><C>man 2 lstat</C></Q>. A &GAP; record is returned with
the same entries than a <C>struct stat</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_mkdir" Arg="pathname, mode"
      Comm="Creates a directory."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Creates a directory.
For details see <Q><C>man 2 mkdir</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_mkfifo" Arg="pathname, mode"
      Comm="Makes a FIFO special file (a named pipe)."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Creates a FIFO special file (a named pipe).
For details see <Q><C>man 3 mkfifo</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_mknod" Arg="pathname, mode, dev"
      Comm="Create a special or ordinary file."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Create a special or ordinary file.
For details see <Q><C>man 2 mknod</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_mkstemp" Arg="template"
      Comm="Create a temporary file and open it, avoiding race conditions."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Create a special or ordinary file.
For details see <Q><C>man 3 mkstemp</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_mkdtemp" Arg="template"
      Comm="Create a temporary directory and return its name."/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
Create a temporary directory.
For details see <Q><C>man 3 mkdtemp</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_open" Arg="pathname, flags, mode"
      Comm="Open and possibly create a file or device."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Open and possibly create a file or device.
For details see <Q><C>man 2 open</C></Q>. Only the variant with 3 arguments
can be used.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_opendir" Arg="name"
      Comm="Opens a directory."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Opens a directory.
For details see <Q><C>man 3 opendir</C></Q>. Note that only <K>true</K> is
returned if everything is OK, since only one <C>DIR</C> struct is
stored on the C level and thus only one directory can be open at any
time.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_pipe" Arg=""
      Comm="Create a pair of file descriptors with a pipe between them."/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
Create a pair of file descriptors with a pipe between them.
For details see <Q><C>man 2 pipe</C></Q>. Note that no arguments are needed. The
result is either <K>fail</K> in case of an error or a record with two
components <C>toread</C> and <C>towrite</C> bound to the two
filedescriptors for reading and writing respectively.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_read" Arg="fd, st, offset, count"
      Comm="Reads from file descriptor."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Reads from file descriptor.
For details see <Q><C>man 2 read</C></Q>. Note that there is one more argument
<A>offset</A> to specify at which position in the string <A>st</A> the
read data should be stored. Note that <A>offset</A> zero means at the
beginning of the string, which is position 1 in &GAP;. The number of bytes
read or <K>fail</K> in case of an error is returned.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_readdir" Arg=""
      Comm="Reads from a directory."/>
<Returns> a string or <K>fail</K> or <K>false</K> </Returns>
<Description>
Reads from a directory.
For details see <Q><C>man 2 readdir</C></Q>. Note that no argument is required
as we have only one <C>DIR</C> struct on the C level. If the directory
is read completely <K>false</K> is returned, and otherwise a string. An
error is indicated by <K>fail</K>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_readlink" Arg="path, buf, bufsize"
      Comm="Reads the value of a symbolic link."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Reads the value of a symbolic link.
For details see <Q><C>man 2 readlink</C></Q>. <A>buf</A> is modified.
The new length of <A>buf</A> is returned or <K>fail</K> in case of
an error.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_recv" Arg="fd, st, offset, len, flags"
      Comm="Receives data from a socket."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Receives data from a socket.
For details see <Q><C>man 2 recv</C></Q>. Note the additional argument
<A>offset</A> which plays the same role as for the <Ref Func="IO_read"/>
function.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_recvfrom" Arg="fd, st, offset, len, flags, addr"
      Comm="Receives data from a socket with given address."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Receives data from a socket with given address.
For details see <Q><C>man 2 recvfrom</C></Q>. Note the additional argument
<A>offset</A> which plays the same role as for the <Ref Func="IO_read"/>
function. The argument <A>addr</A> can be
made with <Ref Func="IO_make_sockaddr_in"/> and contains its length such
that no 7th argument is necessary.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_rename" Arg="oldpath, newpath"
      Comm="Renames a file or moves it."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
Renames a file or moves it.
For details see <Q><C>man 2 rename</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_rewinddir" Arg=""
      Comm="Rewinds a directory."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Rewinds a directory.
For details see <Q><C>man 2 rewinddir</C></Q>. Note that no argument is required
as we have only one <C>DIR</C> struct on the C level. Returns <K>fail</K>
only, if no prior <Ref Func="IO_opendir"/> command has been called.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_rmdir" Arg="name"
      Comm="Removes an empty directory."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Removes an empty directory.
For details see <Q><C>man 2 rmdir</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_seekdir" Arg="offset"
      Comm="Sets the position of the next readdir call."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Sets the position of the next readdir call.
For details see <Q><C>man 3 seekdir</C></Q>. Note that no second argument is
required as we have only one <C>DIR</C> struct on the C level.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_select" Arg="inlist, outlist, exclist, timeoutsec, timeoutusec"
      Comm="Used for I/O multiplexing."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Used for I/O multiplexing.
For details see <Q><C>man 2 select</C></Q>. <A>inlist</A>, <A>outlist</A> and
<A>exclist</A> are lists of filedescriptors, which are modified. If the
corresponding file descriptor is not yet ready, it is replaced by
<K>fail</K>. The timeout values <A>timeoutsec</A> and
<A>timeoutusec</A> correspond to the usual arguments of <C>select</C>,
if both are immediate integers, they are set, otherwise
<C>select</C> is called with no timeout value.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_send" Arg="fd, st, offset, len, flags"
      Comm="Sends data to a socket."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Sends data to a socket.
For details see <Q><C>man 2 send</C></Q>. Note that the additional argument
<A>offset</A> specifies the position of the data to send within the
string <A>st</A>. It is zero based, meaning that zero indicates the
start of the string, which is position 1 in &GAP;.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_sendto" Arg="fd, st, offset, len, flags, addr"
      Comm="Sends data to a socket."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Sends data to a socket.
For details see <Q><C>man 2 sendto</C></Q>. Note that the additional argument
<A>offset</A> specifies the position of the data to send within the
string <A>st</A>. It is zero based, meaning that zero indicates the
start of the string, which is position 1 in &GAP;. The argument
<A>addr</A> can be
made with <Ref Func="IO_make_sockaddr_in"/> and contains its length such
that no 7th argument is necessary.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_setenv" Arg="name, value, overvwrite"
      Comm="Set the value of an environment variable."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Set the current value of the environment variable <A>name</A> to <A>value</A>
if it has either not been set before, or <A>overwrite</A> is <C>true</C>.
For details see <Q><C>man 3 setenv</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_setsockopt" Arg="fd, level, optname, optval"
      Comm="Sets a socket option."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Sets a socket option.
For details see <Q><C>man 2 setsockopt</C></Q>. Note that the argument
<A>optval</A> carries its length around, such that
no 5th argument is necessary.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_socket" Arg="domain, type, protocol"
      Comm="Creates a socket, an endpoint for communication."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Creates a socket, an endpoint for communication.
For details see <Q><C>man 2 socket</C></Q>.
There is one little special: On systems that have <C>getprotobyname</C>
you can pass a string as third argument <A>protocol</A> which is automatically
looked up by <C>getprotobyname</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_stat" Arg="pathname"
      Comm="Returns the file metadata for the file pathname."/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
Returns the file metadata for the file <A>pathname</A>.
For details see <Q><C>man 2 stat</C></Q>. A &GAP; record is returned with
the same entries than a <C>struct stat</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_symlink" Arg="oldpath, newpath"
      Comm="Creates a symbolic link."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Creates a symbolic link.
For details see <Q><C>man 2 symlink</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_telldir" Arg=""
      Comm="Return current location in directory."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Return current location in directory.
For details see <Q><C>man 3 telldir</C></Q>. Note that no second argument is
required as we have only one <C>DIR</C> struct on the C level.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_unlink" Arg="pathname"
      Comm="Delete a name and possibly the file it refers to."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Delete a name and possibly the file it refers to.
For details see <Q><C>man 2 unlink</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_unsetenv" Arg="name"
      Comm="Remove an environment variable."/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
Remove the environment variable <A>name</A>.
For details see <Q><C>man 3 unsetenv</C></Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_WaitPid" Arg="pid, wait"
      Comm="Waits for the termination of a child process."/>
<Returns> a record or <K>fail</K> or <K>false</K> </Returns>
<Description>
Waits for the termination of a child process.
For details see <Q><C>man 2 waitpid</C></Q>.
The first argument must be a process id, otherwise the function
immediately exits with <K>fail</K> as return value.
<P/>

The second argument <A>wait</A> must be either <K>true</K> or <K>false</K>. 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
<K>false</K>; otherwise, returns a &GAP; record describing the PID, the return
value of waitpid, if the process exited normally and the exit status of the
process.
<P/>

See <Ref Func="IO_fork"/>. If you do not
care about the return value of the process, call
<Ref Func="IO_IgnorePid"/>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_IgnorePid" Arg="pid"
      Comm="Disown a child process."/>
<Returns> Nothing </Returns>
<Description>
Disowns a child process. This means there is no need to call
<Ref Func="IO_WaitPid"/>. Calling <Ref Func="IO_WaitPid"/> on
a pid which was previously passed to <Ref Func="IO_IgnorePid"/>
may cause an infinite loop.F
</Description>
</ManSection>

<ManSection>
<Func Name="IO_write" Arg="fd, st, offset, count"
      Comm="Writes to a file descriptor."/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Writes to a file descriptor.
For details see <Q><C>man 2 write</C></Q>. Note that the additional argument
<A>offset</A> specifies the position of the data to send within the
string <A>st</A>. It is zero based, meaning that zero indicates the
start of the string, which is position 1 in &GAP;.
</Description>
</ManSection>

</Section>

<Section>
<Heading>Further C level functions</Heading>

The following functions do not correspond to functions in the C library,
but are there to provide convenience to use other functions:

<ManSection>
<Func Name="IO_make_sockaddr_in" Arg="ip, port"
      Comm="Makes a struct sockaddr_in from IP address and port."/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
    Makes a struct <C>sockaddr&uscore;in</C> 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.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_environ" Arg=""
      Comm="Returns environment as list of strings."/>
<Returns> a list of strings </Returns>
<Description>
For details see <Q><C>man environ</C></Q>. Returns the current environment
as a list of strings of the form <Q>key=value</Q>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_InstallSIGCHLDHandler" Arg=""
      Comm="Installs our SIGCHLD handler."/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
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
<K>true</K> 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
<Ref Func="IO_RestoreSIGCHLDHandler"/>
See <Ref Func="IO_fork"/>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_RestoreSIGCHLDHandler" Arg=""
      Comm="Restores the original SIGCHLD handler."/>
<Description>
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 <K>true</K> when it is called for the first time after calling
<Ref Func="IO_InstallSIGCHLDHandler"/>. See <Ref Func="IO_fork"/>.
</Description>
</ManSection>

</Section>

</Chapter>

<Chapter Label="bufio">
<Heading>High level functions for buffered I/O</Heading>

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.<P/>

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

Note that considerable care has been taken to ensure that one can
do I/O multiplexing with buffered I/O. That is, one always has the
possibility to make sure before a read or write operation, that this
read or write operation will not block. This is crucial when one
wants to serve more than one I/O channel from the same (single-threaded)
&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.<P/>

One remark applies again to nearly all functions presented here: If an
error is indicated by the returned value <K>fail</K> one can use the
library function <Ref Func="LastSystemError" BookName="ref"/> to find
out more about the cause of the error. This fact is not mentioned with
every single function.

<Section>
    <Heading>Types and the creation of <C>File</C> objects</Heading>

The wrapped file objects are in the following category:

<ManSection>
<Filt Name="IsFile" Arg="o" Type="Category"/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description> The category of <C>File</C> objects. </Description>
</ManSection>

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

<ManSection>
<Func Name="IO_WrapFD" Arg="fd, rbufsize, wbufsize"
      Comm="creates buffering I/O objects, called File objects"/>
<Returns> a <C>File</C> object </Returns>
<Description>
The argument <A>fd</A> must be a file descriptor (i.e. an integer)
or -1 (see below). <P/>

<A>rbufsize</A> can either be <K>false</K> 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 <A>fd</A> must be -1 and a <C>File</C> object that reads from that string
is created.<P/>

<A>wbufsize</A> can either be <K>false</K> 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 <A>fd</A> must be -1 and a <C>File</C> object that appends to that string
is created.<P/>

The result of this function is a new <C>File</C> object.
</Description>
</ManSection>

A convenient way to do this for reading or writing of files on disk
is the following function:
<ManSection>
<Func Name="IO_File" Arg="filename [,mode]"
      Comm="open a file for reading or writing and create a File object"
      Label="mode" />
<Func Name="IO_File" Arg="filename [,bufsize]"
      Comm="open a file for reading or writing and create a File object"
      Label="bufsize" />
<Func Name="IO_File" Arg="filename,mode,bufsize"
      Comm="open a file for reading or writing and create a File object"
      Label="mode and bufsize" />
<Returns> a <C>File</C> object or <K>fail</K> </Returns>
<Description>
The argument <A>filename</A> must be a string specifying the path name
of the file to work on. <A>mode</A> must also be a string with possible
values <Q>r</Q>, <Q>w</Q>, or <Q>a</Q>, meaning read access, write
access (with creating and truncating), and append access respectively.
If <A>mode</A> is omitted, it defaults to <Q>r</Q>. <A>bufsize</A>, if given,
must be a positive integer or <C>false</C>, otherwise it defaults to
<C>IO.DefaultBufSize</C>.
Internally, the
<Ref Func="IO_open"/> function is used and the result file descriptor is
wrapped using <Ref Func="IO_WrapFD"/> with <A>bufsize</A>
as the buffer size. <P/>

The result is either <K>fail</K> in case of an error or a <C>File</C> object
in case of success.
</Description>
</ManSection>

Note that there is a similar function <Ref Func="IO_FilteredFile"/> which
also creates a <C>File</C> object but with additional functionality with
respect to a pipeline for filtering. It is described in its section
in Section <Ref Sect="ipc"/>. There is some more low-level functionality
to acquire open file descriptors. These can be wrapped into <C>File</C>
objects using <Ref Func="IO_WrapFD"/>.

</Section>
<Section>
    <Heading>Reading and writing</Heading>

Once a <C>File</C> object is created, one can use the following
functions on it:

<ManSection>
<Func Name="IO_ReadUntilEOF" Arg="f"
      Comm="buffered read until end of file"/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
This function reads all data from the file <A>f</A> until the end of file.
The data is returned as a &GAP; string. If the file is already at end of
file, an empty string is returned. If an error occurs, then <K>fail</K> is
returned. Note that you still have to call <Ref Func="IO_Close"/> on the
<C>File</C> object to properly close the file later.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_ReadBlock" Arg="f, len"
      Comm="buffered read from File object, blocking"/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
This function gets two arguments, the first argument <A>f</A> must be
a <C>File</C> object and the second argument <A>len</A> must be
a positive integer. The function tries to read <A>len</A> 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, <K>fail</K>
is returned. Note that this function blocks until either <A>len</A> 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!
</Description>
</ManSection>

<ManSection>
<Func Name="IO_ReadLine" Arg="f"
      Comm="buffered read from File object, one line"/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
This function gets exactly one argument, which must be a <C>File</C> object
<A>f</A>. 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 <K>fail</K> in case of an error. In the
latter case, one can query the error with <Ref Func="LastSystemError"
BookName="ref"/>.<P/>

Note that the reading is done via the buffer of <A>f</A>, such that
this function will be quite fast also for large amounts of data.<P/>

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!
</Description>
</ManSection>

<ManSection>
<Func Name="IO_ReadLines" Arg="f [,max]"
      Comm="buffered read from File object, many lines"/>
<Returns> a list of strings or <K>fail</K> </Returns>
<Description>
This function gets one or two arguments, the first of which must always
be a <C>File</C> object <A>f</A>. 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 <A>max</A> lines
(with a second argument <A>max</A>. A list of strings with the result is
returned, if everything went well and <K>fail</K> oterwise. In the
latter case, one can query the error with <Ref Func="LastSystemError"
BookName="ref"/>.<P/>

Note that the reading is done via the buffer of <A>f</A>, such that
this function will be quite fast also for large amounts of data.<P/>

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!
</Description>
</ManSection>

<ManSection>
<Func Name="IO_HasData" Arg="f"/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
This function takes one argument <A>f</A> which must be a <C>File</C>
object. It returns <K>true</K> or <K>false</K> according to whether
there is data to read available in the file <A>f</A>. A return value
of <K>true</K> guarantees that the next call to <Ref Func="IO_Read"/>
on that file will succeed without blocking and return at least one
byte or an empty string to indicate the end of file.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Read" Arg="f, len"
      Comm="buffered read from File object"/>
<Returns> a string or <K>fail</K> </Returns>
<Description>
The function gets two arguments, the first of which must
be a <C>File</C> object <A>f</A>. The second argument must be a positive
integer. The function reads data
up to <A>len</A> bytes.
A string with the result is returned, if everything
went well and <K>fail</K> otherwise. In the latter case, one can query
the error with <Ref Func="LastSystemError" BookName="ref"/>.<P/>

Note that the reading is done via the buffer of <A>f</A>, such that
this function will be quite fast also for large amounts of data.<P/>

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!<P/>

If a previous call to <Ref Func="IO_HasData"/> or to <Ref Func="IO_Select"/>
indicated that there is data available to read, then it is guaranteed that
the function <Ref Func="IO_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.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Write" Arg="f [,things ... ]"
      Comm="buffered write to File object"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
This function can get an arbitrary number of arguments, the first of which
must be a <C>File</C> object <A>f</A>. All the other arguments are just
written to <A>f</A> if they are strings. Otherwise, the <K>String</K>
function is called on them and the result is written out to <A>f</A>.<P/>

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 <Ref Func="IO_Flush"/> on <A>f</A>.<P/>

The result is either the number of bytes written in case of success or
<K>fail</K> in case of an error. In the latter case the error can be
queried with <Ref Func="LastSystemError" BookName="ref"/>.<P/>

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.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_WriteLine" Arg="f, line"
      Comm="buffered write to File object, one line"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Behaves like <Ref Func="IO_Write"/> but works on a single string
<A>line</A> and sends an (operating system dependent) end of line
string afterwards. Also <Ref Func="IO_Flush"/> is called automatically
after the operation, such that one can be sure, that the data is actually
written out after the function has completed.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_WriteLines" Arg="f, list"
      Comm="buffered write to File object, many lines"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
Behaves like <Ref Func="IO_Write"/> but works on a list of strings
<A>list</A> and sends an (operating system dependent) end of line
string after each string in the list. Also <Ref Func="IO_Flush"/> is
called automatically after the operation, such that one can be sure,
that the data is actually written out after the function has completed.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Flush" Arg="f"
      Comm="writes stuff in the buffer to the file"/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
This function gets one argument <A>f</A>, which must be a <C>File</C>
object. It writes out all the data that is in the write buffer. This
is not necessary before the call to the function <Ref Func="IO_Close"/>,
since that function calls <Ref Func="IO_Flush"/> automatically.
However, it is necessary to call <Ref Func="IO_Flush"/> after calls to
<Ref Func="IO_Write"/> to be sure that the data is really sent out. The
function returns <K>true</K> if everything goes well and <K>fail</K>
if an error occurs.<P/>

Remember that the functions <Ref Func="IO_WriteLine"/> and <Ref
Func="IO_WriteLines"/> implicitly call <Ref Func="IO_Flush"/> after
they are done.<P/>

Note that this function might block until all data is actually written
to the file descriptor.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_WriteFlush" Arg="f [,things]"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
This function behaves like <Ref Func="IO_Write"/> followed by a call to
<Ref Func="IO_Flush"/>. It returns either the number of bytes written
or <K>fail</K> if an error occurs.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_ReadyForWrite" Arg="f"/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
This function takes one argument <A>f</A> which must be a <C>File</C>
object. It returns <K>true</K> or <K>false</K> according to whether
the file <A>f</A> is ready to write. A return value
of <K>true</K> guarantees that the next call to <Ref
Func="IO_WriteNonBlocking"/>
on that file will succeed without blocking and accept at least one
byte.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_WriteNonBlocking" Arg="f, st, pos, len"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
This function takes four arguments. The first one <A>f</A> must be
a <C>File</C> object, the second <A>st</A> a string, and the arguments
<A>pos</A> and <A>len</A> must be integers, such that positions
<M><A>pos</A>+1</M> until <M><A>pos</A>+<A>len</A></M> are bound in
<A>st</A>. The function tries to write up to <A>len</A> bytes from
<A>st</A> from position <M><A>pos</A>+1</M> to the file <A>f</A>.
If a previous call to <Ref Func="IO_ReadyForWrite"/> or to <Ref
Func="IO_Select"/> indicates that <A>f</A> is writable, then it is
guaranteed that the following call to <Ref Func="IO_WriteNonBlocking"/>
will not block and accept at least one byte of data. Note that it is not
guaranteed that all <A>len</A> bytes are written. The function returns
the number of bytes written or <K>fail</K> if an error occurs.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_ReadyForFlush" Arg="f"/>
<Returns> <K>true</K> or <K>false</K> </Returns>
<Description>
This function takes one argument <A>f</A> which must be a <C>File</C>
object. It returns <K>true</K> or <K>false</K> according to whether
the file <A>f</A> is ready to flush. A return value
of <K>true</K> guarantees that the next call to <Ref
Func="IO_FlushNonBlocking"/>
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!
</Description>
</ManSection>

<ManSection>
<Func Name="IO_FlushNonBlocking" Arg="f"/>
<Returns> <K>true</K>, <K>false</K>, or <K>fail</K> </Returns>
<Description>
This function takes one argument <A>f</A> which must be a <C>File</C>
object. It tries to write all data in the writing buffer to the file
descriptor. If this succeeds, the function returns <K>true</K> and
<K>false</K> otherwise. If an error occurs, <K>fail</K> is returned.
If a previous call to <Ref Func="IO_ReadyForFlush"/> or <Ref
Func="IO_Select"/> indicated that <A>f</A> is flushable, then it is
guaranteed that the following call to <Ref Func="IO_FlushNonBlocking"/>
does not block. However, it is not guaranteed that <K>true</K> is returned
from that call.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Close" Arg="f"
      Comm="closes file and file descriptor"/>
<Returns> <K>true</K> or <K>fail</K> </Returns>
<Description>
This function closes the <C>File</C> object <A>f</A> 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 <K>fail</K> and otherwise
<K>true</K>. Note that for pipes to other processes this function collects
data about the terminated processes using <Ref Func="IO_WaitPid"/>.
</Description>
</ManSection>

</Section>

<Section>
    <Heading>Other functions</Heading>

<ManSection>
<Func Name="IO_GetFD" Arg="f"
      Comm="returns the real file descriptor as an integer"/>
<Returns> an integer </Returns>
<Description>
This function returns the real file descriptor that is behind the
<C>File</C> object <A>f</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_GetWBuf" Arg="f"
      Comm="returns the writing buffer as a string"/>
<Returns> a string or <K>false</K> </Returns>
<Description>
This function gets one argument <A>f</A> which must be a <C>File</C> object
and returns the writing buffer of that <C>File</C> object. This is
necessary for <C>File</C> 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 <C>File</C> object.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Select" Arg="r, w, f, e, t1, t2"/>
<Returns> an integer or <K>fail</K> </Returns>
<Description>
This function is the corresponding function to <Ref Func="IO_select"/>
for buffered file access. It behaves similarly to that function. The
differences are the following: There are four lists of files <A>r</A>,
<A>w</A>, <A>f</A>, and <A>e</A>. They all can contain either integers
(standing for file descriptors) or <C>File</C> objects. The list <A>r</A>
is for checking, whether files or file descriptors are ready to read, the
list <A>w</A> is for checking whether they are ready to write, the
list <A>f</A> is for checking whether they are ready to flush, and
the list <A>e</A> is for checking whether they have exceptions.<P/>

For <C>File</C> 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 <C>File</C> objects to test for flushability necessary).
For the remaining files and for
all specified file descriptors, the function <Ref Func="IO_select"/> is
called to get an overview about readiness. The timeout values <A>t1</A>
and <A>t2</A> are set to zero for immediate returning if one of the
requested buffers were ready.<P/>

<Ref Func="IO_Select"/> returns the number of files or file descriptors
that are ready to serve or <K>fail</K> if an error occurs.
</Description>
</ManSection>

The following function is a convenience function for directory access:

<ManSection>
<Func Name="IO_ListDir" Arg="pathname"
      Comm="returns a list of file names in the directory pathname"/>
<Returns> a list of strings or <K>fail</K> </Returns>
<Description>
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 <K>fail</K>, if an error occurred.
</Description>
</ManSection>

<ManSection>
<Func Name="ChangeDirectoryCurrent" Arg="pathname"
      Comm="changes the current directory"/>
<Returns> <K>true</K> on success and <K>fail</K> on failure </Returns>
<Description>
    Changes the current directory. Returns <K>true</K> on success and
    <K>fail</K> on failure.
</Description>
</ManSection>

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 <C>connect</C>,
<C>bind</C>, <C>recvfrom</C>, and <C>sendto</C> for the arguments
needing such address pairs.

<ManSection>
<Func Name="IO_MakeIPAddressPort" Arg="ipstring, portnr"
      Comm="creates an IP address port number pair for usage with connect"/>
<Returns> a string </Returns>
<Description>
This function gets a string <A>ipstring</A> containing an IP address
in dot notation, i.e. four numbers in the range from 0 to 255 separated
by dots <Q>.</Q>, and an integer <A>portnr</A>, 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 <A>ipstring</A> can also be a host name, which
is then looked up using <Ref Func="IO_gethostbyname"/> to find the IP
address.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Environment" Arg=""
      Comm="returns a record describing the environment"/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
Takes no arguments, uses <Ref Func="IO_environ"/> 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 <Ref Func="IO_MakeEnvList"/>
to produce again a list which can be used for <Ref Func="IO_execve"/> as
third argument.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_MakeEnvList" Arg="r"
      Comm="takes an environment record and returns a list for execve"/>
<Returns> a list of strings </Returns>
<Description>
Takes a record as returned by <Ref Func="IO_Environment"/> and turns it
into a list of strings as needed by <Ref Func="IO_execve"/> as third
argument.
</Description>
</ManSection>
</Section>

<Section Label="ipc">
    <Heading>Inter process communication</Heading>

<ManSection>
<Func Name="IO_FindExecutable" Arg="path"/>
<Returns> <K>fail</K> or the path to an executable </Returns>
<Description>
If the path name <A>path</A> contains a slash, this function simply
checks whether the string <A>path</A> refers to an executable file. If so,
<A>path</A> is returned as is. Otherwise, <K>fail</K> is returned.
If the path name <A>path</A> does not contain a slash, all directories
in the environment variable <F>PATH</F> are searched for an executable
with name <A>path</A>. If so, the full path to that executable is
returned, otherwise <K>fail</K>.<P/>

This function is used whenever one of the following functions gets an
argument that should refer to an executable.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_CloseAllFDs" Arg="exceptions"
      Comm="Closes all file descriptors except those listed in exceptions"/>
<Returns> nothing </Returns>
<Description>
Closes all file descriptors except those listed in <A>exceptions</A>, which
must be a list of integers.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Popen" Arg="path, argv, mode"
      Comm="Starts a child process with either stdout or stdin being a pipe"/>
<Returns> a <C>File</C> object or <K>fail</K> </Returns>
<Description>
The argument <A>path</A> must refer to an executable file in the sense
of <Ref Func="IO_FindExecutable"/>. <P/>

Starts a child process using the executable in <A>path</A>
with either stdout or stdin being a pipe. The
argument <A>mode</A> must be either the string <Q><C>r</C></Q> or the
string <Q><C>w</C></Q>. <P/>

In the first case, the standard output of the
child process will be the writing end of a pipe. A <C>File</C> 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 &GAP; process. <P/>

In the second case, the standard input of the child process will be the
reading end of a pipe. A <C>File</C> 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 &GAP; process. <P/>

In case of an error, <K>fail</K> is returned. <P/>

The process will usually die, when the pipe is closed, but can also
do so without that. The <C>File</C> object remembers the process ID
of the started process and the <Ref Func="IO_Close"/> function then
calls <Ref Func="IO_WaitPid"/> for it to acquire information about
the terminated process. <P/>
Note that <Ref Func="IO_Popen"/> activates our SIGCHLD handler (see <Ref
Func="IO_InstallSIGCHLDHandler"/>). <P/>

In either case the <C>File</C> object will have the attribute
<Q><K>ProcessID</K></Q> set to the process ID of the child process.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Popen2" Arg="path, argv"
      Comm="Starts a child process with stdin and stdout being a pipe"/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
The argument <A>path</A> must refer to an executable file in the sense
of <Ref Func="IO_FindExecutable"/>. <P/>

A new child process is started using the executable in <A>path</A>.
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 <C>File</C> objects bound to two components
<Q><C>stdin</C></Q> and <Q><C>stdout</C></Q> (resp.) of the returned record.
This means, you have to <E>write</E> to <Q><C>stdin</C></Q> and <E>read</E>
from <Q><C>stdout</C></Q> in the calling &GAP; process.
The standard error of the child process will be
the same as the one of the calling &GAP; process. <P/>

Returns <K>fail</K> if an error occurred. <P/>

The process will usually die, when one of the pipes is closed. The <C>File</C>
objects remember the process ID of the called process and the function
call to <Ref Func="IO_Close"/> for the <C>stdout</C> object will call
<Ref Func="IO_WaitPid"/> for it to acquire information about the
terminated process. <P/>
Note that <Ref Func="IO_Popen2"/> activates our SIGCHLD handler (see <Ref
Func="IO_InstallSIGCHLDHandler"/>). <P/>

Both <C>File</C> objects will have the attribute <Q><K>ProcessID</K></Q>
set to the process ID of the child process, which will also be bound to
the <Q><K>pid</K></Q> component of the returned record.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_Popen3" Arg="path, argv"
   Comm="Starts a child process with stdin, stdout, and stderr being a pipe"/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
The argument <A>path</A> must refer to an executable file in the sense
of <Ref Func="IO_FindExecutable"/>. <P/>

A new child process is started using the executable in <A>path</A>
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 <C>File</C> objects bound to two components
<Q><C>stdin</C></Q>, <Q><C>stdout</C></Q>, and <Q><C>stderr</C></Q>
(resp.) of the returned record.
This means, you have to <E>write</E> to <Q><C>stdin</C></Q> and <E>read</E>
from <Q><C>stdout</C></Q> and <Q><C>stderr</C></Q> in the calling
&GAP; process.<P/>

Returns <K>fail</K> if an error occurred. <P/>

The process will usually die, when one of the pipes is closed. All three
<C>File</C> objects will remember the process ID of the newly created
process and the call to the <Ref Func="IO_Close"/> function for the
<C>stdout</C> object will call <Ref Func="IO_WaitPid"/> for it to acquire
information about the terminated child process. <P/>
Note that <Ref Func="IO_Popen3"/> activates our SIGCHLD handler (see <Ref
Func="IO_InstallSIGCHLDHandler"/>). <P/>

All three <C>File</C> objects will have the attribute <Q><K>ProcessID</K></Q>
set to the process ID of the child process, which will also be bound to
the <Q><K>pid</K></Q> component of the returned record.
</Description>
</ManSection>

<ManSection>
<Func Name="IO_StartPipeline" Arg="progs, infd, outfd, switcherror"/>
<Returns> a record or <K>fail</K> </Returns>
<Description>
    The argument <A>progs</A> is a list of pairs, the first entry being a
    path to an executable (in the sense of <Ref Func="IO_FindExecutable"/>),
    the second an argument list, the argument
    <A>infd</A> is an open file descriptor for
    reading, <A>outfd</A> is an open file descriptor for writing, both can be
    replaced by the string <Q><K>open</K></Q> in which case a new pipe will
    be opened. The argument <A>switcherror</A>
is a boolean indicating whether standard error channels are also
--> --------------------

--> maximum size reached

--> --------------------

quality96%

¤ Dauer der Verarbeitung: 0.52 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.