3. Functions directly available from the C library
  
  The  following  functions  from  the  C  library  are  made available as GAP
  functions:
  
  accept,  bind,  chdir,  chmod,  chown, close, closedir, connect, creat, dup,
  dup2,  execv,  execve,  execvp,  exit,  fchmod,  fchown, fcntl, fork, fstat,
  gethostbyname,  getpid,  getppid,  getsockopt,  kill,  lchown, link, listen,
  lseek,  lstat,  mkdir,  mkfifo,  mknod,  open, opendir, pipe, read, readdir,
  readlink,  recv,  recvfrom, rename, rewinddir, rmdir, seekdir, select, send,
  sendto, setsockopt, socket, stat, symlink, telldir, unlink, write.
  
  Use the man command in your shell to get information about these functions.
  
  For  each  of  these  functions there is a corresponding GAP global function
  with  the  prefix  IO_  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 fail instead of -1, and if the
  result can only be success or failure, true indicates success.
  
  All errors are reported via the LastSystemError (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 IO record.
  
  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 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.
  
  
  3.1 Differences in arguments - an overview
  
  The  open  function  has to be called with three arguments. The version with
  two arguments is not available on the GAP level.
  
  The read function takes four arguments: fd is an integer file descriptor, st
  is  a  GAP  string, offset is an offset within this string (zero based), and
  count  is  the  maximal number of bytes to read. The data is read and stored
  into  the  string  st,  starting at position offset+1. The string st is made
  long  enough, such that count bytes would fit into it, beginning at position
  offset+1. The number of bytes read is returned or fail in case of an error.
  
  The  write  function  is  similar,  it  also  takes four arguments: fd is an
  integer file descriptor, st is a GAP string, offset is an offset within this
  string  (zero  based),  and  count is the number of bytes to write, starting
  from  position  offset+1  in  the  string st. The number of bytes written is
  returned, or a fail in case of an error.
  
  The opendir function only returns true or fail.
  
  The  readdir  function  takes  no  argument. It reads the directory that was
  specified  in  the  last call to opendir. It just returns a string, which is
  the  name  of  a  file  or  subdirectory  in the corresponding directory. It
  returns  false  after the last file name in the directory or fail in case of
  an error.
  
  The  closedir  function takes no argument. It should be called after readdir
  returned false or fail to avoid excessive use of file descriptors.
  
  The functions stat, fstat, and lstat only take one argument and return a GAP
  record that has the same entries as a struct stat.
  
  The  function socket can optionally take a string as third argument. In that
  case it automatically calls getprotobyname to look up the protocol name.
  
  The  functions  bind  and  connect  take only one string argument as address
  field, because the string already encodes the length.
  
  There   are   two  convenience  functions  IO_make_sockaddr_in  (3.3-1)  and
  IO_MakeIPAddressPort  (4.3-5)  to create such addresses. The first takes two
  arguments  addr and port, where addr is a string of length 4, containing the
  4  bytes  of  the  IP  address and port is a port number as GAP integer. The
  function  IO_MakeIPAddressPort  (4.3-5)  takes  the  same arguments, but the
  first  can  be  a  string  containing  an  IP  address  in dot notation like
  "137.226.152.77".
  
  The  setsockopt  function  has  no argument optlen. The length of the string
  optval is taken.
  
  The select function works as the function UNIXSelect in the GAP library.
  
  As  of  now, the file locking mechanisms of fcntl using struct flock are not
  yet implemented on the GAP level.
  
  
  3.2 The low-level functions in detail
  
  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  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
  true on the GAP level.
  
  3.2-1 IO_accept
  
  > IO_accept( fd, addr ) ____________________________________________function
  Returns:  an integer or fail
  
  Accepts  an incoming network connection. For details see "man 2 accept". The
  argument  addr can be made with IO_make_sockaddr_in (3.3-1) and contains its
  length such that no third argument is necessary.
  
  3.2-2 IO_bind
  
  > IO_bind( fd, my_addr ) ___________________________________________function
  Returns:  an integer or fail
  
  Binds  a  local  address  to  a  socket.  For  details see "man 2 bind". The
  argument  my_addr  can be made with IO_make_sockaddr_in (3.3-1) and contains
  its length such that no third argument is necessary.
  
  3.2-3 IO_chdir
  
  > IO_chdir( path ) _________________________________________________function
  Returns:  true or fail
  
  Changes the current working directory. For details see "man 2 chdir".
  
  3.2-4 IO_chmod
  
  > IO_chmod( pathname, mode ) _______________________________________function
  Returns:  true or fail
  
  Changes the mode of a file. For details see "man 2 chmod".
  
  3.2-5 IO_chown
  
  > IO_chown( path, owner, group ) ___________________________________function
  Returns:  true or fail
  
  Sets owner and/or group of file. For details see "man 2 chown".
  
  3.2-6 IO_close
  
  > IO_close( fd ) ___________________________________________________function
  Returns:  true or fail
  
  Closes a file descriptor. For details see "man 2 close".
  
  3.2-7 IO_closedir
  
  > IO_closedir(  ) __________________________________________________function
  Returns:  true or fail
  
  Closes  a  directory.  For  details  see "man 3 closedir". Has no arguments,
  because we only have one DIR struct in the C part.
  
  3.2-8 IO_connect
  
  > IO_connect( fd, serv_addr ) ______________________________________function
  Returns:  true or fail
  
  Connects  to  a remote socket. For details see "man 2 connect". The argument
  serv_addr  can  be  made  with  IO_make_sockaddr_in (3.3-1) and contains its
  length such that no third argument is necessary.
  
  3.2-9 IO_creat
  
  > IO_creat( pathname, mode ) _______________________________________function
  Returns:  an integer or fail
  
  Creates a new file. For details see "man 2 creat".
  
  3.2-10 IO_dup
  
  > IO_dup( oldfd ) __________________________________________________function
  Returns:  an integer or fail
  
  Duplicates a file descriptor. For details see "man 2 dup".
  
  3.2-11 IO_dup2
  
  > IO_dup2( oldfd, newfd ) __________________________________________function
  Returns:  true or fail
  
  Duplicates a file descriptor to a new one. For details see "man 2 dup2".
  
  3.2-12 IO_execv
  
  > IO_execv( path, argv ) ___________________________________________function
  Returns:  fail or does not return
  
  Replaces  the  process  with another process. For details see "man 3 execv".
  The  argument argv is a list of strings. The called program does not have to
  be the first argument in this list.
  
  3.2-13 IO_execve
  
  > IO_execve( path, argv, envp ) ____________________________________function
  Returns:  fail or does not return
  
  Replaces  the  process with another process. For details see "man 3 execve".
  The  arguments  argv  and envp are both lists of strings. The called program
  does  not  have  to be the first argument in argv. The list envp can be made
  with  IO_MakeEnvList  (4.3-7)  from  a  record  acquired from IO_Environment
  (4.3-6) and modified later.
  
  3.2-14 IO_execvp
  
  > IO_execvp( path, argv ) __________________________________________function
  Returns:  fail or does not return
  
  Replaces  the  process with another process. For details see "man 3 execvp".
  The  argument argv is a list of strings. The called program does not have to
  be the first argument in this list.
  
  3.2-15 IO_exit
  
  > IO_exit( status ) ________________________________________________function
  
  Stops  process  immediately  with return code status. For details see "man 2
  exit". The argument status must be an integer. Does not return.
  
  3.2-16 IO_fchmod
  
  > IO_fchmod( fd, mode ) ____________________________________________function
  Returns:  true or fail
  
  Changes mode of an opened file. For details see "man 2 fchmod".
  
  3.2-17 IO_fchown
  
  > IO_fchown( fd, owner, group ) ____________________________________function
  Returns:  true or fail
  
  Changes  owner  and/or  group  of  an  opened  file.  For details see "man 2
  fchown".
  
  3.2-18 IO_fcntl
  
  > IO_fcntl( fd, cmd, arg ) _________________________________________function
  Returns:  an integer or fail
  
  Does  various  things  to  control  the  behaviour of a file descriptor. For
  details see "man 2 fcntl".
  
  3.2-19 IO_fork
  
  > IO_fork(  ) ______________________________________________________function
  Returns:  an integer or fail
  
  Forks  off a child process, which is an identical copy. For details see "man
  2  fork".  Note  that if you want to use the IO_WaitPid (3.2-55) function to
  wait  or  check for the termination of child processes, you have to activate
  the  SIGCHLD  handler  for  this  package  beforehand  by using the function
  IO_InstallSIGCHLDHandler  (3.3-3).  Note  further that after that you cannot
  use       the       function       InputOutputLocalProcess       (Reference:
  InputOutputLocalProcess)  any  more, since its SIGCHLD handler does not work
  any   more.   To   switch  back  to  that  functionality  use  the  function
  IO_RestoreSIGCHLDHandler (3.3-4).
  
  3.2-20 IO_fstat
  
  > IO_fstat( fd ) ___________________________________________________function
  Returns:  a record or fail
  
  Returns  the  file  meta  data  for  an  opened file. For details see "man 2
  fstat". A GAP record is returned with the same entries than a struct stat.
  
  3.2-21 IO_gethostbyname
  
  > IO_gethostbyname( name ) _________________________________________function
  Returns:  a record or fail
  
  Return  host  information  by name. For details see "man 3 gethostbyname". A
  GAP record is returned with all the relevant information about the host.
  
  3.2-22 IO_getpid
  
  > IO_getpid(  ) ____________________________________________________function
  Returns:  an integer
  
  Returns the process ID of the current process as an integer. For details see
  "man 2 getpid".
  
  3.2-23 IO_getppid
  
  > IO_getppid(  ) ___________________________________________________function
  Returns:  an integer
  
  Returns  the  process ID of the parent of the current process as an integer.
  For details see "man 2 getppid".
  
  3.2-24 IO_getsockopt
  
  > IO_getsockopt( fd, level, optname, optval ) ______________________function
  Returns:  true or false
  
  Get  a  socket  option.  For  details  see "man 2 getsockopt". Note that the
  argument  optval  carries  its  length  around, such that no 5th argument is
  necessary.
  
  3.2-25 IO_kill
  
  > IO_kill( pid, sig ) ______________________________________________function
  Returns:  true or fail
  
  Sends  the  signal  sig  to the process with process ID pid. For details see
  "man  2  kill".  The  signal numbers available can be found in the global IO
  record with names like SIGTERM.
  
  3.2-26 IO_lchown
  
  > IO_lchown( path, owner, group ) __________________________________function
  Returns:  true or false
  
  Changes  owner  and/or  group of a file not following links. For details see
  "man 2 lchown".
  
  3.2-27 IO_link
  
  > IO_link( oldpath, newpath ) ______________________________________function
  Returns:  true or false
  
  Create a hard link. For details see "man 2 link".
  
  3.2-28 IO_listen
  
  > IO_listen( fd, backlog ) _________________________________________function
  Returns:  true or false
  
  Switch a socket to listening. For details see "man 2 listen".
  
  3.2-29 IO_lseek
  
  > IO_lseek( fd, offset, whence ) ___________________________________function
  Returns:  an integer or fail
  
  Seeks within an open file. For details see "man 2 lseek".
  
  3.2-30 IO_lstat
  
  > IO_lstat( name ) _________________________________________________function
  Returns:  a record or fail
  
  Returns  the  file meta data for a file not following links. For details see
  "man  2 lstat". A GAP record is returned with the same entries than a struct
  stat.
  
  3.2-31 IO_mkdir
  
  > IO_mkdir( pathname, mode ) _______________________________________function
  Returns:  true or false
  
  Creates a directory. For details see "man 2 mkdir".
  
  3.2-32 IO_mkfifo
  
  > IO_mkfifo( pathname, mode ) ______________________________________function
  Returns:  true or false
  
  Creates a FIFO special file (a named pipe). For details see "man 3 mkfifo".
  
  3.2-33 IO_mknod
  
  > IO_mknod( pathname, mode, dev ) __________________________________function
  Returns:  true or false
  
  Create a special or ordinary file. For details see "man 2 mknod".
  
  3.2-34 IO_open
  
  > IO_open( pathname, flags, mode ) _________________________________function
  Returns:  an integer or fail
  
  Open  and  possibly  create  a file or device. For details see "man 2 open".
  Only the variant with 3 arguments can be used.
  
  3.2-35 IO_opendir
  
  > IO_opendir( name ) _______________________________________________function
  Returns:  true or false
  
  Opens  a  directory. For details see "man 3 opendir". Note that only true is
  returned  if  everything is OK, since only one DIR struct is stored on the C
  level and thus only one directory can be open at any time.
  
  3.2-36 IO_pipe
  
  > IO_pipe(  ) ______________________________________________________function
  Returns:  a record or fail
  
  Create  a pair of file descriptors with a pipe between them. For details see
  "man  2  pipe". Note that no arguments are needed. The result is either fail
  in case of an error or a record with two components toread and towrite bound
  to the two filedescriptors for reading and writing respectively.
  
  3.2-37 IO_read
  
  > IO_read( fd, st, offset, count ) _________________________________function
  Returns:  an integer or fail
  
  Reads from file descriptor. For details see "man 2 read". Note that there is
  one  more  argument offset to specify at which position in the string st the
  read  data should be stored. Note that offset zero means at the beginning of
  the  string, which is position 1 in GAP. The number of bytes read or fail in
  case of an error is returned.
  
  3.2-38 IO_readdir
  
  > IO_readdir(  ) ___________________________________________________function
  Returns:  a string or fail or false
  
  Reads  from  a  directory.  For  details  see  "man 2 readdir". Note that no
  argument  is  required as we have only one DIR struct on the C level. If the
  directory  is  read completely false is returned, and otherwise a string. An
  error is indicated by fail.
  
  3.2-39 IO_readlink
  
  > IO_readlink( path, buf, bufsize ) ________________________________function
  Returns:  an integer or fail
  
  Reads the value of a symbolic link. For details see "man 2 readlink". buf is
  modified. The new length of buf is returned or fail in case of an error.
  
  3.2-40 IO_recv
  
  > IO_recv( fd, st, offset, len, flags ) ____________________________function
  Returns:  an integer or fail
  
  Receives  data  from  a  socket.  For  details  see  "man  2 recv". Note the
  additional  argument  offset  which  plays  the same role as for the IO_read
  (3.2-37) function.
  
  3.2-41 IO_recvfrom
  
  > IO_recvfrom( fd, st, offset, len, flags, addr ) __________________function
  Returns:  an integer or fail
  
  Receives  data  from  a  socket  with  given address. For details see "man 2
  recvfrom".  Note the additional argument offset which plays the same role as
  for  the  IO_read  (3.2-37)  function.  The  argument  addr can be made with
  IO_make_sockaddr_in  (3.3-1)  and  contains  its  length  such  that  no 7th
  argument is necessary.
  
  3.2-42 IO_rename
  
  > IO_rename( oldpath, newpath ) ____________________________________function
  Returns:  true or false
  
  Renames a file or moves it. For details see "man 2 rename".
  
  3.2-43 IO_rewinddir
  
  > IO_rewinddir(  ) _________________________________________________function
  Returns:  true or fail
  
  Rewinds  a  directory.  For  details  see  "man  2  rewinddir". Note that no
  argument  is required as we have only one DIR struct on the C level. Returns
  fail only, if no prior IO_opendir (3.2-35) command has been called.
  
  3.2-44 IO_rmdir
  
  > IO_rmdir( name ) _________________________________________________function
  Returns:  true or fail
  
  Removes an empty directory. For details see "man 2 rmdir".
  
  3.2-45 IO_seekdir
  
  > IO_seekdir( offset ) _____________________________________________function
  Returns:  true or fail
  
  Sets the position of the next readdir call. For details see "man 3 seekdir".
  Note  that  no second argument is required as we have only one DIR struct on
  the C level.
  
  3.2-46 IO_select
  
  > IO_select( inlist, outlist, exclist, timeoutsec, timeoutusec ) ___function
  Returns:  an integer or fail
  
  Used  for  I/O multiplexing. For details see "man 2 select". inlist, outlist
  and  exclist  are  lists  of  filedescriptors,  which  are  modified. If the
  corresponding file descriptor is not yet ready, it is replaced by fail.
  
  3.2-47 IO_send
  
  > IO_send( fd, st, offset, len, flags ) ____________________________function
  Returns:  an integer or fail
  
  Sends  data  to  a  socket.  For  details  see  "man  2 send". Note that the
  additional argument offset specifies the position of the data to send within
  the  string  st.  It is zero based, meaning that zero indicates the start of
  the string, which is position 1 in GAP.
  
  3.2-48 IO_sendto
  
  > IO_sendto( fd, st, offset, len, flags, addr ) ____________________function
  Returns:  an integer or fail
  
  Sends  data  to  a  socket.  For  details  see "man 2 sendto". Note that the
  additional argument offset specifies the position of the data to send within
  the  string  st.  It is zero based, meaning that zero indicates the start of
  the  string,  which is position 1 in GAP. The argument addr can be made with
  IO_make_sockaddr_in  (3.3-1)  and  contains  its  length  such  that  no 7th
  argument is necessary.
  
  3.2-49 IO_setsockopt
  
  > IO_setsockopt( fd, level, optname, optval ) ______________________function
  Returns:  true or fail
  
  Sets  a  socket  option.  For  details see "man 2 setsockopt". Note that the
  argument  optval  carries  its  length  around, such that no 5th argument is
  necessary.
  
  3.2-50 IO_socket
  
  > IO_socket( domain, type, protocol ) ______________________________function
  Returns:  an integer or fail
  
  Creates  a  socket,  an  endpoint  for communication. For details see "man 2
  socket".  There  is  one little special: On systems that have getprotobyname
  you  can  pass  a  string  as third argument protocol which is automatically
  looked up by getprotobyname.
  
  3.2-51 IO_stat
  
  > IO_stat( pathname ) ______________________________________________function
  Returns:  a record or fail
  
  Returns  the  file  metadata  for  the file pathname. For details see "man 2
  stat". A GAP record is returned with the same entries than a struct stat.
  
  3.2-52 IO_symlink
  
  > IO_symlink( oldpath, newpath ) ___________________________________function
  Returns:  true or fail
  
  Creates a symbolic link. For details see "man 2 symlink".
  
  3.2-53 IO_telldir
  
  > IO_telldir(  ) ___________________________________________________function
  Returns:  an integer or fail
  
  Return  current location in directory. For details see "man 3 telldir". Note
  that  no second argument is required as we have only one DIR struct on the C
  level.
  
  3.2-54 IO_unlink
  
  > IO_unlink( pathname ) ____________________________________________function
  Returns:  true or fail
  
  Delete  a  name  and  possibly the file it refers to. For details see "man 2
  unlink".
  
  3.2-55 IO_WaitPid
  
  > IO_WaitPid( pid, wait ) __________________________________________function
  Returns:  a record or fail
  
  Waits  for  the  termination  of  a  child  process.  For details see "man 2
  waitpid".  Returns  a  GAP record describing PID and exit status. The second
  argument  wait  must  be  either  true or false. In the first case, the call
  blocks  until new information about a terminated child process is available.
  In  the  second  case  no  such  waiting  is  performed,  the  call  returns
  immediately. See IO_fork (3.2-19).
  
  3.2-56 IO_write
  
  > IO_write( fd, st, offset, count ) ________________________________function
  Returns:  an integer or fail
  
  Writes  to  a  file descriptor. For details see "man 2 write". Note that the
  additional argument offset specifies the position of the data to send within
  the  string  st.  It is zero based, meaning that zero indicates the start of
  the string, which is position 1 in GAP.
  
  
  3.3 Further C level functions
  
  The following functions do not correspond to functions in the C library, but
  are there to provide convenience to use other functions:
  
  3.3-1 IO_make_sockaddr_in
  
  > IO_make_sockaddr_in( ip, port ) __________________________________function
  Returns:  a string or fail
  
  Makes  a struct sockaddr_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.
  
  3.3-2 IO_environ
  
  > IO_environ(  ) ___________________________________________________function
  Returns:  a list of strings
  
  For  details see "man environ". Returns the current environment as a list of
  strings of the form "key=value".
  
  3.3-3 IO_InstallSIGCHLDHandler
  
  > IO_InstallSIGCHLDHandler(  ) _____________________________________function
  Returns:  true or 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
  true  when  it  is called for the first time since then a pointer to the old
  signal handler is stored in a global variable. See IO_fork (3.2-19).
  
  3.3-4 IO_RestoreSIGCHLDHandler
  
  > IO_RestoreSIGCHLDHandler(  ) _____________________________________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   true   when  it  is  called  for  the  first  time  after  calling
  IO_InstallSIGCHLDHandler (3.3-3). See IO_fork (3.2-19).