GAP (ref) - Chapter 11: Processes

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

11 Processes
11.1 Process and Exec
11.1-1 Process
11.1-2 Exec

### 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.

    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).

    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.

    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.

    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.

    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.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind

generated by GAPDoc2HTML