marcuskammer/cl-sites
1
0
Fork 0
Code Activity
cl-sites/ecl.common-lisp.dev/static/manual/Operating-System-Interface.html

579 lines
37 KiB
HTML
Raw Permalink Normal View History

Add ecl manual
2024-12-24 19:15:49 +01:00
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Operating System Interface (ECL Manual)</title>
<meta name="description" content="Operating System Interface (ECL Manual)">
<meta name="keywords" content="Operating System Interface (ECL Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Indexes.html" rel="index" title="Indexes">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Extensions.html" rel="up" title="Extensions">
<link href="Foreign-Function-Interface.html#Foreign-Function-Interface" rel="next" title="Foreign Function Interface">
<link href="System-building.html#System-building" rel="prev" title="System building">
<style type="text/css">
<!--
/* colors */
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
@media (prefers-color-scheme: dark) {
/* dark theme */
html { color: seashell;
background: #1A1A1A; }
body { background: #1A1A1A; }
th { border-bottom: 2px solid lightgray; }
h1, h2, h3, h4, h5 { background-image: linear-gradient(to left, #202020, #3A3A3A); }
code, var, code a { color: darkorange;
background: #2A2A2A; }
a { color: seashell; }
pre { background: #2A2A2A;
color: seashell;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkorange;
padding-left: 10px; }
pre.screen { background: #2A2A2A;
border: 1px solid lightgray; }
pre.programlisting { background: #2A2A2A;
border-left: 1px solid lightgray;
border-top: 1px solid lightgray; }
/* we need a light background in order for the images to be readable */
img { background: white }
}
@media (prefers-color-scheme: light) {
/* light theme */
html { background: white }
body { background: white }
th { border-bottom: 2px solid gray; }
h1, h2, h3, h4, h5 { background: lightgray; }
code, var, code a { color: darkred;
background: whitesmoke; }
a { color: #000; }
pre { background: whitesmoke;
color: black;
/* mark longer code block with stripe on the left */
border-left: 5px solid darkred;
padding-left: 10px; }
pre.screen { background: #EEE;
border: 1px solid black; }
pre.programlisting { background: #EEEEEE;
border-left: 1px solid black;
border-top: 1px solid black; }
}
body {
margin: 1em 125px 0 10%;
line-height: 1.5em;
padding: 0 2em 1em 2em;
font: 13px Verdana,Arial, sans-serif
}
ul, dd, dl, dt { margin-top: 0; margin-bottom: 0; }
p, code, td, dl, dt {
line-height: 1.5em;
}
table {
font: inherit;
border-collapse: collapse;
}
th, td {
vertical-align: top;
}
h1, h2, h3 { padding-left: 15px; }
h4, h5 { padding-left: 5px; }
code, pre {
font-size: 1em;
font-family: monospace;
}
var {
font-size: 1em;
}
/* links inside code appear the same as the code itself */
code a {
font-weight: normal;
text-decoration: none;
}
/* but get an underline when hovering */
code a:hover {
text-decoration: underline;
}
/* ordinary links appear in bold */
a { font-weight: bold; }
pre.verbatim {
margin: 0 0 0 0;
}
pre {
overflow: auto;
}
pre.screen {
font-weight: bold;
padding: 0.5em;
}
pre.programlisting {
padding: 0.5em;
}
div p { padding: 0 2em }
li p { padding: 0; margin: 0 }
hr { display: none; }
div.funcsynopsis p {
text-indent: -2em;
}
div.variablelist {
padding: 0 2em;
}
.type, .funcsynopsis, .symbol {
font-family: monospace;
}
.type, .symbol, .replaceable {
white-space: nowrap;
}
-->
</style>
</head>
<body lang="en">
<div class="section-level-extent" id="Operating-System-Interface">
<div class="nav-panel">
<p>
Next: <a href="Foreign-Function-Interface.html#Foreign-Function-Interface" accesskey="n" rel="next">Foreign Function Interface</a>, Previous: <a href="System-building.html#System-building" accesskey="p" rel="prev">System building</a>, Up: <a href="Extensions.html" accesskey="u" rel="up">Extensions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Operating-System-Interface-1">3.2 Operating System Interface</h3>
<a class="index-entry-id" id="index-Command-line-processing"></a>
<ul class="mini-toc">
<li><a href="Operating-System-Interface.html#Command-line-arguments" accesskey="1">Command line arguments</a></li>
<li><a href="Operating-System-Interface.html#External-processes" accesskey="2">External processes</a></li>
<li><a href="Operating-System-Interface.html#FIFO-files-_0028named-pipes_0029" accesskey="3">FIFO files (named pipes)</a></li>
<li><a href="Operating-System-Interface.html#Operating-System-Interface-Reference" accesskey="4">Operating System Interface Reference</a></li>
</ul>
<hr>
<div class="subsection-level-extent" id="Command-line-arguments">
<div class="nav-panel">
<p>
Next: <a href="Operating-System-Interface.html#External-processes" accesskey="n" rel="next">External processes</a>, Up: <a href="Operating-System-Interface.html#Operating-System-Interface" accesskey="u" rel="up">Operating System Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="Command-line-arguments-1">3.2.1 Command line arguments</h4>
<a class="anchor" id="ext_003a_002ahelp_002dmessage_002a"></a><a class="index-entry-id" id="index-ext_003a_002ahelp_002dmessage_002a"></a>
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-ext_003a_002ahelp_002dmessage_002a-1"><span class="category-def">Variable: </span><span><code class="def-type">string</code> <strong class="def-name">ext:*help-message*</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003a_002ahelp_002dmessage_002a-1'> &para;</a></span></dt>
<dd><p>Command line help message. Initial value is ECL help message. This
variable contains the help message which is output when ECL is invoked
with the <code class="code">--help</code>.
</p></dd></dl>
<a class="anchor" id="ext_003a_002alisp_002dinit_002dfile_002dlist_002a"></a><a class="index-entry-id" id="index-ext_003a_002alisp_002dinit_002dfile_002dlist_002a"></a>
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-ext_003a_002alisp_002dinit_002dfile_002dlist_002a-1"><span class="category-def">Variable: </span><span><code class="def-type">list-of-pathname-designators</code> <strong class="def-name">ext:*lisp-init-file-list*</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003a_002alisp_002dinit_002dfile_002dlist_002a-1'> &para;</a></span></dt>
<dd><p>ECL initialization files. Initial value is <code class="code">'(&quot;~/.ecl&quot;
&quot;~/.eclrc&quot;)</code>. This variable contains the names of initialization files
that are loaded by ECL or embedding programs. The loading of
initialization files happens automatically in ECL unless invoked with
the option <code class="code">--norc</code>. Whether initialization files are loaded or
not is controlled by the command line options rules, as described in
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aprocess_002dcommand_002dargs">ext:process-command-args</a></code>.
</p></dd></dl>
<a class="anchor" id="ext_003a_002bdefault_002dcommand_002darg_002drules_002b"></a><a class="index-entry-id" id="index-ext_003a_002bdefault_002dcommand_002darg_002drules_002b"></a>
<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-ext_003a_002bdefault_002dcommand_002darg_002drules_002b-1"><span class="category-def">Variable: </span><span><code class="def-type">list-of-lists</code> <strong class="def-name">ext:+default-command-arg-rules+</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003a_002bdefault_002dcommand_002darg_002drules_002b-1'> &para;</a></span></dt>
<dd><p>ECL command line options. This constant contains a list of rules for
parsing the command line arguments. This list is made of all the
options which ECL accepts by default. It can be passed as first
argument to <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aprocess_002dcommand_002dargs">ext:process-command-args</a></code>, and you can use it as a
starting point to extend ECL.
</p></dd></dl>
<a class="anchor" id="ext_003acommand_002dargs"></a><a class="index-entry-id" id="index-ext_003acommand_002dargs-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003acommand_002dargs"><span class="category-def">Function: </span><span><strong class="def-name">ext:command-args</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003acommand_002dargs'> &para;</a></span></dt>
<dd><p>Original list of command line arguments. This function returns the
list of command line arguments passed to either ECL or the program it
was embedded in. The output is a list of strings and it corresponds to
the argv vector in a C program. Typically, the first argument is the
name of the program as it was invoked. You should not count on the
filename to be resolved.
</p></dd></dl>
<a class="anchor" id="ext_003aprocess_002dcommand_002dargs"></a><a class="index-entry-id" id="index-ext_003aprocess_002dcommand_002dargs-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aprocess_002dcommand_002dargs"><span class="category-def">Function: </span><span><strong class="def-name">ext:process-command-args</strong> <var class="def-var-arguments">&amp;key args rules</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aprocess_002dcommand_002dargs'> &para;</a></span></dt>
<dd>
<dl class="table">
<dt><var class="var">args</var></dt>
<dd><p>A list of strings. Defaults to the output of <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003acommand_002dargs">ext:command-args</a></code>.
</p></dd>
<dt><var class="var">rules</var></dt>
<dd><p>A list of lists. Defaults to the value of
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003a_002bdefault_002dcommand_002darg_002drules_002b">ext:+default-command-arg-rules+</a></code>.
</p></dd>
</dl>
<p>This function processes the command line arguments passed to either
ECL or the program that embeds it. It uses the list of rules rules,
which has the following syntax:
</p>
<p><code class="code">(option-name nargs template [:stop | :noloadrc | :loadrc]*)</code>
</p>
<dl class="table">
<dt><code class="code">option-name</code></dt>
<dd><p>A string with the option prefix as typed by the user. For instance
<code class="code">--help</code>, <code class="code">-?</code>, <code class="code">--compile</code>, etc.
</p>
</dd>
<dt><code class="code">nargs</code></dt>
<dd><p>A non-negative integer denoting the number of arguments taken by this
option.
</p>
</dd>
<dt><code class="code">template</code></dt>
<dd><p>A lisp form, not evaluated, where numbers from 0 to nargs will be
replaced by the corresponding option argument.
</p>
</dd>
<dt><code class="code">:stop</code></dt>
<dd><p>If present, parsing of arguments stops after this option is found and
processed. The list of remaining arguments is passed to the
rule. ECL&rsquo;s top-level uses this option with the <code class="code">--</code> command line
option to set <code class="code">ext:*unprocessed-ecl-command-args*</code> to the list of
remaining arguments.
</p>
</dd>
<dt><code class="code">:noloadrc, :loadrc</code></dt>
<dd><p>Determine whether the lisp initialization files in
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003a_002alisp_002dinit_002dfile_002dlist_002a">ext:*lisp-init-file-list*</a></code> will be loaded before processing
all forms.
</p></dd>
</dl>
<p><code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aprocess_002dcommand_002dargs">ext:process-command-args</a></code> works as follows. First of all, it
parses all the command line arguments, except for the first one, which
is assumed to contain the program name. Each of these arguments is
matched against the rules, sequentially, until one of the patterns
succeeds.
</p>
<p>A special name <code class="code">*default*</code>, matches any unknown command line
option. If there is no <code class="code">*default*</code> rule and no match is found, an
error is signaled. For each rule that succeeds, the function
constructs a lisp statement using the template.
</p>
<p>After all arguments have been processed,
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aprocess_002dcommand_002dargs">ext:process-command-args</a></code>, and there were no occurrences of
<code class="code">:noloadrc</code>, the first existing file listed in
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003a_002alisp_002dinit_002dfile_002dlist_002a">ext:*lisp-init-file-list*</a></code> will be loaded. Finally, the list of
lisp statements will be evaluated.
</p></dd></dl>
<a class="index-entry-id" id="index-Parsing-arguments-in-standalone-executable"></a>
<a class="index-entry-id" id="index-LS-implementation"></a>
<p>The following piece of code implements the ls command using
lisp. Instructions for building this program are found under
<samp class="file">examples/cmdline/ls.lsp</samp>.
</p>
<div class="example lisp">
<pre class="verbatim">(setq ext:*help-message* &quot;
ls [--help | -?] filename*
Lists the file that match the given patterns.
&quot;)
(defun print-directory (pathnames)
(format t &quot;~{~A~%~}&quot;
(mapcar #'(lambda (x) (enough-namestring x (si::getcwd)))
(mapcan #'directory (or pathnames '(&quot;*.*&quot; &quot;*/&quot;))))))
(defconstant +ls-rules+
'((&quot;--help&quot; 0 (progn (princ ext:*help-message* *standard-output*) (ext:quit 0)))
(&quot;-?&quot; 0 (progn (princ ext:*help-message* *standard-output*) (ext:quit 0)))
(&quot;*DEFAULT*&quot; 1 (print-directory 1) :stop)))
(let ((ext:*lisp-init-file-list* NIL)) ; No initialization files
(handler-case (ext:process-command-args :rules +ls-rules+)
(error (c)
(princ ext:*help-message* *error-output*)
(ext:quit 1))))
(ext:quit 0)
</pre></div>
<a class="index-entry-id" id="index-External-processes"></a>
<hr>
</div>
<div class="subsection-level-extent" id="External-processes">
<div class="nav-panel">
<p>
Next: <a href="Operating-System-Interface.html#FIFO-files-_0028named-pipes_0029" accesskey="n" rel="next">FIFO files (named pipes)</a>, Previous: <a href="Operating-System-Interface.html#Command-line-arguments" accesskey="p" rel="prev">Command line arguments</a>, Up: <a href="Operating-System-Interface.html#Operating-System-Interface" accesskey="u" rel="up">Operating System Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="External-processes-1">3.2.2 External processes</h4>
<p>ECL provides several facilities for invoking and communicating with
external processes. If one just wishes to execute some program, without
caring for its output, then probably <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003asystem">ext:system</a></code> is the best
function. In all other cases it is preferable to use
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003arun_002dprogram">ext:run-program</a></code>, which opens pipes to communicate with the
program and manipulate it while it runs on the background.
</p>
<p>External process is a structure created with <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003arun_002dprogram">ext:run-program</a></code>
(returned as third value). It is programmer responsibility, to call
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aexternal_002dprocess_002dwait">ext:external-process-wait</a></code> on finished processes, however during
garbage collection object will be finalized.
</p>
<a class="anchor" id="ext_003aexternal_002dprocess_002dpid"></a><a class="index-entry-id" id="index-ext_003aexternal_002dprocess_002dpid-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aexternal_002dprocess_002dpid"><span class="category-def">Function: </span><span><strong class="def-name">ext:external-process-pid</strong> <var class="def-var-arguments">process</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aexternal_002dprocess_002dpid'> &para;</a></span></dt>
<dd><p>Returns process PID or <code class="code">nil</code> if already finished.
</p></dd></dl>
<a class="anchor" id="ext_003aexternal_002dprocess_002dstatus"></a><a class="index-entry-id" id="index-ext_003aexternal_002dprocess_002dstatus-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aexternal_002dprocess_002dstatus"><span class="category-def">Function: </span><span><strong class="def-name">ext:external-process-status</strong> <var class="def-var-arguments">process</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aexternal_002dprocess_002dstatus'> &para;</a></span></dt>
<dd><p>Updates process status. <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aexternal_002dprocess_002dstatus">ext:external-process-status</a></code> calls
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aexternal_002dprocess_002dwait">ext:external-process-wait</a></code> if process has not finished yet
(non-blocking call). Returns two values:
</p>
<p><code class="code">status</code> - member of <code class="code">(:abort :error :exited :signaled
:stopped :resumed :running)</code>
</p>
<p><code class="code">code</code> - if process exited it is a returned value, if terminated
it is a signal code. Otherwise NIL.
</p></dd></dl>
<a class="anchor" id="ext_003aexternal_002dprocess_002dwait"></a><a class="index-entry-id" id="index-ext_003aexternal_002dprocess_002dwait-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aexternal_002dprocess_002dwait"><span class="category-def">Function: </span><span><strong class="def-name">ext:external-process-wait</strong> <var class="def-var-arguments">process wait</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aexternal_002dprocess_002dwait'> &para;</a></span></dt>
<dd><p>If the second argument is non-NIL, function blocks until external
process is finished. Otherwise status is updated. Returns two values
(see <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aexternal_002dprocess_002dstatus">ext:external-process-status</a></code>).
</p></dd></dl>
<a class="anchor" id="ext_003aterminate_002dprocess"></a><a class="index-entry-id" id="index-ext_003aterminate_002dprocess-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aterminate_002dprocess"><span class="category-def">Function: </span><span><strong class="def-name">ext:terminate-process</strong> <var class="def-var-arguments">process &amp;optional force</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aterminate_002dprocess'> &para;</a></span></dt>
<dd><p>Terminates external process. May signal an error if the process has
already finished.
</p></dd></dl>
<a class="anchor" id="ext_003aexternal_002dprocess_002dinput"></a><a class="index-entry-id" id="index-ext_003aexternal_002dprocess_002dinput-1"></a>
<a class="anchor" id="ext_003aexternal_002dprocess_002doutput"></a><a class="index-entry-id" id="index-ext_003aexternal_002dprocess_002doutput-1"></a>
<a class="anchor" id="ext_003aexternal_002dprocess_002derror_002dstream"></a><a class="index-entry-id" id="index-ext_003aexternal_002dprocess_002derror_002dstream-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aexternal_002dprocess_002dinput"><span class="category-def">Function: </span><span><strong class="def-name">ext:external-process-input</strong> <var class="def-var-arguments">process</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aexternal_002dprocess_002dinput'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003aexternal_002dprocess_002doutput"><span class="category-def">Function: </span><span><strong class="def-name">ext:external-process-output</strong> <var class="def-var-arguments">process</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aexternal_002dprocess_002doutput'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003aexternal_002dprocess_002derror_002dstream"><span class="category-def">Function: </span><span><strong class="def-name">ext:external-process-error-stream</strong> <var class="def-var-arguments">process</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aexternal_002dprocess_002derror_002dstream'> &para;</a></span></dt>
<dd><p>Process stream accessors (read-only).
</p></dd></dl>
<a class="anchor" id="ext_003arun_002dprogram"></a><a class="index-entry-id" id="index-ext_003arun_002dprogram-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003arun_002dprogram"><span class="category-def">Function: </span><span><strong class="def-name">ext:run-program</strong> <var class="def-var-arguments">command argv &amp;key input output error wait environ if-input-does-not-exist if-output-exists if-error-exists external-format #+windows escape-arguments</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003arun_002dprogram'> &para;</a></span></dt>
<dd>
<p><code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003arun_002dprogram">ext:run-program</a></code> creates a new process specified by the
<var class="var">command</var> argument. <var class="var">argv</var> are the standard arguments that can
be passed to a program. For no arguments, use <code class="code">nil</code> (which means
that just the name of the program is passed as arg 0).
</p>
<p><code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003arun_002dprogram">ext:run-program</a></code> will return three values - two-way stream for
communication, return code or <code class="code">nil</code> (if process is called
asynchronously), and <code class="code">ext:external-process</code> object holding
process state.
</p>
<p>It is programmer responsibility to call
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aexternal_002dprocess_002dwait">ext:external-process-wait</a></code> on finished process, however ECL
associates <a class="ref" href="Memory-Management.html#Finalization">finalizer</a> with the object calling it
when the object is garbage collected. If process didn&rsquo;t finish but is
not referenced, finalizer will be invoked once more during next
garbage collection.
</p>
<p>The <code class="code">&amp;key</code> arguments have the following meanings:
</p>
<dl class="table">
<dt><var class="var">input</var></dt>
<dd><p>Either <code class="code">t</code>, <code class="code">nil</code>, a pathname, a string, a stream or
<code class="code">:stream</code>. If <code class="code">t</code> the standard input for the current process
is inherited. If <code class="code">nil</code>, <code class="code">/dev/null</code> is used. If a pathname (or
a string), the file so specified is used. If a stream, all the input is
read from that stream and sent to the subprocess. If <code class="code">:stream</code>, the
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aexternal_002dprocess_002dinput">ext:external-process-input</a></code> slot is filled in with a stream
that sends its output to the process. Defaults to <code class="code">:stream</code>.
</p>
</dd>
<dt><var class="var">if-input-does-not-exist</var></dt>
<dd><p>Can be one of: <code class="code">:error</code> to generate an error <code class="code">:create</code> to
create an empty file <code class="code">nil</code> (the default) to return nil from
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003arun_002dprogram">ext:run-program</a></code>
</p>
</dd>
<dt><var class="var">output</var></dt>
<dd><p>Either <code class="code">t</code>, <code class="code">nil</code>, a pathname, a string, a stream, or
<code class="code">:stream</code>. If <code class="code">t</code>, the standard output for the current process
is inherited. If <code class="code">nil</code>, <code class="code">/dev/null</code> is used. If a pathname (or
as string), the file so specified is used. If a stream, all the output
from the process is written to this stream. If <code class="code">:stream</code>, the
<code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003aexternal_002dprocess_002doutput">ext:external-process-output</a></code> slot is filled in with a stream
that can be read to get the output. Defaults to <code class="code">:stream</code>.
</p>
</dd>
<dt><var class="var">if-output-exists</var></dt>
<dd><p>Can be one of: <code class="code">:error</code> (the default) to generate an error,
<code class="code">:supersede</code> to supersede the file with output from the program,
<code class="code">:append</code> to append output from the program to the file or
<code class="code">nil</code> to return <code class="code">nil</code> from <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003arun_002dprogram">ext:run-program</a></code>.
</p>
</dd>
<dt><var class="var">error</var></dt>
<dd><p>Same as <code class="code">:output</code>, except that <code class="code">:error</code> can also be
specified as <code class="code">:output</code> in which case all error output is routed
to the same place as normal output. Defaults to <code class="code">:output</code>.
</p>
</dd>
<dt><var class="var">if-error-exists</var></dt>
<dd><p>Same as <code class="code">:if-output-exists</code>.
</p>
</dd>
<dt><var class="var">wait</var></dt>
<dd><p>If non-<code class="code">nil</code> (default), wait until the created process finishes. If
<code class="code">nil</code>, continue running Lisp until the program finishes.
</p>
</dd>
<dt><var class="var">environ</var></dt>
<dd><p>A list of STRINGs describing the new Unix environment (as in &quot;man
environ&quot;). The default is to copy the environment of the current
process. To extend existing environment (instead of replacing it),
use <code class="code">:environ (append *my-env* (ext:environ))</code>.
</p>
<p>If non-<code class="code">nil</code> <code class="code">environ</code> argument is supplied, then first
argument to <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003arun_002dprogram">ext:run-program</a></code>, <var class="var">command</var>, must be full path
to the file.
</p>
</dd>
<dt><var class="var">external-format</var></dt>
<dd><p>The external-format to use for <code class="code">:input</code>, <code class="code">:output</code>, and
<code class="code">:error</code> STREAMs.
</p></dd>
</dl>
<p><strong class="strong">Windows specific options:</strong>
</p><dl class="table">
<dt><var class="var">escape-arguments</var></dt>
<dd><p>Controls escaping of the arguments passed to <code class="code">CreateProcess</code>.
</p></dd>
</dl>
</dd></dl>
<a class="index-entry-id" id="index-FIFO-files-_0028named-pipes_0029"></a>
<hr>
</div>
<div class="subsection-level-extent" id="FIFO-files-_0028named-pipes_0029">
<div class="nav-panel">
<p>
Next: <a href="Operating-System-Interface.html#Operating-System-Interface-Reference" accesskey="n" rel="next">Operating System Interface Reference</a>, Previous: <a href="Operating-System-Interface.html#External-processes" accesskey="p" rel="prev">External processes</a>, Up: <a href="Operating-System-Interface.html#Operating-System-Interface" accesskey="u" rel="up">Operating System Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="FIFO-files-_0028named-pipes_0029-1">3.2.3 FIFO files (named pipes)</h4>
<p>Named pipe (known as fifo) may be created on UNIX with a shell command
mkfifo. They can be opened in non-blocking mode by using <code class="code">:nonblock
t</code> option for <code class="code"><a class="ref" href="Streams.html#open">open</a></code>. <code class="code"><a class="ref" href="Operating-System-Interface.html#ext_003afile_002dkind">ext:file-kind</a></code> will return for
such file <code class="code">:fifo</code>. Since it is impossible to guess how many
characters are available in this special file <code class="code">file-length</code>
function will return <code class="code">nil</code>.
</p>
<hr>
</div>
<div class="subsection-level-extent" id="Operating-System-Interface-Reference">
<div class="nav-panel">
<p>
Previous: <a href="Operating-System-Interface.html#FIFO-files-_0028named-pipes_0029" accesskey="p" rel="prev">FIFO files (named pipes)</a>, Up: <a href="Operating-System-Interface.html#Operating-System-Interface" accesskey="u" rel="up">Operating System Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
<h4 class="subsection" id="Operating-System-Interface-Reference-1">3.2.4 Operating System Interface Reference</h4>
<a class="anchor" id="ext_003asystem"></a><a class="index-entry-id" id="index-ext_003asystem-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003asystem"><span class="category-def">Function: </span><span><strong class="def-name">ext:system</strong> <var class="def-var-arguments">command</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003asystem'> &para;</a></span></dt>
<dd><p>Run shell command ignoring its output. Uses fork.
</p></dd></dl>
<a class="anchor" id="ext_003amake_002dpipe"></a><a class="index-entry-id" id="index-ext_003amake_002dpipe-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003amake_002dpipe"><span class="category-def">Function: </span><span><strong class="def-name">ext:make-pipe</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003amake_002dpipe'> &para;</a></span></dt>
<dd><p>Creates a pipe and wraps it in a two way stream.
</p></dd></dl>
<a class="anchor" id="ext_003aquit"></a><a class="index-entry-id" id="index-ext_003aquit-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aquit"><span class="category-def">Function: </span><span><strong class="def-name">ext:quit</strong> <var class="def-var-arguments">&amp;optional exit-code kill-all-threads</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aquit'> &para;</a></span></dt>
<dd><p>This function abruptly stops the execution of the program in which ECL
is embedded. Depending on the platform, several other functions will
be invoked to free resources, close loaded modules, etc.
</p>
<p>The exit code is the code seen by the parent process that invoked this
program. Normally a code other than zero denotes an error.
</p>
<p>If <var class="var">kill-all-threads</var> is non-<code class="code">nil</code>, tries to gently kill and
join with running threads.
</p></dd></dl>
<a class="anchor" id="ext_003aenviron"></a><a class="index-entry-id" id="index-ext_003aenviron-1"></a>
<a class="anchor" id="ext_003agetenv"></a><a class="index-entry-id" id="index-ext_003agetenv-1"></a>
<a class="anchor" id="ext_003asetenv"></a><a class="index-entry-id" id="index-ext_003asetenv-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003aenviron"><span class="category-def">Function: </span><span><strong class="def-name">ext:environ</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aenviron'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003agetenv"><span class="category-def">Function: </span><span><strong class="def-name">ext:getenv</strong> <var class="def-var-arguments">variable</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003agetenv'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003asetenv"><span class="category-def">Function: </span><span><strong class="def-name">ext:setenv</strong> <var class="def-var-arguments">variable value</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003asetenv'> &para;</a></span></dt>
<dd><p>Environment accessors.
</p></dd></dl>
<a class="anchor" id="ext_003agetpid"></a><a class="index-entry-id" id="index-ext_003agetpid-1"></a>
<a class="anchor" id="ext_003agetuid"></a><a class="index-entry-id" id="index-ext_003agetuid-1"></a>
<a class="anchor" id="ext_003agetcwd"></a><a class="index-entry-id" id="index-ext_003agetcwd-1"></a>
<a class="anchor" id="ext_003achdir"></a><a class="index-entry-id" id="index-ext_003achdir-1"></a>
<a class="anchor" id="ext_003afile_002dkind"></a><a class="index-entry-id" id="index-ext_003afile_002dkind-1"></a>
<a class="anchor" id="ext_003acopy_002dfile"></a><a class="index-entry-id" id="index-ext_003acopy_002dfile-1"></a>
<a class="anchor" id="ext_003achmod"></a><a class="index-entry-id" id="index-ext_003achmod-1"></a>
<dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ext_003agetpid"><span class="category-def">Function: </span><span><strong class="def-name">ext:getpid</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003agetpid'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003agetuid"><span class="category-def">Function: </span><span><strong class="def-name">ext:getuid</strong><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003agetuid'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003agetcwd"><span class="category-def">Function: </span><span><strong class="def-name">ext:getcwd</strong> <var class="def-var-arguments">&amp;optional (change-default-pathname-defaults NIL)</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003agetcwd'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003achdir"><span class="category-def">Function: </span><span><strong class="def-name">ext:chdir</strong> <var class="def-var-arguments">directory &amp;optional (change-default-pathname-defaults T)</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003achdir'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003afile_002dkind"><span class="category-def">Function: </span><span><strong class="def-name">ext:file-kind</strong> <var class="def-var-arguments">filename follow-symlinks-p</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003afile_002dkind'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003acopy_002dfile"><span class="category-def">Function: </span><span><strong class="def-name">ext:copy-file</strong> <var class="def-var-arguments">filename destination-filename</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003acopy_002dfile'> &para;</a></span></dt>
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-ext_003achmod"><span class="category-def">Function: </span><span><strong class="def-name">ext:chmod</strong> <var class="def-var-arguments">filename mode</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003achmod'> &para;</a></span></dt>
<dd><p>Common operating system functions.
</p></dd></dl>
</div>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Foreign-Function-Interface.html#Foreign-Function-Interface" accesskey="n" rel="next">Foreign Function Interface</a>, Previous: <a href="System-building.html#System-building" accesskey="p" rel="prev">System building</a>, Up: <a href="Extensions.html" accesskey="u" rel="up">Extensions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indexes.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
Copy permalink