source: trunk/source/doc/src/external-process.xml @ 8981

Last change on this file since 8981 was 8981, checked in by mikel, 11 years ago

additions to ObjC and ffi docs; many mechanical edits; some standardization of XML elements and formatting

File size: 13.4 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3<!ENTITY rest "<varname>&amp;rest</varname>">
4<!ENTITY key "<varname>&amp;key</varname>">
5<!ENTITY optional "<varname>&amp;optional</varname>">
6<!ENTITY body "<varname>&amp;body</varname>">
7<!ENTITY aux "<varname>&amp;aux</varname>">
8<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
9<!ENTITY CCL "Clozure CL">
10]>
11
12  <chapter id="Running-Other-Programs-as-Subprocesses">
13    <title>Running Other Programs as Subprocesses</title>
14
15    <sect1 id="Subprocess-Overview">
16      <title>Overview</title>
17      <para>&CCL; provides primitives to run external Unix programs,
18      to select and connect Lisp streams to their input and output
19      sources, to (optionally) wait for their completion and to check
20      their execution and exit status.</para>
21      <para>All of the global symbols described below are exported
22      from the CCL package.</para>
23      <para>This implementation is modeled on - and uses some code
24      from - similar facilities in CMUCL.</para>
25    </sect1>
26
27    <sect1 id="Subprocess-Examples">
28      <title>Examples</title>
29      <programlisting>
30;;; Capture the output of the "uname" program in a lisp string-stream
31;;; and return the generated string (which will contain a trailing
32;;; newline.)
33? (with-output-to-string (stream)
34    (run-program "uname" '("-r") :output stream))
35;;; Write a string to *STANDARD-OUTPUT*, the hard way.
36? (run-program "cat" () :input (make-string-input-stream "hello") :output t)
37;;; Find out that "ls" doesn't expand wildcards.
38? (run-program "ls" '("*.lisp") :output t)
39;;; Let the shell expand wildcards.
40? (run-program "sh" '("-c" "ls *.lisp") :output t)
41</programlisting>
42      <para>These last examples will only produce output if &CCL;'s
43      current directory contains .lisp files, of course.</para>
44    </sect1>
45
46    <sect1 id="Limitations-and-known-bugs">
47      <title>Limitations and known bugs</title>
48      <itemizedlist>
49        <listitem><para>&CCL; and the external process may get
50        confused about who owns which streams when input, output, or
51        error are specified as T and wait is specified as
52        NIL.</para></listitem>
53        <listitem><para>External processes that need to talk to a
54        terminal device may not work properly; the environment (SLIME,
55        ILISP) under which &CCL; is run can affect
56        this.</para></listitem>
57     
58      </itemizedlist>
59    </sect1>
60
61    <sect1 id="External-Program-Dictionary">
62      <title>External-Program Dictionary</title>
63        <refentry id="f_run-program">
64          <indexterm zone="f_run-program">
65            <primary>run-program</primary>
66          </indexterm>
67
68          <refnamediv>
69            <refname>RUN-PROGRAM</refname>
70            <refpurpose>Invokes an external program as an OS subprocess
71            of lisp.</refpurpose>
72            <refclass>Function</refclass>
73          </refnamediv>
74
75          <refsynopsisdiv>
76            <synopsis><function>run-program</function>
77            program args &key; (wait t) pty input
78            if-input-does-not-exist output (if-output-exists :error) (error
79            :output) (if-error-exists :error) status-hook</synopsis>
80          </refsynopsisdiv>
81
82          <refsect1>
83            <title>Arguments and Values</title>
84
85            <variablelist>
86              <varlistentry>
87                <term>program</term>
88
89                <listitem>
90                  <para>A string or pathname which denotes an executable file.
91                  The PATH environment variable is used to find programs whose
92                  name doesn't contain a directory component.</para>
93                </listitem>
94              </varlistentry>
95
96              <varlistentry>
97                <term>args</term>
98
99                <listitem>
100                  <para>A list of simple-strings</para>
101                </listitem>
102              </varlistentry>
103
104              <varlistentry>
105                <term>wait</term>
106
107                <listitem>
108                  <para>Indicates whether or not run-program should wait for
109                  the EXTERNAL-PROCESS to complete or should return
110                  immediately.</para>
111                </listitem>
112              </varlistentry>
113
114              <varlistentry>
115                <term>pty</term>
116
117                <listitem>
118                  <para>This option is accepted but currently ignored;
119                  it's intended to make it easier to run external programs
120                  that need to interact with a terminal device.</para>
121                </listitem>
122              </varlistentry>
123
124              <varlistentry>
125                <term>input</term>
126
127                <listitem>
128                  <para>Selects the input source used by the EXTERNAL-PROCESS.
129                  May be any of the following:</para>
130
131                  <itemizedlist>
132                    <listitem>
133                      <para>NIL Specifies that a null input stream (e.g.,
134                      /dev/null) should be used.</para>
135                    </listitem>
136
137                    <listitem>
138                      <para>T Specifies that the EXTERNAL-PROCESS should use
139                      the input source with which &CCL; was invoked.</para>
140                    </listitem>
141
142                    <listitem>
143                      <para>A string or pathname. Specifies that the
144                      EXTERNAL-PROCESS should receive its input from the named
145                      existing file.</para>
146                    </listitem>
147
148                    <listitem>
149                      <para>:STREAM Creates a Lisp stream opened for character
150                      output. Any data written to this stream (accessible as
151                      the EXTERNAL-PROCESS-INPUT-STREAM of the
152                      EXTERNAL-PROCESS object) appears as input to the
153                      external process.</para>
154                    </listitem>
155
156                    <listitem>
157                      <para>A stream. Specifies that the lisp stream should
158                      provide input to the EXTERNAL-PROCESS.</para>
159                    </listitem>
160                  </itemizedlist>
161                </listitem>
162              </varlistentry>
163
164              <varlistentry>
165                <term>if-input-does-not-exist</term>
166
167                <listitem>
168                  <para>If the input argument specifies the name of an
169                  existing file, this argument is used as the
170                  if-does-not-exist argument to OPEN when that file is opened.</para>
171                </listitem>
172              </varlistentry>
173
174              <varlistentry>
175                <term>output</term>
176
177                <listitem>
178                  <para>Specifies where standard output from the external
179                  process should be sent. Analogous to input above.</para>
180                </listitem>
181              </varlistentry>
182
183              <varlistentry>
184                <term>if-output-exists</term>
185
186                <listitem>
187                  <para>If output is specified as a string or pathname, this
188                  argument is used as the if-exists argument to OPEN when that
189                  file is opened.</para>
190                </listitem>
191              </varlistentry>
192
193              <varlistentry>
194                <term>error</term>
195
196                <listitem>
197                  <para>Specifies where error output from the external process
198                  should be sent. In addition to the values allowed for
199                  output, the keyword :OUTPUT can be used to indicate that
200                  error output should be sent where standard output goes.</para>
201                </listitem>
202              </varlistentry>
203
204              <varlistentry>
205                <term>if-error-exists</term>
206
207                <listitem>
208                  <para>Analogous to if-output-exists.</para>
209                </listitem>
210              </varlistentry>
211
212              <varlistentry>
213                <term>status-hook</term>
214
215                <listitem>
216                  <para>A user-defined function of one argument (the
217                  EXTERNAL-PROCESS structure.) This function is called
218                  whenever &CCL; detects a change in the status of the
219                  EXTERNAL-PROCESS.</para>
220                </listitem>
221              </varlistentry>
222            </variablelist>
223          </refsect1>
224
225          <refsect1>
226            <title>Description</title>
227
228            <para>Runs the specified program in an external (Unix) process,
229            returning an object of type EXTERNAL-PROCESS if successful.</para>
230          </refsect1>
231        </refentry>
232
233        <refentry id="f_signal-external-process">
234          <indexterm zone="f_signal-external-process">
235            <primary>signal-external-process</primary>
236          </indexterm>
237
238          <refnamediv>
239            <refname>SIGNAL-EXTERNAL-PROCESS</refname>
240            <refpurpose></refpurpose>
241            <refclass>Function</refclass>
242          </refnamediv>
243
244          <refsynopsisdiv>
245            <synopsis><function>signal-external-process</function>
246            proc signal-number</synopsis>
247          </refsynopsisdiv>
248
249          <refsect1>
250            <title>Arguments and Values</title>
251
252            <variablelist>
253              <varlistentry>
254                <term>proc</term>
255
256                <listitem>
257                  <para>An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.</para>
258                </listitem>
259              </varlistentry>
260
261              <varlistentry>
262                <term>signal</term>
263
264                <listitem>
265                  <para>A small integer.</para>
266                </listitem>
267              </varlistentry>
268            </variablelist>
269          </refsect1>
270
271          <refsect1>
272            <title>Description</title>
273
274            <para>Sends the specified "signal" to the specified
275            external process. (Typically, it would only be useful to call
276            this function if the EXTERNAL-PROCESS was created with :WAIT
277            NIL. ) Returns T if successful; signals an error otherwise.</para>
278          </refsect1>
279        </refentry>
280
281        <refentry id="f_external-process-id">
282          <indexterm zone="f_external-process-id">
283            <primary>external-process-id</primary>
284          </indexterm>
285
286          <refnamediv>
287            <refname>EXTERNAL-PROCESS-ID</refname>
288            <refpurpose>Returns the "process ID" of an OS subprocess,
289            a positive integer which identifies it.</refpurpose>
290            <refclass>Function</refclass>
291          </refnamediv>
292
293          <refsynopsisdiv>
294            <synopsis><function>external-process-id</function>
295            proc</synopsis>
296          </refsynopsisdiv>
297
298          <refsect1>
299            <title>Arguments and Values</title>
300
301            <variablelist>
302              <varlistentry>
303                <term>proc</term>
304
305                <listitem>
306                  <para>An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.</para>
307                </listitem>
308              </varlistentry>
309            </variablelist>
310          </refsect1>
311
312          <refsect1>
313            <title>Description</title>
314
315            <para>Returns the <emphasis>process id</emphasis> assigned to
316            the external process by the operating system. This is typically
317            a positive, 16-bit number.</para>
318          </refsect1>
319        </refentry>
320
321        <refentry id="f_external-process-input-stream">
322          <indexterm zone="f_external-process-input-stream">
323            <primary>external-process-input-stream</primary>
324          </indexterm>
325
326          <refnamediv>
327            <refname>EXTERNAL-PROCESS-INPUT-STREAM</refname>
328            <refpurpose>Returns the lisp stream which is used to write
329            input to a given OS subprocess, if it has one.</refpurpose>
330            <refclass>Function</refclass>
331          </refnamediv>
332
333          <refsynopsisdiv>
334            <synopsis><function>external-process-input-stream</function>
335            proc</synopsis>
336          </refsynopsisdiv>
337
338          <refsect1>
339            <title>Arguments and Values</title>
340
341            <variablelist>
342              <varlistentry>
343                <term>proc</term>
344
345                <listitem>
346                  <para>An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.</para>
347                </listitem>
348              </varlistentry>
349            </variablelist>
350          </refsect1>
351
352          <refsect1>
353            <title>Description</title>
354
355            <para>Returns the stream created when the input argument to
356            run-program is specified as :STREAM.</para>
357          </refsect1>
358        </refentry>
359
360        <refentry id="f_external-process-output-stream">
361          <indexterm zone="f_external-process-output-stream">
362            <primary>external-process-output-stream</primary>
363          </indexterm>
364
365          <refnamediv>
366            <refname>EXTERNAL-PROCESS-OUTPUT-STREAM</refname>
367            <refpurpose>Returns the lisp stream which is used to read
368            output from an OS subprocess, if there is one.</refpurpose>
369            <refclass>Function</refclass>
370          </refnamediv>
371
372          <refsynopsisdiv>
373            <synopsis><function>external-process-output-stream</function>
374            proc</synopsis>
375          </refsynopsisdiv>
376
377          <refsect1>
378            <title>Arguments and Values</title>
379
380            <variablelist>
381              <varlistentry>
382                <term>proc</term>
383
384                <listitem>
385                  <para>An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.</para>
386                </listitem>
387              </varlistentry>
388            </variablelist>
389          </refsect1>
390
391          <refsect1>
392            <title>Description</title>
393
394            <para>Returns the stream created when the output argument to
395            run-program is specified as :STREAM.</para>
396          </refsect1>
397        </refentry>
398
399        <refentry id="f_external-process-error-stream">
400          <indexterm zone="f_external-process-error-stream">
401            <primary>external-process-error-stream</primary>
402          </indexterm>
403
404          <refnamediv>
405            <refname>EXTERNAL-PROCESS-ERROR-STREAM</refname>
406            <refpurpose>Returns the stream which is used to read
407            "error" output from a given OS subprocess, if it has
408            one.</refpurpose>
409            <refclass>Function</refclass>
410          </refnamediv>
411
412          <refsynopsisdiv>
413            <synopsis><function>external-process-error-stream</function>
414            proc</synopsis>
415          </refsynopsisdiv>
416
417          <refsect1>
418            <title>Arguments and Values</title>
419
420            <variablelist>
421              <varlistentry>
422                <term>proc</term>
423
424                <listitem>
425                  <para>An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.</para>
426                </listitem>
427              </varlistentry>
428            </variablelist>
429          </refsect1>
430
431          <refsect1>
432            <title>Description</title>
433
434            <para>Returns the stream created when the error argument to
435            run-program is specified as :STREAM.</para>
436          </refsect1>
437        </refentry>
438
439        <refentry id="f_external-process-status">
440          <indexterm zone="f_external-process-status">
441            <primary>external-process-status</primary>
442          </indexterm>
443
444          <refnamediv>
445            <refname>EXTERNAL-PROCESS-STATUS</refname>
446            <refpurpose>Returns information about whether an OS
447            subprocess is running; or, if not, why not; and what its
448            result code was if it completed.</refpurpose>
449            <refclass>Function</refclass>
450          </refnamediv>
451
452          <refsynopsisdiv>
453            <synopsis><function>external-process-status</function>
454            proc</synopsis>
455          </refsynopsisdiv>
456
457          <refsect1>
458            <title>Arguments and Values</title>
459
460            <variablelist>
461              <varlistentry>
462                <term>proc</term>
463
464                <listitem>
465                  <para>An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.</para>
466                </listitem>
467              </varlistentry>
468            </variablelist>
469          </refsect1>
470
471          <refsect1>
472            <title>Description</title>
473
474            <para>Returns, as multiple values, a keyword denoting the status
475            of the external process (one of :running, :stopped, :signaled, or
476            :exited), and the exit code or terminating signal if the first
477            value is other than :running.</para>
478          </refsect1>
479        </refentry>
480    </sect1>
481  </chapter>
Note: See TracBrowser for help on using the repository browser.