1586 lines
134 KiB
HTML
1586 lines
134 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="nodejs.org:node-version" content="v12.22.12">
|
|
<title>Child process | Node.js v12.22.12 Documentation</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
|
|
<link rel="stylesheet" href="assets/style.css">
|
|
<link rel="stylesheet" href="assets/hljs.css">
|
|
<link rel="canonical" href="https://nodejs.org/api/child_process.html">
|
|
</head>
|
|
<body class="alt apidoc" id="api-section-child_process">
|
|
<div id="content" class="clearfix">
|
|
<div id="column2" class="interior">
|
|
<div id="intro" class="interior">
|
|
<a href="/" title="Go back to the home page">
|
|
Node.js
|
|
</a>
|
|
</div>
|
|
<ul>
|
|
<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
|
|
<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
|
|
<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
|
|
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
|
|
<li><a href="addons.html" class="nav-addons">C++ Addons</a></li>
|
|
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons with N-API</a></li>
|
|
<li><a href="embedding.html" class="nav-embedding">C++ Embedder API</a></li>
|
|
<li><a href="child_process.html" class="nav-child_process active">Child Processes</a></li>
|
|
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
|
|
<li><a href="cli.html" class="nav-cli">Command line options</a></li>
|
|
<li><a href="console.html" class="nav-console">Console</a></li>
|
|
<li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
|
|
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
|
|
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
|
|
<li><a href="dns.html" class="nav-dns">DNS</a></li>
|
|
<li><a href="domain.html" class="nav-domain">Domain</a></li>
|
|
<li><a href="errors.html" class="nav-errors">Errors</a></li>
|
|
<li><a href="events.html" class="nav-events">Events</a></li>
|
|
<li><a href="fs.html" class="nav-fs">File system</a></li>
|
|
<li><a href="globals.html" class="nav-globals">Globals</a></li>
|
|
<li><a href="http.html" class="nav-http">HTTP</a></li>
|
|
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
|
|
<li><a href="https.html" class="nav-https">HTTPS</a></li>
|
|
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
|
|
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
|
|
<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
|
|
<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
|
|
<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li>
|
|
<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
|
|
<li><a href="net.html" class="nav-net">Net</a></li>
|
|
<li><a href="os.html" class="nav-os">OS</a></li>
|
|
<li><a href="path.html" class="nav-path">Path</a></li>
|
|
<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
|
|
<li><a href="policy.html" class="nav-policy">Policies</a></li>
|
|
<li><a href="process.html" class="nav-process">Process</a></li>
|
|
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
|
|
<li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
|
|
<li><a href="readline.html" class="nav-readline">Readline</a></li>
|
|
<li><a href="repl.html" class="nav-repl">REPL</a></li>
|
|
<li><a href="report.html" class="nav-report">Report</a></li>
|
|
<li><a href="stream.html" class="nav-stream">Stream</a></li>
|
|
<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
|
|
<li><a href="timers.html" class="nav-timers">Timers</a></li>
|
|
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
|
|
<li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
|
|
<li><a href="tty.html" class="nav-tty">TTY</a></li>
|
|
<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
|
|
<li><a href="url.html" class="nav-url">URL</a></li>
|
|
<li><a href="util.html" class="nav-util">Utilities</a></li>
|
|
<li><a href="v8.html" class="nav-v8">V8</a></li>
|
|
<li><a href="vm.html" class="nav-vm">VM</a></li>
|
|
<li><a href="wasi.html" class="nav-wasi">WASI</a></li>
|
|
<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
|
|
<li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
|
|
</ul>
|
|
<hr class="line">
|
|
<ul>
|
|
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="column1" data-id="child_process" class="interior">
|
|
<header>
|
|
<h1>Node.js v12.22.12 Documentation</h1>
|
|
<div id="gtoc">
|
|
<ul>
|
|
<li>
|
|
<a href="index.html">Index</a>
|
|
</li>
|
|
<li>
|
|
<a href="all.html">View on single page</a>
|
|
</li>
|
|
<li>
|
|
<a href="child_process.json">View as JSON</a>
|
|
</li>
|
|
|
|
<li class="version-picker">
|
|
<a href="#">View another version <span>▼</span></a>
|
|
<ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v17.x/api/child_process.html">17.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v16.x/api/child_process.html">16.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v15.x/api/child_process.html">15.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v14.x/api/child_process.html">14.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v13.x/api/child_process.html">13.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v12.x/api/child_process.html">12.x <b>LTS</b></a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v11.x/api/child_process.html">11.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v10.x/api/child_process.html">10.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v9.x/api/child_process.html">9.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v8.x/api/child_process.html">8.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v7.x/api/child_process.html">7.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v6.x/api/child_process.html">6.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v5.x/api/child_process.html">5.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v4.x/api/child_process.html">4.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/child_process.html">0.12.x</a></li>
|
|
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/child_process.html">0.10.x</a></li></ol>
|
|
</li>
|
|
|
|
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/child_process.md"><span class="github_icon"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg></span>Edit on GitHub</a></li>
|
|
</ul>
|
|
</div>
|
|
<hr>
|
|
</header>
|
|
|
|
<div id="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><span class="stability_2"><a href="#child_process_child_process">Child process</a></span>
|
|
<ul>
|
|
<li><a href="#child_process_asynchronous_process_creation">Asynchronous process creation</a>
|
|
<ul>
|
|
<li><a href="#child_process_spawning_bat_and_cmd_files_on_windows">Spawning <code>.bat</code> and <code>.cmd</code> files on Windows</a></li>
|
|
<li><a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec(command[, options][, callback])</code></a></li>
|
|
<li><a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile(file[, args][, options][, callback])</code></a></li>
|
|
<li><a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork(modulePath[, args][, options])</code></a></li>
|
|
<li><a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn(command[, args][, options])</code></a>
|
|
<ul>
|
|
<li><a href="#child_process_options_detached"><code>options.detached</code></a></li>
|
|
<li><a href="#child_process_options_stdio"><code>options.stdio</code></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#child_process_synchronous_process_creation">Synchronous process creation</a>
|
|
<ul>
|
|
<li><a href="#child_process_child_process_execfilesync_file_args_options"><code>child_process.execFileSync(file[, args][, options])</code></a></li>
|
|
<li><a href="#child_process_child_process_execsync_command_options"><code>child_process.execSync(command[, options])</code></a></li>
|
|
<li><a href="#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync(command[, args][, options])</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#child_process_class_childprocess">Class: <code>ChildProcess</code></a>
|
|
<ul>
|
|
<li><a href="#child_process_event_close">Event: <code>'close'</code></a></li>
|
|
<li><a href="#child_process_event_disconnect">Event: <code>'disconnect'</code></a></li>
|
|
<li><a href="#child_process_event_error">Event: <code>'error'</code></a></li>
|
|
<li><a href="#child_process_event_exit">Event: <code>'exit'</code></a></li>
|
|
<li><a href="#child_process_event_message">Event: <code>'message'</code></a></li>
|
|
<li><a href="#child_process_subprocess_channel"><code>subprocess.channel</code></a></li>
|
|
<li><a href="#child_process_subprocess_connected"><code>subprocess.connected</code></a></li>
|
|
<li><a href="#child_process_subprocess_disconnect"><code>subprocess.disconnect()</code></a></li>
|
|
<li><a href="#child_process_subprocess_exitcode"><code>subprocess.exitCode</code></a></li>
|
|
<li><a href="#child_process_subprocess_kill_signal"><code>subprocess.kill([signal])</code></a></li>
|
|
<li><a href="#child_process_subprocess_killed"><code>subprocess.killed</code></a></li>
|
|
<li><a href="#child_process_subprocess_pid"><code>subprocess.pid</code></a></li>
|
|
<li><a href="#child_process_subprocess_ref"><code>subprocess.ref()</code></a></li>
|
|
<li><a href="#child_process_subprocess_send_message_sendhandle_options_callback"><code>subprocess.send(message[, sendHandle[, options]][, callback])</code></a>
|
|
<ul>
|
|
<li><a href="#child_process_example_sending_a_server_object">Example: sending a server object</a></li>
|
|
<li><a href="#child_process_example_sending_a_socket_object">Example: sending a socket object</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#child_process_subprocess_signalcode"><code>subprocess.signalCode</code></a></li>
|
|
<li><a href="#child_process_subprocess_spawnargs"><code>subprocess.spawnargs</code></a></li>
|
|
<li><a href="#child_process_subprocess_spawnfile"><code>subprocess.spawnfile</code></a></li>
|
|
<li><a href="#child_process_subprocess_stderr"><code>subprocess.stderr</code></a></li>
|
|
<li><a href="#child_process_subprocess_stdin"><code>subprocess.stdin</code></a></li>
|
|
<li><a href="#child_process_subprocess_stdio"><code>subprocess.stdio</code></a></li>
|
|
<li><a href="#child_process_subprocess_stdout"><code>subprocess.stdout</code></a></li>
|
|
<li><a href="#child_process_subprocess_unref"><code>subprocess.unref()</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#child_process_maxbuffer_and_unicode"><code>maxBuffer</code> and Unicode</a></li>
|
|
<li><a href="#child_process_shell_requirements">Shell requirements</a></li>
|
|
<li><a href="#child_process_default_windows_shell">Default Windows shell</a></li>
|
|
<li><a href="#child_process_advanced_serialization">Advanced serialization</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="apicontent">
|
|
<h1>Child process<span><a class="mark" href="#child_process_child_process" id="child_process_child_process">#</a></span></h1>
|
|
|
|
<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p>
|
|
<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v12.22.12/lib/child_process.js">lib/child_process.js</a></p>
|
|
<p>The <code>child_process</code> module provides the ability to spawn child processes in
|
|
a manner that is similar, but not identical, to <a href="http://man7.org/linux/man-pages/man3/popen.3.html"><code>popen(3)</code></a>. This capability
|
|
is primarily provided by the <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> function:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> ls = spawn(<span class="hljs-string">'ls'</span>, [<span class="hljs-string">'-lh'</span>, <span class="hljs-string">'/usr'</span>]);
|
|
|
|
ls.stdout.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`stdout: <span class="hljs-subst">${data}</span>`</span>);
|
|
});
|
|
|
|
ls.stderr.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">`stderr: <span class="hljs-subst">${data}</span>`</span>);
|
|
});
|
|
|
|
ls.on(<span class="hljs-string">'close'</span>, <span class="hljs-function">(<span class="hljs-params">code</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`child process exited with code <span class="hljs-subst">${code}</span>`</span>);
|
|
});</code></pre>
|
|
<p>By default, pipes for <code>stdin</code>, <code>stdout</code>, and <code>stderr</code> are established between
|
|
the parent Node.js process and the spawned child. These pipes have
|
|
limited (and platform-specific) capacity. If the child process writes to
|
|
stdout in excess of that limit without the output being captured, the child
|
|
process will block waiting for the pipe buffer to accept more data. This is
|
|
identical to the behavior of pipes in the shell. Use the <code>{ stdio: 'ignore' }</code>
|
|
option if the output will not be consumed.</p>
|
|
<p>The command lookup will be performed using <code>options.env.PATH</code> environment
|
|
variable if passed in <code>options</code> object, otherwise <code>process.env.PATH</code> will be
|
|
used. To account for the fact that Windows environment variables are
|
|
case-insensitive Node.js will lexicographically sort all <code>env</code> keys and choose
|
|
the first one case-insensitively matching <code>PATH</code> to perform command lookup.
|
|
This may lead to issues on Windows when passing objects to <code>env</code> option that
|
|
have multiple variants of <code>PATH</code> variable.</p>
|
|
<p>The <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> method spawns the child process asynchronously,
|
|
without blocking the Node.js event loop. The <a href="#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a>
|
|
function provides equivalent functionality in a synchronous manner that blocks
|
|
the event loop until the spawned process either exits or is terminated.</p>
|
|
<p>For convenience, the <code>child_process</code> module provides a handful of synchronous
|
|
and asynchronous alternatives to <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> and
|
|
<a href="#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a>. Each of these alternatives are implemented on
|
|
top of <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> or <a href="#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a>.</p>
|
|
<ul>
|
|
<li><a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a>: spawns a shell and runs a command within that
|
|
shell, passing the <code>stdout</code> and <code>stderr</code> to a callback function when
|
|
complete.</li>
|
|
<li><a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a>: similar to <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> except
|
|
that it spawns the command directly without first spawning a shell by
|
|
default.</li>
|
|
<li><a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>: spawns a new Node.js process and invokes a
|
|
specified module with an IPC communication channel established that allows
|
|
sending messages between parent and child.</li>
|
|
<li><a href="#child_process_child_process_execsync_command_options"><code>child_process.execSync()</code></a>: a synchronous version of
|
|
<a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> that will block the Node.js event loop.</li>
|
|
<li><a href="#child_process_child_process_execfilesync_file_args_options"><code>child_process.execFileSync()</code></a>: a synchronous version of
|
|
<a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a> that will block the Node.js event loop.</li>
|
|
</ul>
|
|
<p>For certain use cases, such as automating shell scripts, the
|
|
<a href="#child_process_synchronous_process_creation">synchronous counterparts</a> may be more convenient. In many cases, however,
|
|
the synchronous methods can have significant impact on performance due to
|
|
stalling the event loop while spawned processes complete.</p>
|
|
<h2>Asynchronous process creation<span><a class="mark" href="#child_process_asynchronous_process_creation" id="child_process_asynchronous_process_creation">#</a></span></h2>
|
|
<p>The <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a>, <a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>, <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a>,
|
|
and <a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a> methods all follow the idiomatic asynchronous
|
|
programming pattern typical of other Node.js APIs.</p>
|
|
<p>Each of the methods returns a <a href="#child_process_child_process"><code>ChildProcess</code></a> instance. These objects
|
|
implement the Node.js <a href="events.html#events_class_eventemitter"><code>EventEmitter</code></a> API, allowing the parent process to
|
|
register listener functions that are called when certain events occur during
|
|
the life cycle of the child process.</p>
|
|
<p>The <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> and <a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a> methods
|
|
additionally allow for an optional <code>callback</code> function to be specified that is
|
|
invoked when the child process terminates.</p>
|
|
<h3>Spawning <code>.bat</code> and <code>.cmd</code> files on Windows<span><a class="mark" href="#child_process_spawning_bat_and_cmd_files_on_windows" id="child_process_spawning_bat_and_cmd_files_on_windows">#</a></span></h3>
|
|
<p>The importance of the distinction between <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> and
|
|
<a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a> can vary based on platform. On Unix-type
|
|
operating systems (Unix, Linux, macOS) <a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a> can be
|
|
more efficient because it does not spawn a shell by default. On Windows,
|
|
however, <code>.bat</code> and <code>.cmd</code> files are not executable on their own without a
|
|
terminal, and therefore cannot be launched using <a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a>.
|
|
When running on Windows, <code>.bat</code> and <code>.cmd</code> files can be invoked using
|
|
<a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> with the <code>shell</code> option set, with
|
|
<a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a>, or by spawning <code>cmd.exe</code> and passing the <code>.bat</code> or
|
|
<code>.cmd</code> file as an argument (which is what the <code>shell</code> option and
|
|
<a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> do). In any case, if the script filename contains
|
|
spaces it needs to be quoted.</p>
|
|
<pre><code class="language-js"><span class="hljs-comment">// On Windows Only...</span>
|
|
<span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> bat = spawn(<span class="hljs-string">'cmd.exe'</span>, [<span class="hljs-string">'/c'</span>, <span class="hljs-string">'my.bat'</span>]);
|
|
|
|
bat.stdout.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(data.toString());
|
|
});
|
|
|
|
bat.stderr.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(data.toString());
|
|
});
|
|
|
|
bat.on(<span class="hljs-string">'exit'</span>, <span class="hljs-function">(<span class="hljs-params">code</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Child exited with code <span class="hljs-subst">${code}</span>`</span>);
|
|
});</code></pre>
|
|
<pre><code class="language-js"><span class="hljs-comment">// OR...</span>
|
|
<span class="hljs-keyword">const</span> { exec, spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
exec(<span class="hljs-string">'my.bat'</span>, <span class="hljs-function">(<span class="hljs-params">err, stdout, stderr</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (err) {
|
|
<span class="hljs-built_in">console</span>.error(err);
|
|
<span class="hljs-keyword">return</span>;
|
|
}
|
|
<span class="hljs-built_in">console</span>.log(stdout);
|
|
});
|
|
|
|
<span class="hljs-comment">// Script with spaces in the filename:</span>
|
|
<span class="hljs-keyword">const</span> bat = spawn(<span class="hljs-string">'"my script.cmd"'</span>, [<span class="hljs-string">'a'</span>, <span class="hljs-string">'b'</span>], { <span class="hljs-attr">shell</span>: <span class="hljs-literal">true</span> });
|
|
<span class="hljs-comment">// or:</span>
|
|
exec(<span class="hljs-string">'"my script.cmd" a b'</span>, <span class="hljs-function">(<span class="hljs-params">err, stdout, stderr</span>) =></span> {
|
|
<span class="hljs-comment">// ...</span>
|
|
});</code></pre>
|
|
<h3><code>child_process.exec(command[, options][, callback])</code><span><a class="mark" href="#child_process_child_process_exec_command_options_callback" id="child_process_child_process_exec_command_options_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v8.8.0</td>
|
|
<td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
|
|
<tr><td>v0.1.90</td>
|
|
<td><p><span>Added in: v0.1.90</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The command to run, with space-separated arguments.</li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Current working directory of the child process.
|
|
<strong>Default:</strong> <code>null</code>.</li>
|
|
<li><code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Environment key-value pairs. <strong>Default:</strong> <code>process.env</code>.</li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
|
<li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Shell to execute the command with. See
|
|
<a href="#child_process_shell_requirements">Shell requirements</a> and <a href="#child_process_default_windows_shell">Default Windows shell</a>. <strong>Default:</strong>
|
|
<code>'/bin/sh'</code> on Unix, <code>process.env.ComSpec</code> on Windows.</li>
|
|
<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>0</code></li>
|
|
<li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Largest amount of data in bytes allowed on stdout or
|
|
stderr. If exceeded, the child process is terminated and any output is
|
|
truncated. See caveat at <a href="#child_process_maxbuffer_and_unicode"><code>maxBuffer</code> and Unicode</a>.
|
|
<strong>Default:</strong> <code>1024 * 1024</code>.</li>
|
|
<li><code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>'SIGTERM'</code></li>
|
|
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the user identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setuid.2.html"><code>setuid(2)</code></a>).</li>
|
|
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the group identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setgid.2.html"><code>setgid(2)</code></a>).</li>
|
|
<li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Hide the subprocess console window that would
|
|
normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> called with the output when process terminates.
|
|
<ul>
|
|
<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
<li><code>stdout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
<li><code>stderr</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="child_process.html#child_process_class_childprocess" class="type"><ChildProcess></a></li>
|
|
</ul>
|
|
<p>Spawns a shell then executes the <code>command</code> within that shell, buffering any
|
|
generated output. The <code>command</code> string passed to the exec function is processed
|
|
directly by the shell and special characters (vary based on
|
|
<a href="https://en.wikipedia.org/wiki/List_of_command-line_interpreters">shell</a>)
|
|
need to be dealt with accordingly:</p>
|
|
<pre><code class="language-js">exec(<span class="hljs-string">'"/path/to/test file/test.sh" arg1 arg2'</span>);
|
|
<span class="hljs-comment">// Double quotes are used so that the space in the path is not interpreted as</span>
|
|
<span class="hljs-comment">// a delimiter of multiple arguments.</span>
|
|
|
|
exec(<span class="hljs-string">'echo "The \\$HOME variable is $HOME"'</span>);
|
|
<span class="hljs-comment">// The $HOME variable is escaped in the first instance, but not in the second.</span></code></pre>
|
|
<p><strong>Never pass unsanitized user input to this function. Any input containing shell
|
|
metacharacters may be used to trigger arbitrary command execution.</strong></p>
|
|
<p>If a <code>callback</code> function is provided, it is called with the arguments
|
|
<code>(error, stdout, stderr)</code>. On success, <code>error</code> will be <code>null</code>. On error,
|
|
<code>error</code> will be an instance of <a href="errors.html#errors_class_error"><code>Error</code></a>. The <code>error.code</code> property will be
|
|
the exit code of the process. By convention, any exit code other than <code>0</code>
|
|
indicates an error. <code>error.signal</code> will be the signal that terminated the
|
|
process.</p>
|
|
<p>The <code>stdout</code> and <code>stderr</code> arguments passed to the callback will contain the
|
|
stdout and stderr output of the child process. By default, Node.js will decode
|
|
the output as UTF-8 and pass strings to the callback. The <code>encoding</code> option
|
|
can be used to specify the character encoding used to decode the stdout and
|
|
stderr output. If <code>encoding</code> is <code>'buffer'</code>, or an unrecognized character
|
|
encoding, <code>Buffer</code> objects will be passed to the callback instead.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { exec } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
exec(<span class="hljs-string">'cat *.js missing_file | wc -l'</span>, <span class="hljs-function">(<span class="hljs-params">error, stdout, stderr</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (error) {
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">`exec error: <span class="hljs-subst">${error}</span>`</span>);
|
|
<span class="hljs-keyword">return</span>;
|
|
}
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`stdout: <span class="hljs-subst">${stdout}</span>`</span>);
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">`stderr: <span class="hljs-subst">${stderr}</span>`</span>);
|
|
});</code></pre>
|
|
<p>If <code>timeout</code> is greater than <code>0</code>, the parent will send the signal
|
|
identified by the <code>killSignal</code> property (the default is <code>'SIGTERM'</code>) if the
|
|
child runs longer than <code>timeout</code> milliseconds.</p>
|
|
<p>Unlike the <a href="http://man7.org/linux/man-pages/man3/exec.3.html"><code>exec(3)</code></a> POSIX system call, <code>child_process.exec()</code> does not replace
|
|
the existing process and uses a shell to execute the command.</p>
|
|
<p>If this method is invoked as its <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed version, it returns
|
|
a <code>Promise</code> for an <code>Object</code> with <code>stdout</code> and <code>stderr</code> properties. The returned
|
|
<code>ChildProcess</code> instance is attached to the <code>Promise</code> as a <code>child</code> property. In
|
|
case of an error (including any error resulting in an exit code other than 0), a
|
|
rejected promise is returned, with the same <code>error</code> object given in the
|
|
callback, but with two additional properties <code>stdout</code> and <code>stderr</code>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> util = <span class="hljs-built_in">require</span>(<span class="hljs-string">'util'</span>);
|
|
<span class="hljs-keyword">const</span> exec = util.promisify(<span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>).exec);
|
|
|
|
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">lsExample</span>(<span class="hljs-params"></span>) </span>{
|
|
<span class="hljs-keyword">const</span> { stdout, stderr } = <span class="hljs-keyword">await</span> exec(<span class="hljs-string">'ls'</span>);
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'stdout:'</span>, stdout);
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'stderr:'</span>, stderr);
|
|
}
|
|
lsExample();</code></pre>
|
|
<h3><code>child_process.execFile(file[, args][, options][, callback])</code><span><a class="mark" href="#child_process_child_process_execfile_file_args_options_callback" id="child_process_child_process_execfile_file_args_options_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v8.8.0</td>
|
|
<td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
|
|
<tr><td>v0.1.91</td>
|
|
<td><p><span>Added in: v0.1.91</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The name or path of the executable file to run.</li>
|
|
<li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> List of string arguments.</li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Current working directory of the child process.</li>
|
|
<li><code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Environment key-value pairs. <strong>Default:</strong> <code>process.env</code>.</li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
|
<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>0</code></li>
|
|
<li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Largest amount of data in bytes allowed on stdout or
|
|
stderr. If exceeded, the child process is terminated and any output is
|
|
truncated. See caveat at <a href="#child_process_maxbuffer_and_unicode"><code>maxBuffer</code> and Unicode</a>.
|
|
<strong>Default:</strong> <code>1024 * 1024</code>.</li>
|
|
<li><code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>'SIGTERM'</code></li>
|
|
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the user identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setuid.2.html"><code>setuid(2)</code></a>).</li>
|
|
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the group identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setgid.2.html"><code>setgid(2)</code></a>).</li>
|
|
<li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Hide the subprocess console window that would
|
|
normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> No quoting or escaping of arguments is
|
|
done on Windows. Ignored on Unix. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If <code>true</code>, runs <code>command</code> inside of a shell. Uses
|
|
<code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
|
|
shell can be specified as a string. See <a href="#child_process_shell_requirements">Shell requirements</a> and
|
|
<a href="#child_process_default_windows_shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</code> (no shell).</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Called with the output when process terminates.
|
|
<ul>
|
|
<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
|
<li><code>stdout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
<li><code>stderr</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="child_process.html#child_process_class_childprocess" class="type"><ChildProcess></a></li>
|
|
</ul>
|
|
<p>The <code>child_process.execFile()</code> function is similar to <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a>
|
|
except that it does not spawn a shell by default. Rather, the specified
|
|
executable <code>file</code> is spawned directly as a new process making it slightly more
|
|
efficient than <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a>.</p>
|
|
<p>The same options as <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> are supported. Since a shell is
|
|
not spawned, behaviors such as I/O redirection and file globbing are not
|
|
supported.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { execFile } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> child = execFile(<span class="hljs-string">'node'</span>, [<span class="hljs-string">'--version'</span>], <span class="hljs-function">(<span class="hljs-params">error, stdout, stderr</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (error) {
|
|
<span class="hljs-keyword">throw</span> error;
|
|
}
|
|
<span class="hljs-built_in">console</span>.log(stdout);
|
|
});</code></pre>
|
|
<p>The <code>stdout</code> and <code>stderr</code> arguments passed to the callback will contain the
|
|
stdout and stderr output of the child process. By default, Node.js will decode
|
|
the output as UTF-8 and pass strings to the callback. The <code>encoding</code> option
|
|
can be used to specify the character encoding used to decode the stdout and
|
|
stderr output. If <code>encoding</code> is <code>'buffer'</code>, or an unrecognized character
|
|
encoding, <code>Buffer</code> objects will be passed to the callback instead.</p>
|
|
<p>If this method is invoked as its <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed version, it returns
|
|
a <code>Promise</code> for an <code>Object</code> with <code>stdout</code> and <code>stderr</code> properties. The returned
|
|
<code>ChildProcess</code> instance is attached to the <code>Promise</code> as a <code>child</code> property. In
|
|
case of an error (including any error resulting in an exit code other than 0), a
|
|
rejected promise is returned, with the same <code>error</code> object given in the
|
|
callback, but with two additional properties <code>stdout</code> and <code>stderr</code>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> util = <span class="hljs-built_in">require</span>(<span class="hljs-string">'util'</span>);
|
|
<span class="hljs-keyword">const</span> execFile = util.promisify(<span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>).execFile);
|
|
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">getVersion</span>(<span class="hljs-params"></span>) </span>{
|
|
<span class="hljs-keyword">const</span> { stdout } = <span class="hljs-keyword">await</span> execFile(<span class="hljs-string">'node'</span>, [<span class="hljs-string">'--version'</span>]);
|
|
<span class="hljs-built_in">console</span>.log(stdout);
|
|
}
|
|
getVersion();</code></pre>
|
|
<p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
|
|
function. Any input containing shell metacharacters may be used to trigger
|
|
arbitrary command execution.</strong></p>
|
|
<h3><code>child_process.fork(modulePath[, args][, options])</code><span><a class="mark" href="#child_process_child_process_fork_modulepath_args_options" id="child_process_child_process_fork_modulepath_args_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.16.0</td>
|
|
<td><p>The <code>serialization</code> option is supported now.</p></td></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>The <code>stdio</code> option can now be a string.</p></td></tr>
|
|
<tr><td>v6.4.0</td>
|
|
<td><p>The <code>stdio</code> option is supported now.</p></td></tr>
|
|
<tr><td>v0.5.0</td>
|
|
<td><p><span>Added in: v0.5.0</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>modulePath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The module to run in the child.</li>
|
|
<li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> List of string arguments.</li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Current working directory of the child process.</li>
|
|
<li><code>detached</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Prepare child to run independently of its parent
|
|
process. Specific behavior depends on the platform, see
|
|
<a href="#child_process_options_detached"><code>options.detached</code></a>).</li>
|
|
<li><code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Environment key-value pairs. <strong>Default:</strong> <code>process.env</code>.</li>
|
|
<li><code>execPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Executable used to create the child process.</li>
|
|
<li><code>execArgv</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> List of string arguments passed to the executable.
|
|
<strong>Default:</strong> <code>process.execArgv</code>.</li>
|
|
<li><code>serialization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Specify the kind of serialization used for sending
|
|
messages between processes. Possible values are <code>'json'</code> and <code>'advanced'</code>.
|
|
See <a href="#child_process_advanced_serialization">Advanced serialization</a> for more details. <strong>Default:</strong> <code>'json'</code>.</li>
|
|
<li><code>silent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, stdin, stdout, and stderr of the child will be
|
|
piped to the parent, otherwise they will be inherited from the parent, see
|
|
the <code>'pipe'</code> and <code>'inherit'</code> options for <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a>'s
|
|
<a href="#child_process_options_stdio"><code>stdio</code></a> for more details. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a>'s <a href="#child_process_options_stdio"><code>stdio</code></a>.
|
|
When this option is provided, it overrides <code>silent</code>. If the array variant
|
|
is used, it must contain exactly one item with value <code>'ipc'</code> or an error
|
|
will be thrown. For instance <code>[0, 1, 2, 'ipc']</code>.</li>
|
|
<li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> No quoting or escaping of arguments is
|
|
done on Windows. Ignored on Unix. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the user identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setuid.2.html"><code>setuid(2)</code></a>).</li>
|
|
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the group identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setgid.2.html"><code>setgid(2)</code></a>).</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="child_process.html#child_process_class_childprocess" class="type"><ChildProcess></a></li>
|
|
</ul>
|
|
<p>The <code>child_process.fork()</code> method is a special case of
|
|
<a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> used specifically to spawn new Node.js processes.
|
|
Like <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a>, a <a href="#child_process_child_process"><code>ChildProcess</code></a> object is returned. The
|
|
returned <a href="#child_process_child_process"><code>ChildProcess</code></a> will have an additional communication channel
|
|
built-in that allows messages to be passed back and forth between the parent and
|
|
child. See <a href="#child_process_subprocess_send_message_sendhandle_options_callback"><code>subprocess.send()</code></a> for details.</p>
|
|
<p>Keep in mind that spawned Node.js child processes are
|
|
independent of the parent with exception of the IPC communication channel
|
|
that is established between the two. Each process has its own memory, with
|
|
their own V8 instances. Because of the additional resource allocations
|
|
required, spawning a large number of child Node.js processes is not
|
|
recommended.</p>
|
|
<p>By default, <code>child_process.fork()</code> will spawn new Node.js instances using the
|
|
<a href="process.html#process_process_execpath"><code>process.execPath</code></a> of the parent process. The <code>execPath</code> property in the
|
|
<code>options</code> object allows for an alternative execution path to be used.</p>
|
|
<p>Node.js processes launched with a custom <code>execPath</code> will communicate with the
|
|
parent process using the file descriptor (fd) identified using the
|
|
environment variable <code>NODE_CHANNEL_FD</code> on the child process.</p>
|
|
<p>Unlike the <a href="http://man7.org/linux/man-pages/man2/fork.2.html"><code>fork(2)</code></a> POSIX system call, <code>child_process.fork()</code> does not clone the
|
|
current process.</p>
|
|
<p>The <code>shell</code> option available in <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> is not supported by
|
|
<code>child_process.fork()</code> and will be ignored if set.</p>
|
|
<h3><code>child_process.spawn(command[, args][, options])</code><span><a class="mark" href="#child_process_child_process_spawn_command_args_options" id="child_process_child_process_spawn_command_args_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v12.16.0</td>
|
|
<td><p>The <code>serialization</code> option is supported now.</p></td></tr>
|
|
<tr><td>v8.8.0</td>
|
|
<td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
|
|
<tr><td>v6.4.0</td>
|
|
<td><p>The <code>argv0</code> option is supported now.</p></td></tr>
|
|
<tr><td>v5.7.0</td>
|
|
<td><p>The <code>shell</code> option is supported now.</p></td></tr>
|
|
<tr><td>v0.1.90</td>
|
|
<td><p><span>Added in: v0.1.90</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The command to run.</li>
|
|
<li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> List of string arguments.</li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Current working directory of the child process.</li>
|
|
<li><code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Environment key-value pairs. <strong>Default:</strong> <code>process.env</code>.</li>
|
|
<li><code>argv0</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Explicitly set the value of <code>argv[0]</code> sent to the child
|
|
process. This will be set to <code>command</code> if not specified.</li>
|
|
<li><code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Child's stdio configuration (see
|
|
<a href="#child_process_options_stdio"><code>options.stdio</code></a>).</li>
|
|
<li><code>detached</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Prepare child to run independently of its parent
|
|
process. Specific behavior depends on the platform, see
|
|
<a href="#child_process_options_detached"><code>options.detached</code></a>).</li>
|
|
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the user identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setuid.2.html"><code>setuid(2)</code></a>).</li>
|
|
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the group identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setgid.2.html"><code>setgid(2)</code></a>).</li>
|
|
<li><code>serialization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Specify the kind of serialization used for sending
|
|
messages between processes. Possible values are <code>'json'</code> and <code>'advanced'</code>.
|
|
See <a href="#child_process_advanced_serialization">Advanced serialization</a> for more details. <strong>Default:</strong> <code>'json'</code>.</li>
|
|
<li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If <code>true</code>, runs <code>command</code> inside of a shell. Uses
|
|
<code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
|
|
shell can be specified as a string. See <a href="#child_process_shell_requirements">Shell requirements</a> and
|
|
<a href="#child_process_default_windows_shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</code> (no shell).</li>
|
|
<li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> No quoting or escaping of arguments is
|
|
done on Windows. Ignored on Unix. This is set to <code>true</code> automatically
|
|
when <code>shell</code> is specified and is CMD. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Hide the subprocess console window that would
|
|
normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="child_process.html#child_process_class_childprocess" class="type"><ChildProcess></a></li>
|
|
</ul>
|
|
<p>The <code>child_process.spawn()</code> method spawns a new process using the given
|
|
<code>command</code>, with command line arguments in <code>args</code>. If omitted, <code>args</code> defaults
|
|
to an empty array.</p>
|
|
<p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
|
|
function. Any input containing shell metacharacters may be used to trigger
|
|
arbitrary command execution.</strong></p>
|
|
<p>A third argument may be used to specify additional options, with these defaults:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> defaults = {
|
|
<span class="hljs-attr">cwd</span>: <span class="hljs-literal">undefined</span>,
|
|
<span class="hljs-attr">env</span>: process.env
|
|
};</code></pre>
|
|
<p>Use <code>cwd</code> to specify the working directory from which the process is spawned.
|
|
If not given, the default is to inherit the current working directory.</p>
|
|
<p>Use <code>env</code> to specify environment variables that will be visible to the new
|
|
process, the default is <a href="process.html#process_process_env"><code>process.env</code></a>.</p>
|
|
<p><code>undefined</code> values in <code>env</code> will be ignored.</p>
|
|
<p>Example of running <code>ls -lh /usr</code>, capturing <code>stdout</code>, <code>stderr</code>, and the
|
|
exit code:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> ls = spawn(<span class="hljs-string">'ls'</span>, [<span class="hljs-string">'-lh'</span>, <span class="hljs-string">'/usr'</span>]);
|
|
|
|
ls.stdout.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`stdout: <span class="hljs-subst">${data}</span>`</span>);
|
|
});
|
|
|
|
ls.stderr.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">`stderr: <span class="hljs-subst">${data}</span>`</span>);
|
|
});
|
|
|
|
ls.on(<span class="hljs-string">'close'</span>, <span class="hljs-function">(<span class="hljs-params">code</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`child process exited with code <span class="hljs-subst">${code}</span>`</span>);
|
|
});</code></pre>
|
|
<p>Example: A very elaborate way to run <code>ps ax | grep ssh</code></p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> ps = spawn(<span class="hljs-string">'ps'</span>, [<span class="hljs-string">'ax'</span>]);
|
|
<span class="hljs-keyword">const</span> grep = spawn(<span class="hljs-string">'grep'</span>, [<span class="hljs-string">'ssh'</span>]);
|
|
|
|
ps.stdout.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
grep.stdin.write(data);
|
|
});
|
|
|
|
ps.stderr.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">`ps stderr: <span class="hljs-subst">${data}</span>`</span>);
|
|
});
|
|
|
|
ps.on(<span class="hljs-string">'close'</span>, <span class="hljs-function">(<span class="hljs-params">code</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (code !== <span class="hljs-number">0</span>) {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`ps process exited with code <span class="hljs-subst">${code}</span>`</span>);
|
|
}
|
|
grep.stdin.end();
|
|
});
|
|
|
|
grep.stdout.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(data.toString());
|
|
});
|
|
|
|
grep.stderr.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">`grep stderr: <span class="hljs-subst">${data}</span>`</span>);
|
|
});
|
|
|
|
grep.on(<span class="hljs-string">'close'</span>, <span class="hljs-function">(<span class="hljs-params">code</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (code !== <span class="hljs-number">0</span>) {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`grep process exited with code <span class="hljs-subst">${code}</span>`</span>);
|
|
}
|
|
});</code></pre>
|
|
<p>Example of checking for failed <code>spawn</code>:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> subprocess = spawn(<span class="hljs-string">'bad_command'</span>);
|
|
|
|
subprocess.on(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'Failed to start subprocess.'</span>);
|
|
});</code></pre>
|
|
<p>Certain platforms (macOS, Linux) will use the value of <code>argv[0]</code> for the process
|
|
title while others (Windows, SunOS) will use <code>command</code>.</p>
|
|
<p>Node.js currently overwrites <code>argv[0]</code> with <code>process.execPath</code> on startup, so
|
|
<code>process.argv[0]</code> in a Node.js child process will not match the <code>argv0</code>
|
|
parameter passed to <code>spawn</code> from the parent, retrieve it with the
|
|
<code>process.argv0</code> property instead.</p>
|
|
<h4><code>options.detached</code><span><a class="mark" href="#child_process_options_detached" id="child_process_options_detached">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.10</span>
|
|
</div>
|
|
<p>On Windows, setting <code>options.detached</code> to <code>true</code> makes it possible for the
|
|
child process to continue running after the parent exits. The child will have
|
|
its own console window. Once enabled for a child process, it cannot be
|
|
disabled.</p>
|
|
<p>On non-Windows platforms, if <code>options.detached</code> is set to <code>true</code>, the child
|
|
process will be made the leader of a new process group and session. Child
|
|
processes may continue running after the parent exits regardless of whether
|
|
they are detached or not. See <a href="http://man7.org/linux/man-pages/man2/setsid.2.html"><code>setsid(2)</code></a> for more information.</p>
|
|
<p>By default, the parent will wait for the detached child to exit. To prevent the
|
|
parent from waiting for a given <code>subprocess</code> to exit, use the
|
|
<code>subprocess.unref()</code> method. Doing so will cause the parent's event loop to not
|
|
include the child in its reference count, allowing the parent to exit
|
|
independently of the child, unless there is an established IPC channel between
|
|
the child and the parent.</p>
|
|
<p>When using the <code>detached</code> option to start a long-running process, the process
|
|
will not stay running in the background after the parent exits unless it is
|
|
provided with a <code>stdio</code> configuration that is not connected to the parent.
|
|
If the parent's <code>stdio</code> is inherited, the child will remain attached to the
|
|
controlling terminal.</p>
|
|
<p>Example of a long-running process, by detaching and also ignoring its parent
|
|
<code>stdio</code> file descriptors, in order to ignore the parent's termination:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> subprocess = spawn(process.argv[<span class="hljs-number">0</span>], [<span class="hljs-string">'child_program.js'</span>], {
|
|
<span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
|
|
<span class="hljs-attr">stdio</span>: <span class="hljs-string">'ignore'</span>
|
|
});
|
|
|
|
subprocess.unref();</code></pre>
|
|
<p>Alternatively one can redirect the child process' output into files:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
<span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> out = fs.openSync(<span class="hljs-string">'./out.log'</span>, <span class="hljs-string">'a'</span>);
|
|
<span class="hljs-keyword">const</span> err = fs.openSync(<span class="hljs-string">'./out.log'</span>, <span class="hljs-string">'a'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> subprocess = spawn(<span class="hljs-string">'prg'</span>, [], {
|
|
<span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
|
|
<span class="hljs-attr">stdio</span>: [ <span class="hljs-string">'ignore'</span>, out, err ]
|
|
});
|
|
|
|
subprocess.unref();</code></pre>
|
|
<h4><code>options.stdio</code><span><a class="mark" href="#child_process_options_stdio" id="child_process_options_stdio">#</a></span></h4>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v3.3.1</td>
|
|
<td><p>The value <code>0</code> is now accepted as a file descriptor.</p></td></tr>
|
|
<tr><td>v0.7.10</td>
|
|
<td><p><span>Added in: v0.7.10</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<p>The <code>options.stdio</code> option is used to configure the pipes that are established
|
|
between the parent and child process. By default, the child's stdin, stdout,
|
|
and stderr are redirected to corresponding <a href="#child_process_subprocess_stdin"><code>subprocess.stdin</code></a>,
|
|
<a href="#child_process_subprocess_stdout"><code>subprocess.stdout</code></a>, and <a href="#child_process_subprocess_stderr"><code>subprocess.stderr</code></a> streams on the
|
|
<a href="#child_process_child_process"><code>ChildProcess</code></a> object. This is equivalent to setting the <code>options.stdio</code>
|
|
equal to <code>['pipe', 'pipe', 'pipe']</code>.</p>
|
|
<p>For convenience, <code>options.stdio</code> may be one of the following strings:</p>
|
|
<ul>
|
|
<li><code>'pipe'</code>: equivalent to <code>['pipe', 'pipe', 'pipe']</code> (the default)</li>
|
|
<li><code>'ignore'</code>: equivalent to <code>['ignore', 'ignore', 'ignore']</code></li>
|
|
<li><code>'inherit'</code>: equivalent to <code>['inherit', 'inherit', 'inherit']</code> or <code>[0, 1, 2]</code></li>
|
|
</ul>
|
|
<p>Otherwise, the value of <code>options.stdio</code> is an array where each index corresponds
|
|
to an fd in the child. The fds 0, 1, and 2 correspond to stdin, stdout,
|
|
and stderr, respectively. Additional fds can be specified to create additional
|
|
pipes between the parent and child. The value is one of the following:</p>
|
|
<ol>
|
|
<li>
|
|
<p><code>'pipe'</code>: Create a pipe between the child process and the parent process.
|
|
The parent end of the pipe is exposed to the parent as a property on the
|
|
<code>child_process</code> object as <a href="#child_process_subprocess_stdio"><code>subprocess.stdio[fd]</code></a>. Pipes
|
|
created for fds 0, 1, and 2 are also available as <a href="#child_process_subprocess_stdin"><code>subprocess.stdin</code></a>,
|
|
<a href="#child_process_subprocess_stdout"><code>subprocess.stdout</code></a> and <a href="#child_process_subprocess_stderr"><code>subprocess.stderr</code></a>, respectively.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>'ipc'</code>: Create an IPC channel for passing messages/file descriptors
|
|
between parent and child. A <a href="#child_process_child_process"><code>ChildProcess</code></a> may have at most one IPC
|
|
stdio file descriptor. Setting this option enables the
|
|
<a href="#child_process_subprocess_send_message_sendhandle_options_callback"><code>subprocess.send()</code></a> method. If the child is a Node.js process, the
|
|
presence of an IPC channel will enable <a href="process.html#process_process_send_message_sendhandle_options_callback"><code>process.send()</code></a> and
|
|
<a href="process.html#process_process_disconnect"><code>process.disconnect()</code></a> methods, as well as <a href="process.html#process_event_disconnect"><code>'disconnect'</code></a> and
|
|
<a href="process.html#process_event_message"><code>'message'</code></a> events within the child.</p>
|
|
<p>Accessing the IPC channel fd in any way other than <a href="process.html#process_process_send_message_sendhandle_options_callback"><code>process.send()</code></a>
|
|
or using the IPC channel with a child process that is not a Node.js instance
|
|
is not supported.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>'ignore'</code>: Instructs Node.js to ignore the fd in the child. While Node.js
|
|
will always open fds 0, 1, and 2 for the processes it spawns, setting the fd
|
|
to <code>'ignore'</code> will cause Node.js to open <code>/dev/null</code> and attach it to the
|
|
child's fd.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>'inherit'</code>: Pass through the corresponding stdio stream to/from the
|
|
parent process. In the first three positions, this is equivalent to
|
|
<code>process.stdin</code>, <code>process.stdout</code>, and <code>process.stderr</code>, respectively. In
|
|
any other position, equivalent to <code>'ignore'</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><a href="stream.html#stream_stream" class="type"><Stream></a> object: Share a readable or writable stream that refers to a tty,
|
|
file, socket, or a pipe with the child process. The stream's underlying
|
|
file descriptor is duplicated in the child process to the fd that
|
|
corresponds to the index in the <code>stdio</code> array. The stream must have an
|
|
underlying descriptor (file streams do not until the <code>'open'</code> event has
|
|
occurred).</p>
|
|
</li>
|
|
<li>
|
|
<p>Positive integer: The integer value is interpreted as a file descriptor
|
|
that is currently open in the parent process. It is shared with the child
|
|
process, similar to how <a href="stream.html#stream_stream" class="type"><Stream></a> objects can be shared. Passing sockets
|
|
is not supported on Windows.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>null</code>, <code>undefined</code>: Use default value. For stdio fds 0, 1, and 2 (in other
|
|
words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
|
|
default is <code>'ignore'</code>.</p>
|
|
</li>
|
|
</ol>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
<span class="hljs-comment">// Child will use parent's stdios.</span>
|
|
spawn(<span class="hljs-string">'prg'</span>, [], { <span class="hljs-attr">stdio</span>: <span class="hljs-string">'inherit'</span> });
|
|
|
|
<span class="hljs-comment">// Spawn child sharing only stderr.</span>
|
|
spawn(<span class="hljs-string">'prg'</span>, [], { <span class="hljs-attr">stdio</span>: [<span class="hljs-string">'pipe'</span>, <span class="hljs-string">'pipe'</span>, process.stderr] });
|
|
|
|
<span class="hljs-comment">// Open an extra fd=4, to interact with programs presenting a</span>
|
|
<span class="hljs-comment">// startd-style interface.</span>
|
|
spawn(<span class="hljs-string">'prg'</span>, [], { <span class="hljs-attr">stdio</span>: [<span class="hljs-string">'pipe'</span>, <span class="hljs-literal">null</span>, <span class="hljs-literal">null</span>, <span class="hljs-literal">null</span>, <span class="hljs-string">'pipe'</span>] });</code></pre>
|
|
<p><em>It is worth noting that when an IPC channel is established between the
|
|
parent and child processes, and the child is a Node.js process, the child
|
|
is launched with the IPC channel unreferenced (using <code>unref()</code>) until the
|
|
child registers an event handler for the <a href="process.html#process_event_disconnect"><code>'disconnect'</code></a> event
|
|
or the <a href="process.html#process_event_message"><code>'message'</code></a> event. This allows the child to exit
|
|
normally without the process being held open by the open IPC channel.</em></p>
|
|
<p>On Unix-like operating systems, the <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> method
|
|
performs memory operations synchronously before decoupling the event loop
|
|
from the child. Applications with a large memory footprint may find frequent
|
|
<a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> calls to be a bottleneck. For more information,
|
|
see <a href="https://bugs.chromium.org/p/v8/issues/detail?id=7381">V8 issue 7381</a>.</p>
|
|
<p>See also: <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> and <a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>.</p>
|
|
<h2>Synchronous process creation<span><a class="mark" href="#child_process_synchronous_process_creation" id="child_process_synchronous_process_creation">#</a></span></h2>
|
|
<p>The <a href="#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a>, <a href="#child_process_child_process_execsync_command_options"><code>child_process.execSync()</code></a>, and
|
|
<a href="#child_process_child_process_execfilesync_file_args_options"><code>child_process.execFileSync()</code></a> methods are synchronous and will block the
|
|
Node.js event loop, pausing execution of any additional code until the spawned
|
|
process exits.</p>
|
|
<p>Blocking calls like these are mostly useful for simplifying general-purpose
|
|
scripting tasks and for simplifying the loading/processing of application
|
|
configuration at startup.</p>
|
|
<h3><code>child_process.execFileSync(file[, args][, options])</code><span><a class="mark" href="#child_process_child_process_execfilesync_file_args_options" id="child_process_child_process_execfilesync_file_args_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.10.0</td>
|
|
<td><p>The <code>input</code> option can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr>
|
|
<tr><td>v8.8.0</td>
|
|
<td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>The <code>input</code> option can now be a <code>Uint8Array</code>.</p></td></tr>
|
|
<tr><td>v6.2.1, v4.5.0</td>
|
|
<td><p>The <code>encoding</code> option can now explicitly be set to <code>buffer</code>.</p></td></tr>
|
|
<tr><td>v0.11.12</td>
|
|
<td><p><span>Added in: v0.11.12</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The name or path of the executable file to run.</li>
|
|
<li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> List of string arguments.</li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Current working directory of the child process.</li>
|
|
<li><code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> The value which will be passed
|
|
as stdin to the spawned process. Supplying this value will override
|
|
<code>stdio[0]</code>.</li>
|
|
<li><code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> Child's stdio configuration. <code>stderr</code> by default will
|
|
be output to the parent process' stderr unless <code>stdio</code> is specified.
|
|
<strong>Default:</strong> <code>'pipe'</code>.</li>
|
|
<li><code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Environment key-value pairs. <strong>Default:</strong> <code>process.env</code>.</li>
|
|
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the user identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setuid.2.html"><code>setuid(2)</code></a>).</li>
|
|
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the group identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setgid.2.html"><code>setgid(2)</code></a>).</li>
|
|
<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> In milliseconds the maximum amount of time the process
|
|
is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
|
|
<li><code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The signal value to be used when the spawned
|
|
process will be killed. <strong>Default:</strong> <code>'SIGTERM'</code>.</li>
|
|
<li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Largest amount of data in bytes allowed on stdout or
|
|
stderr. If exceeded, the child process is terminated. See caveat at
|
|
<a href="#child_process_maxbuffer_and_unicode"><code>maxBuffer</code> and Unicode</a>. <strong>Default:</strong> <code>1024 * 1024</code>.</li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The encoding used for all stdio inputs and outputs.
|
|
<strong>Default:</strong> <code>'buffer'</code>.</li>
|
|
<li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Hide the subprocess console window that would
|
|
normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If <code>true</code>, runs <code>command</code> inside of a shell. Uses
|
|
<code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
|
|
shell can be specified as a string. See <a href="#child_process_shell_requirements">Shell requirements</a> and
|
|
<a href="#child_process_default_windows_shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</code> (no shell).</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The stdout from the command.</li>
|
|
</ul>
|
|
<p>The <code>child_process.execFileSync()</code> method is generally identical to
|
|
<a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a> with the exception that the method will not
|
|
return until the child process has fully closed. When a timeout has been
|
|
encountered and <code>killSignal</code> is sent, the method won't return until the process
|
|
has completely exited.</p>
|
|
<p>If the child process intercepts and handles the <code>SIGTERM</code> signal and
|
|
does not exit, the parent process will still wait until the child process has
|
|
exited.</p>
|
|
<p>If the process times out or has a non-zero exit code, this method will throw an
|
|
<a href="errors.html#errors_class_error"><code>Error</code></a> that will include the full result of the underlying
|
|
<a href="#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a>.</p>
|
|
<p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
|
|
function. Any input containing shell metacharacters may be used to trigger
|
|
arbitrary command execution.</strong></p>
|
|
<h3><code>child_process.execSync(command[, options])</code><span><a class="mark" href="#child_process_child_process_execsync_command_options" id="child_process_child_process_execsync_command_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.10.0</td>
|
|
<td><p>The <code>input</code> option can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr>
|
|
<tr><td>v8.8.0</td>
|
|
<td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>The <code>input</code> option can now be a <code>Uint8Array</code>.</p></td></tr>
|
|
<tr><td>v0.11.12</td>
|
|
<td><p><span>Added in: v0.11.12</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The command to run.</li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Current working directory of the child process.</li>
|
|
<li><code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> The value which will be passed
|
|
as stdin to the spawned process. Supplying this value will override
|
|
<code>stdio[0]</code>.</li>
|
|
<li><code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> Child's stdio configuration. <code>stderr</code> by default will
|
|
be output to the parent process' stderr unless <code>stdio</code> is specified.
|
|
<strong>Default:</strong> <code>'pipe'</code>.</li>
|
|
<li><code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Environment key-value pairs. <strong>Default:</strong> <code>process.env</code>.</li>
|
|
<li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Shell to execute the command with. See
|
|
<a href="#child_process_shell_requirements">Shell requirements</a> and <a href="#child_process_default_windows_shell">Default Windows shell</a>. <strong>Default:</strong>
|
|
<code>'/bin/sh'</code> on Unix, <code>process.env.ComSpec</code> on Windows.</li>
|
|
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the user identity of the process. (See <a href="http://man7.org/linux/man-pages/man2/setuid.2.html"><code>setuid(2)</code></a>).</li>
|
|
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the group identity of the process. (See <a href="http://man7.org/linux/man-pages/man2/setgid.2.html"><code>setgid(2)</code></a>).</li>
|
|
<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> In milliseconds the maximum amount of time the process
|
|
is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
|
|
<li><code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The signal value to be used when the spawned
|
|
process will be killed. <strong>Default:</strong> <code>'SIGTERM'</code>.</li>
|
|
<li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Largest amount of data in bytes allowed on stdout or
|
|
stderr. If exceeded, the child process is terminated and any output is
|
|
truncated. See caveat at <a href="#child_process_maxbuffer_and_unicode"><code>maxBuffer</code> and Unicode</a>.
|
|
<strong>Default:</strong> <code>1024 * 1024</code>.</li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The encoding used for all stdio inputs and outputs.
|
|
<strong>Default:</strong> <code>'buffer'</code>.</li>
|
|
<li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Hide the subprocess console window that would
|
|
normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The stdout from the command.</li>
|
|
</ul>
|
|
<p>The <code>child_process.execSync()</code> method is generally identical to
|
|
<a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a> with the exception that the method will not return
|
|
until the child process has fully closed. When a timeout has been encountered
|
|
and <code>killSignal</code> is sent, the method won't return until the process has
|
|
completely exited. If the child process intercepts and handles the <code>SIGTERM</code>
|
|
signal and doesn't exit, the parent process will wait until the child process
|
|
has exited.</p>
|
|
<p>If the process times out or has a non-zero exit code, this method will throw.
|
|
The <a href="errors.html#errors_class_error"><code>Error</code></a> object will contain the entire result from
|
|
<a href="#child_process_child_process_spawnsync_command_args_options"><code>child_process.spawnSync()</code></a>.</p>
|
|
<p><strong>Never pass unsanitized user input to this function. Any input containing shell
|
|
metacharacters may be used to trigger arbitrary command execution.</strong></p>
|
|
<h3><code>child_process.spawnSync(command[, args][, options])</code><span><a class="mark" href="#child_process_child_process_spawnsync_command_args_options" id="child_process_child_process_spawnsync_command_args_options">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v10.10.0</td>
|
|
<td><p>The <code>input</code> option can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr>
|
|
<tr><td>v8.8.0</td>
|
|
<td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
|
|
<tr><td>v8.0.0</td>
|
|
<td><p>The <code>input</code> option can now be a <code>Uint8Array</code>.</p></td></tr>
|
|
<tr><td>v6.2.1, v4.5.0</td>
|
|
<td><p>The <code>encoding</code> option can now explicitly be set to <code>buffer</code>.</p></td></tr>
|
|
<tr><td>v5.7.0</td>
|
|
<td><p>The <code>shell</code> option is supported now.</p></td></tr>
|
|
<tr><td>v0.11.12</td>
|
|
<td><p><span>Added in: v0.11.12</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The command to run.</li>
|
|
<li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> List of string arguments.</li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Current working directory of the child process.</li>
|
|
<li><code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> The value which will be passed
|
|
as stdin to the spawned process. Supplying this value will override
|
|
<code>stdio[0]</code>.</li>
|
|
<li><code>argv0</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Explicitly set the value of <code>argv[0]</code> sent to the child
|
|
process. This will be set to <code>command</code> if not specified.</li>
|
|
<li><code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> Child's stdio configuration.</li>
|
|
<li><code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Environment key-value pairs. <strong>Default:</strong> <code>process.env</code>.</li>
|
|
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the user identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setuid.2.html"><code>setuid(2)</code></a>).</li>
|
|
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets the group identity of the process (see <a href="http://man7.org/linux/man-pages/man2/setgid.2.html"><code>setgid(2)</code></a>).</li>
|
|
<li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> In milliseconds the maximum amount of time the process
|
|
is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
|
|
<li><code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The signal value to be used when the spawned
|
|
process will be killed. <strong>Default:</strong> <code>'SIGTERM'</code>.</li>
|
|
<li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Largest amount of data in bytes allowed on stdout or
|
|
stderr. If exceeded, the child process is terminated and any output is
|
|
truncated. See caveat at <a href="#child_process_maxbuffer_and_unicode"><code>maxBuffer</code> and Unicode</a>.
|
|
<strong>Default:</strong> <code>1024 * 1024</code>.</li>
|
|
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The encoding used for all stdio inputs and outputs.
|
|
<strong>Default:</strong> <code>'buffer'</code>.</li>
|
|
<li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If <code>true</code>, runs <code>command</code> inside of a shell. Uses
|
|
<code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
|
|
shell can be specified as a string. See <a href="#child_process_shell_requirements">Shell requirements</a> and
|
|
<a href="#child_process_default_windows_shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</code> (no shell).</li>
|
|
<li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> No quoting or escaping of arguments is
|
|
done on Windows. Ignored on Unix. This is set to <code>true</code> automatically
|
|
when <code>shell</code> is specified and is CMD. <strong>Default:</strong> <code>false</code>.</li>
|
|
<li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Hide the subprocess console window that would
|
|
normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
|
<ul>
|
|
<li><code>pid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Pid of the child process.</li>
|
|
<li><code>output</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a> Array of results from stdio output.</li>
|
|
<li><code>stdout</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The contents of <code>output[1]</code>.</li>
|
|
<li><code>stderr</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The contents of <code>output[2]</code>.</li>
|
|
<li><code>status</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> The exit code of the subprocess, or <code>null</code> if the
|
|
subprocess terminated due to a signal.</li>
|
|
<li><code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> The signal used to kill the subprocess, or <code>null</code> if
|
|
the subprocess did not terminate due to a signal.</li>
|
|
<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> The error object if the child process failed or timed out.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>The <code>child_process.spawnSync()</code> method is generally identical to
|
|
<a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> with the exception that the function will not return
|
|
until the child process has fully closed. When a timeout has been encountered
|
|
and <code>killSignal</code> is sent, the method won't return until the process has
|
|
completely exited. If the process intercepts and handles the <code>SIGTERM</code> signal
|
|
and doesn't exit, the parent process will wait until the child process has
|
|
exited.</p>
|
|
<p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
|
|
function. Any input containing shell metacharacters may be used to trigger
|
|
arbitrary command execution.</strong></p>
|
|
<h2>Class: <code>ChildProcess</code><span><a class="mark" href="#child_process_class_childprocess" id="child_process_class_childprocess">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v2.2.0</span>
|
|
</div>
|
|
<ul>
|
|
<li>Extends: <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li>
|
|
</ul>
|
|
<p>Instances of the <code>ChildProcess</code> represent spawned child processes.</p>
|
|
<p>Instances of <code>ChildProcess</code> are not intended to be created directly. Rather,
|
|
use the <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a>, <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a>,
|
|
<a href="#child_process_child_process_execfile_file_args_options_callback"><code>child_process.execFile()</code></a>, or <a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a> methods to create
|
|
instances of <code>ChildProcess</code>.</p>
|
|
<h3>Event: <code>'close'</code><span><a class="mark" href="#child_process_event_close" id="child_process_event_close">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.7</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>code</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The exit code if the child exited on its own.</li>
|
|
<li><code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The signal by which the child process was terminated.</li>
|
|
</ul>
|
|
<p>The <code>'close'</code> event is emitted when the stdio streams of a child process have
|
|
been closed. This is distinct from the <a href="#child_process_event_exit"><code>'exit'</code></a> event, since multiple
|
|
processes might share the same stdio streams.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> ls = spawn(<span class="hljs-string">'ls'</span>, [<span class="hljs-string">'-lh'</span>, <span class="hljs-string">'/usr'</span>]);
|
|
|
|
ls.stdout.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`stdout: <span class="hljs-subst">${data}</span>`</span>);
|
|
});
|
|
|
|
ls.on(<span class="hljs-string">'close'</span>, <span class="hljs-function">(<span class="hljs-params">code</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`child process close all stdio with code <span class="hljs-subst">${code}</span>`</span>);
|
|
});
|
|
|
|
ls.on(<span class="hljs-string">'exit'</span>, <span class="hljs-function">(<span class="hljs-params">code</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`child process exited with code <span class="hljs-subst">${code}</span>`</span>);
|
|
});</code></pre>
|
|
<h3>Event: <code>'disconnect'</code><span><a class="mark" href="#child_process_event_disconnect" id="child_process_event_disconnect">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.2</span>
|
|
</div>
|
|
<p>The <code>'disconnect'</code> event is emitted after calling the
|
|
<a href="#child_process_subprocess_disconnect"><code>subprocess.disconnect()</code></a> method in parent process or
|
|
<a href="process.html#process_process_disconnect"><code>process.disconnect()</code></a> in child process. After disconnecting it is no longer
|
|
possible to send or receive messages, and the <a href="#child_process_subprocess_connected"><code>subprocess.connected</code></a>
|
|
property is <code>false</code>.</p>
|
|
<h3>Event: <code>'error'</code><span><a class="mark" href="#child_process_event_error" id="child_process_event_error">#</a></span></h3>
|
|
<ul>
|
|
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> The error.</li>
|
|
</ul>
|
|
<p>The <code>'error'</code> event is emitted whenever:</p>
|
|
<ol>
|
|
<li>The process could not be spawned, or</li>
|
|
<li>The process could not be killed, or</li>
|
|
<li>Sending a message to the child process failed.</li>
|
|
</ol>
|
|
<p>The <code>'exit'</code> event may or may not fire after an error has occurred. When
|
|
listening to both the <code>'exit'</code> and <code>'error'</code> events, guard
|
|
against accidentally invoking handler functions multiple times.</p>
|
|
<p>See also <a href="#child_process_subprocess_kill_signal"><code>subprocess.kill()</code></a> and <a href="#child_process_subprocess_send_message_sendhandle_options_callback"><code>subprocess.send()</code></a>.</p>
|
|
<h3>Event: <code>'exit'</code><span><a class="mark" href="#child_process_event_exit" id="child_process_event_exit">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>code</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The exit code if the child exited on its own.</li>
|
|
<li><code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The signal by which the child process was terminated.</li>
|
|
</ul>
|
|
<p>The <code>'exit'</code> event is emitted after the child process ends. If the process
|
|
exited, <code>code</code> is the final exit code of the process, otherwise <code>null</code>. If the
|
|
process terminated due to receipt of a signal, <code>signal</code> is the string name of
|
|
the signal, otherwise <code>null</code>. One of the two will always be non-<code>null</code>.</p>
|
|
<p>When the <code>'exit'</code> event is triggered, child process stdio streams might still be
|
|
open.</p>
|
|
<p>Node.js establishes signal handlers for <code>SIGINT</code> and <code>SIGTERM</code> and Node.js
|
|
processes will not terminate immediately due to receipt of those signals.
|
|
Rather, Node.js will perform a sequence of cleanup actions and then will
|
|
re-raise the handled signal.</p>
|
|
<p>See <a href="http://man7.org/linux/man-pages/man2/waitpid.2.html"><code>waitpid(2)</code></a>.</p>
|
|
<h3>Event: <code>'message'</code><span><a class="mark" href="#child_process_event_message" id="child_process_event_message">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.9</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> A parsed JSON object or primitive value.</li>
|
|
<li><code>sendHandle</code> <a href="net.html#net_server_listen_handle_backlog_callback" class="type"><Handle></a> A <a href="net.html#net_class_net_socket"><code>net.Socket</code></a> or <a href="net.html#net_class_net_server"><code>net.Server</code></a> object, or
|
|
undefined.</li>
|
|
</ul>
|
|
<p>The <code>'message'</code> event is triggered when a child process uses
|
|
<a href="process.html#process_process_send_message_sendhandle_options_callback"><code>process.send()</code></a> to send messages.</p>
|
|
<p>The message goes through serialization and parsing. The resulting
|
|
message might not be the same as what is originally sent.</p>
|
|
<p>If the <code>serialization</code> option was set to <code>'advanced'</code> used when spawning the
|
|
child process, the <code>message</code> argument can contain data that JSON is not able
|
|
to represent.
|
|
See <a href="#child_process_advanced_serialization">Advanced serialization</a> for more details.</p>
|
|
<h3><code>subprocess.channel</code><span><a class="mark" href="#child_process_subprocess_channel" id="child_process_subprocess_channel">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v7.1.0</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> A pipe representing the IPC channel to the child process.</li>
|
|
</ul>
|
|
<p>The <code>subprocess.channel</code> property is a reference to the child's IPC channel. If
|
|
no IPC channel currently exists, this property is <code>undefined</code>.</p>
|
|
<h3><code>subprocess.connected</code><span><a class="mark" href="#child_process_subprocess_connected" id="child_process_subprocess_connected">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.2</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Set to <code>false</code> after <code>subprocess.disconnect()</code> is called.</li>
|
|
</ul>
|
|
<p>The <code>subprocess.connected</code> property indicates whether it is still possible to
|
|
send and receive messages from a child process. When <code>subprocess.connected</code> is
|
|
<code>false</code>, it is no longer possible to send or receive messages.</p>
|
|
<h3><code>subprocess.disconnect()</code><span><a class="mark" href="#child_process_subprocess_disconnect" id="child_process_subprocess_disconnect">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.2</span>
|
|
</div>
|
|
<p>Closes the IPC channel between parent and child, allowing the child to exit
|
|
gracefully once there are no other connections keeping it alive. After calling
|
|
this method the <code>subprocess.connected</code> and <code>process.connected</code> properties in
|
|
both the parent and child (respectively) will be set to <code>false</code>, and it will be
|
|
no longer possible to pass messages between the processes.</p>
|
|
<p>The <code>'disconnect'</code> event will be emitted when there are no messages in the
|
|
process of being received. This will most often be triggered immediately after
|
|
calling <code>subprocess.disconnect()</code>.</p>
|
|
<p>When the child process is a Node.js instance (e.g. spawned using
|
|
<a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>), the <code>process.disconnect()</code> method can be invoked
|
|
within the child process to close the IPC channel as well.</p>
|
|
<h3><code>subprocess.exitCode</code><span><a class="mark" href="#child_process_subprocess_exitcode" id="child_process_subprocess_exitcode">#</a></span></h3>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>The <code>subprocess.exitCode</code> property indicates the exit code of the child process.
|
|
If the child process is still running, the field will be <code>null</code>.</p>
|
|
<h3><code>subprocess.kill([signal])</code><span><a class="mark" href="#child_process_subprocess_kill_signal" id="child_process_subprocess_kill_signal">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>The <code>subprocess.kill()</code> method sends a signal to the child process. If no
|
|
argument is given, the process will be sent the <code>'SIGTERM'</code> signal. See
|
|
<a href="http://man7.org/linux/man-pages/man7/signal.7.html"><code>signal(7)</code></a> for a list of available signals. This function returns <code>true</code> if
|
|
<a href="http://man7.org/linux/man-pages/man2/kill.2.html"><code>kill(2)</code></a> succeeds, and <code>false</code> otherwise.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> grep = spawn(<span class="hljs-string">'grep'</span>, [<span class="hljs-string">'ssh'</span>]);
|
|
|
|
grep.on(<span class="hljs-string">'close'</span>, <span class="hljs-function">(<span class="hljs-params">code, signal</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(
|
|
<span class="hljs-string">`child process terminated due to receipt of signal <span class="hljs-subst">${signal}</span>`</span>);
|
|
});
|
|
|
|
<span class="hljs-comment">// Send SIGHUP to process.</span>
|
|
grep.kill(<span class="hljs-string">'SIGHUP'</span>);</code></pre>
|
|
<p>The <a href="#child_process_child_process"><code>ChildProcess</code></a> object may emit an <a href="#child_process_event_error"><code>'error'</code></a> event if the signal
|
|
cannot be delivered. Sending a signal to a child process that has already exited
|
|
is not an error but may have unforeseen consequences. Specifically, if the
|
|
process identifier (PID) has been reassigned to another process, the signal will
|
|
be delivered to that process instead which can have unexpected results.</p>
|
|
<p>While the function is called <code>kill</code>, the signal delivered to the child process
|
|
may not actually terminate the process.</p>
|
|
<p>See <a href="http://man7.org/linux/man-pages/man2/kill.2.html"><code>kill(2)</code></a> for reference.</p>
|
|
<p>On Linux, child processes of child processes will not be terminated
|
|
when attempting to kill their parent. This is likely to happen when running a
|
|
new process in a shell or with the use of the <code>shell</code> option of <code>ChildProcess</code>:</p>
|
|
<pre><code class="language-js"><span class="hljs-meta">'use strict'</span>;
|
|
<span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> subprocess = spawn(
|
|
<span class="hljs-string">'sh'</span>,
|
|
[
|
|
<span class="hljs-string">'-c'</span>,
|
|
<span class="hljs-string">`node -e "setInterval(() => {
|
|
console.log(process.pid, 'is alive')
|
|
}, 500);"`</span>
|
|
], {
|
|
<span class="hljs-attr">stdio</span>: [<span class="hljs-string">'inherit'</span>, <span class="hljs-string">'inherit'</span>, <span class="hljs-string">'inherit'</span>]
|
|
}
|
|
);
|
|
|
|
<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> {
|
|
subprocess.kill(); <span class="hljs-comment">// Does not terminate the Node.js process in the shell.</span>
|
|
}, <span class="hljs-number">2000</span>);</code></pre>
|
|
<h3><code>subprocess.killed</code><span><a class="mark" href="#child_process_subprocess_killed" id="child_process_subprocess_killed">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.5.10</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Set to <code>true</code> after <code>subprocess.kill()</code> is used to successfully
|
|
send a signal to the child process.</li>
|
|
</ul>
|
|
<p>The <code>subprocess.killed</code> property indicates whether the child process
|
|
successfully received a signal from <code>subprocess.kill()</code>. The <code>killed</code> property
|
|
does not indicate that the child process has been terminated.</p>
|
|
<h3><code>subprocess.pid</code><span><a class="mark" href="#child_process_subprocess_pid" id="child_process_subprocess_pid">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>Returns the process identifier (PID) of the child process.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> grep = spawn(<span class="hljs-string">'grep'</span>, [<span class="hljs-string">'ssh'</span>]);
|
|
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Spawned child pid: <span class="hljs-subst">${grep.pid}</span>`</span>);
|
|
grep.stdin.end();</code></pre>
|
|
<h3><code>subprocess.ref()</code><span><a class="mark" href="#child_process_subprocess_ref" id="child_process_subprocess_ref">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.10</span>
|
|
</div>
|
|
<p>Calling <code>subprocess.ref()</code> after making a call to <code>subprocess.unref()</code> will
|
|
restore the removed reference count for the child process, forcing the parent
|
|
to wait for the child to exit before exiting itself.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> subprocess = spawn(process.argv[<span class="hljs-number">0</span>], [<span class="hljs-string">'child_program.js'</span>], {
|
|
<span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
|
|
<span class="hljs-attr">stdio</span>: <span class="hljs-string">'ignore'</span>
|
|
});
|
|
|
|
subprocess.unref();
|
|
subprocess.ref();</code></pre>
|
|
<h3><code>subprocess.send(message[, sendHandle[, options]][, callback])</code><span><a class="mark" href="#child_process_subprocess_send_message_sendhandle_options_callback" id="child_process_subprocess_send_message_sendhandle_options_callback">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<details class="changelog"><summary>History</summary>
|
|
<table>
|
|
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
|
<tr><td>v5.8.0</td>
|
|
<td><p>The <code>options</code> parameter, and the <code>keepOpen</code> option in particular, is supported now.</p></td></tr>
|
|
<tr><td>v5.0.0</td>
|
|
<td><p>This method returns a boolean for flow control now.</p></td></tr>
|
|
<tr><td>v4.0.0</td>
|
|
<td><p>The <code>callback</code> parameter is supported now.</p></td></tr>
|
|
<tr><td>v0.5.9</td>
|
|
<td><p><span>Added in: v0.5.9</span></p></td></tr>
|
|
</tbody></table>
|
|
</details>
|
|
</div>
|
|
<ul>
|
|
<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
|
<li><code>sendHandle</code> <a href="net.html#net_server_listen_handle_backlog_callback" class="type"><Handle></a></li>
|
|
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> The <code>options</code> argument, if present, is an object used to
|
|
parameterize the sending of certain types of handles. <code>options</code> supports
|
|
the following properties:
|
|
<ul>
|
|
<li><code>keepOpen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> A value that can be used when passing instances of
|
|
<code>net.Socket</code>. When <code>true</code>, the socket is kept open in the sending process.
|
|
<strong>Default:</strong> <code>false</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
|
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
|
</ul>
|
|
<p>When an IPC channel has been established between the parent and child (
|
|
i.e. when using <a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>), the <code>subprocess.send()</code> method can
|
|
be used to send messages to the child process. When the child process is a
|
|
Node.js instance, these messages can be received via the <a href="process.html#process_event_message"><code>'message'</code></a> event.</p>
|
|
<p>The message goes through serialization and parsing. The resulting
|
|
message might not be the same as what is originally sent.</p>
|
|
<p>For example, in the parent script:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> cp = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> n = cp.fork(<span class="hljs-string">`<span class="hljs-subst">${__dirname}</span>/sub.js`</span>);
|
|
|
|
n.on(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">m</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'PARENT got message:'</span>, m);
|
|
});
|
|
|
|
<span class="hljs-comment">// Causes the child to print: CHILD got message: { hello: 'world' }</span>
|
|
n.send({ <span class="hljs-attr">hello</span>: <span class="hljs-string">'world'</span> });</code></pre>
|
|
<p>And then the child script, <code>'sub.js'</code> might look like this:</p>
|
|
<pre><code class="language-js">process.on(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">m</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'CHILD got message:'</span>, m);
|
|
});
|
|
|
|
<span class="hljs-comment">// Causes the parent to print: PARENT got message: { foo: 'bar', baz: null }</span>
|
|
process.send({ <span class="hljs-attr">foo</span>: <span class="hljs-string">'bar'</span>, <span class="hljs-attr">baz</span>: <span class="hljs-literal">NaN</span> });</code></pre>
|
|
<p>Child Node.js processes will have a <a href="process.html#process_process_send_message_sendhandle_options_callback"><code>process.send()</code></a> method of their own
|
|
that allows the child to send messages back to the parent.</p>
|
|
<p>There is a special case when sending a <code>{cmd: 'NODE_foo'}</code> message. Messages
|
|
containing a <code>NODE_</code> prefix in the <code>cmd</code> property are reserved for use within
|
|
Node.js core and will not be emitted in the child's <a href="process.html#process_event_message"><code>'message'</code></a>
|
|
event. Rather, such messages are emitted using the
|
|
<code>'internalMessage'</code> event and are consumed internally by Node.js.
|
|
Applications should avoid using such messages or listening for
|
|
<code>'internalMessage'</code> events as it is subject to change without notice.</p>
|
|
<p>The optional <code>sendHandle</code> argument that may be passed to <code>subprocess.send()</code> is
|
|
for passing a TCP server or socket object to the child process. The child will
|
|
receive the object as the second argument passed to the callback function
|
|
registered on the <a href="process.html#process_event_message"><code>'message'</code></a> event. Any data that is received
|
|
and buffered in the socket will not be sent to the child.</p>
|
|
<p>The optional <code>callback</code> is a function that is invoked after the message is
|
|
sent but before the child may have received it. The function is called with a
|
|
single argument: <code>null</code> on success, or an <a href="errors.html#errors_class_error"><code>Error</code></a> object on failure.</p>
|
|
<p>If no <code>callback</code> function is provided and the message cannot be sent, an
|
|
<code>'error'</code> event will be emitted by the <a href="#child_process_child_process"><code>ChildProcess</code></a> object. This can
|
|
happen, for instance, when the child process has already exited.</p>
|
|
<p><code>subprocess.send()</code> will return <code>false</code> if the channel has closed or when the
|
|
backlog of unsent messages exceeds a threshold that makes it unwise to send
|
|
more. Otherwise, the method returns <code>true</code>. The <code>callback</code> function can be
|
|
used to implement flow control.</p>
|
|
<h4>Example: sending a server object<span><a class="mark" href="#child_process_example_sending_a_server_object" id="child_process_example_sending_a_server_object">#</a></span></h4>
|
|
<p>The <code>sendHandle</code> argument can be used, for instance, to pass the handle of
|
|
a TCP server object to the child process as illustrated in the example below:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> subprocess = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>).fork(<span class="hljs-string">'subprocess.js'</span>);
|
|
|
|
<span class="hljs-comment">// Open up the server object and send the handle.</span>
|
|
<span class="hljs-keyword">const</span> server = <span class="hljs-built_in">require</span>(<span class="hljs-string">'net'</span>).createServer();
|
|
server.on(<span class="hljs-string">'connection'</span>, <span class="hljs-function">(<span class="hljs-params">socket</span>) =></span> {
|
|
socket.end(<span class="hljs-string">'handled by parent'</span>);
|
|
});
|
|
server.listen(<span class="hljs-number">1337</span>, <span class="hljs-function">() =></span> {
|
|
subprocess.send(<span class="hljs-string">'server'</span>, server);
|
|
});</code></pre>
|
|
<p>The child would then receive the server object as:</p>
|
|
<pre><code class="language-js">process.on(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">m, server</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (m === <span class="hljs-string">'server'</span>) {
|
|
server.on(<span class="hljs-string">'connection'</span>, <span class="hljs-function">(<span class="hljs-params">socket</span>) =></span> {
|
|
socket.end(<span class="hljs-string">'handled by child'</span>);
|
|
});
|
|
}
|
|
});</code></pre>
|
|
<p>Once the server is now shared between the parent and child, some connections
|
|
can be handled by the parent and some by the child.</p>
|
|
<p>While the example above uses a server created using the <code>net</code> module, <code>dgram</code>
|
|
module servers use exactly the same workflow with the exceptions of listening on
|
|
a <code>'message'</code> event instead of <code>'connection'</code> and using <code>server.bind()</code> instead
|
|
of <code>server.listen()</code>. This is, however, currently only supported on Unix
|
|
platforms.</p>
|
|
<h4>Example: sending a socket object<span><a class="mark" href="#child_process_example_sending_a_socket_object" id="child_process_example_sending_a_socket_object">#</a></span></h4>
|
|
<p>Similarly, the <code>sendHandler</code> argument can be used to pass the handle of a
|
|
socket to the child process. The example below spawns two children that each
|
|
handle connections with "normal" or "special" priority:</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { fork } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
<span class="hljs-keyword">const</span> normal = fork(<span class="hljs-string">'subprocess.js'</span>, [<span class="hljs-string">'normal'</span>]);
|
|
<span class="hljs-keyword">const</span> special = fork(<span class="hljs-string">'subprocess.js'</span>, [<span class="hljs-string">'special'</span>]);
|
|
|
|
<span class="hljs-comment">// Open up the server and send sockets to child. Use pauseOnConnect to prevent</span>
|
|
<span class="hljs-comment">// the sockets from being read before they are sent to the child process.</span>
|
|
<span class="hljs-keyword">const</span> server = <span class="hljs-built_in">require</span>(<span class="hljs-string">'net'</span>).createServer({ <span class="hljs-attr">pauseOnConnect</span>: <span class="hljs-literal">true</span> });
|
|
server.on(<span class="hljs-string">'connection'</span>, <span class="hljs-function">(<span class="hljs-params">socket</span>) =></span> {
|
|
|
|
<span class="hljs-comment">// If this is special priority...</span>
|
|
<span class="hljs-keyword">if</span> (socket.remoteAddress === <span class="hljs-string">'74.125.127.100'</span>) {
|
|
special.send(<span class="hljs-string">'socket'</span>, socket);
|
|
<span class="hljs-keyword">return</span>;
|
|
}
|
|
<span class="hljs-comment">// This is normal priority.</span>
|
|
normal.send(<span class="hljs-string">'socket'</span>, socket);
|
|
});
|
|
server.listen(<span class="hljs-number">1337</span>);</code></pre>
|
|
<p>The <code>subprocess.js</code> would receive the socket handle as the second argument
|
|
passed to the event callback function:</p>
|
|
<pre><code class="language-js">process.on(<span class="hljs-string">'message'</span>, <span class="hljs-function">(<span class="hljs-params">m, socket</span>) =></span> {
|
|
<span class="hljs-keyword">if</span> (m === <span class="hljs-string">'socket'</span>) {
|
|
<span class="hljs-keyword">if</span> (socket) {
|
|
<span class="hljs-comment">// Check that the client socket exists.</span>
|
|
<span class="hljs-comment">// It is possible for the socket to be closed between the time it is</span>
|
|
<span class="hljs-comment">// sent and the time it is received in the child process.</span>
|
|
socket.end(<span class="hljs-string">`Request handled with <span class="hljs-subst">${process.argv[<span class="hljs-number">2</span>]}</span> priority`</span>);
|
|
}
|
|
}
|
|
});</code></pre>
|
|
<p>Do not use <code>.maxConnections</code> on a socket that has been passed to a subprocess.
|
|
The parent cannot track when the socket is destroyed.</p>
|
|
<p>Any <code>'message'</code> handlers in the subprocess should verify that <code>socket</code> exists,
|
|
as the connection may have been closed during the time it takes to send the
|
|
connection to the child.</p>
|
|
<h3><code>subprocess.signalCode</code><span><a class="mark" href="#child_process_subprocess_signalcode" id="child_process_subprocess_signalcode">#</a></span></h3>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
|
</ul>
|
|
<p>The <code>subprocess.signalCode</code> property indicates the signal number received by
|
|
the child process if any, else <code>null</code>.</p>
|
|
<h3><code>subprocess.spawnargs</code><span><a class="mark" href="#child_process_subprocess_spawnargs" id="child_process_subprocess_spawnargs">#</a></span></h3>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a></li>
|
|
</ul>
|
|
<p>The <code>subprocess.spawnargs</code> property represents the full list of command line
|
|
arguments the child process was launched with.</p>
|
|
<h3><code>subprocess.spawnfile</code><span><a class="mark" href="#child_process_subprocess_spawnfile" id="child_process_subprocess_spawnfile">#</a></span></h3>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
|
</ul>
|
|
<p>The <code>subprocess.spawnfile</code> property indicates the executable file name of
|
|
the child process that is launched.</p>
|
|
<p>For <a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>, its value will be equal to
|
|
<a href="process.html#process_process_execpath"><code>process.execPath</code></a>.
|
|
For <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a>, its value will be the name of
|
|
the executable file.
|
|
For <a href="#child_process_child_process_exec_command_options_callback"><code>child_process.exec()</code></a>, its value will be the name of the shell
|
|
in which the child process is launched.</p>
|
|
<h3><code>subprocess.stderr</code><span><a class="mark" href="#child_process_subprocess_stderr" id="child_process_subprocess_stderr">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="stream.html#stream_class_stream_readable" class="type"><stream.Readable></a></li>
|
|
</ul>
|
|
<p>A <code>Readable Stream</code> that represents the child process's <code>stderr</code>.</p>
|
|
<p>If the child was spawned with <code>stdio[2]</code> set to anything other than <code>'pipe'</code>,
|
|
then this will be <code>null</code>.</p>
|
|
<p><code>subprocess.stderr</code> is an alias for <code>subprocess.stdio[2]</code>. Both properties will
|
|
refer to the same value.</p>
|
|
<h3><code>subprocess.stdin</code><span><a class="mark" href="#child_process_subprocess_stdin" id="child_process_subprocess_stdin">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="stream.html#stream_class_stream_writable" class="type"><stream.Writable></a></li>
|
|
</ul>
|
|
<p>A <code>Writable Stream</code> that represents the child process's <code>stdin</code>.</p>
|
|
<p>If a child process waits to read all of its input, the child will not continue
|
|
until this stream has been closed via <code>end()</code>.</p>
|
|
<p>If the child was spawned with <code>stdio[0]</code> set to anything other than <code>'pipe'</code>,
|
|
then this will be <code>null</code>.</p>
|
|
<p><code>subprocess.stdin</code> is an alias for <code>subprocess.stdio[0]</code>. Both properties will
|
|
refer to the same value.</p>
|
|
<h3><code>subprocess.stdio</code><span><a class="mark" href="#child_process_subprocess_stdio" id="child_process_subprocess_stdio">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.10</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" class="type"><Array></a></li>
|
|
</ul>
|
|
<p>A sparse array of pipes to the child process, corresponding with positions in
|
|
the <a href="#child_process_options_stdio"><code>stdio</code></a> option passed to <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a> that have been set
|
|
to the value <code>'pipe'</code>. <code>subprocess.stdio[0]</code>, <code>subprocess.stdio[1]</code>, and
|
|
<code>subprocess.stdio[2]</code> are also available as <code>subprocess.stdin</code>,
|
|
<code>subprocess.stdout</code>, and <code>subprocess.stderr</code>, respectively.</p>
|
|
<p>In the following example, only the child's fd <code>1</code> (stdout) is configured as a
|
|
pipe, so only the parent's <code>subprocess.stdio[1]</code> is a stream, all other values
|
|
in the array are <code>null</code>.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> assert = <span class="hljs-built_in">require</span>(<span class="hljs-string">'assert'</span>);
|
|
<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
|
<span class="hljs-keyword">const</span> child_process = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> subprocess = child_process.spawn(<span class="hljs-string">'ls'</span>, {
|
|
<span class="hljs-attr">stdio</span>: [
|
|
<span class="hljs-number">0</span>, <span class="hljs-comment">// Use parent's stdin for child.</span>
|
|
<span class="hljs-string">'pipe'</span>, <span class="hljs-comment">// Pipe child's stdout to parent.</span>
|
|
fs.openSync(<span class="hljs-string">'err.out'</span>, <span class="hljs-string">'w'</span>) <span class="hljs-comment">// Direct child's stderr to a file.</span>
|
|
]
|
|
});
|
|
|
|
assert.strictEqual(subprocess.stdio[<span class="hljs-number">0</span>], <span class="hljs-literal">null</span>);
|
|
assert.strictEqual(subprocess.stdio[<span class="hljs-number">0</span>], subprocess.stdin);
|
|
|
|
assert(subprocess.stdout);
|
|
assert.strictEqual(subprocess.stdio[<span class="hljs-number">1</span>], subprocess.stdout);
|
|
|
|
assert.strictEqual(subprocess.stdio[<span class="hljs-number">2</span>], <span class="hljs-literal">null</span>);
|
|
assert.strictEqual(subprocess.stdio[<span class="hljs-number">2</span>], subprocess.stderr);</code></pre>
|
|
<h3><code>subprocess.stdout</code><span><a class="mark" href="#child_process_subprocess_stdout" id="child_process_subprocess_stdout">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.1.90</span>
|
|
</div>
|
|
<ul>
|
|
<li><a href="stream.html#stream_class_stream_readable" class="type"><stream.Readable></a></li>
|
|
</ul>
|
|
<p>A <code>Readable Stream</code> that represents the child process's <code>stdout</code>.</p>
|
|
<p>If the child was spawned with <code>stdio[1]</code> set to anything other than <code>'pipe'</code>,
|
|
then this will be <code>null</code>.</p>
|
|
<p><code>subprocess.stdout</code> is an alias for <code>subprocess.stdio[1]</code>. Both properties will
|
|
refer to the same value.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> subprocess = spawn(<span class="hljs-string">'ls'</span>);
|
|
|
|
subprocess.stdout.on(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> {
|
|
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Received chunk <span class="hljs-subst">${data}</span>`</span>);
|
|
});</code></pre>
|
|
<h3><code>subprocess.unref()</code><span><a class="mark" href="#child_process_subprocess_unref" id="child_process_subprocess_unref">#</a></span></h3>
|
|
<div class="api_metadata">
|
|
<span>Added in: v0.7.10</span>
|
|
</div>
|
|
<p>By default, the parent will wait for the detached child to exit. To prevent the
|
|
parent from waiting for a given <code>subprocess</code> to exit, use the
|
|
<code>subprocess.unref()</code> method. Doing so will cause the parent's event loop to not
|
|
include the child in its reference count, allowing the parent to exit
|
|
independently of the child, unless there is an established IPC channel between
|
|
the child and the parent.</p>
|
|
<pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'child_process'</span>);
|
|
|
|
<span class="hljs-keyword">const</span> subprocess = spawn(process.argv[<span class="hljs-number">0</span>], [<span class="hljs-string">'child_program.js'</span>], {
|
|
<span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
|
|
<span class="hljs-attr">stdio</span>: <span class="hljs-string">'ignore'</span>
|
|
});
|
|
|
|
subprocess.unref();</code></pre>
|
|
<h2><code>maxBuffer</code> and Unicode<span><a class="mark" href="#child_process_maxbuffer_and_unicode" id="child_process_maxbuffer_and_unicode">#</a></span></h2>
|
|
<p>The <code>maxBuffer</code> option specifies the largest number of bytes allowed on <code>stdout</code>
|
|
or <code>stderr</code>. If this value is exceeded, then the child process is terminated.
|
|
This impacts output that includes multibyte character encodings such as UTF-8 or
|
|
UTF-16. For instance, <code>console.log('中文测试')</code> will send 13 UTF-8 encoded bytes
|
|
to <code>stdout</code> although there are only 4 characters.</p>
|
|
<h2>Shell requirements<span><a class="mark" href="#child_process_shell_requirements" id="child_process_shell_requirements">#</a></span></h2>
|
|
<p>The shell should understand the <code>-c</code> switch. If the shell is <code>'cmd.exe'</code>, it
|
|
should understand the <code>/d /s /c</code> switches and command line parsing should be
|
|
compatible.</p>
|
|
<h2>Default Windows shell<span><a class="mark" href="#child_process_default_windows_shell" id="child_process_default_windows_shell">#</a></span></h2>
|
|
<p>Although Microsoft specifies <code>%COMSPEC%</code> must contain the path to
|
|
<code>'cmd.exe'</code> in the root environment, child processes are not always subject to
|
|
the same requirement. Thus, in <code>child_process</code> functions where a shell can be
|
|
spawned, <code>'cmd.exe'</code> is used as a fallback if <code>process.env.ComSpec</code> is
|
|
unavailable.</p>
|
|
<h2>Advanced serialization<span><a class="mark" href="#child_process_advanced_serialization" id="child_process_advanced_serialization">#</a></span></h2>
|
|
<div class="api_metadata">
|
|
<span>Added in: v12.16.0</span>
|
|
</div>
|
|
<p>Child processes support a serialization mechanism for IPC that is based on the
|
|
<a href="v8.html#v8_serialization_api">serialization API of the <code>v8</code> module</a>, based on the
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">HTML structured clone algorithm</a>. This is generally more powerful and
|
|
supports more built-in JavaScript object types, such as <code>BigInt</code>, <code>Map</code>
|
|
and <code>Set</code>, <code>ArrayBuffer</code> and <code>TypedArray</code>, <code>Buffer</code>, <code>Error</code>, <code>RegExp</code> etc.</p>
|
|
<p>However, this format is not a full superset of JSON, and e.g. properties set on
|
|
objects of such built-in types will not be passed on through the serialization
|
|
step. Additionally, performance may not be equivalent to that of JSON, depending
|
|
on the structure of the passed data.
|
|
Therefore, this feature requires opting in by setting the
|
|
<code>serialization</code> option to <code>'advanced'</code> when calling <a href="#child_process_child_process_spawn_command_args_options"><code>child_process.spawn()</code></a>
|
|
or <a href="#child_process_child_process_fork_modulepath_args_options"><code>child_process.fork()</code></a>.</p>
|
|
<!-- API END -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|