chap11.txt

  
  11 Processes
  
  GAP  can  call other programs, such programs are called processes. There are
  two  kinds of processes: first there are processes that are started, run and
  return  a  result, while GAP is suspended until the process terminates. Then
  there are processes that will run in parallel to GAP as subprocesses and GAP
  can    communicate    and    control    the    processes    using    streams
  (see InputOutputLocalProcess (10.8-2)).
  
  
  11.1 Process and Exec
  
  11.1-1 Process
  
  Process( dir, prg, stream-in, stream-out, options )  operation
  
  Process  runs  a  new  process  and  returns when the process terminates. It
  returns  the  return  value  of the process if the operating system supports
  such a concept.
  
  The  first  argument  dir  is a directory object (see 9.3) which will be the
  current  directory  (in  the  usual UNIX or MSDOS sense) when the program is
  run.  This will only matter if the program accesses files (including running
  other programs) via relative path names. In particular, it has nothing to do
  with finding the binary to run.
  
  In  general  the  directory  will  either be the current directory, which is
  returned  by DirectoryCurrent (9.3-4) –this was the behaviour of GAP 3– or a
  temporary  directory  returned by DirectoryTemporary (9.3-3). If one expects
  that  the  process  creates temporary or log files the latter should be used
  because  GAP  will attempt to remove these directories together with all the
  files in them when quitting.
  
  If  a program of a GAP package which does not only consist of GAP code needs
  to  be  launched in a directory relative to certain data libraries, then the
  first  entry  of  DirectoriesPackageLibrary  (76.3-5)  should  be  used. The
  argument  of  DirectoriesPackageLibrary  (76.3-5)  should be the path to the
  data library relative to the package directory.
  
  If  a  program  calls other programs and needs to be launched in a directory
  containing  the  executables  for such a GAP package then the first entry of
  DirectoriesPackagePrograms (76.3-6) should be used.
  
  The  latter  two  alternatives  should  only be used if absolutely necessary
  because  otherwise  one  risks accumulating log or core files in the package
  directory.
  
    Example  
    gap> path := DirectoriesSystemPrograms();;
    gap> ls := Filename( path, "ls" );;
    gap> stdin := InputTextUser();;
    gap> stdout := OutputTextUser();;
    gap> Process( path[1], ls, stdin, stdout, ["-c"] );;
    awk    ls     mkdir
    gap> # current directory, here the root directory
    gap> Process( DirectoryCurrent(), ls, stdin, stdout, ["-c"] );;
    bin    lib    trans  tst    CVS    grp    prim   thr    two
    src    dev    etc    tbl    doc    pkg    small  tom
    gap> # create a temporary directory
    gap> tmpdir := DirectoryTemporary();;
    gap> Process( tmpdir, ls, stdin, stdout, ["-c"] );;
    gap> PrintTo( Filename( tmpdir, "emil" ) );
    gap> Process( tmpdir, ls, stdin, stdout, ["-c"] );;
    emil
  
  
  prg  is  the filename of the program to launch, for portability it should be
  the  result  of  Filename  (9.4-1) and should pass IsExecutableFile (9.6-4).
  Note  that  Process does no searching through a list of directories, this is
  done by Filename (9.4-1).
  
  stream-in  is  the input stream that delivers the characters to the process.
  For  portability  it should either be InputTextNone (10.9-1) (if the process
  reads  no  characters),  InputTextUser  (10.6-1),  the  result  of a call to
  InputTextFile  (10.5-1)  from  which  no  characters  have been read, or the
  result of a call to InputTextString (10.7-1).
  
  Process is free to consume all the input even if the program itself does not
  require any input at all.
  
  stream-out  is  the  output  stream  which  receives the characters from the
  process. For portability it should either be OutputTextNone (10.9-2) (if the
  process writes no characters), OutputTextUser (10.6-2), the result of a call
  to  OutputTextFile (10.5-2) to which no characters have been written, or the
  result of a call to OutputTextString (10.7-2).
  
  options is a list of strings which are passed to the process as command line
  argument.  Note  that  no  substitutions are performed on the strings, i.e.,
  they  are  passed  immediately  to  the  process  and are not processed by a
  command  interpreter (shell). Further note that each string is passed as one
  argument,  even  if  it  contains  space  characters. Note that input/output
  redirection commands are not allowed as options.
  
  In  order  to  find  a  system program use DirectoriesSystemPrograms (9.3-6)
  together with Filename (9.4-1).
  
    Example  
    gap> path := DirectoriesSystemPrograms();;
    gap> date := Filename( path, "date" );
    "/bin/date"
  
  
  The  next  example  shows how to execute date with no argument and no input,
  and collect the output into a string stream.
  
    Example  
    gap> str := "";; a := OutputTextString(str,true);;
    gap> Process( DirectoryCurrent(), date, InputTextNone(), a, [] );
    0
    gap> CloseStream(a);
    gap> Print(str);
    Fri Jul 11 09:04:23 MET DST 1997
  
  
  11.1-2 Exec
  
  Exec( cmd, option1, ..., optionN )  function
  
  Exec  runs  a shell in the current directory to execute the command given by
  the string cmd with options option1, ..., optionN.
  
    Example  
    gap> Exec( "date" );
    Thu Jul 24 10:04:13 BST 1997
  
  
  cmd is interpreted by the shell and therefore we can make use of the various
  features that a shell offers as in following example.
  
    Example  
    gap> Exec( "echo \"GAP is great!\" > foo" );
    gap> Exec( "cat foo" );
    GAP is great!
    gap> Exec( "rm foo" );
  
  
  Exec  calls  the  more general operation Process (11.1-1). The function Edit
  (6.10-1) should be used to call an editor from within GAP.