child_process.html - OpenGrok cross reference for /third_party/node/doc/api/child

Lines Matching +full:code +full:-
4   <meta charset="utf-8">
5   <meta name="viewport" content="width=device-width">
6   <meta name="nodejs.org:node-version" content="v18.20.1">
15 <body class="alt apidoc" id="api-section-child_process">
24 <li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
25 <li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
29 <li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
30 <li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li>
31 <li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
32 <li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
33 <li><a href="addons.html" class="nav-addons">C++ addons</a></li>
34 <li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li>
35 <li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li>
36 <li><a href="child_process.html" class="nav-child_process active">Child processes</a></li>
37 <li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
38 <li><a href="cli.html" class="nav-cli">Command-line options</a></li>
39 <li><a href="console.html" class="nav-console">Console</a></li>
40 <li><a href="corepack.html" class="nav-corepack">Corepack</a></li>
41 <li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
42 <li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
43 <li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
44 <li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li>
45 <li><a href="dns.html" class="nav-dns">DNS</a></li>
46 <li><a href="domain.html" class="nav-domain">Domain</a></li>
47 <li><a href="errors.html" class="nav-errors">Errors</a></li>
48 <li><a href="events.html" class="nav-events">Events</a></li>
49 <li><a href="fs.html" class="nav-fs">File system</a></li>
50 <li><a href="globals.html" class="nav-globals">Globals</a></li>
51 <li><a href="http.html" class="nav-http">HTTP</a></li>
52 <li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
53 <li><a href="https.html" class="nav-https">HTTPS</a></li>
54 <li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
55 <li><a href="intl.html" class="nav-intl">Internationalization</a></li>
56 <li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
57 <li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
58 <li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li>
59 <li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
60 <li><a href="net.html" class="nav-net">Net</a></li>
61 <li><a href="os.html" class="nav-os">OS</a></li>
62 <li><a href="path.html" class="nav-path">Path</a></li>
63 <li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
64 <li><a href="permissions.html" class="nav-permissions">Permissions</a></li>
65 <li><a href="process.html" class="nav-process">Process</a></li>
66 <li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
67 <li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
68 <li><a href="readline.html" class="nav-readline">Readline</a></li>
69 <li><a href="repl.html" class="nav-repl">REPL</a></li>
70 <li><a href="report.html" class="nav-report">Report</a></li>
71 <li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single…
72 <li><a href="stream.html" class="nav-stream">Stream</a></li>
73 <li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
74 <li><a href="test.html" class="nav-test">Test runner</a></li>
75 <li><a href="timers.html" class="nav-timers">Timers</a></li>
76 <li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
77 <li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
78 <li><a href="tty.html" class="nav-tty">TTY</a></li>
79 <li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
80 <li><a href="url.html" class="nav-url">URL</a></li>
81 <li><a href="util.html" class="nav-util">Utilities</a></li>
82 <li><a href="v8.html" class="nav-v8">V8</a></li>
83 <li><a href="vm.html" class="nav-vm">VM</a></li>
84 <li><a href="wasi.html" class="nav-wasi">WASI</a></li>
85 <li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li>
86 <li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li>
87 <li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
88 <li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
92 <li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code reposito…
96     <div id="column1" data-id="child_process" class="interior">
98         <div class="header-container">
100 …<button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-la…
101             <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24">
103 …-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.6…
104 …<path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2…
106             <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24">
108 …-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.4…
114             <li class="pinned-header">Node.js v18.20.1</li>
116     <li class="picker-header">
118         <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
123 <li><span class="stability_2"><a href="#child-process">Child process</a></span>
125 <li><a href="#asynchronous-process-creation">Asynchronous process creation</a>
127 <li><a href="#spawning-bat-and-cmd-files-on-windows">Spawning <code>.bat</code> and <code>.cmd</cod…
128 …i><a href="#child_processexeccommand-options-callback"><code>child_process.exec(command[, options]…
129 …f="#child_processexecfilefile-args-options-callback"><code>child_process.execFile(file[, args][, o…
130 …><a href="#child_processforkmodulepath-args-options"><code>child_process.fork(modulePath[, args][,…
131 <li><a href="#child_processspawncommand-args-options"><code>child_process.spawn(command[, args][, o…
133 <li><a href="#optionsdetached"><code>options.detached</code></a></li>
134 <li><a href="#optionsstdio"><code>options.stdio</code></a></li>
139 <li><a href="#synchronous-process-creation">Synchronous process creation</a>
141 … href="#child_processexecfilesyncfile-args-options"><code>child_process.execFileSync(file[, args][…
142 <li><a href="#child_processexecsynccommand-options"><code>child_process.execSync(command[, options]…
143 … href="#child_processspawnsynccommand-args-options"><code>child_process.spawnSync(command[, args][…
146 <li><a href="#class-childprocess">Class: <code>ChildProcess</code></a>
148 <li><a href="#event-close">Event: <code>'close'</code></a></li>
149 <li><a href="#event-disconnect">Event: <code>'disconnect'</code></a></li>
150 <li><a href="#event-error">Event: <code>'error'</code></a></li>
151 <li><a href="#event-exit">Event: <code>'exit'</code></a></li>
152 <li><a href="#event-message">Event: <code>'message'</code></a></li>
153 <li><a href="#event-spawn">Event: <code>'spawn'</code></a></li>
154 <li><a href="#subprocesschannel"><code>subprocess.channel</code></a>
156 <li><a href="#subprocesschannelref"><code>subprocess.channel.ref()</code></a></li>
157 <li><a href="#subprocesschannelunref"><code>subprocess.channel.unref()</code></a></li>
160 <li><a href="#subprocessconnected"><code>subprocess.connected</code></a></li>
161 <li><a href="#subprocessdisconnect"><code>subprocess.disconnect()</code></a></li>
162 <li><a href="#subprocessexitcode"><code>subprocess.exitCode</code></a></li>
163 <li><a href="#subprocesskillsignal"><code>subprocess.kill([signal])</code></a></li>
164 … class="stability_1"><a href="#subprocesssymboldispose"><code>subprocess[Symbol.dispose]()</code><…
165 <li><a href="#subprocesskilled"><code>subprocess.killed</code></a></li>
166 <li><a href="#subprocesspid"><code>subprocess.pid</code></a></li>
167 <li><a href="#subprocessref"><code>subprocess.ref()</code></a></li>
168 …f="#subprocesssendmessage-sendhandle-options-callback"><code>subprocess.send(message[, sendHandle[…
170 <li><a href="#example-sending-a-server-object">Example: sending a server object</a></li>
171 <li><a href="#example-sending-a-socket-object">Example: sending a socket object</a></li>
174 <li><a href="#subprocesssignalcode"><code>subprocess.signalCode</code></a></li>
175 <li><a href="#subprocessspawnargs"><code>subprocess.spawnargs</code></a></li>
176 <li><a href="#subprocessspawnfile"><code>subprocess.spawnfile</code></a></li>
177 <li><a href="#subprocessstderr"><code>subprocess.stderr</code></a></li>
178 <li><a href="#subprocessstdin"><code>subprocess.stdin</code></a></li>
179 <li><a href="#subprocessstdio"><code>subprocess.stdio</code></a></li>
180 <li><a href="#subprocessstdout"><code>subprocess.stdout</code></a></li>
181 <li><a href="#subprocessunref"><code>subprocess.unref()</code></a></li>
184 <li><a href="#maxbuffer-and-unicode"><code>maxBuffer</code> and Unicode</a></li>
185 <li><a href="#shell-requirements">Shell requirements</a></li>
186 <li><a href="#default-windows-shell">Default Windows shell</a></li>
187 <li><a href="#advanced-serialization">Advanced serialization</a></li>
194     <li class="picker-header">
196         <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
201 <li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
202 <li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
211 <li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
212 <li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li>
213 <li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
214 <li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
215 <li><a href="addons.html" class="nav-addons">C++ addons</a></li>
216 <li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li>
217 <li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li>
218 <li><a href="child_process.html" class="nav-child_process active">Child processes</a></li>
219 <li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
220 <li><a href="cli.html" class="nav-cli">Command-line options</a></li>
221 <li><a href="console.html" class="nav-console">Console</a></li>
222 <li><a href="corepack.html" class="nav-corepack">Corepack</a></li>
223 <li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
224 <li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
225 <li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
226 <li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li>
227 <li><a href="dns.html" class="nav-dns">DNS</a></li>
228 <li><a href="domain.html" class="nav-domain">Domain</a></li>
229 <li><a href="errors.html" class="nav-errors">Errors</a></li>
230 <li><a href="events.html" class="nav-events">Events</a></li>
231 <li><a href="fs.html" class="nav-fs">File system</a></li>
232 <li><a href="globals.html" class="nav-globals">Globals</a></li>
233 <li><a href="http.html" class="nav-http">HTTP</a></li>
234 <li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
235 <li><a href="https.html" class="nav-https">HTTPS</a></li>
236 <li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
237 <li><a href="intl.html" class="nav-intl">Internationalization</a></li>
238 <li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
239 <li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
240 <li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li>
241 <li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
242 <li><a href="net.html" class="nav-net">Net</a></li>
243 <li><a href="os.html" class="nav-os">OS</a></li>
244 <li><a href="path.html" class="nav-path">Path</a></li>
245 <li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
246 <li><a href="permissions.html" class="nav-permissions">Permissions</a></li>
247 <li><a href="process.html" class="nav-process">Process</a></li>
248 <li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
249 <li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
250 <li><a href="readline.html" class="nav-readline">Readline</a></li>
251 <li><a href="repl.html" class="nav-repl">REPL</a></li>
252 <li><a href="report.html" class="nav-report">Report</a></li>
253 <li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single…
254 <li><a href="stream.html" class="nav-stream">Stream</a></li>
255 <li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
256 <li><a href="test.html" class="nav-test">Test runner</a></li>
257 <li><a href="timers.html" class="nav-timers">Timers</a></li>
258 <li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
259 <li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
260 <li><a href="tty.html" class="nav-tty">TTY</a></li>
261 <li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
262 <li><a href="url.html" class="nav-url">URL</a></li>
263 <li><a href="util.html" class="nav-util">Utilities</a></li>
264 <li><a href="v8.html" class="nav-v8">V8</a></li>
265 <li><a href="vm.html" class="nav-vm">VM</a></li>
266 <li><a href="wasi.html" class="nav-wasi">WASI</a></li>
267 <li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li>
268 <li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li>
269 <li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
270 <li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
274 <li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code reposito…
279     <li class="picker-header">
281         <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
284 …<div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/child_…
285 <li><a href="https://nodejs.org/docs/latest-v20.x/api/child_process.html">20.x <b>LTS</b></a></li>
286 <li><a href="https://nodejs.org/docs/latest-v19.x/api/child_process.html">19.x</a></li>
287 <li><a href="https://nodejs.org/docs/latest-v18.x/api/child_process.html">18.x <b>LTS</b></a></li>
288 <li><a href="https://nodejs.org/docs/latest-v17.x/api/child_process.html">17.x</a></li>
289 <li><a href="https://nodejs.org/docs/latest-v16.x/api/child_process.html">16.x</a></li>
290 <li><a href="https://nodejs.org/docs/latest-v15.x/api/child_process.html">15.x</a></li>
291 <li><a href="https://nodejs.org/docs/latest-v14.x/api/child_process.html">14.x</a></li>
292 <li><a href="https://nodejs.org/docs/latest-v13.x/api/child_process.html">13.x</a></li>
293 <li><a href="https://nodejs.org/docs/latest-v12.x/api/child_process.html">12.x</a></li>
294 <li><a href="https://nodejs.org/docs/latest-v11.x/api/child_process.html">11.x</a></li>
295 <li><a href="https://nodejs.org/docs/latest-v10.x/api/child_process.html">10.x</a></li>
296 <li><a href="https://nodejs.org/docs/latest-v9.x/api/child_process.html">9.x</a></li>
297 <li><a href="https://nodejs.org/docs/latest-v8.x/api/child_process.html">8.x</a></li>
298 <li><a href="https://nodejs.org/docs/latest-v7.x/api/child_process.html">7.x</a></li>
299 <li><a href="https://nodejs.org/docs/latest-v6.x/api/child_process.html">6.x</a></li>
300 <li><a href="https://nodejs.org/docs/latest-v5.x/api/child_process.html">5.x</a></li>
301 <li><a href="https://nodejs.org/docs/latest-v4.x/api/child_process.html">4.x</a></li>
302 <li><a href="https://nodejs.org/docs/latest-v0.12.x/api/child_process.html">0.12.x</a></li>
303 <li><a href="https://nodejs.org/docs/latest-v0.10.x/api/child_process.html">0.10.x</a></li></ol></d…
306             <li class="picker-header">
308 …          <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
330 <li><span class="stability_2"><a href="#child-process">Child process</a></span>
332 <li><a href="#asynchronous-process-creation">Asynchronous process creation</a>
334 <li><a href="#spawning-bat-and-cmd-files-on-windows">Spawning <code>.bat</code> and <code>.cmd</cod…
335 …i><a href="#child_processexeccommand-options-callback"><code>child_process.exec(command[, options]…
336 …f="#child_processexecfilefile-args-options-callback"><code>child_process.execFile(file[, args][, o…
337 …><a href="#child_processforkmodulepath-args-options"><code>child_process.fork(modulePath[, args][,…
338 <li><a href="#child_processspawncommand-args-options"><code>child_process.spawn(command[, args][, o…
340 <li><a href="#optionsdetached"><code>options.detached</code></a></li>
341 <li><a href="#optionsstdio"><code>options.stdio</code></a></li>
346 <li><a href="#synchronous-process-creation">Synchronous process creation</a>
348 … href="#child_processexecfilesyncfile-args-options"><code>child_process.execFileSync(file[, args][…
349 <li><a href="#child_processexecsynccommand-options"><code>child_process.execSync(command[, options]…
350 … href="#child_processspawnsynccommand-args-options"><code>child_process.spawnSync(command[, args][…
353 <li><a href="#class-childprocess">Class: <code>ChildProcess</code></a>
355 <li><a href="#event-close">Event: <code>'close'</code></a></li>
356 <li><a href="#event-disconnect">Event: <code>'disconnect'</code></a></li>
357 <li><a href="#event-error">Event: <code>'error'</code></a></li>
358 <li><a href="#event-exit">Event: <code>'exit'</code></a></li>
359 <li><a href="#event-message">Event: <code>'message'</code></a></li>
360 <li><a href="#event-spawn">Event: <code>'spawn'</code></a></li>
361 <li><a href="#subprocesschannel"><code>subprocess.channel</code></a>
363 <li><a href="#subprocesschannelref"><code>subprocess.channel.ref()</code></a></li>
364 <li><a href="#subprocesschannelunref"><code>subprocess.channel.unref()</code></a></li>
367 <li><a href="#subprocessconnected"><code>subprocess.connected</code></a></li>
368 <li><a href="#subprocessdisconnect"><code>subprocess.disconnect()</code></a></li>
369 <li><a href="#subprocessexitcode"><code>subprocess.exitCode</code></a></li>
370 <li><a href="#subprocesskillsignal"><code>subprocess.kill([signal])</code></a></li>
371 … class="stability_1"><a href="#subprocesssymboldispose"><code>subprocess[Symbol.dispose]()</code><…
372 <li><a href="#subprocesskilled"><code>subprocess.killed</code></a></li>
373 <li><a href="#subprocesspid"><code>subprocess.pid</code></a></li>
374 <li><a href="#subprocessref"><code>subprocess.ref()</code></a></li>
375 …f="#subprocesssendmessage-sendhandle-options-callback"><code>subprocess.send(message[, sendHandle[…
377 <li><a href="#example-sending-a-server-object">Example: sending a server object</a></li>
378 <li><a href="#example-sending-a-socket-object">Example: sending a socket object</a></li>
381 <li><a href="#subprocesssignalcode"><code>subprocess.signalCode</code></a></li>
382 <li><a href="#subprocessspawnargs"><code>subprocess.spawnargs</code></a></li>
383 <li><a href="#subprocessspawnfile"><code>subprocess.spawnfile</code></a></li>
384 <li><a href="#subprocessstderr"><code>subprocess.stderr</code></a></li>
385 <li><a href="#subprocessstdin"><code>subprocess.stdin</code></a></li>
386 <li><a href="#subprocessstdio"><code>subprocess.stdio</code></a></li>
387 <li><a href="#subprocessstdout"><code>subprocess.stdout</code></a></li>
388 <li><a href="#subprocessunref"><code>subprocess.unref()</code></a></li>
391 <li><a href="#maxbuffer-and-unicode"><code>maxBuffer</code> and Unicode</a></li>
392 <li><a href="#shell-requirements">Shell requirements</a></li>
393 <li><a href="#default-windows-shell">Default Windows shell</a></li>
394 <li><a href="#advanced-serialization">Advanced serialization</a></li>
400 …<h2>Child process<span><a class="mark" href="#child-process" id="child-process">#</a></span><a ari…
402 …tability api_stability_2"><a href="documentation.html#stability-index">Stability: 2</a> - Stable</…
403 <p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v18.20.1/lib/child_pr…
404 <p>The <code>node:child_process</code> module provides the ability to spawn subprocesses in
405 … not identical, to <a href="http://man7.org/linux/man-pages/man3/popen.3.html"><code>popen(3)</cod…
406 … provided by the <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</co…
407 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
408 …-keyword">const</span> ls = <span class="hljs-title function_">spawn</span>(<span class="hljs-stri…
410 …-property">stdout</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
411 …ass="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span c…
414 …-property">stderr</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
415 …ss="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span …
418 … class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hlj…
419 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
420 });</code> <button class="copy-button">copy</button></pre>
421 <p>By default, pipes for <code>stdin</code>, <code>stdout</code>, and <code>stderr</code> are estab…
423 limited (and platform-specific) capacity. If the subprocess writes to
426 identical to the behavior of pipes in the shell. Use the <code>{ stdio: 'ignore' }</code>
428 <p>The command lookup is performed using the <code>options.env.PATH</code> environment
429 variable if <code>env</code> is in the <code>options</code> object. Otherwise, <code>process.env.PA…
430 used. If <code>options.env</code> is set without <code>PATH</code>, lookup on Unix is performed
431 on a default search path search of <code>/usr/bin:/bin</code> (see your operating system's
433 variable <code>PATH</code> is used.</p>
434 <p>On Windows, environment variables are case-insensitive. Node.js
435 lexicographically sorts the <code>env</code> keys and uses the first one that
436 case-insensitively matches. Only first (in lexicographic order) entry will be
438 objects to the <code>env</code> option that have multiple variants of the same key, such as
439 <code>PATH</code> and <code>Path</code>.</p>
440 <p>The <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</code></a> met…
441 … loop. The <a href="#child_processspawnsynccommand-args-options"><code>child_process.spawnSync()</…
444 <p>For convenience, the <code>node:child_process</code> module provides a handful of
445 … alternatives to <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</co…
446 <a href="#child_processspawnsynccommand-args-options"><code>child_process.spawnSync()</code></a>. E…
447 …nd-args-options"><code>child_process.spawn()</code></a> or <a href="#child_processspawnsynccommand…
449 <li><a href="#child_processexeccommand-options-callback"><code>child_process.exec()</code></a>: spa…
450 shell, passing the <code>stdout</code> and <code>stderr</code> to a callback function when
452 …-args-options-callback"><code>child_process.execFile()</code></a>: similar to <a href="#child_proc…
455 <li><a href="#child_processforkmodulepath-args-options"><code>child_process.fork()</code></a>: spaw…
458 <li><a href="#child_processexecsynccommand-options"><code>child_process.execSync()</code></a>: a sy…
459 <a href="#child_processexeccommand-options-callback"><code>child_process.exec()</code></a> that wil…
460 <li><a href="#child_processexecfilesyncfile-args-options"><code>child_process.execFileSync()</code>…
461 <a href="#child_processexecfilefile-args-options-callback"><code>child_process.execFile()</code></a…
464 <a href="#synchronous-process-creation">synchronous counterparts</a> may be more convenient. In man…
467 …pan><a class="mark" href="#asynchronous-process-creation" id="asynchronous-process-creation">#</a>…
468 …-args-options"><code>child_process.spawn()</code></a>, <a href="#child_processforkmodulepath-args-…
469 and <a href="#child_processexecfilefile-args-options-callback"><code>child_process.execFile()</code…
471 <p>Each of the methods returns a <a href="#class-childprocess"><code>ChildProcess</code></a> instan…
472 implement the Node.js <a href="events.html#class-eventemitter"><code>EventEmitter</code></a> API, a…
475 …-options-callback"><code>child_process.exec()</code></a> and <a href="#child_processexecfilefile-a…
476 additionally allow for an optional <code>callback</code> function to be specified that is
478 …code>.bat</code> and <code>.cmd</code> files on Windows<span><a class="mark" href="#spawning-bat-a…
479 …tinction between <a href="#child_processexeccommand-options-callback"><code>child_process.exec()</…
480 …child_processexecfilefile-args-options-callback"><code>child_process.execFile()</code></a> can var…
481 …ux, macOS) <a href="#child_processexecfilefile-args-options-callback"><code>child_process.execFile…
483 however, <code>.bat</code> and <code>.cmd</code> files are not executable on their own without a
484 …ched using <a href="#child_processexecfilefile-args-options-callback"><code>child_process.execFile…
485 When running on Windows, <code>.bat</code> and <code>.cmd</code> files can be invoked using
486 <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</code></a> with the <…
487 …ssexeccommand-options-callback"><code>child_process.exec()</code></a>, or by spawning <code>cmd.ex…
488 <code>.cmd</code> file as an argument (which is what the <code>shell</code> option and
489 <a href="#child_processexeccommand-options-callback"><code>child_process.exec()</code></a> do). In …
491 <pre><code class="language-js"><span class="hljs-comment">// On Windows Only...</span>
492 <span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<spa…
493 …-keyword">const</span> bat = <span class="hljs-title function_">spawn</span>(<span class="hljs-str…
495 …-property">stdout</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
496 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
499 …-property">stderr</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
500 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</spa…
503 … class="hljs-title function_">on</span>(<span class="hljs-string">'exit'</span>, <span class="hljs…
504 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
505 });</code> <button class="copy-button">copy</button></pre>
506 <pre><code class="language-js"><span class="hljs-comment">// OR...</span>
507 <span class="hljs-keyword">const</span> { exec, spawn } = <span class="hljs-built_in">require</span…
508 …span class="hljs-title function_">exec</span>(<span class="hljs-string">'my.bat'</span>, <span cla…
509   <span class="hljs-keyword">if</span> (err) {
510 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</spa…
511     <span class="hljs-keyword">return</span>;
513 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
516 <span class="hljs-comment">// Script with spaces in the filename:</span>
517 …-keyword">const</span> bat = <span class="hljs-title function_">spawn</span>(<span class="hljs-str…
518 <span class="hljs-comment">// or:</span>
519 …lass="hljs-title function_">exec</span>(<span class="hljs-string">'"my script.cmd" a b'</span>, <s…
520   <span class="hljs-comment">// ...</span>
521 });</code> <button class="copy-button">copy</button></pre>
522 …code>child_process.exec(command[, options][, callback])</code><span><a class="mark" href="#child_p…
530 <td><p>The <code>cwd</code> option can be a WHATWG <code>URL</code> object using <code>file:</code>…
532 <td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
539 …code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structur…
540 <li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
542 …code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#S…
543 <strong>Default:</strong> <code>process.cwd()</code>.</li>
544 …code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_…
545 …code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
546 <li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struct…
547 <a href="#shell-requirements">Shell requirements</a> and <a href="#default-windows-shell">Default W…
548 <code>'/bin/sh'</code> on Unix, <code>process.env.ComSpec</code> on Windows.</li>
549 <li><code>signal</code> <a href="globals.html#class-abortsignal" class="type">&#x3C;AbortSignal></a…
551 …code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structur…
552 <li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_st…
554 truncated. See caveat at <a href="#maxbuffer-and-unicode"><code>maxBuffer</code> and Unicode</a>.
555 <strong>Default:</strong> <code>1024 * 1024</code>.</li>
556 …code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
557 …code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
558 …code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
559 <li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_…
560 normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
563 <li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referenc…
565 <li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/G…
566 …code>stdout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
567 …code>stderr</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
570 <li>Returns: <a href="child_process.html#class-childprocess" class="type">&#x3C;ChildProcess></a></…
572 <p>Spawns a shell then executes the <code>command</code> within that shell, buffering any
573 generated output. The <code>command</code> string passed to the exec function is processed
575 <a href="https://en.wikipedia.org/wiki/List_of_command-line_interpreters">shell</a>)
577 <pre><code class="language-js"><span class="hljs-keyword">const</span> { exec } = <span class="hljs…
579 <span class="hljs-title function_">exec</span>(<span class="hljs-string">'"/path/to/test file/test.…
580 <span class="hljs-comment">// Double quotes are used so that the space in the path is not interpret…
581 <span class="hljs-comment">// a delimiter of multiple arguments.</span>
583 <span class="hljs-title function_">exec</span>(<span class="hljs-string">'echo "The \\$HOME variabl…
584 …pan class="hljs-comment">// The $HOME variable is escaped in the first instance, but not in the se…
587 <p>If a <code>callback</code> function is provided, it is called with the arguments
588 <code>(error, stdout, stderr)</code>. On success, <code>error</code> will be <code>null</code>. On …
589 <code>error</code> will be an instance of <a href="errors.html#class-error"><code>Error</code></a>.…
590 the exit code of the process. By convention, any exit code other than <code>0</code>
591 indicates an error. <code>error.signal</code> will be the signal that terminated the
593 <p>The <code>stdout</code> and <code>stderr</code> arguments passed to the callback will contain the
595 the output as UTF-8 and pass strings to the callback. The <code>encoding</code> option
597 stderr output. If <code>encoding</code> is <code>'buffer'</code>, or an unrecognized character
598 encoding, <code>Buffer</code> objects will be passed to the callback instead.</p>
599 <pre><code class="language-js"><span class="hljs-keyword">const</span> { exec } = <span class="hljs…
600 …"hljs-title function_">exec</span>(<span class="hljs-string">'cat *.js missing_file | wc -l'</span…
601   <span class="hljs-keyword">if</span> (error) {
602 …="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span cl…
603     <span class="hljs-keyword">return</span>;
605 …ass="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span c…
606 …ss="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span …
607 });</code> <button class="copy-button">copy</button></pre>
608 <p>If <code>timeout</code> is greater than <code>0</code>, the parent will send the signal
609 identified by the <code>killSignal</code> property (the default is <code>'SIGTERM'</code>) if the
610 child runs longer than <code>timeout</code> milliseconds.</p>
611 …"http://man7.org/linux/man-pages/man3/exec.3.html"><code>exec(3)</code></a> POSIX system call, <co…
613 …d is invoked as its <a href="util.html#utilpromisifyoriginal"><code>util.promisify()</code></a>ed …
614 a <code>Promise</code> for an <code>Object</code> with <code>stdout</code> and <code>stderr</code> …
615 <code>ChildProcess</code> instance is attached to the <code>Promise</code> as a <code>child</code> …
616 case of an error (including any error resulting in an exit code other than 0), a
617 rejected promise is returned, with the same <code>error</code> object given in the
618 callback, but with two additional properties <code>stdout</code> and <code>stderr</code>.</p>
619 <pre><code class="language-js"><span class="hljs-keyword">const</span> util = <span class="hljs-bui…
620 …-keyword">const</span> exec = util.<span class="hljs-title function_">promisify</span>(<span class…
622 …ss="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title …
623 …js-keyword">const</span> { stdout, stderr } = <span class="hljs-keyword">await</span> <span class=…
624 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
625 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</spa…
627 <span class="hljs-title function_">lsExample</span>();</code> <button class="copy-button">copy</but…
628 <p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding
629 <code>AbortController</code> is similar to calling <code>.kill()</code> on the child process except
630 the error passed to the callback will be an <code>AbortError</code>:</p>
631 <pre><code class="language-js"><span class="hljs-keyword">const</span> { exec } = <span class="hljs…
632 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span cl…
633 <span class="hljs-keyword">const</span> { signal } = controller;
634 …-keyword">const</span> child = <span class="hljs-title function_">exec</span>(<span class="hljs-st…
635 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</spa…
637 controller.<span class="hljs-title function_">abort</span>();</code> <button class="copy-button">co…
638 …code>child_process.execFile(file[, args][, options][, callback])</code><span><a class="mark" href=…
644 <td><p>The <code>cwd</code> option can be a WHATWG <code>URL</code> object using <code>file:</code>…
648 <td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
655 <li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
656 <li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
657 <li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
659 …code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#S…
660 …code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_…
661 …code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
662 …code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structur…
663 <li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_st…
665 truncated. See caveat at <a href="#maxbuffer-and-unicode"><code>maxBuffer</code> and Unicode</a>.
666 <strong>Default:</strong> <code>1024 * 1024</code>.</li>
667 …code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
668 …code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
669 …code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
670 <li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_…
671 normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
672 <li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/Jav…
673 done on Windows. Ignored on Unix. <strong>Default:</strong> <code>false</code>.</li>
674 …code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
675 <code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
676 shell can be specified as a string. See <a href="#shell-requirements">Shell requirements</a> and
677 <a href="#default-windows-shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</…
678 <li><code>signal</code> <a href="globals.html#class-abortsignal" class="type">&#x3C;AbortSignal></a…
682 <li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referenc…
684 <li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/G…
685 …code>stdout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
686 …code>stderr</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
689 <li>Returns: <a href="child_process.html#class-childprocess" class="type">&#x3C;ChildProcess></a></…
691 …he <code>child_process.execFile()</code> function is similar to <a href="#child_processexeccommand…
693 executable <code>file</code> is spawned directly as a new process making it slightly more
694 efficient than <a href="#child_processexeccommand-options-callback"><code>child_process.exec()</cod…
695 … same options as <a href="#child_processexeccommand-options-callback"><code>child_process.exec()</…
698 <pre><code class="language-js"><span class="hljs-keyword">const</span> { execFile } = <span class="…
699 …-keyword">const</span> child = <span class="hljs-title function_">execFile</span>(<span class="hlj…
700   <span class="hljs-keyword">if</span> (error) {
701     <span class="hljs-keyword">throw</span> error;
703 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
704 });</code> <button class="copy-button">copy</button></pre>
705 <p>The <code>stdout</code> and <code>stderr</code> arguments passed to the callback will contain the
707 the output as UTF-8 and pass strings to the callback. The <code>encoding</code> option
709 stderr output. If <code>encoding</code> is <code>'buffer'</code>, or an unrecognized character
710 encoding, <code>Buffer</code> objects will be passed to the callback instead.</p>
711 …d is invoked as its <a href="util.html#utilpromisifyoriginal"><code>util.promisify()</code></a>ed …
712 a <code>Promise</code> for an <code>Object</code> with <code>stdout</code> and <code>stderr</code> …
713 <code>ChildProcess</code> instance is attached to the <code>Promise</code> as a <code>child</code> …
714 case of an error (including any error resulting in an exit code other than 0), a
715 rejected promise is returned, with the same <code>error</code> object given in the
716 callback, but with two additional properties <code>stdout</code> and <code>stderr</code>.</p>
717 <pre><code class="language-js"><span class="hljs-keyword">const</span> util = <span class="hljs-bui…
718 …-keyword">const</span> execFile = util.<span class="hljs-title function_">promisify</span>(<span c…
719 …ss="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title …
720 …-keyword">const</span> { stdout } = <span class="hljs-keyword">await</span> <span class="hljs-titl…
721 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
723 <span class="hljs-title function_">getVersion</span>();</code> <button class="copy-button">copy</bu…
724 <p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
727 <p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding
728 <code>AbortController</code> is similar to calling <code>.kill()</code> on the child process except
729 the error passed to the callback will be an <code>AbortError</code>:</p>
730 <pre><code class="language-js"><span class="hljs-keyword">const</span> { execFile } = <span class="…
731 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span cl…
732 <span class="hljs-keyword">const</span> { signal } = controller;
733 …-keyword">const</span> child = <span class="hljs-title function_">execFile</span>(<span class="hlj…
734 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</spa…
736 controller.<span class="hljs-title function_">abort</span>();</code> <button class="copy-button">co…
737 …code>child_process.fork(modulePath[, args][, options])</code><span><a class="mark" href="#child_pr…
743 <td><p>The <code>modulePath</code> parameter can be a WHATWG <code>URL</code> object using <code>fi…
745 <td><p>The <code>cwd</code> option can be a WHATWG <code>URL</code> object using <code>file:</code>…
753 <td><p>The <code>serialization</code> option is supported now.</p></td></tr>
755 <td><p>The <code>stdio</code> option can now be a string.</p></td></tr>
757 <td><p>The <code>stdio</code> option is supported now.</p></td></tr>
764 …code>modulePath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
765 <li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
766 <li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
768 …code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#S…
769 <li><code>detached</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
771 <a href="#optionsdetached"><code>options.detached</code></a>).</li>
772 …code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_…
773 <li><code>execPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
774 <li><code>execArgv</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
775 <strong>Default:</strong> <code>process.execArgv</code>.</li>
776 …code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
777 <li><code>serialization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Dat…
778 messages between processes. Possible values are <code>'json'</code> and <code>'advanced'</code>.
779 See <a href="#advanced-serialization">Advanced serialization</a> for more details. <strong>Default:…
780 <li><code>signal</code> <a href="globals.html#class-abortsignal" class="type">&#x3C;AbortSignal></a…
782 …code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
783 process will be killed by timeout or abort signal. <strong>Default:</strong> <code>'SIGTERM'</code>…
784 …code>silent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
786 the <code>'pipe'</code> and <code>'inherit'</code> options for <a href="#child_processspawncommand-…
787 <a href="#optionsstdio"><code>stdio</code></a> for more details. <strong>Default:</strong> <code>fa…
788 …code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Globa…
789 When this option is provided, it overrides <code>silent</code>. If the array variant
790 is used, it must contain exactly one item with value <code>'ipc'</code> or an error
791 will be thrown. For instance <code>[0, 1, 2, 'ipc']</code>.</li>
792 …code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
793 <li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/Jav…
794 done on Windows. Ignored on Unix. <strong>Default:</strong> <code>false</code>.</li>
795 <li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
796 is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
799 <li>Returns: <a href="child_process.html#class-childprocess" class="type">&#x3C;ChildProcess></a></…
801 <p>The <code>child_process.fork()</code> method is a special case of
802 <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</code></a> used speci…
803 …d_processspawncommand-args-options"><code>child_process.spawn()</code></a>, a <a href="#class-chil…
804 returned <a href="#class-childprocess"><code>ChildProcess</code></a> will have an additional commun…
805 built-in that allows messages to be passed back and forth between the parent and
806 child. See <a href="#subprocesssendmessage-sendhandle-options-callback"><code>subprocess.send()</co…
813 <p>By default, <code>child_process.fork()</code> will spawn new Node.js instances using the
814 …ref="process.html#processexecpath"><code>process.execPath</code></a> of the parent process. The <c…
815 <code>options</code> object allows for an alternative execution path to be used.</p>
816 <p>Node.js processes launched with a custom <code>execPath</code> will communicate with the
818 environment variable <code>NODE_CHANNEL_FD</code> on the child process.</p>
819 …"http://man7.org/linux/man-pages/man2/fork.2.html"><code>fork(2)</code></a> POSIX system call, <co…
821 <p>The <code>shell</code> option available in <a href="#child_processspawncommand-args-options"><co…
822 <code>child_process.fork()</code> and will be ignored if set.</p>
823 <p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding
824 <code>AbortController</code> is similar to calling <code>.kill()</code> on the child process except
825 the error passed to the callback will be an <code>AbortError</code>:</p>
826 …code class="language-js"><span class="hljs-keyword">if</span> (process.<span class="hljs-property"…
827   <span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> {
828 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
829   }, <span class="hljs-number">1_000</span>);
830 } <span class="hljs-keyword">else</span> {
831 …<span class="hljs-keyword">const</span> { fork } = <span class="hljs-built_in">require</span>(<spa…
832 …<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span c…
833   <span class="hljs-keyword">const</span> { signal } = controller;
834 …<span class="hljs-keyword">const</span> child = <span class="hljs-title function_">fork</span>(__f…
835 ….<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span clas…
836 …<span class="hljs-comment">// This will be called with err being an AbortError if the controller a…
838 …controller.<span class="hljs-title function_">abort</span>(); <span class="hljs-comment">// Stops …
839 }</code> <button class="copy-button">copy</button></pre>
840 …code>child_process.spawn(command[, args][, options])</code><span><a class="mark" href="#child_proc…
846 <td><p>The <code>cwd</code> option can be a WHATWG <code>URL</code> object using <code>file:</code>…
854 <td><p>The <code>serialization</code> option is supported now.</p></td></tr>
856 <td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
858 <td><p>The <code>argv0</code> option is supported now.</p></td></tr>
860 <td><p>The <code>shell</code> option is supported now.</p></td></tr>
867 <li><code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
868 <li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
869 <li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
871 …code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#S…
872 …code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_…
873 …code>argv0</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
874 process. This will be set to <code>command</code> if not specified.</li>
875 …code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Globa…
876 <a href="#optionsstdio"><code>options.stdio</code></a>).</li>
877 <li><code>detached</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
879 <a href="#optionsdetached"><code>options.detached</code></a>).</li>
880 …code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
881 …code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
882 <li><code>serialization</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Dat…
883 messages between processes. Possible values are <code>'json'</code> and <code>'advanced'</code>.
884 See <a href="#advanced-serialization">Advanced serialization</a> for more details. <strong>Default:…
885 …code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
886 <code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
887 shell can be specified as a string. See <a href="#shell-requirements">Shell requirements</a> and
888 <a href="#default-windows-shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</…
889 <li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/Jav…
890 done on Windows. Ignored on Unix. This is set to <code>true</code> automatically
891 when <code>shell</code> is specified and is CMD. <strong>Default:</strong> <code>false</code>.</li>
892 <li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_…
893 normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
894 <li><code>signal</code> <a href="globals.html#class-abortsignal" class="type">&#x3C;AbortSignal></a…
896 <li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
897 is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
898 …code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
899 process will be killed by timeout or abort signal. <strong>Default:</strong> <code>'SIGTERM'</code>…
902 <li>Returns: <a href="child_process.html#class-childprocess" class="type">&#x3C;ChildProcess></a></…
904 <p>The <code>child_process.spawn()</code> method spawns a new process using the given
905 <code>command</code>, with command-line arguments in <code>args</code>. If omitted, <code>args</cod…
907 <p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
911 <pre><code class="language-js"><span class="hljs-keyword">const</span> defaults = {
912   <span class="hljs-attr">cwd</span>: <span class="hljs-literal">undefined</span>,
913   <span class="hljs-attr">env</span>: process.<span class="hljs-property">env</span>,
914 };</code> <button class="copy-button">copy</button></pre>
915 <p>Use <code>cwd</code> to specify the working directory from which the process is spawned.
917 but the path does not exist, the child process emits an <code>ENOENT</code> error
918 and exits immediately. <code>ENOENT</code> is also emitted when the command
920 <p>Use <code>env</code> to specify environment variables that will be visible to the new
921 process, the default is <a href="process.html#processenv"><code>process.env</code></a>.</p>
922 <p><code>undefined</code> values in <code>env</code> will be ignored.</p>
923 <p>Example of running <code>ls -lh /usr</code>, capturing <code>stdout</code>, <code>stderr</code>,…
924 exit code:</p>
925 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
926 …-keyword">const</span> ls = <span class="hljs-title function_">spawn</span>(<span class="hljs-stri…
928 …-property">stdout</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
929 …ass="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span c…
932 …-property">stderr</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
933 …ss="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span …
936 … class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hlj…
937 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
938 });</code> <button class="copy-button">copy</button></pre>
939 <p>Example: A very elaborate way to run <code>ps ax | grep ssh</code></p>
940 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
941 …ass="hljs-keyword">const</span> ps = <span class="hljs-title function_">spawn</span>(<span class="…
942 …s="hljs-keyword">const</span> grep = <span class="hljs-title function_">spawn</span>(<span class="…
944 …-property">stdout</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
945 …grep.<span class="hljs-property">stdin</span>.<span class="hljs-title function_">write</span>(data…
948 …-property">stderr</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
949 …="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span cl…
952 … class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hlj…
953   <span class="hljs-keyword">if</span> (code !== <span class="hljs-number">0</span>) {
954 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
956   grep.<span class="hljs-property">stdin</span>.<span class="hljs-title function_">end</span>();
959 …-property">stdout</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
960 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
963 …-property">stderr</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
964 …"hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span cla…
967 … class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hlj…
968   <span class="hljs-keyword">if</span> (code !== <span class="hljs-number">0</span>) {
969 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
971 });</code> <button class="copy-button">copy</button></pre>
972 <p>Example of checking for failed <code>spawn</code>:</p>
973 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
974 <span class="hljs-keyword">const</span> subprocess = <span class="hljs-title function_">spawn</span…
976 ….<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span clas…
977 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</spa…
978 });</code> <button class="copy-button">copy</button></pre>
979 <p>Certain platforms (macOS, Linux) will use the value of <code>argv[0]</code> for the process
980 title while others (Windows, SunOS) will use <code>command</code>.</p>
981 <p>Node.js overwrites <code>argv[0]</code> with <code>process.execPath</code> on startup, so
982 <code>process.argv[0]</code> in a Node.js child process will not match the <code>argv0</code>
983 parameter passed to <code>spawn</code> from the parent. Retrieve it with the
984 <code>process.argv0</code> property instead.</p>
985 <p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding
986 <code>AbortController</code> is similar to calling <code>.kill()</code> on the child process except
987 the error passed to the callback will be an <code>AbortError</code>:</p>
988 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
989 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span cl…
990 <span class="hljs-keyword">const</span> { signal } = controller;
991 …s="hljs-keyword">const</span> grep = <span class="hljs-title function_">spawn</span>(<span class="…
992 ….<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span clas…
993 …<span class="hljs-comment">// This will be called with err being an AbortError if the controller a…
995 …pan class="hljs-title function_">abort</span>(); <span class="hljs-comment">// Stops the child pro…
996 <h5><code>options.detached</code><span><a class="mark" href="#optionsdetached" id="optionsdetached"…
1000 <p>On Windows, setting <code>options.detached</code> to <code>true</code> makes it possible for the
1004 <p>On non-Windows platforms, if <code>options.detached</code> is set to <code>true</code>, the child
1007 …ached or not. See <a href="http://man7.org/linux/man-pages/man2/setsid.2.html"><code>setsid(2)</co…
1009 parent from waiting for a given <code>subprocess</code> to exit, use the
1010 <code>subprocess.unref()</code> method. Doing so will cause the parent's event loop to not
1014 <p>When using the <code>detached</code> option to start a long-running process, the process
1016 provided with a <code>stdio</code> configuration that is not connected to the parent.
1017 If the parent's <code>stdio</code> is inherited, the child will remain attached to the
1019 <p>Example of a long-running process, by detaching and also ignoring its parent
1020 <code>stdio</code> file descriptors, in order to ignore the parent's termination:</p>
1021 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1023 …-keyword">const</span> subprocess = <span class="hljs-title function_">spawn</span>(process.<span …
1024   <span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
1025   <span class="hljs-attr">stdio</span>: <span class="hljs-string">'ignore'</span>,
1028 subprocess.<span class="hljs-title function_">unref</span>();</code> <button class="copy-button">co…
1030 <pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built…
1031 <span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<spa…
1032 …ljs-keyword">const</span> out = fs.<span class="hljs-title function_">openSync</span>(<span class=…
1033 …ljs-keyword">const</span> err = fs.<span class="hljs-title function_">openSync</span>(<span class=…
1035 <span class="hljs-keyword">const</span> subprocess = <span class="hljs-title function_">spawn</span…
1036   <span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
1037   <span class="hljs-attr">stdio</span>: [ <span class="hljs-string">'ignore'</span>, out, err ],
1040 subprocess.<span class="hljs-title function_">unref</span>();</code> <button class="copy-button">co…
1041 <h5><code>options.stdio</code><span><a class="mark" href="#optionsstdio" id="optionsstdio">#</a></s…
1047 <td><p>Added the <code>overlapped</code> stdio flag.</p></td></tr>
1049 <td><p>The value <code>0</code> is now accepted as a file descriptor.</p></td></tr>
1055 <p>The <code>options.stdio</code> option is used to configure the pipes that are established
1057 and stderr are redirected to corresponding <a href="#subprocessstdin"><code>subprocess.stdin</code>…
1058 …a href="#subprocessstdout"><code>subprocess.stdout</code></a>, and <a href="#subprocessstderr"><co…
1059 <a href="#class-childprocess"><code>ChildProcess</code></a> object. This is equivalent to setting t…
1060 equal to <code>['pipe', 'pipe', 'pipe']</code>.</p>
1061 <p>For convenience, <code>options.stdio</code> may be one of the following strings:</p>
1063 <li><code>'pipe'</code>: equivalent to <code>['pipe', 'pipe', 'pipe']</code> (the default)</li>
1064 <li><code>'overlapped'</code>: equivalent to <code>['overlapped', 'overlapped', 'overlapped']</code…
1065 <li><code>'ignore'</code>: equivalent to <code>['ignore', 'ignore', 'ignore']</code></li>
1066 <li><code>'inherit'</code>: equivalent to <code>['inherit', 'inherit', 'inherit']</code> or <code>[…
1068 <p>Otherwise, the value of <code>options.stdio</code> is an array where each index corresponds
1074 <p><code>'pipe'</code>: Create a pipe between the child process and the parent process.
1076 <code>child_process</code> object as <a href="#subprocessstdio"><code>subprocess.stdio[fd]</code></…
1077 …fds 0, 1, and 2 are also available as <a href="#subprocessstdin"><code>subprocess.stdin</code></a>,
1078 <a href="#subprocessstdout"><code>subprocess.stdout</code></a> and <a href="#subprocessstderr"><cod…
1081 e.g. <code>/dev/fd/2</code> or <code>/dev/stdout</code>.</p>
1084 <p><code>'overlapped'</code>: Same as <code>'pipe'</code> except that the <code>FILE_FLAG_OVERLAPPE…
1087 <a href="https://docs.microsoft.com/en-us/windows/win32/fileio/synchronous-and-asynchronous-i-o">do…
1088 for more details. This is exactly the same as <code>'pipe'</code> on non-Windows
1092 <p><code>'ipc'</code>: Create an IPC channel for passing messages/file descriptors
1093 between parent and child. A <a href="#class-childprocess"><code>ChildProcess</code></a> may have at…
1095 <a href="#subprocesssendmessage-sendhandle-options-callback"><code>subprocess.send()</code></a> met…
1096 … enable <a href="process.html#processsendmessage-sendhandle-options-callback"><code>process.send()…
1097 …essdisconnect"><code>process.disconnect()</code></a> methods, as well as <a href="process.html#eve…
1098 <a href="process.html#event-message"><code>'message'</code></a> events within the child.</p>
1099 …er than <a href="process.html#processsendmessage-sendhandle-options-callback"><code>process.send()…
1104 <p><code>'ignore'</code>: Instructs Node.js to ignore the fd in the child. While Node.js
1106 to <code>'ignore'</code> will cause Node.js to open <code>/dev/null</code> and attach it to the
1110 <p><code>'inherit'</code>: Pass through the corresponding stdio stream to/from the
1112 <code>process.stdin</code>, <code>process.stdout</code>, and <code>process.stderr</code>, respectiv…
1113 any other position, equivalent to <code>'ignore'</code>.</p>
1119 corresponds to the index in the <code>stdio</code> array. The stream must have an
1120 underlying descriptor (file streams do not until the <code>'open'</code> event has
1130 <p><code>null</code>, <code>undefined</code>: Use default value. For stdio fds 0, 1, and 2 (in other
1132 default is <code>'ignore'</code>.</p>
1135 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1137 <span class="hljs-comment">// Child will use parent's stdios.</span>
1138 …lass="hljs-title function_">spawn</span>(<span class="hljs-string">'prg'</span>, [], { <span class…
1140 <span class="hljs-comment">// Spawn child sharing only stderr.</span>
1141 …-title function_">spawn</span>(<span class="hljs-string">'prg'</span>, [], { <span class="hljs-att…
1143 <span class="hljs-comment">// Open an extra fd=4, to interact with programs presenting a</span>
1144 <span class="hljs-comment">// startd-style interface.</span>
1145 …-title function_">spawn</span>(<span class="hljs-string">'prg'</span>, [], { <span class="hljs-att…
1148 is launched with the IPC channel unreferenced (using <code>unref()</code>) until the
1149 …sters an event handler for the <a href="process.html#event-disconnect"><code>'disconnect'</code></…
1150 or the <a href="process.html#event-message"><code>'message'</code></a> event. This allows the child…
1152 <p>On Unix-like operating systems, the <a href="#child_processspawncommand-args-options"><code>chil…
1155 <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</code></a> calls to b…
1157 …mand-options-callback"><code>child_process.exec()</code></a> and <a href="#child_processforkmodule…
1158 …<span><a class="mark" href="#synchronous-process-creation" id="synchronous-process-creation">#</a>…
1159 …mmand-args-options"><code>child_process.spawnSync()</code></a>, <a href="#child_processexecsynccom…
1160 <a href="#child_processexecfilesyncfile-args-options"><code>child_process.execFileSync()</code></a>…
1161 Node.js event loop, pausing execution of any additional code until the spawned
1163 <p>Blocking calls like these are mostly useful for simplifying general-purpose
1166 …code>child_process.execFileSync(file[, args][, options])</code><span><a class="mark" href="#child_…
1172 <td><p>The <code>cwd</code> option can be a WHATWG <code>URL</code> object using <code>file:</code>…
1174 <td><p>The <code>input</code> option can now be any <code>TypedArray</code> or a <code>DataView</co…
1176 <td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
1178 <td><p>The <code>input</code> option can now be a <code>Uint8Array</code>.</p></td></tr>
1180 <td><p>The <code>encoding</code> option can now explicitly be set to <code>buffer</code>.</p></td><…
1187 <li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
1188 <li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
1189 <li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
1191 …code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#S…
1192 …code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1194 <code>stdio[0]</code>.</li>
1195 …code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1196 be output to the parent process' stderr unless <code>stdio</code> is specified.
1197 <strong>Default:</strong> <code>'pipe'</code>.</li>
1198 …code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_…
1199 …code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
1200 …code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
1201 <li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
1202 is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
1203 …code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
1204 process will be killed. <strong>Default:</strong> <code>'SIGTERM'</code>.</li>
1205 <li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_st…
1207 <a href="#maxbuffer-and-unicode"><code>maxBuffer</code> and Unicode</a>. <strong>Default:</strong> …
1208 <li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
1209 <strong>Default:</strong> <code>'buffer'</code>.</li>
1210 <li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_…
1211 normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
1212 …code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1213 <code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
1214 shell can be specified as a string. See <a href="#shell-requirements">Shell requirements</a> and
1215 <a href="#default-windows-shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</…
1218 …eturns: <a href="buffer.html#class-buffer" class="type">&#x3C;Buffer></a> | <a href="https://devel…
1220 <p>The <code>child_process.execFileSync()</code> method is generally identical to
1221 <a href="#child_processexecfilefile-args-options-callback"><code>child_process.execFile()</code></a…
1223 encountered and <code>killSignal</code> is sent, the method won't return until the process
1225 <p>If the child process intercepts and handles the <code>SIGTERM</code> signal and
1228 <p>If the process times out or has a non-zero exit code, this method will throw an
1229 <a href="errors.html#class-error"><code>Error</code></a> that will include the full result of the u…
1230 <a href="#child_processspawnsynccommand-args-options"><code>child_process.spawnSync()</code></a>.</…
1231 <p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
1234 …code>child_process.execSync(command[, options])</code><span><a class="mark" href="#child_processex…
1240 <td><p>The <code>cwd</code> option can be a WHATWG <code>URL</code> object using <code>file:</code>…
1242 <td><p>The <code>input</code> option can now be any <code>TypedArray</code> or a <code>DataView</co…
1244 <td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
1246 <td><p>The <code>input</code> option can now be a <code>Uint8Array</code>.</p></td></tr>
1253 <li><code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
1254 <li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
1256 …code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#S…
1257 …code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1259 <code>stdio[0]</code>.</li>
1260 …code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1261 be output to the parent process' stderr unless <code>stdio</code> is specified.
1262 <strong>Default:</strong> <code>'pipe'</code>.</li>
1263 …code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_…
1264 <li><code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struct…
1265 <a href="#shell-requirements">Shell requirements</a> and <a href="#default-windows-shell">Default W…
1266 <code>'/bin/sh'</code> on Unix, <code>process.env.ComSpec</code> on Windows.</li>
1267 …code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
1268 …code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
1269 <li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
1270 is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
1271 …code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
1272 process will be killed. <strong>Default:</strong> <code>'SIGTERM'</code>.</li>
1273 <li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_st…
1275 truncated. See caveat at <a href="#maxbuffer-and-unicode"><code>maxBuffer</code> and Unicode</a>.
1276 <strong>Default:</strong> <code>1024 * 1024</code>.</li>
1277 <li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
1278 <strong>Default:</strong> <code>'buffer'</code>.</li>
1279 <li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_…
1280 normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
1283 …eturns: <a href="buffer.html#class-buffer" class="type">&#x3C;Buffer></a> | <a href="https://devel…
1285 <p>The <code>child_process.execSync()</code> method is generally identical to
1286 <a href="#child_processexeccommand-options-callback"><code>child_process.exec()</code></a> with the…
1288 and <code>killSignal</code> is sent, the method won't return until the process has
1289 completely exited. If the child process intercepts and handles the <code>SIGTERM</code>
1292 <p>If the process times out or has a non-zero exit code, this method will throw.
1293 The <a href="errors.html#class-error"><code>Error</code></a> object will contain the entire result …
1294 <a href="#child_processspawnsynccommand-args-options"><code>child_process.spawnSync()</code></a>.</…
1297 …code>child_process.spawnSync(command[, args][, options])</code><span><a class="mark" href="#child_…
1303 <td><p>The <code>cwd</code> option can be a WHATWG <code>URL</code> object using <code>file:</code>…
1305 <td><p>The <code>input</code> option can now be any <code>TypedArray</code> or a <code>DataView</co…
1307 <td><p>The <code>windowsHide</code> option is supported now.</p></td></tr>
1309 <td><p>The <code>input</code> option can now be a <code>Uint8Array</code>.</p></td></tr>
1311 <td><p>The <code>shell</code> option is supported now.</p></td></tr>
1313 <td><p>The <code>encoding</code> option can now explicitly be set to <code>buffer</code>.</p></td><…
1320 <li><code>command</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
1321 <li><code>args</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structu…
1322 <li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
1324 …code>cwd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#S…
1325 …code>input</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1327 <code>stdio[0]</code>.</li>
1328 …code>argv0</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1329 process. This will be set to <code>command</code> if not specified.</li>
1330 …code>stdio</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1331 …code>env</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_…
1332 …code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
1333 …code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#N…
1334 <li><code>timeout</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_stru…
1335 is allowed to run. <strong>Default:</strong> <code>undefined</code>.</li>
1336 …code>killSignal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
1337 process will be killed. <strong>Default:</strong> <code>'SIGTERM'</code>.</li>
1338 <li><code>maxBuffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_st…
1340 truncated. See caveat at <a href="#maxbuffer-and-unicode"><code>maxBuffer</code> and Unicode</a>.
1341 <strong>Default:</strong> <code>1024 * 1024</code>.</li>
1342 <li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
1343 <strong>Default:</strong> <code>'buffer'</code>.</li>
1344 …code>shell</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures…
1345 <code>'/bin/sh'</code> on Unix, and <code>process.env.ComSpec</code> on Windows. A different
1346 shell can be specified as a string. See <a href="#shell-requirements">Shell requirements</a> and
1347 <a href="#default-windows-shell">Default Windows shell</a>. <strong>Default:</strong> <code>false</…
1348 <li><code>windowsVerbatimArguments</code> <a href="https://developer.mozilla.org/en-US/docs/Web/Jav…
1349 done on Windows. Ignored on Unix. This is set to <code>true</code> automatically
1350 when <code>shell</code> is specified and is CMD. <strong>Default:</strong> <code>false</code>.</li>
1351 <li><code>windowsHide</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_…
1352 normally be created on Windows systems. <strong>Default:</strong> <code>false</code>.</li>
1355 <li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Obje…
1357 <li><code>pid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structur…
1358 <li><code>output</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/…
1359 …code>stdout</code> <a href="buffer.html#class-buffer" class="type">&#x3C;Buffer></a> | <a href="ht…
1360 …code>stderr</code> <a href="buffer.html#class-buffer" class="type">&#x3C;Buffer></a> | <a href="ht…
1361 …code>status</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
1363 …code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
1365 <li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/G…
1369 <p>The <code>child_process.spawnSync()</code> method is generally identical to
1370 <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</code></a> with the e…
1372 and <code>killSignal</code> is sent, the method won't return until the process has
1373 completely exited. If the process intercepts and handles the <code>SIGTERM</code> signal
1376 <p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this
1379 …ction><h3>Class: <code>ChildProcess</code><span><a class="mark" href="#class-childprocess" id="cla…
1384 <li>Extends: <a href="events.html#class-eventemitter" class="type">&#x3C;EventEmitter></a></li>
1386 <p>Instances of the <code>ChildProcess</code> represent spawned child processes.</p>
1387 <p>Instances of <code>ChildProcess</code> are not intended to be created directly. Rather,
1388 …ommand-args-options"><code>child_process.spawn()</code></a>, <a href="#child_processexeccommand-op…
1389 …-args-options-callback"><code>child_process.execFile()</code></a>, or <a href="#child_processforkm…
1390 instances of <code>ChildProcess</code>.</p>
1391 <h4>Event: <code>'close'</code><span><a class="mark" href="#event-close" id="event-close">#</a></sp…
1396 …code>code</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#…
1397 <li><code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
1399 <p>The <code>'close'</code> event is emitted after a process has ended <em>and</em> the stdio
1401 <a href="#event-exit"><code>'exit'</code></a> event, since multiple processes might share the same …
1402 streams. The <code>'close'</code> event will always emit after <a href="#event-exit"><code>'exit'</…
1403 already emitted, or <a href="#event-error"><code>'error'</code></a> if the child failed to spawn.</…
1404 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1405 …-keyword">const</span> ls = <span class="hljs-title function_">spawn</span>(<span class="hljs-stri…
1407 …-property">stdout</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
1408 …ass="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span c…
1411 … class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hlj…
1412 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
1415 … class="hljs-title function_">on</span>(<span class="hljs-string">'exit'</span>, <span class="hljs…
1416 …-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hlj…
1417 });</code> <button class="copy-button">copy</button></pre>
1418 <h4>Event: <code>'disconnect'</code><span><a class="mark" href="#event-disconnect" id="event-discon…
1422 <p>The <code>'disconnect'</code> event is emitted after calling the
1423 <a href="#subprocessdisconnect"><code>subprocess.disconnect()</code></a> method in parent process or
1424 <a href="process.html#processdisconnect"><code>process.disconnect()</code></a> in child process. Af…
1425 …d or receive messages, and the <a href="#subprocessconnected"><code>subprocess.connected</code></a>
1426 property is <code>false</code>.</p>
1427 <h4>Event: <code>'error'</code><span><a class="mark" href="#event-error" id="event-error">#</a></sp…
1429 <li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Glo…
1431 <p>The <code>'error'</code> event is emitted whenever:</p>
1436 <li>The child process was aborted via the <code>signal</code> option.</li>
1438 <p>The <code>'exit'</code> event may or may not fire after an error has occurred. When
1439 listening to both the <code>'exit'</code> and <code>'error'</code> events, guard
1441 …illsignal"><code>subprocess.kill()</code></a> and <a href="#subprocesssendmessage-sendhandle-optio…
1442 <h4>Event: <code>'exit'</code><span><a class="mark" href="#event-exit" id="event-exit">#</a></span>…
1447 …code>code</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#…
1448 <li><code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_struc…
1450 <p>The <code>'exit'</code> event is emitted after the child process ends. If the process
1451 exited, <code>code</code> is the final exit code of the process, otherwise <code>null</code>. If the
1452 process terminated due to receipt of a signal, <code>signal</code> is the string name of
1453 the signal, otherwise <code>null</code>. One of the two will always be non-<code>null</code>.</p>
1454 <p>When the <code>'exit'</code> event is triggered, child process stdio streams might still be
1456 <p>Node.js establishes signal handlers for <code>SIGINT</code> and <code>SIGTERM</code> and Node.js
1459 re-raise the handled signal.</p>
1460 <p>See <a href="http://man7.org/linux/man-pages/man2/waitpid.2.html"><code>waitpid(2)</code></a>.</…
1461 <h4>Event: <code>'message'</code><span><a class="mark" href="#event-message" id="event-message">#</…
1466 <li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
1467 …code>sendHandle</code> <a href="net.html#serverlistenhandle-backlog-callback" class="type">&#x3C;H…
1470 <p>The <code>'message'</code> event is triggered when a child process uses
1471 <a href="process.html#processsendmessage-sendhandle-options-callback"><code>process.send()</code></…
1474 <p>If the <code>serialization</code> option was set to <code>'advanced'</code> used when spawning t…
1475 child process, the <code>message</code> argument can contain data that JSON is not able
1477 See <a href="#advanced-serialization">Advanced serialization</a> for more details.</p>
1478 <h4>Event: <code>'spawn'</code><span><a class="mark" href="#event-spawn" id="event-spawn">#</a></sp…
1482 <p>The <code>'spawn'</code> event is emitted once the child process has spawned successfully.
1483 If the child process does not spawn successfully, the <code>'spawn'</code> event is not
1484 emitted and the <code>'error'</code> event is emitted instead.</p>
1485 <p>If emitted, the <code>'spawn'</code> event comes before all other events and before any
1486 data is received via <code>stdout</code> or <code>stderr</code>.</p>
1487 <p>The <code>'spawn'</code> event will fire regardless of whether an error occurs <strong>within</s…
1488 the spawned process. For example, if <code>bash some-command</code> spawns successfully,
1489 the <code>'spawn'</code> event will fire, though <code>bash</code> may fail to spawn <code>some-com…
1490 This caveat also applies when using <code>{ shell: true }</code>.</p>
1491 <h4><code>subprocess.channel</code><span><a class="mark" href="#subprocesschannel" id="subprocessch…
1504 <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Objec…
1506 <p>The <code>subprocess.channel</code> property is a reference to the child's IPC channel. If
1507 no IPC channel exists, this property is <code>undefined</code>.</p>
1508 <h5><code>subprocess.channel.ref()</code><span><a class="mark" href="#subprocesschannelref" id="sub…
1513 running if <code>.unref()</code> has been called before.</p>
1514 <h5><code>subprocess.channel.unref()</code><span><a class="mark" href="#subprocesschannelunref" id=…
1520 <h4><code>subprocess.connected</code><span><a class="mark" href="#subprocessconnected" id="subproce…
1525 …-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&#x3C;boolean></a> Set to <code…
1527 <p>The <code>subprocess.connected</code> property indicates whether it is still possible to
1528 send and receive messages from a child process. When <code>subprocess.connected</code> is
1529 <code>false</code>, it is no longer possible to send or receive messages.</p>
1530 <h4><code>subprocess.disconnect()</code><span><a class="mark" href="#subprocessdisconnect" id="subp…
1536 this method the <code>subprocess.connected</code> and <code>process.connected</code> properties in
1537 both the parent and child (respectively) will be set to <code>false</code>, and it will be
1539 <p>The <code>'disconnect'</code> event will be emitted when there are no messages in the
1541 calling <code>subprocess.disconnect()</code>.</p>
1543 …f="#child_processforkmodulepath-args-options"><code>child_process.fork()</code></a>), the <code>pr…
1545 <h4><code>subprocess.exitCode</code><span><a class="mark" href="#subprocessexitcode" id="subprocess…
1547 <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" c…
1549 <p>The <code>subprocess.exitCode</code> property indicates the exit code of the child process.
1550 If the child process is still running, the field will be <code>null</code>.</p>
1551 <h4><code>subprocess.kill([signal])</code><span><a class="mark" href="#subprocesskillsignal" id="su…
1556 …code>signal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structure…
1557 <li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boole…
1559 <p>The <code>subprocess.kill()</code> method sends a signal to the child process. If no
1560 argument is given, the process will be sent the <code>'SIGTERM'</code> signal. See
1561 ….org/linux/man-pages/man7/signal.7.html"><code>signal(7)</code></a> for a list of available signal…
1562 <a href="http://man7.org/linux/man-pages/man2/kill.2.html"><code>kill(2)</code></a> succeeds, and <…
1563 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1564 …s="hljs-keyword">const</span> grep = <span class="hljs-title function_">spawn</span>(<span class="…
1566 … class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hlj…
1567 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(
1568 …<span class="hljs-string">`child process terminated due to receipt of signal <span class="hljs-sub…
1571 <span class="hljs-comment">// Send SIGHUP to process.</span>
1572 grep.<span class="hljs-title function_">kill</span>(<span class="hljs-string">'SIGHUP'</span>);</co…
1573 <p>The <a href="#class-childprocess"><code>ChildProcess</code></a> object may emit an <a href="#eve…
1578 <p>While the function is called <code>kill</code>, the signal delivered to the child process
1580 <p>See <a href="http://man7.org/linux/man-pages/man2/kill.2.html"><code>kill(2)</code></a> for refe…
1581 <p>On Windows, where POSIX signals do not exist, the <code>signal</code> argument will be
1583 <code>'SIGKILL'</code>).
1584 See <a href="process.html#signal-events">Signal Events</a> for more details.</p>
1587 new process in a shell or with the use of the <code>shell</code> option of <code>ChildProcess</code…
1588 <pre><code class="language-js"><span class="hljs-meta">'use strict'</span>;
1589 <span class="hljs-keyword">const</span> { spawn } = <span class="hljs-built_in">require</span>(<spa…
1591 <span class="hljs-keyword">const</span> subprocess = <span class="hljs-title function_">spawn</span…
1592   <span class="hljs-string">'sh'</span>,
1594     <span class="hljs-string">'-c'</span>,
1595     <span class="hljs-string">`node -e "setInterval(() => {
1599 … class="hljs-attr">stdio</span>: [<span class="hljs-string">'inherit'</span>, <span class="hljs-st…
1603 <span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> {
1604 …subprocess.<span class="hljs-title function_">kill</span>(); <span class="hljs-comment">// Does no…
1605 }, <span class="hljs-number">2000</span>);</code> <button class="copy-button">copy</button></pre>
1606 <h4><code>subprocess[Symbol.dispose]()</code><span><a class="mark" href="#subprocesssymboldispose" …
1610 …tability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experime…
1611 <p>Calls <a href="#subprocesskillsignal"><code>subprocess.kill()</code></a> with <code>'SIGTERM'</c…
1612 <h4><code>subprocess.killed</code><span><a class="mark" href="#subprocesskilled" id="subprocesskill…
1617 …/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&#x3C;boolean></a> Set to <c…
1620 <p>The <code>subprocess.killed</code> property indicates whether the child process
1621 successfully received a signal from <code>subprocess.kill()</code>. The <code>killed</code> property
1623 <h4><code>subprocess.pid</code><span><a class="mark" href="#subprocesspid" id="subprocesspid">#</a>…
1628 …zilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type">&#x3C;integer></a> |…
1631 fails to spawn due to errors, then the value is <code>undefined</code> and <code>error</code> is
1633 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1634 …s="hljs-keyword">const</span> grep = <span class="hljs-title function_">spawn</span>(<span class="…
1636 …ljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="…
1637 grep.<span class="hljs-property">stdin</span>.<span class="hljs-title function_">end</span>();</cod…
1638 <h4><code>subprocess.ref()</code><span><a class="mark" href="#subprocessref" id="subprocessref">#</…
1642 <p>Calling <code>subprocess.ref()</code> after making a call to <code>subprocess.unref()</code> will
1645 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1647 …-keyword">const</span> subprocess = <span class="hljs-title function_">spawn</span>(process.<span …
1648   <span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
1649   <span class="hljs-attr">stdio</span>: <span class="hljs-string">'ignore'</span>,
1652 subprocess.<span class="hljs-title function_">unref</span>();
1653 subprocess.<span class="hljs-title function_">ref</span>();</code> <button class="copy-button">copy…
1654 …code>subprocess.send(message[, sendHandle[, options]][, callback])</code><span><a class="mark" hre…
1660 <td><p>The <code>options</code> parameter, and the <code>keepOpen</code> option in particular, is s…
1664 <td><p>The <code>callback</code> parameter is supported now.</p></td></tr>
1671 <li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference…
1672 <li><code>sendHandle</code> <a href="net.html#serverlistenhandle-backlog-callback" class="type">&#x…
1673 …code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Glo…
1674 parameterize the sending of certain types of handles. <code>options</code> supports
1677 <li><code>keepOpen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_str…
1678 <code>net.Socket</code>. When <code>true</code>, the socket is kept open in the sending process.
1679 <strong>Default:</strong> <code>false</code>.</li>
1682 <li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referenc…
1683 <li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boole…
1686 …ef="#child_processforkmodulepath-args-options"><code>child_process.fork()</code></a>), the <code>s…
1688 … messages can be received via the <a href="process.html#event-message"><code>'message'</code></a> …
1692 <pre><code class="language-js"><span class="hljs-keyword">const</span> cp = <span class="hljs-built…
1693 …pan class="hljs-keyword">const</span> n = cp.<span class="hljs-title function_">fork</span>(<span …
1695 …<span class="hljs-title function_">on</span>(<span class="hljs-string">'message'</span>, <span cla…
1696 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
1699 <span class="hljs-comment">// Causes the child to print: CHILD got message: { hello: 'world' }</spa…
1700 …"hljs-title function_">send</span>({ <span class="hljs-attr">hello</span>: <span class="hljs-strin…
1701 <p>And then the child script, <code>'sub.js'</code> might look like this:</p>
1702 …code class="language-js">process.<span class="hljs-title function_">on</span>(<span class="hljs-st…
1703 …<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>…
1706 <span class="hljs-comment">// Causes the parent to print: PARENT got message: { foo: 'bar', baz: nu…
1707 …-title function_">send</span>({ <span class="hljs-attr">foo</span>: <span class="hljs-string">'bar…
1708 … have a <a href="process.html#processsendmessage-sendhandle-options-callback"><code>process.send()…
1710 <p>There is a special case when sending a <code>{cmd: 'NODE_foo'}</code> message. Messages
1711 containing a <code>NODE_</code> prefix in the <code>cmd</code> property are reserved for use within
1712 … will not be emitted in the child's <a href="process.html#event-message"><code>'message'</code></a>
1714 <code>'internalMessage'</code> event and are consumed internally by Node.js.
1716 <code>'internalMessage'</code> events as it is subject to change without notice.</p>
1717 <p>The optional <code>sendHandle</code> argument that may be passed to <code>subprocess.send()</cod…
1720 registered on the <a href="process.html#event-message"><code>'message'</code></a> event. Any data t…
1722 <p>The optional <code>callback</code> is a function that is invoked after the message is
1724 single argument: <code>null</code> on success, or an <a href="errors.html#class-error"><code>Error<…
1725 <p>If no <code>callback</code> function is provided and the message cannot be sent, an
1726 <code>'error'</code> event will be emitted by the <a href="#class-childprocess"><code>ChildProcess<…
1728 <p><code>subprocess.send()</code> will return <code>false</code> if the channel has closed or when …
1730 more. Otherwise, the method returns <code>true</code>. The <code>callback</code> function can be
1732 …span><a class="mark" href="#example-sending-a-server-object" id="example-sending-a-server-object">…
1733 <p>The <code>sendHandle</code> argument can be used, for instance, to pass the handle of
1735 …code class="language-js"><span class="hljs-keyword">const</span> subprocess = <span class="hljs-bu…
1737 <span class="hljs-comment">// Open up the server object and send the handle.</span>
1738 …s="hljs-keyword">const</span> server = <span class="hljs-built_in">require</span>(<span class="hlj…
1739 …pan class="hljs-title function_">on</span>(<span class="hljs-string">'connection'</span>, <span cl…
1740 …socket.<span class="hljs-title function_">end</span>(<span class="hljs-string">'handled by parent'…
1742 server.<span class="hljs-title function_">listen</span>(<span class="hljs-number">1337</span>, <spa…
1743 …subprocess.<span class="hljs-title function_">send</span>(<span class="hljs-string">'server'</span…
1744 });</code> <button class="copy-button">copy</button></pre>
1746 …code class="language-js">process.<span class="hljs-title function_">on</span>(<span class="hljs-st…
1747   <span class="hljs-keyword">if</span> (m === <span class="hljs-string">'server'</span>) {
1748 …pan class="hljs-title function_">on</span>(<span class="hljs-string">'connection'</span>, <span cl…
1749 …socket.<span class="hljs-title function_">end</span>(<span class="hljs-string">'handled by child'<…
1752 });</code> <button class="copy-button">copy</button></pre>
1755 <p>While the example above uses a server created using the <code>node:net</code> module,
1756 <code>node:dgram</code> module servers use exactly the same workflow with the exceptions of
1757 listening on a <code>'message'</code> event instead of <code>'connection'</code> and using
1758 <code>server.bind()</code> instead of <code>server.listen()</code>. This is, however, only
1760 …span><a class="mark" href="#example-sending-a-socket-object" id="example-sending-a-socket-object">…
1761 <p>Similarly, the <code>sendHandler</code> argument can be used to pass the handle of a
1764 <pre><code class="language-js"><span class="hljs-keyword">const</span> { fork } = <span class="hljs…
1765 …js-keyword">const</span> normal = <span class="hljs-title function_">fork</span>(<span class="hljs…
1766 …js-keyword">const</span> special = <span class="hljs-title function_">fork</span>(<span class="hlj…
1768 <span class="hljs-comment">// Open up the server and send sockets to child. Use pauseOnConnect to p…
1769 <span class="hljs-comment">// the sockets from being read before they are sent to the child process…
1770 …-keyword">const</span> server = <span class="hljs-built_in">require</span>(<span class="hljs-strin…
1771 …pan class="hljs-title function_">on</span>(<span class="hljs-string">'connection'</span>, <span cl…
1773   <span class="hljs-comment">// If this is special priority...</span>
1774 …<span class="hljs-keyword">if</span> (socket.<span class="hljs-property">remoteAddress</span> === …
1775 …special.<span class="hljs-title function_">send</span>(<span class="hljs-string">'socket'</span>, …
1776     <span class="hljs-keyword">return</span>;
1778   <span class="hljs-comment">// This is normal priority.</span>
1779 …normal.<span class="hljs-title function_">send</span>(<span class="hljs-string">'socket'</span>, s…
1781 server.<span class="hljs-title function_">listen</span>(<span class="hljs-number">1337</span>);</co…
1782 <p>The <code>subprocess.js</code> would receive the socket handle as the second argument
1784 …code class="language-js">process.<span class="hljs-title function_">on</span>(<span class="hljs-st…
1785   <span class="hljs-keyword">if</span> (m === <span class="hljs-string">'socket'</span>) {
1786     <span class="hljs-keyword">if</span> (socket) {
1787       <span class="hljs-comment">// Check that the client socket exists.</span>
1788 …<span class="hljs-comment">// It is possible for the socket to be closed between the time it is</s…
1789       <span class="hljs-comment">// sent and the time it is received in the child process.</span>
1790 …ass="hljs-title function_">end</span>(<span class="hljs-string">`Request handled with <span class=…
1793 });</code> <button class="copy-button">copy</button></pre>
1794 <p>Do not use <code>.maxConnections</code> on a socket that has been passed to a subprocess.
1796 <p>Any <code>'message'</code> handlers in the subprocess should verify that <code>socket</code> exi…
1799 <h4><code>subprocess.signalCode</code><span><a class="mark" href="#subprocesssignalcode" id="subpro…
1801 …zilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&#x3C;string></a> | …
1803 <p>The <code>subprocess.signalCode</code> property indicates the signal received by
1804 the child process if any, else <code>null</code>.</p>
1805 <h4><code>subprocess.spawnargs</code><span><a class="mark" href="#subprocessspawnargs" id="subproce…
1807 <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array…
1809 <p>The <code>subprocess.spawnargs</code> property represents the full list of command-line
1811 <h4><code>subprocess.spawnfile</code><span><a class="mark" href="#subprocessspawnfile" id="subproce…
1813 <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" c…
1815 <p>The <code>subprocess.spawnfile</code> property indicates the executable file name of
1817 <p>For <a href="#child_processforkmodulepath-args-options"><code>child_process.fork()</code></a>, i…
1818 <a href="process.html#processexecpath"><code>process.execPath</code></a>.
1819 For <a href="#child_processspawncommand-args-options"><code>child_process.spawn()</code></a>, its v…
1821 For <a href="#child_processexeccommand-options-callback"><code>child_process.exec()</code></a>,  it…
1823 <h4><code>subprocess.stderr</code><span><a class="mark" href="#subprocessstderr" id="subprocessstde…
1828 …-streamreadable" class="type">&#x3C;stream.Readable></a> | <a href="https://developer.mozilla.org/…
1830 <p>A <code>Readable Stream</code> that represents the child process's <code>stderr</code>.</p>
1831 <p>If the child was spawned with <code>stdio[2]</code> set to anything other than <code>'pipe'</cod…
1832 then this will be <code>null</code>.</p>
1833 <p><code>subprocess.stderr</code> is an alias for <code>subprocess.stdio[2]</code>. Both properties…
1835 <p>The <code>subprocess.stderr</code> property can be <code>null</code> or <code>undefined</code>
1837 <h4><code>subprocess.stdin</code><span><a class="mark" href="#subprocessstdin" id="subprocessstdin"…
1842 …-streamwritable" class="type">&#x3C;stream.Writable></a> | <a href="https://developer.mozilla.org/…
1844 <p>A <code>Writable Stream</code> that represents the child process's <code>stdin</code>.</p>
1846 until this stream has been closed via <code>end()</code>.</p>
1847 <p>If the child was spawned with <code>stdio[0]</code> set to anything other than <code>'pipe'</cod…
1848 then this will be <code>null</code>.</p>
1849 <p><code>subprocess.stdin</code> is an alias for <code>subprocess.stdio[0]</code>. Both properties …
1851 <p>The <code>subprocess.stdin</code> property can be <code>null</code> or <code>undefined</code>
1853 <h4><code>subprocess.stdio</code><span><a class="mark" href="#subprocessstdio" id="subprocessstdio"…
1858 <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array…
1861 …optionsstdio"><code>stdio</code></a> option passed to <a href="#child_processspawncommand-args-opt…
1862 to the value <code>'pipe'</code>. <code>subprocess.stdio[0]</code>, <code>subprocess.stdio[1]</code…
1863 <code>subprocess.stdio[2]</code> are also available as <code>subprocess.stdin</code>,
1864 <code>subprocess.stdout</code>, and <code>subprocess.stderr</code>, respectively.</p>
1865 <p>In the following example, only the child's fd <code>1</code> (stdout) is configured as a
1866 pipe, so only the parent's <code>subprocess.stdio[1]</code> is a stream, all other values
1867 in the array are <code>null</code>.</p>
1868 <pre><code class="language-js"><span class="hljs-keyword">const</span> assert = <span class="hljs-b…
1869 <span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class…
1870 <span class="hljs-keyword">const</span> child_process = <span class="hljs-built_in">require</span>(…
1872 <span class="hljs-keyword">const</span> subprocess = child_process.<span class="hljs-title function…
1873   <span class="hljs-attr">stdio</span>: [
1874 …<span class="hljs-number">0</span>, <span class="hljs-comment">// Use parent's stdin for child.</s…
1875 …<span class="hljs-string">'pipe'</span>, <span class="hljs-comment">// Pipe child's stdout to pare…
1876 …ass="hljs-title function_">openSync</span>(<span class="hljs-string">'err.out'</span>, <span class…
1880 …hljs-title function_">strictEqual</span>(subprocess.<span class="hljs-property">stdio</span>[<span…
1881 …-title function_">strictEqual</span>(subprocess.<span class="hljs-property">stdio</span>[<span cla…
1883 <span class="hljs-title function_">assert</span>(subprocess.<span class="hljs-property">stdout</spa…
1884 …-title function_">strictEqual</span>(subprocess.<span class="hljs-property">stdio</span>[<span cla…
1886 …hljs-title function_">strictEqual</span>(subprocess.<span class="hljs-property">stdio</span>[<span…
1887 …-title function_">strictEqual</span>(subprocess.<span class="hljs-property">stdio</span>[<span cla…
1888 <p>The <code>subprocess.stdio</code> property can be <code>undefined</code> if the child process co…
1890 <h4><code>subprocess.stdout</code><span><a class="mark" href="#subprocessstdout" id="subprocessstdo…
1895 …-streamreadable" class="type">&#x3C;stream.Readable></a> | <a href="https://developer.mozilla.org/…
1897 <p>A <code>Readable Stream</code> that represents the child process's <code>stdout</code>.</p>
1898 <p>If the child was spawned with <code>stdio[1]</code> set to anything other than <code>'pipe'</cod…
1899 then this will be <code>null</code>.</p>
1900 <p><code>subprocess.stdout</code> is an alias for <code>subprocess.stdio[1]</code>. Both properties…
1902 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1904 <span class="hljs-keyword">const</span> subprocess = <span class="hljs-title function_">spawn</span…
1906 …-property">stdout</span>.<span class="hljs-title function_">on</span>(<span class="hljs-string">'d…
1907 …"hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class…
1908 });</code> <button class="copy-button">copy</button></pre>
1909 <p>The <code>subprocess.stdout</code> property can be <code>null</code> or <code>undefined</code>
1911 <h4><code>subprocess.unref()</code><span><a class="mark" href="#subprocessunref" id="subprocessunre…
1916 parent from waiting for a given <code>subprocess</code> to exit, use the
1917 <code>subprocess.unref()</code> method. Doing so will cause the parent's event loop to not
1921 <pre><code class="language-js"><span class="hljs-keyword">const</span> { spawn } = <span class="hlj…
1923 …-keyword">const</span> subprocess = <span class="hljs-title function_">spawn</span>(process.<span …
1924   <span class="hljs-attr">detached</span>: <span class="hljs-literal">true</span>,
1925   <span class="hljs-attr">stdio</span>: <span class="hljs-string">'ignore'</span>,
1928 subprocess.<span class="hljs-title function_">unref</span>();</code> <button class="copy-button">co…
1929 …tion><h3><code>maxBuffer</code> and Unicode<span><a class="mark" href="#maxbuffer-and-unicode" id=…
1930 <p>The <code>maxBuffer</code> option specifies the largest number of bytes allowed on <code>stdout<…
1931 or <code>stderr</code>. If this value is exceeded, then the child process is terminated.
1932 This impacts output that includes multibyte character encodings such as UTF-8 or
1933 UTF-16. For instance, <code>console.log('中文测试')</code> will send 13 UTF-8 encoded bytes
1934 to <code>stdout</code> although there are only 4 characters.</p>
1935 … requirements<span><a class="mark" href="#shell-requirements" id="shell-requirements">#</a></span>…
1936 <p>The shell should understand the <code>-c</code> switch. If the shell is <code>'cmd.exe'</code>, …
1937 should understand the <code>/d /s /c</code> switches and command-line parsing should be
1939 …ows shell<span><a class="mark" href="#default-windows-shell" id="default-windows-shell">#</a></spa…
1940 <p>Although Microsoft specifies <code>%COMSPEC%</code> must contain the path to
1941 <code>'cmd.exe'</code> in the root environment, child processes are not always subject to
1942 the same requirement. Thus, in <code>child_process</code> functions where a shell can be
1943 spawned, <code>'cmd.exe'</code> is used as a fallback if <code>process.env.ComSpec</code> is
1945 …ization<span><a class="mark" href="#advanced-serialization" id="advanced-serialization">#</a></spa…
1950 <a href="v8.html#serialization-api">serialization API of the <code>node:v8</code> module</a>, based…
1951 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorith…
1952 supports more built-in JavaScript object types, such as <code>BigInt</code>, <code>Map</code>
1953 and <code>Set</code>, <code>ArrayBuffer</code> and <code>TypedArray</code>, <code>Buffer</code>, <c…
1955 objects of such built-in types will not be passed on through the serialization
1959 …code>serialization</code> option to <code>'advanced'</code> when calling <a href="#child_processsp…
1960 or <a href="#child_processforkmodulepath-args-options"><code>child_process.fork()</code></a>.</p></…
1961         <!-- API END -->