248 lines
167 KiB
HTML
248 lines
167 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>15.4 Processes</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="extras.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">The Racket Reference</a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="model.html" class="tocviewlink" data-pltdoc="x">Language Model</a></td></tr><tr><td align="right">2 </td><td><a href="notation.html" class="tocviewlink" data-pltdoc="x">Notation for Documentation</a></td></tr><tr><td align="right">3 </td><td><a href="syntax.html" class="tocviewlink" data-pltdoc="x">Syntactic Forms</a></td></tr><tr><td align="right">4 </td><td><a href="data.html" class="tocviewlink" data-pltdoc="x">Datatypes</a></td></tr><tr><td align="right">5 </td><td><a href="structures.html" class="tocviewlink" data-pltdoc="x">Structures</a></td></tr><tr><td align="right">6 </td><td><a href="mzlib_class.html" class="tocviewlink" data-pltdoc="x">Classes and Objects</a></td></tr><tr><td align="right">7 </td><td><a href="mzlib_unit.html" class="tocviewlink" data-pltdoc="x">Units</a></td></tr><tr><td align="right">8 </td><td><a href="contracts.html" class="tocviewlink" data-pltdoc="x">Contracts</a></td></tr><tr><td align="right">9 </td><td><a href="match.html" class="tocviewlink" data-pltdoc="x">Pattern Matching</a></td></tr><tr><td align="right">10 </td><td><a href="control.html" class="tocviewlink" data-pltdoc="x">Control Flow</a></td></tr><tr><td align="right">11 </td><td><a href="concurrency.html" class="tocviewlink" data-pltdoc="x">Concurrency and Parallelism</a></td></tr><tr><td align="right">12 </td><td><a href="Macros.html" class="tocviewlink" data-pltdoc="x">Macros</a></td></tr><tr><td align="right">13 </td><td><a href="input-and-output.html" class="tocviewlink" data-pltdoc="x">Input and Output</a></td></tr><tr><td align="right">14 </td><td><a href="security.html" class="tocviewlink" data-pltdoc="x">Reflection and Security</a></td></tr><tr><td align="right">15 </td><td><a href="os.html" class="tocviewselflink" data-pltdoc="x">Operating System</a></td></tr><tr><td align="right">16 </td><td><a href="memory.html" class="tocviewlink" data-pltdoc="x">Memory Management</a></td></tr><tr><td align="right">17 </td><td><a href="unsafe.html" class="tocviewlink" data-pltdoc="x">Unsafe Operations</a></td></tr><tr><td align="right">18 </td><td><a href="running.html" class="tocview
|
||
|
|
<span class="RktVar">command</span> asynchronously, providing the new process with
|
||
|
|
environment variables <span class="RktSym"><a href="envvars.html#%28def._%28%28quote._~23~25kernel%29._current-environment-variables%29%29" class="RktValLink" data-pltdoc="x">current-environment-variables</a></span>. See also
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span> and <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span> from
|
||
|
|
<a href="subprocess.html#%28mod-path._racket%2Fsystem%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/system</span></a>.</div></p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>On Unix and Mac OS, subprocess creation is separate
|
||
|
|
from starting the program indicated by <span class="RktVar">command</span>. In
|
||
|
|
particular, if <span class="RktVar">command</span> refers to a non-existent or
|
||
|
|
non-executable file, an error will be reported (via standard error and
|
||
|
|
a non-0 exit code) in the subprocess, not in the creating
|
||
|
|
process.</p></blockquote></blockquote></blockquote><p>The <span class="RktVar">command</span> argument is a path to a program executable, and
|
||
|
|
the <span class="RktVar">arg</span>s are command-line arguments for the program. See
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValLink" data-pltdoc="x">find-executable-path</a></span> for locating an executable based on
|
||
|
|
the <span class="stt">PATH</span> environment variable. On
|
||
|
|
Unix and Mac OS, command-line arguments are passed as byte strings,
|
||
|
|
and string <span class="RktVar">arg</span>s are converted using the current locale’s
|
||
|
|
encoding (see <a href="encodings.html" data-pltdoc="x">Encodings and Locales</a>). On Windows, command-line
|
||
|
|
arguments are passed as strings, and byte strings are converted using
|
||
|
|
UTF-8.</p><p>On Windows, the first <span class="RktVar">arg</span> can be replaced with
|
||
|
|
<a name="(idx._(gentag._384._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">exact</span>, which triggers a Windows-specific behavior:
|
||
|
|
the sole <span class="RktVar">arg</span> is used exactly as the command-line for the
|
||
|
|
subprocess. Otherwise, on Windows, a command-line string is
|
||
|
|
constructed from <span class="RktVar">command</span> and <span class="RktVar">arg</span> so that a typical
|
||
|
|
Windows console application can parse it back to an array of
|
||
|
|
arguments. If <span class="RktVal">'</span><span class="RktVal">exact</span> is provided on a non-Windows platform,
|
||
|
|
the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29" class="RktValLink" data-pltdoc="x">exn:fail:contract</a></span> exception is raised.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>For information on the Windows command-line conventions,
|
||
|
|
search for “command line parsing” at
|
||
|
|
<span class="stt">http://msdn.microsoft.com/</span>.</p></blockquote></blockquote></blockquote><p>When provided as a port, <span class="RktVar">stdout</span> is used for the launched
|
||
|
|
process’s standard output, <span class="RktVar">stdin</span> is used for the process’s
|
||
|
|
standard input, and <span class="RktVar">stderr</span> is used for the process’s standard
|
||
|
|
error. All provided ports must be file-stream ports. Any of the ports
|
||
|
|
can be <span class="RktVal">#f</span>, in which case a system pipe is created and
|
||
|
|
returned by <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span>. The <span class="RktVar">stderr</span> argument can be
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">stdout</span>, in which case the same file-stream port or system pipe
|
||
|
|
that is supplied as standard output is also used for standard error.
|
||
|
|
For each port or <span class="RktVal">'</span><span class="RktVal">stdout</span> that is provided, no
|
||
|
|
pipe is created and the corresponding returned value is <span class="RktVal">#f</span>.
|
||
|
|
If <span class="RktVar">stdout</span> or <span class="RktVar">stderr</span> is a port for which
|
||
|
|
<span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._port-waiting-peer~3f%29%29" class="RktValLink" data-pltdoc="x">port-waiting-peer?</a></span> returns true, then <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span>
|
||
|
|
waits for the port to become ready for writing before proceeding with
|
||
|
|
the subprocess creation.</p><p>If <span class="RktVar">group</span> is <span class="RktVal">'</span><span class="RktVal">new</span>, then the new process is created as
|
||
|
|
a new OS-level process group. In that case, <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span>
|
||
|
|
attempts to terminate all processes within the group, which may
|
||
|
|
include additional processes created by the subprocess.
|
||
|
|
<span class="refelem"><span class="refcolumn"><span class="refcontent">Beware that creating a group may interfere with the job
|
||
|
|
control in an interactive shell, since job control is based on process
|
||
|
|
groups.</span></span></span> See <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span> for details. If <span class="RktVar">group</span>
|
||
|
|
is a subprocess, then that subprocess must have been created with
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">new</span>, and the new subprocess will be added to the group;
|
||
|
|
adding to the group will succeed only on Unix and Mac OS, and only in
|
||
|
|
the same cases that <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span> would have an effect
|
||
|
|
(i.e., the subprocess is not known to have terminated), otherwise it
|
||
|
|
will fail silently.</p><p>The <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> procedure returns four values:</p><ul><li><p>a <a name="(tech._subproces)"></a><span style="font-style: italic">subprocess</span> value representing the created process;</p></li><li><p>an input port piped from the process’s standard output, or
|
||
|
|
<span class="RktVal">#f</span> if <span class="RktVar">stdout</span> was a port;</p></li><li><p>an output port piped to the process’s standard input, or
|
||
|
|
<span class="RktVal">#f</span> if <span class="RktVar">stdin</span> was a port;</p></li><li><p>an input port piped from the process’s standard error, or
|
||
|
|
<span class="RktVal">#f</span> if <span class="RktVar">stderr</span> was a port or <span class="RktVal">'</span><span class="RktVal">stdout</span>.</p></li></ul><p><span style="font-weight: bold">Important:</span> All ports returned from <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> must be
|
||
|
|
explicitly closed, usually with <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29" class="RktValLink" data-pltdoc="x">close-input-port</a></span> or
|
||
|
|
<span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29" class="RktValLink" data-pltdoc="x">close-output-port</a></span>.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>A <a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream port</span></a> for communicating with a
|
||
|
|
subprocess is normally a pipe with a limited capacity. Beware of
|
||
|
|
creating deadlock by serializing a write to a subprocess followed by a
|
||
|
|
read, while the subprocess does the same, so that both processes end
|
||
|
|
up blocking on a write because the other end must first read to make
|
||
|
|
room in the pipe. Beware also of waiting for a subprocess to finish
|
||
|
|
without reading its output, because the subprocess may be blocked attempting
|
||
|
|
to write output into a full pipe.</p></blockquote></blockquote></blockquote><p>The returned ports are <a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream ports</span></a> (see
|
||
|
|
<a href="file-ports.html" data-pltdoc="x">File Ports</a>), and they are placed into the management of
|
||
|
|
the current custodian (see <a href="custodians.html" data-pltdoc="x">Custodians</a>). The
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span> exception is raised when a low-level error prevents the spawning of a
|
||
|
|
process or the creation of operating system pipes for process
|
||
|
|
communication.</p><p>The <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-custodian-mode%29%29" class="RktValLink" data-pltdoc="x">current-subprocess-custodian-mode</a></span> parameter determines
|
||
|
|
whether the subprocess itself is registered with the current
|
||
|
|
<a href="eval-model.html#%28tech._custodian%29" class="techoutside" data-pltdoc="x"><span class="techinside">custodian</span></a> so that a custodian shutdown calls
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span> for the subprocess.</p><p>The <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-keep-file-descriptors%29%29" class="RktValLink" data-pltdoc="x">current-subprocess-keep-file-descriptors</a></span> parameter
|
||
|
|
determines how file descriptors and handles in the current process are
|
||
|
|
shared with the subprocess. File descriptors (on Unix and Mac OS) or
|
||
|
|
handles (on Windows) represented by <span class="RktVar">stdin</span>, <span class="RktVar">stdout</span>,
|
||
|
|
and <span class="RktVar">stderr</span> are always shared with the subprocess. With the
|
||
|
|
default parameter value of <span class="RktVal">'</span><span class="RktVal">inherited</span>, handles that are
|
||
|
|
inherited on Windows are also shared, while no other file descriptors
|
||
|
|
are shared on Unix and Mac OS. The parameter value <span class="RktVal">'</span><span class="RktVal">all</span> is
|
||
|
|
equivalent to <span class="RktVal">'</span><span class="RktVal">inherited</span> on Windows, but on Unix and Mac OS,
|
||
|
|
all file descriptors from the current process are shared with the
|
||
|
|
subprocess—<wbr></wbr>except for file descriptors 0, 1, and 2 as replaced by
|
||
|
|
newly created pipes when the corresponding <span class="RktVar">stdin</span>,
|
||
|
|
<span class="RktVar">stdout</span>, and <span class="RktVar">stderr</span> argument is <span class="RktVal">#f</span>. The
|
||
|
|
parameter value <span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">)</span> is the same as <span class="RktVal">'</span><span class="RktVal">inherited</span> on
|
||
|
|
Unix and Mac OS , but it prevents sharing of inheritable handles on
|
||
|
|
Windows. (A future extension may support a list of specific file
|
||
|
|
descriptors or handles to share.)</p><p>A subprocess can be used as a <a href="sync.html#%28tech._synchronizable._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronizable event</span></a> (see <a href="sync.html" data-pltdoc="x">Events</a>).
|
||
|
|
A subprocess value is <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> when
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-wait%29%29" class="RktValLink" data-pltdoc="x">subprocess-wait</a></span> would not block; the <a href="sync.html#%28tech._synchronization._result%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronization result</span></a> of a subprocess value is the subprocess value itself.</p><p>Example:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28quote._~23~25kernel%29._define-values%29%29" class="RktStxLink" data-pltdoc="x">define-values</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">sp</span><span class="hspace"> </span><span class="RktSym">out</span><span class="hspace"> </span><span class="RktSym">in</span><span class="hspace"> </span><span class="RktSym">err</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">"/bin/ls"</span><span class="hspace"> </span><span class="RktVal">"-l"</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"stdout:\n~a"</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._port-~3estring%29%29" class="RktValLink" data-pltdoc="x">port->string</a></span><span class="hspace"> </span><span class="RktSym">out</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"stderr:\n~a"</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._port-~3estring%29%29" class="RktValLink" data-pltdoc="x">port->string</a></span><span class="hspace"> </span><span class="RktSym">err</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29" class="RktValLink" data-pltdoc="x">close-input-port</a></span><span class="hspace"> </span><span class="RktSym">out</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29" class="RktValLink" data-pltdoc="x">close-output-port</a></span><span class="hspace"> </span><span class="RktSym">in</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29" class="RktValLink" data-pltdoc="x">close-input-port</a></span><span class="hspace"> </span><span class="RktSym">err</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-wait%29%29" class="RktValLink" data-pltdoc="x">subprocess-wait</a></span><span class="hspace"> </span><span class="RktSym">sp</span><span class="RktPn
|
||
|
|
as <span class="RktVar">stdout</span> and/or <span class="RktVar">stderr</span>.<br/>Changed in version 8.3.0.4: Added <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-custodian-mode%29%29" class="RktValLink" data-pltdoc="x">current-subprocess-custodian-mode</a></span> support.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._subprocess-wait))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-wait%29%29" class="RktValDef RktValLink" data-pltdoc="x">subprocess-wait</a></span></span><span class="hspace"> </span><span class="RktVar">subproc</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">subproc</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess~3f%29%29" class="RktValLink" data-pltdoc="x">subprocess?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Blocks until the process represented by <span class="RktVar">subproc</span>
|
||
|
|
terminates. The <span class="RktVar">subproc</span> value also can be used with
|
||
|
|
<span class="RktSym"><a href="sync.html#%28def._%28%28quote._~23~25kernel%29._sync%29%29" class="RktValLink" data-pltdoc="x">sync</a></span> and <span class="RktSym"><a href="sync.html#%28def._%28%28quote._~23~25kernel%29._sync%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">sync/timeout</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._subprocess-status))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-status%29%29" class="RktValDef RktValLink" data-pltdoc="x">subprocess-status</a></span></span><span class="hspace"> </span><span class="RktVar">subproc</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">running</span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-nonnegative-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-nonnegative-integer?</a></span><span class="RktPn">)</span></td></tr></table></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">subproc</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess~3f%29%29" class="RktValLink" data-pltdoc="x">subprocess?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <a name="(idx._(gentag._385._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">running</span> if the process represented by
|
||
|
|
<span class="RktVar">subproc</span> is still running, or its exit code otherwise. The
|
||
|
|
exit code is an exact integer, and <span class="RktVal">0</span> typically indicates
|
||
|
|
success. If the process terminated due to a fault or signal, the exit
|
||
|
|
code is non-zero.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._subprocess-kill))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValDef RktValLink" data-pltdoc="x">subprocess-kill</a></span></span><span class="hspace"> </span><span class="RktVar">subproc</span><span class="hspace"> </span><span class="RktVar">force?</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">subproc</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess~3f%29%29" class="RktValLink" data-pltdoc="x">subprocess?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">force?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Terminates the subprocess represented by <span class="RktVar">subproc</span>. The precise
|
||
|
|
action depends on whether <span class="RktVar">force?</span> is true, whether the process
|
||
|
|
was created in its own group by setting the
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-group-enabled%29%29" class="RktValLink" data-pltdoc="x">subprocess-group-enabled</a></span> parameter to a true value, and the
|
||
|
|
current platform:</div></p><ul><li><p><span class="RktVar">force?</span> is true, not a group, all platforms: Terminates
|
||
|
|
the process if the process still running.</p></li><li><p><span class="RktVar">force?</span> is false, not a group, on Unix or Mac OS:
|
||
|
|
Sends the process an interrupt signal instead of a kill
|
||
|
|
signal.</p></li><li><p><span class="RktVar">force?</span> is false, not a group, on Windows: No action
|
||
|
|
is taken.</p></li><li><p><span class="RktVar">force?</span> is true, a group, on Unix or Mac OS:
|
||
|
|
Terminates all processes in the group, but only if
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-status%29%29" class="RktValLink" data-pltdoc="x">subprocess-status</a></span> has never produced a
|
||
|
|
non-<span class="RktVal">'</span><span class="RktVal">running</span> result for the subprocess and only if
|
||
|
|
functions like <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-wait%29%29" class="RktValLink" data-pltdoc="x">subprocess-wait</a></span> and <span class="RktSym"><a href="sync.html#%28def._%28%28quote._~23~25kernel%29._sync%29%29" class="RktValLink" data-pltdoc="x">sync</a></span> have
|
||
|
|
not detected the subprocess’s completion. Otherwise, no action
|
||
|
|
is taken (because the immediate process is known to have
|
||
|
|
terminated while the continued existence of the group is
|
||
|
|
unknown).</p></li><li><p><span class="RktVar">force?</span> is true, a group, on Windows: Terminates
|
||
|
|
the process if the process still running.</p></li><li><p><span class="RktVar">force?</span> is false, a group, on Unix or Mac OS: The
|
||
|
|
same as when <span class="RktVar">force?</span> is <span class="RktVal">#t</span>, but when the group
|
||
|
|
is sent a signal, it is an interrupt signal instead of a kill
|
||
|
|
signal.</p></li><li><p><span class="RktVar">force?</span> is false, a group, on Windows: All processes
|
||
|
|
in the group receive a CTRL-BREAK signal (independent of
|
||
|
|
whether the immediate subprocess has terminated).</p></li></ul><p>If an error occurs during termination, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span> exception is raised.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._subprocess-pid))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-pid%29%29" class="RktValDef RktValLink" data-pltdoc="x">subprocess-pid</a></span></span><span class="hspace"> </span><span class="RktVar">subproc</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-nonnegative-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-nonnegative-integer?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">subproc</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess~3f%29%29" class="RktValLink" data-pltdoc="x">subprocess?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns the operating system’s numerical ID (if any) for the process
|
||
|
|
represented by <span class="RktVar">subproc</span>. The result is valid only as long as
|
||
|
|
the process is running.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._subprocess~3f))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">subprocess?</a></span></span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if <span class="RktVar">v</span> is a subprocess value, <span class="RktVal">#f</span>
|
||
|
|
otherwise.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._current-subprocess-custodian-mode))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-custodian-mode%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-subprocess-custodian-mode</a></span></span><span class="RktPn"></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">kill</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">interrupt</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-custodian-mode%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-subprocess-custodian-mode</a></span></span><span class="hspace"> </span><span class="RktVar">mode</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">kill</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">interrupt</span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">A <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a> that determines whether a subprocess (as created by
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> or wrappers like <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span>) is registered
|
||
|
|
with the current <a href="eval-model.html#%28tech._custodian%29" class="techoutside" data-pltdoc="x"><span class="techinside">custodian</span></a>. If the parameter value is
|
||
|
|
<span class="RktVal">#f</span>, then the subprocess is not registered with the
|
||
|
|
custodian—<wbr></wbr>although any created ports are registered. If the
|
||
|
|
parameter value is <span class="RktVal">'</span><span class="RktVal">kill</span> or <span class="RktVal">'</span><span class="RktVal">interrupt</span>, then the
|
||
|
|
subprocess is shut down through <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span>, where
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">kill</span> supplies a <span class="RktVal">#t</span> value for the <span class="RktVar">force?</span>
|
||
|
|
argument and <span class="RktVal">'</span><span class="RktVal">interrupt</span> supplies a <span class="RktVal">#f</span> value. The
|
||
|
|
shutdown may occur either before or after ports created for the
|
||
|
|
subprocess are closed.</div></p><p>Custodian-triggered shutdown is limited by details of process handling
|
||
|
|
in the host system. For example, <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span> and <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span>
|
||
|
|
may create an intermediate shell process to run a program, in which
|
||
|
|
case custodian-based termination shuts down the shell process and
|
||
|
|
probably not the process started by the shell. See also
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span>. Process groups (see
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-group-enabled%29%29" class="RktValLink" data-pltdoc="x">subprocess-group-enabled</a></span>) can address some limitations, but
|
||
|
|
not all of them.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._subprocess-group-enabled))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-group-enabled%29%29" class="RktValDef RktValLink" data-pltdoc="x">subprocess-group-enabled</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-group-enabled%29%29" class="RktValDef RktValLink" data-pltdoc="x">subprocess-group-enabled</a></span></span><span class="hspace"> </span><span class="RktVar">on?</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">on?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">A <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a> that determines whether a subprocess is created as
|
||
|
|
a new process group by default. See <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> and
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span> for more information.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._current-subprocess-keep-file-descriptors))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-keep-file-descriptors%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-subprocess-keep-file-descriptors</a></span></span><span class="RktPn"></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">inherited</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">all</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-keep-file-descriptors%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-subprocess-keep-file-descriptors</a></span></span><span class="hspace"> </span><span class="RktVar">keeps</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">keeps</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">inherited</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">all</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">A <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a> that determines how file descriptors (on Unix and
|
||
|
|
Mac OS) and handles (on Windows) are shared in a subprocess as created
|
||
|
|
by <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> or wrappers like <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span>. See
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> for more information.</div></p><p class="SHistory">Added in version 8.3.0.4 of package <span class="stt">base</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._shell-execute))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._shell-execute%29%29" class="RktValDef RktValLink" data-pltdoc="x">shell-execute</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">verb</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">target</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">parameters</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">dir</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">show-mode</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVal">#f</span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">verb</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">target</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">parameters</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28
|
||
|
|
on <span class="RktVar">target</span> in Windows. For platforms other than Windows, the
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aunsupported%29%29" class="RktValLink" data-pltdoc="x">exn:fail:unsupported</a></span> exception is raised.</div></p><p>For example,</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._shell-execute%29%29" class="RktValLink" data-pltdoc="x">shell-execute</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">"http://racket-lang.org"</span><span class="hspace"> </span><span class="RktVal">""</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">sw_shownormal</span><span class="RktPn">)</span></td></tr></table></blockquote><p>Opens the Racket home page in a browser window.</p><p>The <span class="RktVar">verb</span> can be <span class="RktVal">#f</span>, in which case the operating
|
||
|
|
system will use a default verb. Common verbs include <span class="RktVal">"open"</span>,
|
||
|
|
<span class="RktVal">"edit"</span>, <span class="RktVal">"find"</span>, <span class="RktVal">"explore"</span>, and
|
||
|
|
<span class="RktVal">"print"</span>.</p><p>The <span class="RktVar">target</span> is the target for the action, usually a filename
|
||
|
|
path. The file could be executable, or it could be a file with a
|
||
|
|
recognized extension that can be handled by an installed application.</p><p>The <span class="RktVar">parameters</span> argument is passed on to the system to perform
|
||
|
|
the action. For example, in the case of opening an executable, the
|
||
|
|
<span class="RktVar">parameters</span> is used as the command line (after the executable
|
||
|
|
name).</p><p>The <span class="RktVar">dir</span> is used as the current directory when performing the
|
||
|
|
action.</p><p>The <span class="RktVar">show-mode</span> sets the display mode for a Window affected by
|
||
|
|
the action. It must be one of the following symbols; the description
|
||
|
|
of each symbol’s meaning is taken from the Windows API documentation.</p><ul><li><p><a name="(idx._(gentag._387._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_hide</span> or <a name="(idx._(gentag._388._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_HIDE</span> —<wbr></wbr>
|
||
|
|
Hides the window and activates another window.</p></li><li><p><a name="(idx._(gentag._389._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_maximize</span> or <a name="(idx._(gentag._390._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_MAXIMIZE</span>
|
||
|
|
—<wbr></wbr> Maximizes the window.</p></li><li><p><a name="(idx._(gentag._391._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_minimize</span> or <a name="(idx._(gentag._392._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_MINIMIZE</span>
|
||
|
|
—<wbr></wbr> Minimizes the window and activates the next top-level window in
|
||
|
|
the z-order.</p></li><li><p><a name="(idx._(gentag._393._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_restore</span> or <a name="(idx._(gentag._394._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_RESTORE</span>
|
||
|
|
—<wbr></wbr> Activates and displays the window. If the window is minimized or
|
||
|
|
maximized, Windows restores it to its original size and position.</p></li><li><p><a name="(idx._(gentag._395._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_show</span> or <a name="(idx._(gentag._396._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOW</span> —<wbr></wbr>
|
||
|
|
Activates the window and displays it in its current size and
|
||
|
|
position.</p></li><li><p><a name="(idx._(gentag._397._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_showdefault</span> or
|
||
|
|
<a name="(idx._(gentag._398._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOWDEFAULT</span> —<wbr></wbr> Uses a default.</p></li><li><p><a name="(idx._(gentag._399._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_showmaximized</span> or
|
||
|
|
<a name="(idx._(gentag._400._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOWMAXIMIZED</span> —<wbr></wbr> Activates the window and
|
||
|
|
displays it as a maximized window.</p></li><li><p><a name="(idx._(gentag._401._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_showminimized</span> or
|
||
|
|
<a name="(idx._(gentag._402._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOWMINIMIZED</span> —<wbr></wbr> Activates the window and
|
||
|
|
displays it as a minimized window.</p></li><li><p><a name="(idx._(gentag._403._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_showminnoactive</span> or
|
||
|
|
<a name="(idx._(gentag._404._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOWMINNOACTIVE</span> —<wbr></wbr> Displays the window as a
|
||
|
|
minimized window. The active window remains active.</p></li><li><p><a name="(idx._(gentag._405._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_showna</span> or <a name="(idx._(gentag._406._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOWNA</span> —<wbr></wbr>
|
||
|
|
Displays the window in its current state. The active window remains
|
||
|
|
active.</p></li><li><p><a name="(idx._(gentag._407._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_shownoactivate</span> or
|
||
|
|
<a name="(idx._(gentag._408._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOWNOACTIVATE</span> —<wbr></wbr> Displays a window in its most
|
||
|
|
recent size and position. The active window remains active.</p></li><li><p><a name="(idx._(gentag._409._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sw_shownormal</span> or
|
||
|
|
<a name="(idx._(gentag._410._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">SW_SHOWNORMAL</span> —<wbr></wbr> Activates and displays a
|
||
|
|
window. If the window is minimized or maximized, Windows restores it
|
||
|
|
to its original size and position.</p></li></ul><p>If the action fails, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span> exception is raised. If the action succeeds,
|
||
|
|
the result is <span class="RktVal">#f</span>.</p><p>In future versions of Racket, the result may be a subprocess value if
|
||
|
|
the operating system did returns a process handle (but if a subprocess
|
||
|
|
value is returned, its process ID will be <span class="RktVal">0</span> instead of the
|
||
|
|
real process ID).</p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Simple_Subprocesses"">15.4.1<tt> </tt><a name="(part._.Simple_.Subprocesses)"></a><a name="(mod-path._racket/system)"></a>Simple Subprocesses</h5><p><div class="SIntrapara"><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="subprocess.html#%28mod-path._racket%2Fsystem%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/system</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <a href="https://pkgs.racket-lang.org/package/base" title="Install this package using `raco pkg install base`"><span class="stt">base</span></a></span></td></tr></table></div><div class="SIntrapara">The bindings documented in this section are provided by the <a href="subprocess.html#%28mod-path._racket%2Fsystem%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/system</span></a> and <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket</span></a> libraries, but not <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/base</span></a>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._system))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValDef RktValLink" data-pltdoc="x">system</a></span></span><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._string-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">string-no-nuls?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._bytes-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">bytes-no-nuls?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._member%29%29" class="RktValLink" data-pltdoc="x">me
|
||
|
|
(i.e., the call to <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span> does not return until the
|
||
|
|
subprocess has ended). The <span class="RktVar">command</span> argument is a string or
|
||
|
|
byte string containing no nul characters. If the command succeeds, the
|
||
|
|
return value is <span class="RktVal">#t</span>, <span class="RktVal">#f</span> otherwise.</div></p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>See also <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> for notes about error
|
||
|
|
handling and the limited buffer capacity of subprocess pipes.</p></blockquote></blockquote></blockquote><p>If <span class="RktVar">set-pwd?</span> is true, then the <span class="stt">PWD</span> environment
|
||
|
|
variable is set to the value of <span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span> when
|
||
|
|
starting the shell process.</p><p>See also <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-custodian-mode%29%29" class="RktValLink" data-pltdoc="x">current-subprocess-custodian-mode</a></span> and
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-group-enabled%29%29" class="RktValLink" data-pltdoc="x">subprocess-group-enabled</a></span>, which affect the subprocess used to
|
||
|
|
implement <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span>.</p><p>The resulting process writes to <span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-output-port%29%29" class="RktValLink" data-pltdoc="x">current-output-port</a></span><span class="RktPn">)</span>, reads
|
||
|
|
from <span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29" class="RktValLink" data-pltdoc="x">current-input-port</a></span><span class="RktPn">)</span>, and logs errors to
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-error-port%29%29" class="RktValLink" data-pltdoc="x">current-error-port</a></span><span class="RktPn">)</span>. To gather the process’s non-error
|
||
|
|
output to a string, for example, use <span class="RktSym"><a href="port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._with-output-to-string%29%29" class="RktValLink" data-pltdoc="x">with-output-to-string</a></span>,
|
||
|
|
which sets <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-output-port%29%29" class="RktValLink" data-pltdoc="x">current-output-port</a></span> while calling the given
|
||
|
|
function:</p><blockquote class="SCodeFlow"><p><span class="RktPn">(</span><span class="RktSym"><a href="port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._with-output-to-string%29%29" class="RktValLink" data-pltdoc="x">with-output-to-string</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span><span class="hspace"> </span><span class="RktVal">"date"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></p></blockquote><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._system*))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2A%29%29" class="RktValDef RktValLink" data-pltdoc="x">system*</a></span></span><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span><span class="RktVar">arg</span><span class="hspace"> </span><span class="RktMeta">...</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">arg</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._string-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">string-no-nuls?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._bytes-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">bytes-no-nuls?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28lib
|
||
|
|
is executed directly (instead of through a shell command; see
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValLink" data-pltdoc="x">find-executable-path</a></span> for locating an executable based on
|
||
|
|
the <span class="stt">PATH</span> environment variable), and the
|
||
|
|
<span class="RktVar">arg</span>s are the arguments. The executed file is passed the
|
||
|
|
specified string arguments (which must contain no nul
|
||
|
|
characters).</div></p><p>On Windows, the first argument after <span class="RktVar">command</span> can be
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">exact</span>, and the final <span class="RktVar">arg</span> is a complete command
|
||
|
|
line. See <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> for details.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._system/exit-code))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2Fexit-code%29%29" class="RktValDef RktValLink" data-pltdoc="x">system/exit-code</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">command</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._byte~3f%29%29" class="RktValLink" data-pltdoc="x">byte?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._string-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">string-no-nuls?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._bytes-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">bytes-no-nuls?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._member%29%29" class="RktValLink" data-pltdoc="x">member</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._system-type%29%29" class="RktValLink" data-pltdoc="x">system-type</a></span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">unix</span><span class="hspace"> </span><span class="RktVal">macosx</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span>, except that the result is the exit code returne
|
||
|
|
by the subprocess. A <span class="RktVal">0</span> result normally indicates success.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._system*/exit-code))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2A%2Fexit-code%29%29" class="RktValDef RktValLink" data-pltdoc="x">system*/exit-code</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">command</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">arg</span><span class="hspace"> </span><span class="RktMeta">...</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._byte~3f%29%29" class="RktValLink" data-pltdoc="x">byte?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">arg</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._string-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">string-no-nuls?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._bytes-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">bytes-no-nuls?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2Fexit-code%29%29" class="RktValLink" data-pltdoc="x">system/exit-code</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._process))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValDef RktValLink" data-pltdoc="x">process</a></span></span><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="prototype"><tr><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._input-port~3f%29%29" class="RktValLink" data-pltdoc="x">input-port?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._output-port~3f%29%29" class="RktValLink" data-pltdoc="x">output-port?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-nonnegative-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-nonnegative-integer?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._input-port~3f%29%29" class="RktValLink" data-pltdoc="x">input-port?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">status</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">wait</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">interrupt</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">kill</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr></table></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-stru
|
||
|
|
and Mac OS, <span class="stt">cmd</span> on Windows). The result is a list of five
|
||
|
|
values:</div></p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>See also <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29" class="RktValLink" data-pltdoc="x">subprocess</a></span> for notes about error
|
||
|
|
handling and the limited buffer capacity of subprocess pipes.</p></blockquote></blockquote></blockquote><ul><li><p>an input port piped from the subprocess’s standard output,</p></li><li><p>an output port piped to the subprocess’s standard input,</p></li><li><p>the system process id of the subprocess,</p></li><li><p>an input port piped from the subprocess’s standard
|
||
|
|
error, and</p></li><li><p>a procedure of one argument, either <span class="RktVal">'</span><span class="RktVal">status</span>, <span class="RktVal">'</span><span class="RktVal">wait</span>,
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">interrupt</span>, <span class="RktVal">'</span><span class="RktVal">exit-code</span> or <span class="RktVal">'</span><span class="RktVal">kill</span>:</p><ul><li><p><span class="RktVal">'</span><span class="RktVal">status</span> returns the status of the subprocess as one
|
||
|
|
of <span class="RktVal">'</span><span class="RktVal">running</span>, <span class="RktVal">'</span><span class="RktVal">done-ok</span>, or
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">done-error</span>.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">exit-code</span> returns the integer exit code of the
|
||
|
|
subprocess or <span class="RktVal">#f</span> if it is still running.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">wait</span> blocks execution in the current thread until
|
||
|
|
the subprocess has completed.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">interrupt</span> sends the subprocess an interrupt signal
|
||
|
|
on Unix and Mac OS, and takes no action on Windows. The result is
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="nobreak"><span class="RktRes">#<void></span></span></a>.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>On Unix and Mac OS, if <span class="RktVar">command</span> runs a
|
||
|
|
single program, then <span class="stt">sh</span> typically runs the program in
|
||
|
|
such a way that it replaces <span class="stt">sh</span> in the same process. For
|
||
|
|
reliable and precise control over process creation, however, use
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%2A%29%29" class="RktValLink" data-pltdoc="x">process*</a></span>.</p></blockquote></blockquote></blockquote></li><li><p><span class="RktVal">'</span><span class="RktVal">kill</span> terminates the subprocess and returns
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="nobreak"><span class="RktRes">#<void></span></span></a>. Note that the immediate process created by
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span> is a shell process that may run another program;
|
||
|
|
terminating the shell process may not terminate processes that
|
||
|
|
the shell starts, particularly on Windows.</p></li></ul></li></ul><p><span style="font-weight: bold">Important:</span> All three ports returned from <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span> must
|
||
|
|
be explicitly closed with <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29" class="RktValLink" data-pltdoc="x">close-input-port</a></span> or
|
||
|
|
<span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29" class="RktValLink" data-pltdoc="x">close-output-port</a></span>.</p><p>If <span class="RktVar">set-pwd?</span> is true, then <span class="stt">PWD</span> is set in the same way
|
||
|
|
as <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span>.</p><p>See also <span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._current-subprocess-custodian-mode%29%29" class="RktValLink" data-pltdoc="x">current-subprocess-custodian-mode</a></span> and
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-group-enabled%29%29" class="RktValLink" data-pltdoc="x">subprocess-group-enabled</a></span>, which affect the subprocess used to
|
||
|
|
implement <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span>. In particular, the <span class="RktVal">'</span><span class="RktVal">interrupt</span> and
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">kill</span> process-control messages are implemented via
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess-kill%29%29" class="RktValLink" data-pltdoc="x">subprocess-kill</a></span>, so they can affect a process group instead
|
||
|
|
of a single process.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._process*))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%2A%29%29" class="RktValDef RktValLink" data-pltdoc="x">process*</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">command</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">arg</span><span class="hspace"> </span><span class="RktMeta">...</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">command</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">arg</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._string-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">string-no-nuls?</a></span><span class="hspace"> </span><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._bytes-no-nuls~3f%29%29" class="RktValLink" data-pltdoc="x">bytes-no-nuls?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._member%29%29" class="Rkt
|
||
|
|
is executed directly like <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2A%29%29" class="RktValLink" data-pltdoc="x">system*</a></span>, and the <span class="RktVar">arg</span>s are the arguments. On
|
||
|
|
Windows, as for <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%2A%29%29" class="RktValLink" data-pltdoc="x">system*</a></span>, the first <span class="RktVar">arg</span> can be
|
||
|
|
replaced with <span class="RktVal">'</span><span class="RktVal">exact</span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._process/ports))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%2Fports%29%29" class="RktValDef RktValLink" data-pltdoc="x">process/ports</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">out</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">in</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">error-out</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">command</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">out</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._output-port~3f%29%29" class="RktValLink" data-pltdoc="x">output-port?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">in</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace">&nbs
|
||
|
|
process’s standard output, <span class="RktVar">in</span> is used for the process’s
|
||
|
|
standard input, and <span class="RktVar">error-out</span> is used for the process’s
|
||
|
|
standard error. Any of the ports can be <span class="RktVal">#f</span>, in which case a
|
||
|
|
system pipe is created and returned, as in <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%29%29" class="RktValLink" data-pltdoc="x">process</a></span>. If
|
||
|
|
<span class="RktVar">error-out</span> is <span class="RktVal">'</span><span class="RktVal">stdout</span>, then standard error is
|
||
|
|
redirected to standard output. For each port or <span class="RktVal">'</span><span class="RktVal">stdout</span> that
|
||
|
|
is provided, no pipe is created, and the corresponding value in the
|
||
|
|
returned list is <span class="RktVal">#f</span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._process*/ports))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%2A%2Fports%29%29" class="RktValDef RktValLink" data-pltdoc="x">process*/ports</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">out</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">in</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">error-out</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">command</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">arg</span><span class="hspace"> </span><span class="RktMeta">...</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:set-pwd?</span><span class="hspace"> </span><span class="RktVar">set-pwd?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">out</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._output-port~3f%29%29" class="RktValLink" data-pltdoc="x">output-port?</a></span><span class="RktPn">)</span></td></tr><
|
||
|
|
<span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._process%2Fports%29%29" class="RktValLink" data-pltdoc="x">process/ports</a></span>.</div></p><p>The contracts of <span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._system%29%29" class="RktValLink" data-pltdoc="x">system</a></span> and related functions may signal a
|
||
|
|
contract error with references to the following functions.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._string-no-nuls~3f))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._string-no-nuls~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">string-no-nuls?</a></span></span><span class="hspace"> </span><span class="RktVar">x</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">x</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Ensures that <span class="RktVar">x</span> is a string and does not contain <span class="RktVal">"\u0000"</span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/system..rkt)._bytes-no-nuls~3f))"></a><span title="Provided from: racket/system, racket | Package: base"><span class="RktSym"><a href="subprocess.html#%28def._%28%28lib._racket%2Fsystem..rkt%29._bytes-no-nuls~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">bytes-no-nuls?</a></span></span><span class="hspace"> </span><span class="RktVar">x</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">x</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Ensures that <span class="RktVar">x</span> is a byte-string and does not contain <span class="RktVal">#"\0"</span>.</div></p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" id="searchbox" type="text" tabindex="1" placeholder="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "8.6", "../");"/></form> <a href="https://docs.racket-lang.org/index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("8.6");">top</a><span class="tocsettoggle"> <a href="javascript:void(0);" title="show/hide table of contents" onclick="TocsetToggle();">contents</a></span></span><span class="navright"> <a href="udp.html" title="backward to "15.3.2 UDP"" data-pltdoc="x">← prev</a> <a href="os.html" title="up to "15 Operating System"" data-pltdoc="x">up</a> <a href="logging.html" title="forward to "15.5 Logging"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator
|