  
  [1m[4m[31m4. Higher level functions for buffered I/O[0m
  
  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
  [1mGAP[0m  language and is intended to provide a good interface for programming in
  [1mGAP[0m.  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 [1mGAP[0m objects
  that do the buffering.
  
  Note  that  considerable  care  has been taken to ensure that one can do I/O
  multiplexing  with  buffered I/O. That is, one always has the possibility to
  make  sure  before  a  read  or  write  operation,  that  this read or write
  operation  will not block. This is crucial when one wants to serve more than
  one  I/O  channel  from  the same (single-threaded) [1mGAP[0m 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.
  
  
  [1m[4m[31m4.1 Types and the creation of [22m[32mFile[1m[4m[31m objects[0m
  
  The wrapped file objects are in the following category:
  
  [1m[4m[31m4.1-1 IsFile[0m
  
  [1m[34m> IsFile( [0m[22m[34mo[0m[1m[34m ) ______________________________________________________[0mCategory
  
  The category of [22m[32mFile[0m objects.
  
  To create objects in this category, one uses the following function:
  
  [1m[4m[31m4.1-2 IO_WrapFD[0m
  
  [1m[34m> IO_WrapFD( [0m[22m[34mfd, rbufsize, wbufsize[0m[1m[34m ) ______________________________[0mfunction
  
  The  argument  [22m[34mfd[0m  must  be  a  file descriptor (i.e. an integer) or -1 (see
  below).
  
  [22m[34mrbufsize[0m  can  either  be  [22m[32mfalse[0m 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 [22m[34mfd[0m must be -1 and a [22m[32mFile[0m object that reads from that
  string is created.
  
  [22m[34mwbufsize[0m  can  either  be  [22m[32mfalse[0m 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 [22m[34mfd[0m must be -1 and a [22m[32mFile[0m object that appends to that
  string is created.
  
  The result of this function is a new [22m[32mFile[0m object.
  
  A  convenient  way to do this for reading or writing of files on disk is the
  following function:
  
  [1m[4m[31m4.1-3 IO_File[0m
  
  [1m[34m> IO_File( [0m[22m[34mfilename[, mode][0m[1m[34m ) ______________________________________[0mfunction
  [1m[34m> IO_File( [0m[22m[34mfilename[, bufsize][0m[1m[34m ) ___________________________________[0mfunction
  [1m[34m> IO_File( [0m[22m[34mfilename, mode, bufsize[0m[1m[34m ) _______________________________[0mfunction
  
  The  argument [22m[34mfilename[0m must be a string specifying the path name of the file
  to  work  on.  [22m[34mmode[0m  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 [22m[34mmode[0m is omitted, it defaults to "r". [22m[34mbufsize[0m,
  if  given,  must  be  a  positive integer or [22m[32mfalse[0m, otherwise it defaults to
  [22m[32mIO.DefaultBufSize[0m. Internally, the [1m[34mIO_open[0m ([1m3.2-31[0m) function is used and the
  result  file  descriptor  is wrapped using [1m[34mIO_WrapFD[0m ([1m4.1-2[0m) with [22m[34mbufsize[0m as
  the buffer size.
  
  The  result  is  either [22m[32mfail[0m in case of an error or a [22m[32mFile[0m object in case of
  success.
  
  
  [1m[4m[31m4.2 Reading and writing[0m
  
  Once a [22m[32mFile[0m object is created, one can use the following functions on it:
  
  [1m[4m[31m4.2-1 IO_ReadUntilEOF[0m
  
  [1m[34m> IO_ReadUntilEOF( [0m[22m[34mf[0m[1m[34m ) _____________________________________________[0mfunction
  
  This function reads all data from the file [22m[34mf[0m until the end of file. The data
  is returned as a [1mGAP[0m string. If the file is already at end of file, an empty
  string is returned. If an error occurs, then [22m[32mfail[0m is returned.
  
  [1m[4m[31m4.2-2 IO_ReadBlock[0m
  
  [1m[34m> IO_ReadBlock( [0m[22m[34mf, len[0m[1m[34m ) ___________________________________________[0mfunction
  
  This function gets two arguments, the first argument [22m[34mf[0m must be a [22m[32mFile[0m object
  and  the  second argument [22m[34mlen[0m must be a positive integer. The function tries
  to  read  [22m[34mlen[0m  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,  [22m[32mfail[0m  is  returned. Note that this function blocks until either [22m[34mlen[0m
  bytes are read, or the end of file is reached, or an error occurs.
  
  [1m[4m[31m4.2-3 IO_ReadLine[0m
  
  [1m[34m> IO_ReadLine( [0m[22m[34mf[0m[1m[34m ) _________________________________________________[0mfunction
  
  This  function  gets exactly one argument, which must be a [22m[32mFile[0m object [22m[34mf[0m. 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 [22m[32mfail[0m in case
  of   an   error.   In  the  latter  case,  one  can  query  the  error  with
  [1m[34mLastSystemError[0m ([1mReference: LastSystemError[0m).
  
  Note  that  the reading is done via the buffer of [22m[34mf[0m, 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!
  
  [1m[4m[31m4.2-4 IO_ReadLines[0m
  
  [1m[34m> IO_ReadLines( [0m[22m[34mf[, max][0m[1m[34m ) _________________________________________[0mfunction
  
  This function gets one or two arguments, the first of which must always be a
  [22m[32mFile[0m  object  [22m[34mf[0m.  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 [22m[34mmax[0m lines (with a second argument [22m[34mmax[0m. A list of strings
  with  the  result is returned, if everything went well and [22m[32mfail[0m oterwise. In
  the  latter  case,  one can query the error with [1m[34mLastSystemError[0m ([1mReference:
  LastSystemError[0m).
  
  Note  that  the reading is done via the buffer of [22m[34mf[0m, 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!
  
  [1m[4m[31m4.2-5 IO_HasData[0m
  
  [1m[34m> IO_HasData( [0m[22m[34mf[0m[1m[34m ) __________________________________________________[0mfunction
  
  This  function  takes one argument [22m[34mf[0m which must be a [22m[32mFile[0m object. It returns
  [22m[32mtrue[0m  or  [22m[32mfalse[0m  according to whether there is data to read available in the
  file  [22m[34mf[0m.  A  return  value  of [22m[32mtrue[0m guarantees that the next call to [1m[34mIO_Read[0m
  ([1m4.2-6[0m)  on  that file will succeed without blocking and return at least one
  byte or an empty string to indicate the end of file.
  
  [1m[4m[31m4.2-6 IO_Read[0m
  
  [1m[34m> IO_Read( [0m[22m[34mf, len[0m[1m[34m ) ________________________________________________[0mfunction
  
  The function gets two arguments, the first of which must be a [22m[32mFile[0m object [22m[34mf[0m.
  The  second  argument must be a positive integer. The function reads data up
  to  [22m[34mlen[0m bytes. A string with the result is returned, if everything went well
  and  [22m[32mfail[0m  otherwise.  In  the  latter  case,  one  can query the error with
  [1m[34mLastSystemError[0m ([1mReference: LastSystemError[0m).
  
  Note  that  the reading is done via the buffer of [22m[34mf[0m, 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 [1m[34mIO_HasData[0m ([1m4.2-5[0m) or to [1m[34mIO_Select[0m ([1m4.3-3[0m) indicated
  that  there  is  data  available  to  read,  then  it is guaranteed that the
  function [1m[34mIO_Read[0m does not block and returns at least one byte if the file is
  not yet at end of file and an empty string otherwise.
  
  [1m[4m[31m4.2-7 IO_Write[0m
  
  [1m[34m> IO_Write( [0m[22m[34mf[, things, ...][0m[1m[34m ) _____________________________________[0mfunction
  
  This  function  can get an arbitrary number of arguments, the first of which
  must  be  a  [22m[32mFile[0m object [22m[34mf[0m. All the other arguments are just written to [22m[34mf[0m if
  they  are  strings. Otherwise, the [22m[32mString[0m function is called on them and the
  result is written out to [22m[34mf[0m.
  
  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 [1m[34mIO_Flush[0m ([1m4.2-10[0m) on [22m[34mf[0m.
  
  The  result is either the number of bytes written in case of success or [22m[32mfail[0m
  in  case  of  an  error.  In  the  latter case the error can be queried with
  [1m[34mLastSystemError[0m ([1mReference: LastSystemError[0m).
  
  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.
  
  [1m[4m[31m4.2-8 IO_WriteLine[0m
  
  [1m[34m> IO_WriteLine( [0m[22m[34mf, line[0m[1m[34m ) __________________________________________[0mfunction
  
  Behaves like [1m[34mIO_Write[0m ([1m4.2-7[0m) but works on a single string [22m[34mline[0m and sends an
  (operating  system  dependent)  end of line string afterwards. Also [1m[34mIO_Flush[0m
  ([1m4.2-10[0m)  is  called automatically after the operation, such that one can be
  sure,  that  the  data  is  actually  written  out  after  the  function has
  completed.
  
  [1m[4m[31m4.2-9 IO_WriteLines[0m
  
  [1m[34m> IO_WriteLines( [0m[22m[34mf, list[0m[1m[34m ) _________________________________________[0mfunction
  
  Behaves  like [1m[34mIO_Write[0m ([1m4.2-7[0m) but works on a list of strings [22m[34mlist[0m and sends
  an  (operating system dependent) end of line string after each string in the
  list.  Also  [1m[34mIO_Flush[0m  ([1m4.2-10[0m) is called automatically after the operation,
  such  that  one can be sure, that the data is actually written out after the
  function has completed.
  
  [1m[4m[31m4.2-10 IO_Flush[0m
  
  [1m[34m> IO_Flush( [0m[22m[34mf[0m[1m[34m ) ____________________________________________________[0mfunction
  
  This  function  gets  one argument [22m[34mf[0m, which must be a [22m[32mFile[0m object. It writes
  out all the data that is in the writing buffer. This is not necessary before
  the  call  to  the  function  [1m[34mIO_Close[0m  ([1m4.2-16[0m),  since that function calls
  [1m[34mIO_Flush[0m  automatically.  However,  it  is  necessary to call [1m[34mIO_Flush[0m after
  calls  to  [1m[34mIO_Write[0m ([1m4.2-7[0m) to be sure that the data is really sent out. The
  function returns [22m[32mtrue[0m if everything goes well and [22m[32mfail[0m if an error occurs.
  
  Remember  that  the functions [1m[34mIO_WriteLine[0m ([1m4.2-8[0m) and [1m[34mIO_WriteLines[0m ([1m4.2-9[0m)
  implicitly call [1m[34mIO_Flush[0m after they are done.
  
  Note  that  this  function might block until all data is actually written to
  the file descriptor.
  
  [1m[4m[31m4.2-11 IO_WriteFlush[0m
  
  [1m[34m> IO_WriteFlush( [0m[22m[34mf[, things][0m[1m[34m ) _____________________________________[0mfunction
  
  This  function  behaves like [1m[34mIO_Write[0m ([1m4.2-7[0m) followed by a call to [1m[34mIO_Flush[0m
  ([1m4.2-10[0m).  It returns either the number of bytes written or [22m[32mfail[0m if an error
  occurs.
  
  [1m[4m[31m4.2-12 IO_ReadyForWrite[0m
  
  [1m[34m> IO_ReadyForWrite( [0m[22m[34mf[0m[1m[34m ) ____________________________________________[0mfunction
  
  This  function  takes one argument [22m[34mf[0m which must be a [22m[32mFile[0m object. It returns
  [22m[32mtrue[0m  or  [22m[32mfalse[0m  according to whether the file [22m[34mf[0m is ready to write. A return
  value  of [22m[32mtrue[0m guarantees that the next call to [1m[34mIO_WriteNonBlocking[0m ([1m4.2-13[0m)
  on that file will succeed without blocking and accept at least one byte.
  
  [1m[4m[31m4.2-13 IO_WriteNonBlocking[0m
  
  [1m[34m> IO_WriteNonBlocking( [0m[22m[34mf, st, pos, len[0m[1m[34m ) ___________________________[0mfunction
  
  This  function  takes four arguments. The first one [22m[34mf[0m must be a [22m[32mFile[0m object,
  the second [22m[34mst[0m a string, and the arguments [22m[34mpos[0m and [22m[34mlen[0m must be integers, such
  that  positions  [22m[34mpos[0m+1  until [22m[34mpos[0m+[22m[34mlen[0m are bound in [22m[34mst[0m. The function tries to
  write  up  to  [22m[34mlen[0m  bytes  from  [22m[34mst[0m  from position [22m[34mpos[0m+1 to the file [22m[34mf[0m. If a
  previous call to [1m[34mIO_ReadyForWrite[0m ([1m4.2-12[0m) or to [1m[34mIO_Select[0m ([1m4.3-3[0m) indicates
  that  [22m[34mf[0m  is  writable,  then  it  is  guaranteed  that the following call to
  [1m[34mIO_WriteNonBlocking[0m  will  not  block  and accept at least one byte of data.
  Note  that it is not guaranteed that all [22m[34mlen[0m bytes are written. The function
  returns the number of bytes written or [22m[32mfail[0m if an error occurs.
  
  [1m[4m[31m4.2-14 IO_ReadyForFlush[0m
  
  [1m[34m> IO_ReadyForFlush( [0m[22m[34mf[0m[1m[34m ) ____________________________________________[0mfunction
  
  This  function  takes one argument [22m[34mf[0m which must be a [22m[32mFile[0m object. It returns
  [22m[32mtrue[0m  or  [22m[32mfalse[0m  according to whether the file [22m[34mf[0m is ready to flush. A return
  value  of [22m[32mtrue[0m guarantees that the next call to [1m[34mIO_FlushNonBlocking[0m ([1m4.2-15[0m)
  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!
  
  [1m[4m[31m4.2-15 IO_FlushNonBlocking[0m
  
  [1m[34m> IO_FlushNonBlocking( [0m[22m[34mf[0m[1m[34m ) _________________________________________[0mfunction
  
  This  function takes one argument [22m[34mf[0m which must be a [22m[32mFile[0m object. It tries to
  write  all  data  in  the  writing  buffer  to  the file descriptor. If this
  succeeds, the function returns [22m[32mtrue[0m and [22m[32mfalse[0m otherwise. If an error occurs,
  [22m[32mfail[0m  is  returned.  If  a  previous  call  to  [1m[34mIO_ReadyForFlush[0m ([1m4.2-14[0m) or
  [1m[34mIO_Select[0m  ([1m4.3-3[0m) indicated that [22m[34mf[0m is flushable, then it is guaranteed that
  the following call to [1m[34mIO_FlushNonBlocking[0m does not block. However, it is not
  guaranteed that [22m[32mtrue[0m is returned from that call.
  
  [1m[4m[31m4.2-16 IO_Close[0m
  
  [1m[34m> IO_Close( [0m[22m[34mf[0m[1m[34m ) ____________________________________________________[0mfunction
  
  This  function  closes the [22m[32mFile[0m object [22m[34mf[0m 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 [22m[32mfail[0m and otherwise [22m[32mtrue[0m.
  
  
  [1m[4m[31m4.3 Other functions[0m
  
  [1m[4m[31m4.3-1 IO_GetFD[0m
  
  [1m[34m> IO_GetFD( [0m[22m[34mf[0m[1m[34m ) ____________________________________________________[0mfunction
  
  This  function  returns  the  real  file  descriptor that is behind the [22m[32mFile[0m
  object [22m[34mf[0m.
  
  [1m[4m[31m4.3-2 IO_GetWBuf[0m
  
  [1m[34m> IO_GetWBuf( [0m[22m[34mf[0m[1m[34m ) __________________________________________________[0mfunction
  
  This  function  gets  one argument [22m[34mf[0m which must be a [22m[32mFile[0m object and returns
  the  writing buffer of that [22m[32mFile[0m object. This is necessary for [22m[32mFile[0m 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 [22m[32mFile[0m object.
  
  [1m[4m[31m4.3-3 IO_Select[0m
  
  [1m[34m> IO_Select( [0m[22m[34mr, w, f, e, t1, t2[0m[1m[34m ) __________________________________[0mfunction
  
  This  function  is  the  corresponding  function  to  [1m[34mIO_select[0m ([1m3.2-43[0m) for
  buffered file access. It behaves similarly to that function. The differences
  are  the  following:  There are four lists of files [22m[34mr[0m, [22m[34mw[0m, [22m[34mf[0m, and [22m[34me[0m. They all
  can contain either integers (standing for file descriptors) or [22m[32mFile[0m objects.
  The  list  [22m[34mr[0m is for checking, whether files or file descriptors are ready to
  read, the list [22m[34mw[0m is for checking whether they are ready to write, the list [22m[34mf[0m
  is  for  checking  whether  they  are  ready to flush, and the list [22m[34me[0m is for
  checking whether they have exceptions.
  
  For  [22m[32mFile[0m  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.  For  the  remaining files and for all
  specified file descriptors, the function [1m[34mIO_select[0m ([1m3.2-43[0m) is called to get
  an  overview  about  readiness. The timeout values [22m[34mt1[0m and [22m[34mt2[0m are set to zero
  for immediate returning if one of the requested buffers were ready.
  
  [1m[34mIO_Select[0m  returns the number of files or file descriptors that are ready to
  serve or [22m[32mfail[0m if an error occurs.
  
  The following function is a convenience function for directory access:
  
  [1m[4m[31m4.3-4 IO_ListDir[0m
  
  [1m[34m> IO_ListDir( [0m[22m[34mpathname[0m[1m[34m ) ___________________________________________[0mfunction
  
  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 [22m[32mfail[0m, if an error occurred.
  
  The  following function is used to create strings describing a pair of an IP
  address  and  a  port  number  in a binary way. These strings can be used in
  connection  with the C library functions [22m[32mconnect[0m, [22m[32mbind[0m, [22m[32mrecvfrom[0m, and [22m[32msendto[0m
  for the arguments needing such address pairs.
  
  [1m[4m[31m4.3-5 IO_MakeIPAddressPort[0m
  
  [1m[34m> IO_MakeIPAddressPort( [0m[22m[34mipstring, portnr[0m[1m[34m ) _________________________[0mfunction
  
  This  function  gets  a  string  [22m[34mipstring[0m  containing  an  IP address in dot
  notation,  i.e.  four  numbers  in the range from 0 to 255 separated by dots
  ".",  and  an integer [22m[34mportnr[0m, 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.
  
  [1m[4m[31m4.3-6 IO_Environment[0m
  
  [1m[34m> IO_Environment( [0m[22m[34m[0m[1m[34m ) _______________________________________________[0mfunction
  
  Takes  no  arguments,  uses  [1m[34mIO_environ[0m  ([1m3.3-2[0m)  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 [1m[34mIO_MakeEnvList[0m ([1m4.3-7[0m) to
  produce  again  a  list  which  can  be used for [1m[34mIO_execve[0m ([1m3.2-13[0m) as third
  argument.
  
  [1m[4m[31m4.3-7 IO_MakeEnvList[0m
  
  [1m[34m> IO_MakeEnvList( [0m[22m[34mr[0m[1m[34m ) ______________________________________________[0mfunction
  
  Takes  a  record  as  returned by [1m[34mIO_Environment[0m ([1m4.3-6[0m) and turns it into a
  list of strings as needed by [1m[34mIO_execve[0m ([1m3.2-13[0m) as third argument.
  
  
  [1m[4m[31m4.4 Inter process communication[0m
  
  [1m[4m[31m4.4-1 IO_CloseAllFDs[0m
  
  [1m[34m> IO_CloseAllFDs( [0m[22m[34mexceptions[0m[1m[34m ) _____________________________________[0mfunction
  
  Closes all file descriptors except those listed in [22m[34mexceptions[0m, which must be
  a list of integers.
  
  [1m[4m[31m4.4-2 IO_Popen[0m
  
  [1m[34m> IO_Popen( [0m[22m[34mpath, argv, mode[0m[1m[34m ) _____________________________________[0mfunction
  
  Starts  a  child  process  with  either  stdout  or  stdin being a pipe. The
  argument [22m[34mmode[0m must be either the string "[22m[32mr[0m" or the string "[22m[32mw[0m".
  
  In  the  first  case,  the  standard output of the child process will be the
  writing  end  of  a pipe. A [22m[32mFile[0m object for reading connected to the reading
  end  of  the  pipe is returned. The standard input and standard error of the
  child process will be the same than the calling [1mGAP[0m process.
  
  In  the  second  case,  the  standard input of the child process will be the
  reading  end  of  a pipe. A [22m[32mFile[0m object for writing connected to the writing
  end  of  the pipe is returned. The standard output and standard error of the
  child process will be the same than the calling [1mGAP[0m process.
  
  In case of an error, [22m[32mfail[0m is returned.
  
  The  process  will  usually die, when the pipe is closed, but can also do so
  without  that.  It  lies  in  the responsability of the caller to [1m[34mIO_WaitPid[0m
  ([1m3.2-52[0m)   for   it,   if  our  SIGCHLD  handler  has  been  activated  (see
  [1m[34mIO_InstallSIGCHLDHandler[0m ([1m3.3-3[0m)).
  
  In  either  case  the [22m[32mFile[0m object will have the attribute "[22m[32mProcessID[0m" set to
  the process ID of the child process.
  
  [1m[4m[31m4.4-3 IO_Popen2[0m
  
  [1m[34m> IO_Popen2( [0m[22m[34mpath, argv[0m[1m[34m ) __________________________________________[0mfunction
  
  A new child process is started. 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 [22m[32mFile[0m objects bound to two components "[22m[32mstdin[0m" and
  "[22m[32mstdout[0m"  (resp.)  of  the returned record. This means, you have to [22m[36mwrite[0m to
  "[22m[32mstdin[0m"  and  [22m[36mread[0m  from  "[22m[32mstdout[0m"  in the calling [1mGAP[0m process. The standard
  error  of  the  child process will be the same as the one of the calling [1mGAP[0m
  process.
  
  Returns [22m[32mfail[0m if an error occurred.
  
  The  process  will  usually die, when one of the pipes is closed. It lies in
  the  responsability  of  the  caller  to  [1m[34mIO_WaitPid[0m ([1m3.2-52[0m) for it, if our
  SIGCHLD handler has been activated (see [1m[34mIO_InstallSIGCHLDHandler[0m ([1m3.3-3[0m)).
  
  Both  [22m[32mFile[0m objects will have the attribute "[22m[32mProcessID[0m" set to the process ID
  of the child process, which will also be bound to the "[22m[32mpid[0m" component of the
  returned record.
  
  [1m[4m[31m4.4-4 IO_Popen3[0m
  
  [1m[34m> IO_Popen3( [0m[22m[34mpath, argv[0m[1m[34m ) __________________________________________[0mfunction
  
  A  new  child  process  is started. 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 pie are
  returned  as  [22m[32mFile[0m  objects  bound  to two components "[22m[32mstdin[0m", "[22m[32mstdout[0m", and
  "[22m[32mstderr[0m"  (resp.)  of  the returned record. This means, you have to [22m[36mwrite[0m to
  "[22m[32mstdin[0m" and [22m[36mread[0m from "[22m[32mstdout[0m" and "[22m[32mstderr[0m" in the calling [1mGAP[0m process.
  
  Returns [22m[32mfail[0m if an error occurred.
  
  The  process  will  usually die, when one of the pipes is closed. It lies in
  the  responsability  of  the  caller  to  [1m[34mIO_WaitPid[0m ([1m3.2-52[0m) for it, if our
  SIGCHLD handler has been activated (see [1m[34mIO_InstallSIGCHLDHandler[0m ([1m3.3-3[0m)).
  
  All  three  [22m[32mFile[0m  objects  will  have  the  attribute "[22m[32mProcessID[0m" set to the
  process  ID  of  the  child  process,  which will also be bound to the "[22m[32mpid[0m"
  component of the returned record.
  
  [1m[4m[31m4.4-5 IO_SendStringBackground[0m
  
  [1m[34m> IO_SendStringBackground( [0m[22m[34mf, st[0m[1m[34m ) _________________________________[0mfunction
  
  This  functions  uses  [1m[34mIO_Write[0m  ([1m4.2-7[0m) to write the whole string [22m[34mst[0m to the
  [22m[32mFile[0m  object  [22m[34mf[0m.  However,  this  is  done  by  forking  off a child process
  identical  to the calling [1mGAP[0m process that does the sending. The calling [1mGAP[0m
  process  returns  immediately,  even before anything has been sent away with
  the   result   [22m[32mtrue[0m.   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
  [1m[34mIO_Popen2[0m  ([1m4.4-3[0m)  or  [1m[34mIO_Popen3[0m  ([1m4.4-4[0m)  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 [1mGAP[0m 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
  [1mGAP[0m  process  directly  after  [1m[34mIO_SendStringBackground[0m has returned, because
  otherwise  the  child  process  might  not notice that all data has arrived,
  because  the  pipe  persists! See the file [1mpopen2.g[0m in the [1mexample[0m directory
  for an example.
  
  Note that with most modern operating systems the forking off of an identical
  child  process  does in fact [22m[36mnot[0m 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.
  
  [1m[4m[31m4.4-6 IO_PipeThrough[0m
  
  [1m[34m> IO_PipeThrough( [0m[22m[34mcmd, args, input[0m[1m[34m ) _______________________________[0mfunction
  [1mReturns:[0m  a string or [22m[32mfail[0m
  
  Starts  the process with the executable stored at the file name [22m[34mcmd[0m (must be
  a  string) with arguments in the argument list [22m[34margs[0m (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 [22m[34minput[0m is written to the
  standard  input  of  the  called process and its standard output is read and
  returned as a string.
  
  All  the  necessary I/O multiplexing and non-blocking I/O to avoid deadlocks
  is done in this function.
  
  [1m[4m[31m4.4-7 IO_PipeThroughWithError[0m
  
  [1m[34m> IO_PipeThroughWithError( [0m[22m[34mcmd, args, input[0m[1m[34m ) ______________________[0mfunction
  [1mReturns:[0m  a string or [22m[32mfail[0m
  
  Starts  the process with the executable stored at the file name [22m[34mcmd[0m (must be
  a  string) with arguments in the argument list [22m[34margs[0m (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 [22m[34minput[0m 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 [22m[32mout[0m and [22m[32merr[0m, which are
  strings.
  
  All  the  necessary I/O multiplexing and non-blocking I/O to avoid deadlocks
  is done in this function.
  
