578 lines
37 KiB
HTML
578 lines
37 KiB
HTML
<!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> [<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> [<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'> ¶</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'> ¶</a></span></dt>
|
|
<dd><p>ECL initialization files. Initial value is <code class="code">'("~/.ecl"
|
|
"~/.eclrc")</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'> ¶</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'> ¶</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">&key args rules</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aprocess_002dcommand_002dargs'> ¶</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’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* "
|
|
ls [--help | -?] filename*
|
|
Lists the file that match the given patterns.
|
|
")
|
|
|
|
(defun print-directory (pathnames)
|
|
(format t "~{~A~%~}"
|
|
(mapcar #'(lambda (x) (enough-namestring x (si::getcwd)))
|
|
(mapcan #'directory (or pathnames '("*.*" "*/"))))))
|
|
|
|
(defconstant +ls-rules+
|
|
'(("--help" 0 (progn (princ ext:*help-message* *standard-output*) (ext:quit 0)))
|
|
("-?" 0 (progn (princ ext:*help-message* *standard-output*) (ext:quit 0)))
|
|
("*DEFAULT*" 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> [<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'> ¶</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'> ¶</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'> ¶</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 &optional force</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aterminate_002dprocess'> ¶</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'> ¶</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'> ¶</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'> ¶</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 &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'> ¶</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’t finish but is
|
|
not referenced, finalizer will be invoked once more during next
|
|
garbage collection.
|
|
</p>
|
|
<p>The <code class="code">&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 "man
|
|
environ"). 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> [<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> [<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'> ¶</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'> ¶</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">&optional exit-code kill-all-threads</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003aquit'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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'> ¶</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">&optional (change-default-pathname-defaults NIL)</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003agetcwd'> ¶</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 &optional (change-default-pathname-defaults T)</var><a class="copiable-link" href='Operating-System-Interface.html#index-ext_003achdir'> ¶</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'> ¶</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'> ¶</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'> ¶</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> [<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>
|