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
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
% This file was created automatically from process.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W process.msk GAP documentation Frank Celler
%W & Martin Schoenert
%%
%H @(#)$Id: process.msk,v 1.3 2001/09/21 12:29:29 gap Exp $
%%
%Y Copyright 1997, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany
%%
%% This file contains the description of processes.
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{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").
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Process}\nolabel
\>Process( <dir>, <prg>, <stream-in>, <stream-out>, <options> ) O
`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~"Directories")
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' (see~"DirectoryCurrent")
--this was the behaviour of {\GAP}~3--
or a temporary directory returned by `DirectoryTemporary'
(see~"DirectoryTemporary").
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' should be
used.
The argument of `DirectoriesPackageLibrary' 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' 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.
*Examples*
%notest
\beginexample
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
\endexample
%notest
\beginexample
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
\endexample
%notest
\beginexample
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
\endexample
<prg> is the filename of the program to launch, for portability it should
be the result of `Filename' (see~"Filename") and should pass
`IsExecutableFile'.
Note that `Process' does *no* searching through a list of directories,
this is done by `Filename'.
<stream-in> is the input stream that delivers the characters to the
process.
For portability it should either be `InputTextNone' (if the process reads
no characters), `InputTextUser', the result of a call to `InputTextFile'
from which no characters have been read, or the result of a call to
`InputTextString'.
`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' (if the process
writes no characters), `OutputTextUser', the result of a call to
`OutputTextFile' to which no characters have been written, or the result
of a call to `OutputTextString'.
<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>.
*Examples*
In order to find a system program use `DirectoriesSystemPrograms'
together with `Filename'.
\beginexample
gap> path := DirectoriesSystemPrograms();;
gap> date := Filename( path, "date" );
"/bin/date"
\endexample
Now execute `date' with no argument and no input, collect the output into
a string stream.
%notest
\beginexample
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
\endexample
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Exec}\nolabel
\>Exec( <cmd>, <option1>, ..., <optionN> ) F
`Exec' runs a shell in the current directory to execute the command given
by the string <cmd> with options `<option1>, ..., <optionN>'.
%notest
\beginexample
gap> Exec( "date" );
Thu Jul 24 10:04:13 BST 1997
\endexample
<cmd> is interpreted by the shell and therefore we can make use of the
various features that a shell offers as in following example.
%notest
\beginexample
gap> Exec( "echo \"GAP is great!\" > foo" );
gap> Exec( "cat foo" );
GAP is great!
gap> Exec( "rm foo" );
\endexample
`Exec' calls the more general operation `Process' (see~"Process").
`Edit' (see~"Edit") should be used to call an editor from within {\GAP}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E
|
