  
  [1X4. High level functions for buffered I/O[0X
  
  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
  [5XGAP[0X  language and is intended to provide a good interface for programming in
  [5XGAP[0X.  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 [5XGAP[0X 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) [5XGAP[0X process. This design
  principle  sometimes  made it necessary to have more than one function for a
  certain  operation.  Those  functions  usually  differ  in a subtle way with
  respect to their blocking behaviour.
  
  One remark applies again to nearly all functions presented here: If an error
  is  indicated  by  the  returned value [9Xfail[0X one can use the library function
  [2XLastSystemError[0X  ([14XReference:  LastSystemError[0X)  to  find  out more about the
  cause of the error. This fact is not mentioned with every single function.
  
  
  [1X4.1 Types and the creation of [10XFile[0X[1X objects[0X
  
  The wrapped file objects are in the following category:
  
  [1X4.1-1 IsFile[0X
  
  [2X> IsFile( [0X[3Xo[0X[2X ) ______________________________________________________[0XCategory
  [6XReturns:[0X  [9Xtrue[0X or [9Xfalse[0X
  
  The category of [10XFile[0X objects.
  
  To create objects in this category, one uses the following function:
  
  [1X4.1-2 IO_WrapFD[0X
  
  [2X> IO_WrapFD( [0X[3Xfd, rbufsize, wbufsize[0X[2X ) ______________________________[0Xfunction
  [6XReturns:[0X  a [10XFile[0X object
  
  The  argument  [3Xfd[0X  must  be  a  file descriptor (i.e. an integer) or -1 (see
  below).
  
  [3Xrbufsize[0X  can  either  be  [9Xfalse[0X 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 [3Xfd[0X must be -1 and a [10XFile[0X object that reads from that
  string is created.
  
  [3Xwbufsize[0X  can  either  be  [9Xfalse[0X 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 [3Xfd[0X must be -1 and a [10XFile[0X object that appends to that
  string is created.
  
  The result of this function is a new [10XFile[0X object.
  
  A  convenient  way to do this for reading or writing of files on disk is the
  following function:
  
  [1X4.1-3 IO_File[0X
  
  [2X> IO_File( [0X[3Xfilename[, mode][0X[2X ) ______________________________________[0Xfunction
  [2X> IO_File( [0X[3Xfilename[, bufsize][0X[2X ) ___________________________________[0Xfunction
  [2X> IO_File( [0X[3Xfilenamemodebufsize[0X[2X ) ___________________________________[0Xfunction
  [6XReturns:[0X  a [10XFile[0X object or [9Xfail[0X
  
  The  argument [3Xfilename[0X must be a string specifying the path name of the file
  to  work  on.  [3Xmode[0X  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 [3Xmode[0X is omitted, it defaults to "r". [3Xbufsize[0X,
  if  given,  must  be  a  positive integer or [10Xfalse[0X, otherwise it defaults to
  [10XIO.DefaultBufSize[0X. Internally, the [2XIO_open[0X ([14X3.2-34[0X) function is used and the
  result  file  descriptor  is wrapped using [2XIO_WrapFD[0X ([14X4.1-2[0X) with [3Xbufsize[0X as
  the buffer size.
  
  The  result  is  either [9Xfail[0X in case of an error or a [10XFile[0X object in case of
  success.
  
  Note  that  there  is  a similar function [2XIO_FilteredFile[0X ([14X4.4-9[0X) which also
  creates  a  [10XFile[0X  object but with additional functionality with respect to a
  pipeline for filtering. It is described in its section in Section [14X4.4[0X. There
  is some more low-level functionality to acquire open file descriptors. These
  can be wrapped into [10XFile[0X objects using [2XIO_WrapFD[0X ([14X4.1-2[0X).
  
  
  [1X4.2 Reading and writing[0X
  
  Once a [10XFile[0X object is created, one can use the following functions on it:
  
  [1X4.2-1 IO_ReadUntilEOF[0X
  
  [2X> IO_ReadUntilEOF( [0X[3Xf[0X[2X ) _____________________________________________[0Xfunction
  [6XReturns:[0X  a string or [9Xfail[0X
  
  This function reads all data from the file [3Xf[0X until the end of file. The data
  is returned as a [5XGAP[0X string. If the file is already at end of file, an empty
  string is returned. If an error occurs, then [9Xfail[0X is returned. Note that you
  still  have  to  call [2XIO_Close[0X ([14X4.2-16[0X) on the [10XFile[0X object to properly close
  the file later.
  
  [1X4.2-2 IO_ReadBlock[0X
  
  [2X> IO_ReadBlock( [0X[3Xf, len[0X[2X ) ___________________________________________[0Xfunction
  [6XReturns:[0X  a string or [9Xfail[0X
  
  This function gets two arguments, the first argument [3Xf[0X must be a [10XFile[0X object
  and  the  second argument [3Xlen[0X must be a positive integer. The function tries
  to  read  [3Xlen[0X  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,  [9Xfail[0X  is  returned. Note that this function blocks until either [3Xlen[0X
  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!
  
  [1X4.2-3 IO_ReadLine[0X
  
  [2X> IO_ReadLine( [0X[3Xf[0X[2X ) _________________________________________________[0Xfunction
  [6XReturns:[0X  a string or [9Xfail[0X
  
  This  function  gets exactly one argument, which must be a [10XFile[0X object [3Xf[0X. 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 [9Xfail[0X in case
  of   an   error.   In  the  latter  case,  one  can  query  the  error  with
  [2XLastSystemError[0X ([14XReference: LastSystemError[0X).
  
  Note  that  the reading is done via the buffer of [3Xf[0X, 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!
  
  [1X4.2-4 IO_ReadLines[0X
  
  [2X> IO_ReadLines( [0X[3Xf[, max][0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  a list of strings or [9Xfail[0X
  
  This function gets one or two arguments, the first of which must always be a
  [10XFile[0X  object  [3Xf[0X.  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 [3Xmax[0X lines (with a second argument [3Xmax[0X. A list of strings
  with  the  result is returned, if everything went well and [9Xfail[0X oterwise. In
  the  latter  case,  one can query the error with [2XLastSystemError[0X ([14XReference:
  LastSystemError[0X).
  
  Note  that  the reading is done via the buffer of [3Xf[0X, 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!
  
  [1X4.2-5 IO_HasData[0X
  
  [2X> IO_HasData( [0X[3Xf[0X[2X ) __________________________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or [9Xfalse[0X
  
  This  function  takes one argument [3Xf[0X which must be a [10XFile[0X object. It returns
  [9Xtrue[0X  or  [9Xfalse[0X  according to whether there is data to read available in the
  file  [3Xf[0X.  A  return  value  of [9Xtrue[0X guarantees that the next call to [2XIO_Read[0X
  ([14X4.2-6[0X)  on  that file will succeed without blocking and return at least one
  byte or an empty string to indicate the end of file.
  
  [1X4.2-6 IO_Read[0X
  
  [2X> IO_Read( [0X[3Xf, len[0X[2X ) ________________________________________________[0Xfunction
  [6XReturns:[0X  a string or [9Xfail[0X
  
  The function gets two arguments, the first of which must be a [10XFile[0X object [3Xf[0X.
  The  second  argument must be a positive integer. The function reads data up
  to  [3Xlen[0X bytes. A string with the result is returned, if everything went well
  and  [9Xfail[0X  otherwise.  In  the  latter  case,  one  can query the error with
  [2XLastSystemError[0X ([14XReference: LastSystemError[0X).
  
  Note  that  the reading is done via the buffer of [3Xf[0X, 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 [2XIO_HasData[0X ([14X4.2-5[0X) or to [2XIO_Select[0X ([14X4.3-3[0X) indicated
  that  there  is  data  available  to  read,  then  it is guaranteed that the
  function [2XIO_Read[0X does not block and returns at least one byte if the file is
  not yet at end of file and an empty string otherwise.
  
  [1X4.2-7 IO_Write[0X
  
  [2X> IO_Write( [0X[3Xf[, things, ...][0X[2X ) _____________________________________[0Xfunction
  [6XReturns:[0X  an integer or [9Xfail[0X
  
  This  function  can get an arbitrary number of arguments, the first of which
  must  be  a  [10XFile[0X object [3Xf[0X. All the other arguments are just written to [3Xf[0X if
  they  are  strings. Otherwise, the [9XString[0X function is called on them and the
  result is written out to [3Xf[0X.
  
  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 [2XIO_Flush[0X ([14X4.2-10[0X) on [3Xf[0X.
  
  The  result is either the number of bytes written in case of success or [9Xfail[0X
  in  case  of  an  error.  In  the  latter case the error can be queried with
  [2XLastSystemError[0X ([14XReference: LastSystemError[0X).
  
  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.
  
  [1X4.2-8 IO_WriteLine[0X
  
  [2X> IO_WriteLine( [0X[3Xf, line[0X[2X ) __________________________________________[0Xfunction
  [6XReturns:[0X  an integer or [9Xfail[0X
  
  Behaves like [2XIO_Write[0X ([14X4.2-7[0X) but works on a single string [3Xline[0X and sends an
  (operating  system  dependent)  end of line string afterwards. Also [2XIO_Flush[0X
  ([14X4.2-10[0X)  is  called automatically after the operation, such that one can be
  sure,  that  the  data  is  actually  written  out  after  the  function has
  completed.
  
  [1X4.2-9 IO_WriteLines[0X
  
  [2X> IO_WriteLines( [0X[3Xf, list[0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  an integer or [9Xfail[0X
  
  Behaves  like [2XIO_Write[0X ([14X4.2-7[0X) but works on a list of strings [3Xlist[0X and sends
  an  (operating system dependent) end of line string after each string in the
  list.  Also  [2XIO_Flush[0X  ([14X4.2-10[0X) is called automatically after the operation,
  such  that  one can be sure, that the data is actually written out after the
  function has completed.
  
  [1X4.2-10 IO_Flush[0X
  
  [2X> IO_Flush( [0X[3Xf[0X[2X ) ____________________________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or [9Xfail[0X
  
  This  function  gets  one argument [3Xf[0X, which must be a [10XFile[0X object. It writes
  out  all  the data that is in the write buffer. This is not necessary before
  the  call  to  the  function  [2XIO_Close[0X  ([14X4.2-16[0X),  since that function calls
  [2XIO_Flush[0X  automatically.  However,  it  is  necessary to call [2XIO_Flush[0X after
  calls  to  [2XIO_Write[0X ([14X4.2-7[0X) to be sure that the data is really sent out. The
  function returns [9Xtrue[0X if everything goes well and [9Xfail[0X if an error occurs.
  
  Remember  that  the functions [2XIO_WriteLine[0X ([14X4.2-8[0X) and [2XIO_WriteLines[0X ([14X4.2-9[0X)
  implicitly call [2XIO_Flush[0X after they are done.
  
  Note  that  this  function might block until all data is actually written to
  the file descriptor.
  
  [1X4.2-11 IO_WriteFlush[0X
  
  [2X> IO_WriteFlush( [0X[3Xf[, things][0X[2X ) _____________________________________[0Xfunction
  [6XReturns:[0X  an integer or [9Xfail[0X
  
  This  function  behaves like [2XIO_Write[0X ([14X4.2-7[0X) followed by a call to [2XIO_Flush[0X
  ([14X4.2-10[0X).  It returns either the number of bytes written or [9Xfail[0X if an error
  occurs.
  
  [1X4.2-12 IO_ReadyForWrite[0X
  
  [2X> IO_ReadyForWrite( [0X[3Xf[0X[2X ) ____________________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or [9Xfalse[0X
  
  This  function  takes one argument [3Xf[0X which must be a [10XFile[0X object. It returns
  [9Xtrue[0X  or  [9Xfalse[0X  according to whether the file [3Xf[0X is ready to write. A return
  value  of [9Xtrue[0X guarantees that the next call to [2XIO_WriteNonBlocking[0X ([14X4.2-13[0X)
  on that file will succeed without blocking and accept at least one byte.
  
  [1X4.2-13 IO_WriteNonBlocking[0X
  
  [2X> IO_WriteNonBlocking( [0X[3Xf, st, pos, len[0X[2X ) ___________________________[0Xfunction
  [6XReturns:[0X  an integer or [9Xfail[0X
  
  This  function  takes four arguments. The first one [3Xf[0X must be a [10XFile[0X object,
  the second [3Xst[0X a string, and the arguments [3Xpos[0X and [3Xlen[0X must be integers, such
  that  positions  [3Xpos[0X+1  until [3Xpos[0X+[3Xlen[0X are bound in [3Xst[0X. The function tries to
  write  up  to  [3Xlen[0X  bytes  from  [3Xst[0X  from position [3Xpos[0X+1 to the file [3Xf[0X. If a
  previous call to [2XIO_ReadyForWrite[0X ([14X4.2-12[0X) or to [2XIO_Select[0X ([14X4.3-3[0X) indicates
  that  [3Xf[0X  is  writable,  then  it  is  guaranteed  that the following call to
  [2XIO_WriteNonBlocking[0X  will  not  block  and accept at least one byte of data.
  Note  that it is not guaranteed that all [3Xlen[0X bytes are written. The function
  returns the number of bytes written or [9Xfail[0X if an error occurs.
  
  [1X4.2-14 IO_ReadyForFlush[0X
  
  [2X> IO_ReadyForFlush( [0X[3Xf[0X[2X ) ____________________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or [9Xfalse[0X
  
  This  function  takes one argument [3Xf[0X which must be a [10XFile[0X object. It returns
  [9Xtrue[0X  or  [9Xfalse[0X  according to whether the file [3Xf[0X is ready to flush. A return
  value  of [9Xtrue[0X guarantees that the next call to [2XIO_FlushNonBlocking[0X ([14X4.2-15[0X)
  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!
  
  [1X4.2-15 IO_FlushNonBlocking[0X
  
  [2X> IO_FlushNonBlocking( [0X[3Xf[0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X, [9Xfalse[0X, or [9Xfail[0X
  
  This  function takes one argument [3Xf[0X which must be a [10XFile[0X object. It tries to
  write  all  data  in  the  writing  buffer  to  the file descriptor. If this
  succeeds, the function returns [9Xtrue[0X and [9Xfalse[0X otherwise. If an error occurs,
  [9Xfail[0X  is  returned.  If  a  previous  call  to  [2XIO_ReadyForFlush[0X ([14X4.2-14[0X) or
  [2XIO_Select[0X  ([14X4.3-3[0X) indicated that [3Xf[0X is flushable, then it is guaranteed that
  the following call to [2XIO_FlushNonBlocking[0X does not block. However, it is not
  guaranteed that [9Xtrue[0X is returned from that call.
  
  [1X4.2-16 IO_Close[0X
  
  [2X> IO_Close( [0X[3Xf[0X[2X ) ____________________________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or [9Xfail[0X
  
  This  function  closes the [10XFile[0X object [3Xf[0X 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 [9Xfail[0X and otherwise [9Xtrue[0X. Note that for
  pipes  to  other  processes this function collects data about the terminated
  processes using [2XIO_WaitPid[0X ([14X3.2-55[0X).
  
  
  [1X4.3 Other functions[0X
  
  [1X4.3-1 IO_GetFD[0X
  
  [2X> IO_GetFD( [0X[3Xf[0X[2X ) ____________________________________________________[0Xfunction
  [6XReturns:[0X  an integer
  
  This  function  returns  the  real  file  descriptor that is behind the [10XFile[0X
  object [3Xf[0X.
  
  [1X4.3-2 IO_GetWBuf[0X
  
  [2X> IO_GetWBuf( [0X[3Xf[0X[2X ) __________________________________________________[0Xfunction
  [6XReturns:[0X  a string or [9Xfalse[0X
  
  This  function  gets  one argument [3Xf[0X which must be a [10XFile[0X object and returns
  the  writing buffer of that [10XFile[0X object. This is necessary for [10XFile[0X 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 [10XFile[0X object.
  
  [1X4.3-3 IO_Select[0X
  
  [2X> IO_Select( [0X[3Xr, w, f, e, t1, t2[0X[2X ) __________________________________[0Xfunction
  [6XReturns:[0X  an integer or [9Xfail[0X
  
  This  function  is  the  corresponding  function  to  [2XIO_select[0X ([14X3.2-46[0X) for
  buffered file access. It behaves similarly to that function. The differences
  are  the  following:  There are four lists of files [3Xr[0X, [3Xw[0X, [3Xf[0X, and [3Xe[0X. They all
  can contain either integers (standing for file descriptors) or [10XFile[0X objects.
  The  list  [3Xr[0X is for checking, whether files or file descriptors are ready to
  read, the list [3Xw[0X is for checking whether they are ready to write, the list [3Xf[0X
  is  for  checking  whether  they  are  ready to flush, and the list [3Xe[0X is for
  checking whether they have exceptions.
  
  For  [10XFile[0X  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 [10XFile[0X
  objects to test for flushability necessary). For the remaining files and for
  all specified file descriptors, the function [2XIO_select[0X ([14X3.2-46[0X) is called to
  get  an  overview  about  readiness. The timeout values [3Xt1[0X and [3Xt2[0X are set to
  zero for immediate returning if one of the requested buffers were ready.
  
  [2XIO_Select[0X  returns the number of files or file descriptors that are ready to
  serve or [9Xfail[0X if an error occurs.
  
  The following function is a convenience function for directory access:
  
  [1X4.3-4 IO_ListDir[0X
  
  [2X> IO_ListDir( [0X[3Xpathname[0X[2X ) ___________________________________________[0Xfunction
  [6XReturns:[0X  a list of strings or [9Xfail[0X
  
  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 [9Xfail[0X, 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 [10Xconnect[0X, [10Xbind[0X, [10Xrecvfrom[0X, and [10Xsendto[0X
  for the arguments needing such address pairs.
  
  [1X4.3-5 IO_MakeIPAddressPort[0X
  
  [2X> IO_MakeIPAddressPort( [0X[3Xipstring, portnr[0X[2X ) _________________________[0Xfunction
  [6XReturns:[0X  a string
  
  This  function  gets  a  string  [3Xipstring[0X  containing  an  IP address in dot
  notation,  i.e.  four  numbers  in the range from 0 to 255 separated by dots
  ".",  and  an integer [3Xportnr[0X, 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.
  
  [1X4.3-6 IO_Environment[0X
  
  [2X> IO_Environment( [0X[3X[0X[2X ) _______________________________________________[0Xfunction
  [6XReturns:[0X  a record or [9Xfail[0X
  
  Takes  no  arguments,  uses  [2XIO_environ[0X  ([14X3.3-2[0X)  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 [2XIO_MakeEnvList[0X ([14X4.3-7[0X) to
  produce  again  a  list  which  can  be used for [2XIO_execve[0X ([14X3.2-13[0X) as third
  argument.
  
  [1X4.3-7 IO_MakeEnvList[0X
  
  [2X> IO_MakeEnvList( [0X[3Xr[0X[2X ) ______________________________________________[0Xfunction
  [6XReturns:[0X  a list of strings
  
  Takes  a  record  as  returned by [2XIO_Environment[0X ([14X4.3-6[0X) and turns it into a
  list of strings as needed by [2XIO_execve[0X ([14X3.2-13[0X) as third argument.
  
  
  [1X4.4 Inter process communication[0X
  
  [1X4.4-1 IO_FindExecutable[0X
  
  [2X> IO_FindExecutable( [0X[3Xpath[0X[2X ) ________________________________________[0Xfunction
  [6XReturns:[0X  [9Xfail[0X or the path to an executable
  
  If  the path name [3Xpath[0X contains a slash, this function simply checks whether
  the string [3Xpath[0X refers to an executable file. If so, [3Xpath[0X is returned as is.
  Otherwise, [9Xfail[0X is returned. If the path name [3Xpath[0X does not contain a slash,
  all  directories  in  the  environment  variable  [11XPATH[0X  are  searched for an
  executable  with  name  [3Xpath[0X.  If  so,  the  full path to that executable is
  returned, otherwise [9Xfail[0X.
  
  This  function  is  used  whenever  one  of  the following functions gets an
  argument that should refer to an executable.
  
  [1X4.4-2 IO_CloseAllFDs[0X
  
  [2X> IO_CloseAllFDs( [0X[3Xexceptions[0X[2X ) _____________________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  Closes all file descriptors except those listed in [3Xexceptions[0X, which must be
  a list of integers.
  
  [1X4.4-3 IO_Popen[0X
  
  [2X> IO_Popen( [0X[3Xpath, argv, mode[0X[2X ) _____________________________________[0Xfunction
  [6XReturns:[0X  a [10XFile[0X object or [9Xfail[0X
  
  The  argument  [3Xpath[0X  must  refer  to  an  executable  file  in  the sense of
  [2XIO_FindExecutable[0X ([14X4.4-1[0X).
  
  Starts  a  child  process using the executable in [3Xpath[0X with either stdout or
  stdin  being  a pipe. The argument [3Xmode[0X must be either the string "[10Xr[0X" or the
  string "[10Xw[0X".
  
  In  the  first  case,  the  standard output of the child process will be the
  writing  end  of  a pipe. A [10XFile[0X 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 [5XGAP[0X process.
  
  In  the  second  case,  the  standard input of the child process will be the
  reading  end  of  a pipe. A [10XFile[0X 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 [5XGAP[0X process.
  
  In case of an error, [9Xfail[0X is returned.
  
  The  process  will  usually die, when the pipe is closed, but can also do so
  without  that.  The  [10XFile[0X  object  remembers  the  process ID of the started
  process  and  the  [2XIO_Close[0X ([14X4.2-16[0X) function then calls [2XIO_WaitPid[0X ([14X3.2-55[0X)
  for it to acquire information about the terminated process.
  
  Note     that     [2XIO_Popen[0X    activates    our    SIGCHLD    handler    (see
  [2XIO_InstallSIGCHLDHandler[0X ([14X3.3-3[0X)).
  
  In  either  case  the [10XFile[0X object will have the attribute "[9XProcessID[0X" set to
  the process ID of the child process.
  
  [1X4.4-4 IO_Popen2[0X
  
  [2X> IO_Popen2( [0X[3Xpath, argv[0X[2X ) __________________________________________[0Xfunction
  [6XReturns:[0X  a record or [9Xfail[0X
  
  The  argument  [3Xpath[0X  must  refer  to  an  executable  file  in  the sense of
  [2XIO_FindExecutable[0X ([14X4.4-1[0X).
  
  A  new  child  process  is started using the executable in [3Xpath[0X 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 [10XFile[0X objects bound to
  two  components  "[10Xstdin[0X"  and  "[10Xstdout[0X" (resp.) of the returned record. This
  means,  you  have  to [13Xwrite[0X to "[10Xstdin[0X" and [13Xread[0X from "[10Xstdout[0X" in the calling
  [5XGAP[0X process. The standard error of the child process will be the same as the
  one of the calling [5XGAP[0X process.
  
  Returns [9Xfail[0X if an error occurred.
  
  The  process  will  usually  die,  when one of the pipes is closed. The [10XFile[0X
  objects  remember the process ID of the called process and the function call
  to [2XIO_Close[0X ([14X4.2-16[0X) for the [10Xstdout[0X object will call [2XIO_WaitPid[0X ([14X3.2-55[0X) for
  it to acquire information about the terminated process.
  
  Note     that    [2XIO_Popen2[0X    activates    our    SIGCHLD    handler    (see
  [2XIO_InstallSIGCHLDHandler[0X ([14X3.3-3[0X)).
  
  Both  [10XFile[0X objects will have the attribute "[9XProcessID[0X" set to the process ID
  of the child process, which will also be bound to the "[9Xpid[0X" component of the
  returned record.
  
  [1X4.4-5 IO_Popen3[0X
  
  [2X> IO_Popen3( [0X[3Xpath, argv[0X[2X ) __________________________________________[0Xfunction
  [6XReturns:[0X  a record or [9Xfail[0X
  
  The  argument  [3Xpath[0X  must  refer  to  an  executable  file  in  the sense of
  [2XIO_FindExecutable[0X ([14X4.4-1[0X).
  
  A  new  child  process  is started using the executable in [3Xpath[0X 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 [10XFile[0X objects bound to two components "[10Xstdin[0X",
  "[10Xstdout[0X",  and "[10Xstderr[0X" (resp.) of the returned record. This means, you have
  to  [13Xwrite[0X  to "[10Xstdin[0X" and [13Xread[0X from "[10Xstdout[0X" and "[10Xstderr[0X" in the calling [5XGAP[0X
  process.
  
  Returns [9Xfail[0X if an error occurred.
  
  The  process  will  usually  die, when one of the pipes is closed. All three
  [10XFile[0X  objects  will remember the process ID of the newly created process and
  the  call  to the [2XIO_Close[0X ([14X4.2-16[0X) function for the [10Xstdout[0X object will call
  [2XIO_WaitPid[0X ([14X3.2-55[0X) for it to acquire information about the terminated child
  process.
  
  Note     that    [2XIO_Popen3[0X    activates    our    SIGCHLD    handler    (see
  [2XIO_InstallSIGCHLDHandler[0X ([14X3.3-3[0X)).
  
  All  three  [10XFile[0X  objects  will  have  the  attribute "[9XProcessID[0X" set to the
  process  ID  of  the  child  process,  which will also be bound to the "[9Xpid[0X"
  component of the returned record.
  
  [1X4.4-6 IO_StartPipeline[0X
  
  [2X> IO_StartPipeline( [0X[3Xprogs, infd, outfd, switcherror[0X[2X ) ______________[0Xfunction
  [6XReturns:[0X  a record or [9Xfail[0X
  
  The  argument  [3Xprogs[0X  is a list of pairs, the first entry being a path to an
  executable  (in  the  sense  of  [2XIO_FindExecutable[0X  ([14X4.4-1[0X)),  the second an
  argument  list,  the  argument  [3Xinfd[0X is an open file descriptor for reading,
  [3Xoutfd[0X  is  an  open file descriptor for writing, both can be replaced by the
  string  "[9Xopen[0X"  in  which  case  a  new  pipe  will  be opened. The argument
  [3Xswitcherror[0X is a boolean indicating whether standard error channels are also
  switched to the corresponding output channels.
  
  This  function  starts  up  all  processes and connects them with pipes. The
  input of the first is switched to [3Xinfd[0X and the output of the last to [3Xoutfd[0X.
  
  Returns  a  record  with the following components: [9Xpids[0X is a list of process
  ids if everything worked. For each process for which some error occurred the
  corresponding  pid  is  replaced  by  [9Xfail[0X.  The [9Xstdin[0X component is equal to
  [9Xfalse[0X,  or  to  the  file descriptor of the writing end of the newly created
  pipe  which  is  connected  to  the  standard  input of the first of the new
  processes  if  [3Xinfd[0X was "[9Xopen[0X". The [9Xstdout[0X component is equal to [9Xfalse[0X or to
  the  file  descriptor  of the reading end of the newly created pipe which is
  connected  to  the standard output of the last of the new processes if [3Xoutfd[0X
  was "[9Xopen[0X".
  
  Note  that  the  SIGCHLD  handler  of  the  [5XIO[0X  package is installed by this
  function  (see  [2XIO_InstallSIGCHLDHandler[0X  ([14X3.3-3[0X))  and  that it lies in the
  responsibility  of  the  caller  to  use  [2XIO_WaitPid[0X ([14X3.2-55[0X) to ask for the
  status information of all child processes after their termination.
  
  [1X4.4-7 IO_StringFilterFile[0X
  
  [2X> IO_StringFilterFile( [0X[3Xprogs, filename[0X[2X ) ___________________________[0Xfunction
  [6XReturns:[0X  a string or [9Xfail[0X
  
  Reads the file with the name [3Xfilename[0X, however, a pipeline is created by the
  processes  described  by  [3Xprogs[0X (see [2XIO_StartPipeline[0X ([14X4.4-6[0X)) to filter the
  content  of  the  file  through  the  pipeline. The result is put into a [5XGAP[0X
  string and returned. If something goes wrong, [9Xfail[0X is returned.
  
  [1X4.4-8 IO_StringFilterFile[0X
  
  [2X> IO_StringFilterFile( [0X[3Xfilename, progs, st[, append][0X[2X ) _____________[0Xfunction
  [6XReturns:[0X  a string or [9Xfail[0X
  
  Writes  the  content  of  the  string [3Xst[0X to the file with the name [3Xfilename[0X,
  however,  a  pipeline  is  created  by the processes described by [3Xprogs[0X (see
  [2XIO_StartPipeline[0X  ([14X4.4-6[0X))  to  filter the content of the string through the
  pipeline.  The  result  is put into the file. If the boolean value [3Xappend[0X is
  given  and  equal  to  [9Xtrue[0X,  then  the data will be appended to the already
  existing file. If something goes wrong, [9Xfail[0X is returned.
  
  [1X4.4-9 IO_FilteredFile[0X
  
  [2X> IO_FilteredFile( [0X[3Xprogs, filename[, mode][, bufsize][0X[2X ) ____________[0Xfunction
  [6XReturns:[0X  a [10XFile[0X object or [9Xfail[0X
  
  This  function is similar to [2XIO_File[0X ([14X4.1-3[0X) and behaves nearly identically.
  The  only  difference  is  that a filtering pipeline is switched between the
  file  and  the [10XFile[0X object such that all things read or written respectively
  are filtered through this pipeline of processes.
  
  The  [10XFile[0X  object remembers the started processes and upon the final call to
  [2XIO_Close[0X  ([14X4.2-16[0X)  automatically  uses  the [2XIO_WaitPid[0X ([14X3.2-55[0X) function to
  acquire  information  from  the  terminated  processes in the pipeline after
  their  termination.  This  means  that  you  do  not have to call [2XIO_WaitPid[0X
  ([14X3.2-55[0X) any more after the call to [2XIO_Close[0X ([14X4.2-16[0X).
  
  Note    that    [2XIO_FilteredFile[0X   activates   our   SIGCHLD   handler   (see
  [2XIO_InstallSIGCHLDHandler[0X ([14X3.3-3[0X)).
  
  The  [10XFile[0X  object  will  have  the  attribute "[9XProcessID[0X" set to the list of
  process IDs of the child processes.
  
  [1X4.4-10 IO_SendStringBackground[0X
  
  [2X> IO_SendStringBackground( [0X[3Xf, st[0X[2X ) _________________________________[0Xfunction
  
  This  functions  uses  [2XIO_Write[0X  ([14X4.2-7[0X) to write the whole string [3Xst[0X to the
  [10XFile[0X  object  [3Xf[0X.  However,  this  is  done  by  forking  off a child process
  identical  to the calling [5XGAP[0X process that does the sending. The calling [5XGAP[0X
  process  returns  immediately,  even before anything has been sent away with
  the result [9Xtrue[0X. 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
  [2XIO_Popen2[0X  ([14X4.4-4[0X)  or  [2XIO_Popen3[0X  ([14X4.4-5[0X)  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 [5XGAP[0X 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
  [5XGAP[0X  process  directly  after  [2XIO_SendStringBackground[0X has returned, because
  otherwise  the  child  process  might  not notice that all data has arrived,
  because  the  pipe  persists! See the file [11Xpopen2.g[0X in the [11Xexample[0X directory
  for an example.
  
  Note that with most modern operating systems the forking off of an identical
  child  process  does in fact [13Xnot[0X 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.
  
  [1X4.4-11 IO_PipeThrough[0X
  
  [2X> IO_PipeThrough( [0X[3Xcmd, args, input[0X[2X ) _______________________________[0Xfunction
  [6XReturns:[0X  a string or [9Xfail[0X
  
  Starts  the  process  with the executable given by the file name [3Xcmd[0X (in the
  sense of [2XIO_FindExecutable[0X ([14X4.4-1[0X)) with arguments in the argument list [3Xargs[0X
  (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
  [3Xinput[0X  is  written  to  the  standard  input  of  the called process and its
  standard output is read and returned as a string.
  
  All  the  necessary I/O multiplexing and non-blocking I/O to avoid deadlocks
  is done in this function.
  
  This  function properly does [2XIO_WaitPid[0X ([14X3.2-55[0X) to wait for the termination
  of  the  child  process but does not restore the original [5XGAP[0X SIGCHLD signal
  handler (see [2XIO_InstallSIGCHLDHandler[0X ([14X3.3-3[0X)).
  
  [1X4.4-12 IO_PipeThroughWithError[0X
  
  [2X> IO_PipeThroughWithError( [0X[3Xcmd, args, input[0X[2X ) ______________________[0Xfunction
  [6XReturns:[0X  a record or [9Xfail[0X
  
  Starts  the  process  with the executable given by the file name [3Xcmd[0X (in the
  sense of [2XIO_FindExecutable[0X ([14X4.4-1[0X)) with arguments in the argument list [3Xargs[0X
  (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  [3Xinput[0X 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
  [9Xout[0X and [9Xerr[0X, which are strings.
  
  All  the  necessary I/O multiplexing and non-blocking I/O to avoid deadlocks
  is done in this function.
  
  This  function properly does [2XIO_WaitPid[0X ([14X3.2-55[0X) to wait for the termination
  of  the  child  process but does not restore the original [5XGAP[0X SIGCHLD signal
  handler (see [2XIO_InstallSIGCHLDHandler[0X ([14X3.3-3[0X)).
  
  The  functions  returns  either  [9Xfail[0X  if  an error occurred, or otherwise a
  record with components [9Xout[0X and [9Xerr[0X which are bound to strings containing the
  full standard output and standard error of the called process.
  
