|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
1 |
<!doctype html>
|
2 |
<html lang="en"> |
|
3 |
<head> |
|
4 |
<meta charset="utf-8"> |
|
|
1.1.23
by Jérémy Lal
Import upstream version 0.10.15~dfsg1 |
5 |
<title>Child Process Node.js v0.10.15 Manual & Documentation</title> |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
6 |
<link rel="stylesheet" href="assets/style.css"> |
7 |
<link rel="stylesheet" href="assets/sh.css"> |
|
8 |
<link rel="canonical" href="http://nodejs.org/api/child_process.html"> |
|
9 |
</head> |
|
10 |
<body class="alt apidoc" id="api-section-child_process"> |
|
11 |
<div id="intro" class="interior"> |
|
12 |
<a href="/" title="Go back to the home page"> |
|
13 |
<img id="logo" src="http://nodejs.org/images/logo-light.png" alt="node.js"> |
|
14 |
</a> |
|
15 |
</div> |
|
16 |
<div id="content" class="clearfix"> |
|
17 |
<div id="column2" class="interior"> |
|
18 |
<ul> |
|
19 |
<li><a href="/" class="home">Home</a></li> |
|
20 |
<li><a href="/download/" class="download">Download</a></li> |
|
21 |
<li><a href="/about/" class="about">About</a></li> |
|
|
1.1.16
by Jérémy Lal
Import upstream version 0.10.6~dfsg1 |
22 |
<li><a href="http://npmjs.org/" class="npm">npm Registry</a></li> |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
23 |
<li><a href="http://nodejs.org/api/" class="docs current">Docs</a></li> |
24 |
<li><a href="http://blog.nodejs.org" class="blog">Blog</a></li> |
|
25 |
<li><a href="/community/" class="community">Community</a></li> |
|
26 |
<li><a href="/logos/" class="logos">Logos</a></li> |
|
27 |
<li><a href="http://jobs.nodejs.org/" class="jobs">Jobs</a></li> |
|
28 |
</ul> |
|
29 |
<p class="twitter"><a href="http://twitter.com/nodejs">@nodejs</a></p> |
|
30 |
</div> |
|
31 |
||
32 |
<div id="column1" class="interior"> |
|
33 |
<header> |
|
|
1.1.23
by Jérémy Lal
Import upstream version 0.10.15~dfsg1 |
34 |
<h1>Node.js v0.10.15 Manual & Documentation</h1> |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
35 |
<div id="gtoc"> |
36 |
<p> |
|
37 |
<a href="index.html" name="toc">Index</a> | |
|
38 |
<a href="all.html">View on single page</a> | |
|
39 |
<a href="child_process.json">View as JSON</a> |
|
40 |
</p> |
|
41 |
</div> |
|
42 |
<hr> |
|
43 |
</header> |
|
44 |
||
45 |
<div id="toc"> |
|
46 |
<h2>Table of Contents</h2> |
|
47 |
<ul> |
|
48 |
<li><a href="#child_process_child_process">Child Process</a><ul> |
|
49 |
<li><a href="#child_process_class_childprocess">Class: ChildProcess</a><ul> |
|
|
1.1.15
by Jérémy Lal
Import upstream version 0.10.5~dfsg1 |
50 |
<li><a href="#child_process_event_error">Event: 'error'</a></li> |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
51 |
<li><a href="#child_process_event_exit">Event: 'exit'</a></li> |
52 |
<li><a href="#child_process_event_close">Event: 'close'</a></li> |
|
53 |
<li><a href="#child_process_event_disconnect">Event: 'disconnect'</a></li> |
|
54 |
<li><a href="#child_process_event_message">Event: 'message'</a></li> |
|
55 |
<li><a href="#child_process_child_stdin">child.stdin</a></li> |
|
56 |
<li><a href="#child_process_child_stdout">child.stdout</a></li> |
|
57 |
<li><a href="#child_process_child_stderr">child.stderr</a></li> |
|
58 |
<li><a href="#child_process_child_pid">child.pid</a></li> |
|
59 |
<li><a href="#child_process_child_kill_signal">child.kill([signal])</a></li> |
|
60 |
<li><a href="#child_process_child_send_message_sendhandle">child.send(message, [sendHandle])</a><ul> |
|
61 |
<li><a href="#child_process_example_sending_server_object">Example: sending server object</a></li> |
|
62 |
<li><a href="#child_process_example_sending_socket_object">Example: sending socket object</a></li> |
|
63 |
</ul> |
|
64 |
</li> |
|
65 |
<li><a href="#child_process_child_disconnect">child.disconnect()</a></li> |
|
66 |
</ul> |
|
67 |
</li> |
|
68 |
<li><a href="#child_process_child_process_spawn_command_args_options">child_process.spawn(command, [args], [options])</a></li> |
|
69 |
<li><a href="#child_process_child_process_exec_command_options_callback">child_process.exec(command, [options], callback)</a></li> |
|
70 |
<li><a href="#child_process_child_process_execfile_file_args_options_callback">child_process.execFile(file, args, options, callback)</a></li> |
|
71 |
<li><a href="#child_process_child_process_fork_modulepath_args_options">child_process.fork(modulePath, [args], [options])</a></li> |
|
72 |
</ul> |
|
73 |
</li> |
|
74 |
</ul> |
|
75 |
||
76 |
</div> |
|
77 |
||
78 |
<div id="apicontent"> |
|
79 |
<h1>Child Process<span><a class="mark" href="#child_process_child_process" id="child_process_child_process">#</a></span></h1> |
|
80 |
<pre class="api_stability_3">Stability: 3 - Stable</pre><p>Node provides a tri-directional <code>popen(3)</code> facility through the |
|
81 |
<code>child_process</code> module. |
|
82 |
||
83 |
</p> |
|
84 |
<p>It is possible to stream data through a child's <code>stdin</code>, <code>stdout</code>, and |
|
85 |
<code>stderr</code> in a fully non-blocking way. (Note that some programs use |
|
86 |
line-buffered I/O internally. That doesn't affect node.js but it means
|
|
87 |
data you send to the child process is not immediately consumed.) |
|
88 |
||
89 |
</p> |
|
90 |
<p>To create a child process use <code>require('child_process').spawn()</code> or |
|
91 |
<code>require('child_process').fork()</code>. The semantics of each are slightly |
|
92 |
different, and explained below. |
|
93 |
||
94 |
</p> |
|
95 |
<h2>Class: ChildProcess<span><a class="mark" href="#child_process_class_childprocess" id="child_process_class_childprocess">#</a></span></h2> |
|
96 |
<p><code>ChildProcess</code> is an <a href="events.html#events_class_events_eventemitter">EventEmitter</a>. |
|
97 |
||
98 |
</p> |
|
99 |
<p>Child processes always have three streams associated with them. <code>child.stdin</code>, |
|
100 |
<code>child.stdout</code>, and <code>child.stderr</code>. These may be shared with the stdio |
|
101 |
streams of the parent process, or they may be separate stream objects |
|
102 |
which can be piped to and from. |
|
103 |
||
104 |
</p> |
|
105 |
<p>The ChildProcess class is not intended to be used directly. Use the |
|
106 |
<code>spawn()</code> or <code>fork()</code> methods to create a Child Process instance. |
|
107 |
||
108 |
</p> |
|
|
1.1.15
by Jérémy Lal
Import upstream version 0.10.5~dfsg1 |
109 |
<h3>Event: 'error'<span><a class="mark" href="#child_process_event_error" id="child_process_event_error">#</a></span></h3> |
110 |
<div class="signature"><ul> |
|
111 |
<li><code>err</code> <span class="type">Error Object</span> the error.</li> |
|
112 |
</div></ul> |
|
113 |
<p>Emitted when: |
|
114 |
||
115 |
</p> |
|
116 |
<ol> |
|
117 |
<li>The process could not be spawned, or</li> |
|
118 |
<li>The process could not be killed, or</li> |
|
119 |
<li>Sending a message to the child process failed for whatever reason.</li> |
|
120 |
</ol> |
|
121 |
<p>See also <a href="#child_process_child_kill_signal"><code>ChildProcess#kill()</code></a> and |
|
122 |
<a href="#child_process_child_send_message_sendhandle"><code>ChildProcess#send()</code></a>. |
|
123 |
||
124 |
</p> |
|
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
125 |
<h3>Event: 'exit'<span><a class="mark" href="#child_process_event_exit" id="child_process_event_exit">#</a></span></h3> |
126 |
<div class="signature"><ul> |
|
127 |
<li><code>code</code> <span class="type">Number</span> the exit code, if it exited normally.</li> |
|
128 |
<li><code>signal</code> <span class="type">String</span> the signal passed to kill the child process, if it |
|
129 |
was killed by the parent.</li> |
|
130 |
</div></ul> |
|
131 |
<p>This event is emitted after the child process ends. If the process terminated |
|
132 |
normally, <code>code</code> is the final exit code of the process, otherwise <code>null</code>. If |
|
133 |
the process terminated due to receipt of a signal, <code>signal</code> is the string name |
|
134 |
of the signal, otherwise <code>null</code>. |
|
135 |
||
136 |
</p> |
|
137 |
<p>Note that the child process stdio streams might still be open. |
|
138 |
||
139 |
</p> |
|
140 |
<p>See <code>waitpid(2)</code>. |
|
141 |
||
142 |
</p> |
|
143 |
<h3>Event: 'close'<span><a class="mark" href="#child_process_event_close" id="child_process_event_close">#</a></span></h3> |
|
144 |
<div class="signature"><ul> |
|
145 |
<li><code>code</code> <span class="type">Number</span> the exit code, if it exited normally.</li> |
|
146 |
<li><code>signal</code> <span class="type">String</span> the signal passed to kill the child process, if it |
|
147 |
was killed by the parent.</li> |
|
148 |
</div></ul> |
|
149 |
<p>This event is emitted when the stdio streams of a child process have all |
|
150 |
terminated. This is distinct from 'exit', since multiple processes |
|
151 |
might share the same stdio streams. |
|
152 |
||
153 |
</p> |
|
154 |
<h3>Event: 'disconnect'<span><a class="mark" href="#child_process_event_disconnect" id="child_process_event_disconnect">#</a></span></h3> |
|
155 |
<p>This event is emitted after using the <code>.disconnect()</code> method in the parent or |
|
156 |
in the child. After disconnecting it is no longer possible to send messages. |
|
157 |
An alternative way to check if you can send messages is to see if the |
|
158 |
<code>child.connected</code> property is <code>true</code>. |
|
159 |
||
160 |
</p> |
|
161 |
<h3>Event: 'message'<span><a class="mark" href="#child_process_event_message" id="child_process_event_message">#</a></span></h3> |
|
162 |
<div class="signature"><ul> |
|
163 |
<li><code>message</code> <span class="type">Object</span> a parsed JSON object or primitive value</li> |
|
164 |
<li><code>sendHandle</code> <span class="type">Handle object</span> a Socket or Server object</li> |
|
165 |
</div></ul> |
|
166 |
<p>Messages send by <code>.send(message, [sendHandle])</code> are obtained using the |
|
167 |
<code>message</code> event. |
|
168 |
||
169 |
</p> |
|
170 |
<h3>child.stdin<span><a class="mark" href="#child_process_child_stdin" id="child_process_child_stdin">#</a></span></h3> |
|
171 |
<div class="signature"><ul> |
|
172 |
<li><span class="type">Stream object</span></li> |
|
173 |
</div></ul> |
|
174 |
<p>A <code>Writable Stream</code> that represents the child process's <code>stdin</code>. |
|
175 |
Closing this stream via <code>end()</code> often causes the child process to terminate. |
|
176 |
||
177 |
</p> |
|
178 |
<p>If the child stdio streams are shared with the parent, then this will |
|
179 |
not be set. |
|
180 |
||
181 |
</p> |
|
182 |
<h3>child.stdout<span><a class="mark" href="#child_process_child_stdout" id="child_process_child_stdout">#</a></span></h3> |
|
183 |
<div class="signature"><ul> |
|
184 |
<li><span class="type">Stream object</span></li> |
|
185 |
</div></ul> |
|
186 |
<p>A <code>Readable Stream</code> that represents the child process's <code>stdout</code>. |
|
187 |
||
188 |
</p> |
|
189 |
<p>If the child stdio streams are shared with the parent, then this will |
|
190 |
not be set. |
|
191 |
||
192 |
</p> |
|
193 |
<h3>child.stderr<span><a class="mark" href="#child_process_child_stderr" id="child_process_child_stderr">#</a></span></h3> |
|
194 |
<div class="signature"><ul> |
|
195 |
<li><span class="type">Stream object</span></li> |
|
196 |
</div></ul> |
|
197 |
<p>A <code>Readable Stream</code> that represents the child process's <code>stderr</code>. |
|
198 |
||
199 |
</p> |
|
200 |
<p>If the child stdio streams are shared with the parent, then this will |
|
201 |
not be set. |
|
202 |
||
203 |
</p> |
|
204 |
<h3>child.pid<span><a class="mark" href="#child_process_child_pid" id="child_process_child_pid">#</a></span></h3> |
|
205 |
<div class="signature"><ul> |
|
206 |
<li><span class="type">Integer</span></li> |
|
207 |
</div></ul> |
|
208 |
<p>The PID of the child process. |
|
209 |
||
210 |
</p> |
|
211 |
<p>Example: |
|
212 |
||
213 |
</p> |
|
214 |
<pre><code>var spawn = require('child_process').spawn, |
|
215 |
grep = spawn('grep', ['ssh']); |
|
216 |
||
217 |
console.log('Spawned child pid: ' + grep.pid); |
|
218 |
grep.stdin.end();</code></pre> |
|
219 |
<h3>child.kill([signal])<span><a class="mark" href="#child_process_child_kill_signal" id="child_process_child_kill_signal">#</a></span></h3> |
|
220 |
<div class="signature"><ul> |
|
221 |
<li><code>signal</code> <span class="type">String</span></li> |
|
222 |
</div></ul> |
|
223 |
<p>Send a signal to the child process. If no argument is given, the process will |
|
224 |
be sent <code>'SIGTERM'</code>. See <code>signal(7)</code> for a list of available signals. |
|
225 |
||
226 |
</p> |
|
227 |
<pre><code>var spawn = require('child_process').spawn, |
|
228 |
grep = spawn('grep', ['ssh']); |
|
229 |
||
230 |
grep.on('close', function (code, signal) { |
|
231 |
console.log('child process terminated due to receipt of signal '+signal); |
|
232 |
}); |
|
233 |
||
234 |
// send SIGHUP to process |
|
235 |
grep.kill('SIGHUP');</code></pre> |
|
|
1.1.15
by Jérémy Lal
Import upstream version 0.10.5~dfsg1 |
236 |
<p>May emit an <code>'error'</code> event when the signal cannot be delivered. Sending a |
237 |
signal to a child process that has already exited is not an error but may |
|
238 |
have unforeseen consequences: if the PID (the process ID) has been reassigned |
|
239 |
to another process, the signal will be delivered to that process instead. |
|
240 |
What happens next is anyone's guess.
|
|
241 |
||
242 |
</p> |
|
243 |
<p>Note that while the function is called <code>kill</code>, the signal delivered to the |
|
244 |
child process may not actually kill it. <code>kill</code> really just sends a signal |
|
245 |
to a process. |
|
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
246 |
|
247 |
</p> |
|
248 |
<p>See <code>kill(2)</code> |
|
249 |
||
250 |
</p> |
|
251 |
<h3>child.send(message, [sendHandle])<span><a class="mark" href="#child_process_child_send_message_sendhandle" id="child_process_child_send_message_sendhandle">#</a></span></h3> |
|
252 |
<div class="signature"><ul> |
|
253 |
<li><code>message</code> <span class="type">Object</span></li> |
|
254 |
<li><code>sendHandle</code> <span class="type">Handle object</span></li> |
|
255 |
</div></ul> |
|
256 |
<p>When using <code>child_process.fork()</code> you can write to the child using |
|
257 |
<code>child.send(message, [sendHandle])</code> and messages are received by |
|
258 |
a <code>'message'</code> event on the child. |
|
259 |
||
260 |
</p> |
|
261 |
<p>For example: |
|
262 |
||
263 |
</p> |
|
264 |
<pre><code>var cp = require('child_process'); |
|
265 |
||
266 |
var n = cp.fork(__dirname + '/sub.js'); |
|
267 |
||
268 |
n.on('message', function(m) { |
|
269 |
console.log('PARENT got message:', m); |
|
270 |
}); |
|
271 |
||
272 |
n.send({ hello: 'world' });</code></pre>
|
|
273 |
<p>And then the child script, <code>'sub.js'</code> might look like this: |
|
274 |
||
275 |
</p> |
|
276 |
<pre><code>process.on('message', function(m) { |
|
277 |
console.log('CHILD got message:', m); |
|
278 |
}); |
|
279 |
||
280 |
process.send({ foo: 'bar' });</code></pre>
|
|
281 |
<p>In the child the <code>process</code> object will have a <code>send()</code> method, and <code>process</code> |
|
282 |
will emit objects each time it receives a message on its channel. |
|
283 |
||
284 |
</p> |
|
285 |
<p>There is a special case when sending a <code>{cmd: 'NODE_foo'}</code> message. All messages |
|
286 |
containing a <code>NODE_</code> prefix in its <code>cmd</code> property will not be emitted in |
|
287 |
the <code>message</code> event, since they are internal messages used by node core. |
|
288 |
Messages containing the prefix are emitted in the <code>internalMessage</code> event, you |
|
289 |
should by all means avoid using this feature, it is subject to change without notice. |
|
290 |
||
291 |
</p> |
|
292 |
<p>The <code>sendHandle</code> option to <code>child.send()</code> is for sending a TCP server or |
|
293 |
socket object to another process. The child will receive the object as its |
|
294 |
second argument to the <code>message</code> event. |
|
295 |
||
296 |
</p> |
|
|
1.1.15
by Jérémy Lal
Import upstream version 0.10.5~dfsg1 |
297 |
<p>Emits an <code>'error'</code> event if the message cannot be sent, for example because |
298 |
the child process has already exited. |
|
299 |
||
300 |
</p> |
|
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
301 |
<h4>Example: sending server object<span><a class="mark" href="#child_process_example_sending_server_object" id="child_process_example_sending_server_object">#</a></span></h4> |
302 |
<p>Here is an example of sending a server: |
|
303 |
||
304 |
</p> |
|
305 |
<pre><code>var child = require('child_process').fork('child.js'); |
|
306 |
||
307 |
// Open up the server object and send the handle. |
|
308 |
var server = require('net').createServer(); |
|
309 |
server.on('connection', function (socket) { |
|
310 |
socket.end('handled by parent'); |
|
311 |
}); |
|
312 |
server.listen(1337, function() {
|
|
313 |
child.send('server', server); |
|
314 |
});</code></pre> |
|
315 |
<p>And the child would the receive the server object as: |
|
316 |
||
317 |
</p> |
|
318 |
<pre><code>process.on('message', function(m, server) { |
|
319 |
if (m === 'server') { |
|
320 |
server.on('connection', function (socket) { |
|
321 |
socket.end('handled by child'); |
|
322 |
}); |
|
323 |
} |
|
324 |
});</code></pre> |
|
325 |
<p>Note that the server is now shared between the parent and child, this means |
|
326 |
that some connections will be handled by the parent and some by the child. |
|
327 |
||
328 |
</p> |
|
329 |
<p>For <code>dgram</code> servers the workflow is exactly the same. Here you listen on |
|
330 |
a <code>message</code> event instead of <code>connection</code> and use <code>server.bind</code> instead of |
|
|
1.1.19
by Jérémy Lal
Import upstream version 0.10.9~dfsg1 |
331 |
<code>server.listen</code>. (Currently only supported on UNIX platforms.) |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
332 |
|
333 |
</p> |
|
334 |
<h4>Example: sending socket object<span><a class="mark" href="#child_process_example_sending_socket_object" id="child_process_example_sending_socket_object">#</a></span></h4> |
|
335 |
<p>Here is an example of sending a socket. It will spawn two children and handle |
|
336 |
connections with the remote address <code>74.125.127.100</code> as VIP by sending the |
|
337 |
socket to a "special" child process. Other sockets will go to a "normal" process. |
|
338 |
||
339 |
</p> |
|
340 |
<pre><code>var normal = require('child_process').fork('child.js', ['normal']); |
|
341 |
var special = require('child_process').fork('child.js', ['special']); |
|
342 |
||
343 |
// Open up the server and send sockets to child |
|
344 |
var server = require('net').createServer(); |
|
345 |
server.on('connection', function (socket) { |
|
346 |
||
347 |
// if this is a VIP |
|
348 |
if (socket.remoteAddress === '74.125.127.100') { |
|
349 |
special.send('socket', socket); |
|
350 |
return; |
|
351 |
} |
|
352 |
// just the usual dudes |
|
353 |
normal.send('socket', socket); |
|
354 |
}); |
|
355 |
server.listen(1337);</code></pre> |
|
356 |
<p>The <code>child.js</code> could look like this: |
|
357 |
||
358 |
</p> |
|
359 |
<pre><code>process.on('message', function(m, socket) { |
|
360 |
if (m === 'socket') { |
|
361 |
socket.end('You were handled as a ' + process.argv[2] + ' person'); |
|
362 |
} |
|
363 |
});</code></pre> |
|
364 |
<p>Note that once a single socket has been sent to a child the parent can no |
|
365 |
longer keep track of when the socket is destroyed. To indicate this condition |
|
366 |
the <code>.connections</code> property becomes <code>null</code>. |
|
367 |
It is also recommended not to use <code>.maxConnections</code> in this condition. |
|
368 |
||
369 |
</p> |
|
370 |
<h3>child.disconnect()<span><a class="mark" href="#child_process_child_disconnect" id="child_process_child_disconnect">#</a></span></h3> |
|
371 |
<p>To close the IPC connection between parent and child use the |
|
372 |
<code>child.disconnect()</code> method. This allows the child to exit gracefully since |
|
373 |
there is no IPC channel keeping it alive. When calling this method the |
|
374 |
<code>disconnect</code> event will be emitted in both parent and child, and the |
|
375 |
<code>connected</code> flag will be set to <code>false</code>. Please note that you can also call |
|
376 |
<code>process.disconnect()</code> in the child process. |
|
377 |
||
378 |
</p> |
|
379 |
<h2>child_process.spawn(command, [args], [options])<span><a class="mark" href="#child_process_child_process_spawn_command_args_options" id="child_process_child_process_spawn_command_args_options">#</a></span></h2> |
|
380 |
<div class="signature"><ul> |
|
381 |
<li><code>command</code> <span class="type">String</span> The command to run</li> |
|
382 |
<li><code>args</code> <span class="type">Array</span> List of string arguments</li> |
|
383 |
<li><code>options</code> <span class="type">Object</span><ul> |
|
384 |
<li><code>cwd</code> <span class="type">String</span> Current working directory of the child process</li> |
|
385 |
<li><code>stdio</code> <span class="type">Array|String</span> Child's stdio configuration. (See below)</li> |
|
386 |
<li><code>customFds</code> <span class="type">Array</span> <strong>Deprecated</strong> File descriptors for the child to use |
|
387 |
for stdio. (See below)</li> |
|
388 |
<li><code>env</code> <span class="type">Object</span> Environment key-value pairs</li> |
|
389 |
<li><code>detached</code> <span class="type">Boolean</span> The child will be a process group leader. (See below)</li> |
|
390 |
<li><code>uid</code> <span class="type">Number</span> Sets the user identity of the process. (See setuid(2).)</li> |
|
391 |
<li><code>gid</code> <span class="type">Number</span> Sets the group identity of the process. (See setgid(2).)</li> |
|
392 |
</ul> |
|
393 |
</li> |
|
394 |
<li>return: <span class="type">ChildProcess object</span></li> |
|
395 |
</div></ul> |
|
396 |
<p>Launches a new process with the given <code>command</code>, with command line arguments in <code>args</code>. |
|
397 |
If omitted, <code>args</code> defaults to an empty Array. |
|
398 |
||
399 |
</p> |
|
400 |
<p>The third argument is used to specify additional options, which defaults to: |
|
401 |
||
402 |
</p> |
|
403 |
<pre><code>{ cwd: undefined, |
|
404 |
env: process.env |
|
405 |
}</code></pre> |
|
406 |
<p><code>cwd</code> allows you to specify the working directory from which the process is spawned. |
|
407 |
Use <code>env</code> to specify environment variables that will be visible to the new process. |
|
408 |
||
409 |
</p> |
|
410 |
<p>Example of running <code>ls -lh /usr</code>, capturing <code>stdout</code>, <code>stderr</code>, and the exit code: |
|
411 |
||
412 |
</p> |
|
413 |
<pre><code>var spawn = require('child_process').spawn, |
|
414 |
ls = spawn('ls', ['-lh', '/usr']); |
|
415 |
||
416 |
ls.stdout.on('data', function (data) { |
|
417 |
console.log('stdout: ' + data); |
|
418 |
}); |
|
419 |
||
420 |
ls.stderr.on('data', function (data) { |
|
421 |
console.log('stderr: ' + data); |
|
422 |
}); |
|
423 |
||
424 |
ls.on('close', function (code) { |
|
425 |
console.log('child process exited with code ' + code); |
|
426 |
});</code></pre> |
|
427 |
<p>Example: A very elaborate way to run 'ps ax | grep ssh' |
|
428 |
||
429 |
</p> |
|
430 |
<pre><code>var spawn = require('child_process').spawn, |
|
431 |
ps = spawn('ps', ['ax']), |
|
432 |
grep = spawn('grep', ['ssh']); |
|
433 |
||
434 |
ps.stdout.on('data', function (data) { |
|
435 |
grep.stdin.write(data); |
|
436 |
}); |
|
437 |
||
438 |
ps.stderr.on('data', function (data) { |
|
439 |
console.log('ps stderr: ' + data); |
|
440 |
}); |
|
441 |
||
442 |
ps.on('close', function (code) { |
|
443 |
if (code !== 0) {
|
|
444 |
console.log('ps process exited with code ' + code); |
|
445 |
} |
|
446 |
grep.stdin.end(); |
|
447 |
}); |
|
448 |
||
449 |
grep.stdout.on('data', function (data) { |
|
450 |
console.log('' + data);
|
|
451 |
}); |
|
452 |
||
453 |
grep.stderr.on('data', function (data) { |
|
454 |
console.log('grep stderr: ' + data); |
|
455 |
}); |
|
456 |
||
457 |
grep.on('close', function (code) { |
|
458 |
if (code !== 0) {
|
|
459 |
console.log('grep process exited with code ' + code); |
|
460 |
} |
|
461 |
});</code></pre> |
|
462 |
<p>Example of checking for failed exec: |
|
463 |
||
464 |
</p> |
|
465 |
<pre><code>var spawn = require('child_process').spawn, |
|
466 |
child = spawn('bad_command'); |
|
467 |
||
468 |
child.stderr.setEncoding('utf8'); |
|
469 |
child.stderr.on('data', function (data) { |
|
470 |
if (/^execvp\(\)/.test(data)) {
|
|
471 |
console.log('Failed to start child process.'); |
|
472 |
} |
|
473 |
});</code></pre> |
|
474 |
<p>Note that if spawn receives an empty options object, it will result in |
|
475 |
spawning the process with an empty environment rather than using |
|
476 |
<code>process.env</code>. This due to backwards compatibility issues with a deprecated |
|
477 |
API. |
|
478 |
||
479 |
</p> |
|
480 |
<p>The 'stdio' option to <code>child_process.spawn()</code> is an array where each |
|
481 |
index corresponds to a fd in the child. The value is one of the following: |
|
482 |
||
483 |
</p> |
|
484 |
<ol> |
|
485 |
<li><code>'pipe'</code> - Create a pipe between the child process and the parent process. |
|
486 |
The parent end of the pipe is exposed to the parent as a property on the |
|
487 |
<code>child_process</code> object as <code>ChildProcess.stdio[fd]</code>. Pipes created for |
|
488 |
fds 0 - 2 are also available as ChildProcess.stdin, ChildProcess.stdout |
|
489 |
and ChildProcess.stderr, respectively.</li> |
|
490 |
<li><code>'ipc'</code> - Create an IPC channel for passing messages/file descriptors |
|
491 |
between parent and child. A ChildProcess may have at most <em>one</em> IPC stdio |
|
492 |
file descriptor. Setting this option enables the ChildProcess.send() method. |
|
493 |
If the child writes JSON messages to this file descriptor, then this will |
|
494 |
trigger ChildProcess.on('message'). If the child is a Node.js program, then |
|
495 |
the presence of an IPC channel will enable process.send() and |
|
496 |
process.on('message').</li> |
|
497 |
<li><code>'ignore'</code> - Do not set this file descriptor in the child. Note that Node |
|
498 |
will always open fd 0 - 2 for the processes it spawns. When any of these is |
|
499 |
ignored node will open <code>/dev/null</code> and attach it to the child's fd.</li> |
|
500 |
<li><code>Stream</code> object - Share a readable or writable stream that refers to a tty, |
|
501 |
file, socket, or a pipe with the child process. The stream's underlying
|
|
502 |
file descriptor is duplicated in the child process to the fd that |
|
503 |
corresponds to the index in the <code>stdio</code> array.</li> |
|
504 |
<li>Positive integer - The integer value is interpreted as a file descriptor |
|
505 |
that is is currently open in the parent process. It is shared with the child |
|
506 |
process, similar to how <code>Stream</code> objects can be shared.</li> |
|
507 |
<li><code>null</code>, <code>undefined</code> - Use default value. For stdio fds 0, 1 and 2 (in other |
|
508 |
words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the |
|
509 |
default is <code>'ignore'</code>.</li> |
|
510 |
</ol> |
|
511 |
<p>As a shorthand, the <code>stdio</code> argument may also be one of the following |
|
512 |
strings, rather than an array: |
|
513 |
||
514 |
</p> |
|
515 |
<ul> |
|
516 |
<li><code>ignore</code> - <code>['ignore', 'ignore', 'ignore']</code></li> |
|
517 |
<li><code>pipe</code> - <code>['pipe', 'pipe', 'pipe']</code></li> |
|
518 |
<li><code>inherit</code> - <code>[process.stdin, process.stdout, process.stderr]</code> or <code>[0,1,2]</code></li> |
|
519 |
</ul> |
|
520 |
<p>Example: |
|
521 |
||
522 |
</p> |
|
523 |
<pre><code>var spawn = require('child_process').spawn; |
|
524 |
||
525 |
// Child will use parent's stdios
|
|
526 |
spawn('prg', [], { stdio: 'inherit' }); |
|
527 |
||
528 |
// Spawn child sharing only stderr |
|
529 |
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] }); |
|
530 |
||
531 |
// Open an extra fd=4, to interact with programs present a |
|
532 |
// startd-style interface. |
|
533 |
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });</code></pre> |
|
534 |
<p>If the <code>detached</code> option is set, the child process will be made the leader of a |
|
535 |
new process group. This makes it possible for the child to continue running |
|
536 |
after the parent exits. |
|
537 |
||
538 |
</p> |
|
539 |
<p>By default, the parent will wait for the detached child to exit. To prevent |
|
540 |
the parent from waiting for a given <code>child</code>, use the <code>child.unref()</code> method, |
|
541 |
and the parent's event loop will not include the child in its reference count.
|
|
542 |
||
543 |
</p> |
|
544 |
<p>Example of detaching a long-running process and redirecting its output to a |
|
545 |
file: |
|
546 |
||
547 |
</p> |
|
548 |
<pre><code> var fs = require('fs'), |
|
549 |
spawn = require('child_process').spawn, |
|
550 |
out = fs.openSync('./out.log', 'a'), |
|
551 |
err = fs.openSync('./out.log', 'a'); |
|
552 |
||
553 |
var child = spawn('prg', [], { |
|
554 |
detached: true, |
|
555 |
stdio: [ 'ignore', out, err ] |
|
556 |
}); |
|
557 |
||
558 |
child.unref();</code></pre> |
|
559 |
<p>When using the <code>detached</code> option to start a long-running process, the process |
|
560 |
will not stay running in the background unless it is provided with a <code>stdio</code> |
|
561 |
configuration that is not connected to the parent. If the parent's <code>stdio</code> is |
|
562 |
inherited, the child will remain attached to the controlling terminal. |
|
563 |
||
564 |
</p> |
|
565 |
<p>There is a deprecated option called <code>customFds</code> which allows one to specify |
|
566 |
specific file descriptors for the stdio of the child process. This API was |
|
567 |
not portable to all platforms and therefore removed. |
|
568 |
With <code>customFds</code> it was possible to hook up the new process' <code>[stdin, stdout, |
|
569 |
stderr]</code> to existing streams; <code>-1</code> meant that a new stream should be created. |
|
570 |
Use at your own risk. |
|
571 |
||
572 |
</p> |
|
573 |
<p>See also: <code>child_process.exec()</code> and <code>child_process.fork()</code> |
|
574 |
||
575 |
</p> |
|
576 |
<h2>child_process.exec(command, [options], callback)<span><a class="mark" href="#child_process_child_process_exec_command_options_callback" id="child_process_child_process_exec_command_options_callback">#</a></span></h2> |
|
577 |
<div class="signature"><ul> |
|
578 |
<li><code>command</code> <span class="type">String</span> The command to run, with space-separated arguments</li> |
|
579 |
<li><code>options</code> <span class="type">Object</span><ul> |
|
580 |
<li><code>cwd</code> <span class="type">String</span> Current working directory of the child process</li> |
|
581 |
<li><code>env</code> <span class="type">Object</span> Environment key-value pairs</li> |
|
582 |
<li><code>encoding</code> <span class="type">String</span> (Default: 'utf8')</li> |
|
583 |
<li><code>timeout</code> <span class="type">Number</span> (Default: 0)</li> |
|
584 |
<li><code>maxBuffer</code> <span class="type">Number</span> (Default: 200*1024)</li> |
|
585 |
<li><code>killSignal</code> <span class="type">String</span> (Default: 'SIGTERM')</li> |
|
586 |
</ul> |
|
587 |
</li> |
|
588 |
<li><code>callback</code> <span class="type">Function</span> called with the output when process terminates<ul> |
|
589 |
<li><code>error</code> <span class="type">Error</span></li> |
|
590 |
<li><code>stdout</code> <span class="type">Buffer</span></li> |
|
591 |
<li><code>stderr</code> <span class="type">Buffer</span></li> |
|
592 |
</ul> |
|
593 |
</li> |
|
594 |
<li>Return: ChildProcess object</li> |
|
595 |
</div></ul> |
|
596 |
<p>Runs a command in a shell and buffers the output. |
|
597 |
||
598 |
</p> |
|
599 |
<pre><code>var exec = require('child_process').exec, |
|
600 |
child; |
|
601 |
||
602 |
child = exec('cat *.js bad_file | wc -l', |
|
603 |
function (error, stdout, stderr) {
|
|
604 |
console.log('stdout: ' + stdout); |
|
605 |
console.log('stderr: ' + stderr); |
|
606 |
if (error !== null) {
|
|
607 |
console.log('exec error: ' + error); |
|
608 |
} |
|
609 |
});</code></pre> |
|
610 |
<p>The callback gets the arguments <code>(error, stdout, stderr)</code>. On success, <code>error</code> |
|
611 |
will be <code>null</code>. On error, <code>error</code> will be an instance of <code>Error</code> and <code>err.code</code> |
|
612 |
will be the exit code of the child process, and <code>err.signal</code> will be set to the |
|
613 |
signal that terminated the process. |
|
614 |
||
615 |
</p> |
|
616 |
<p>There is a second optional argument to specify several options. The |
|
617 |
default options are |
|
618 |
||
619 |
</p> |
|
620 |
<pre><code>{ encoding: 'utf8', |
|
621 |
timeout: 0, |
|
622 |
maxBuffer: 200*1024, |
|
623 |
killSignal: 'SIGTERM', |
|
624 |
cwd: null, |
|
625 |
env: null }</code></pre> |
|
626 |
<p>If <code>timeout</code> is greater than 0, then it will kill the child process |
|
627 |
if it runs longer than <code>timeout</code> milliseconds. The child process is killed with |
|
628 |
<code>killSignal</code> (default: <code>'SIGTERM'</code>). <code>maxBuffer</code> specifies the largest |
|
629 |
amount of data allowed on stdout or stderr - if this value is exceeded then |
|
630 |
the child process is killed. |
|
631 |
||
632 |
||
633 |
</p> |
|
634 |
<h2>child_process.execFile(file, args, options, callback)<span><a class="mark" href="#child_process_child_process_execfile_file_args_options_callback" id="child_process_child_process_execfile_file_args_options_callback">#</a></span></h2> |
|
635 |
<div class="signature"><ul> |
|
636 |
<li><code>file</code> <span class="type">String</span> The filename of the program to run</li> |
|
637 |
<li><code>args</code> <span class="type">Array</span> List of string arguments</li> |
|
638 |
<li><code>options</code> <span class="type">Object</span><ul> |
|
639 |
<li><code>cwd</code> <span class="type">String</span> Current working directory of the child process</li> |
|
640 |
<li><code>env</code> <span class="type">Object</span> Environment key-value pairs</li> |
|
641 |
<li><code>encoding</code> <span class="type">String</span> (Default: 'utf8')</li> |
|
642 |
<li><code>timeout</code> <span class="type">Number</span> (Default: 0)</li> |
|
643 |
<li><code>maxBuffer</code> <span class="type">Number</span> (Default: 200*1024)</li> |
|
644 |
<li><code>killSignal</code> <span class="type">String</span> (Default: 'SIGTERM')</li> |
|
645 |
</ul> |
|
646 |
</li> |
|
647 |
<li><code>callback</code> <span class="type">Function</span> called with the output when process terminates<ul> |
|
648 |
<li><code>error</code> <span class="type">Error</span></li> |
|
649 |
<li><code>stdout</code> <span class="type">Buffer</span></li> |
|
650 |
<li><code>stderr</code> <span class="type">Buffer</span></li> |
|
651 |
</ul> |
|
652 |
</li> |
|
653 |
<li>Return: ChildProcess object</li> |
|
654 |
</div></ul> |
|
655 |
<p>This is similar to <code>child_process.exec()</code> except it does not execute a |
|
656 |
subshell but rather the specified file directly. This makes it slightly |
|
657 |
leaner than <code>child_process.exec</code>. It has the same options. |
|
658 |
||
659 |
||
660 |
</p> |
|
661 |
<h2>child_process.fork(modulePath, [args], [options])<span><a class="mark" href="#child_process_child_process_fork_modulepath_args_options" id="child_process_child_process_fork_modulepath_args_options">#</a></span></h2> |
|
662 |
<div class="signature"><ul> |
|
663 |
<li><code>modulePath</code> <span class="type">String</span> The module to run in the child</li> |
|
664 |
<li><code>args</code> <span class="type">Array</span> List of string arguments</li> |
|
665 |
<li><code>options</code> <span class="type">Object</span><ul> |
|
666 |
<li><code>cwd</code> <span class="type">String</span> Current working directory of the child process</li> |
|
667 |
<li><code>env</code> <span class="type">Object</span> Environment key-value pairs</li> |
|
668 |
<li><code>encoding</code> <span class="type">String</span> (Default: 'utf8')</li> |
|
669 |
<li><code>execPath</code> <span class="type">String</span> Executable used to create the child process</li> |
|
670 |
</ul> |
|
671 |
</li> |
|
672 |
<li>Return: ChildProcess object</li> |
|
673 |
</div></ul> |
|
674 |
<p>This is a special case of the <code>spawn()</code> functionality for spawning Node |
|
675 |
processes. In addition to having all the methods in a normal ChildProcess |
|
676 |
instance, the returned object has a communication channel built-in. See |
|
677 |
<code>child.send(message, [sendHandle])</code> for details. |
|
678 |
||
679 |
</p> |
|
680 |
<p>By default the spawned Node process will have the stdout, stderr associated |
|
681 |
with the parent's. To change this behavior set the <code>silent</code> property in the |
|
682 |
<code>options</code> object to <code>true</code>. |
|
683 |
||
684 |
</p> |
|
685 |
<p>The child process does not automatically exit once it's done, you need to call |
|
686 |
<code>process.exit()</code> explicitly. This limitation may be lifted in the future. |
|
687 |
||
688 |
</p> |
|
689 |
<p>These child Nodes are still whole new instances of V8. Assume at least 30ms |
|
690 |
startup and 10mb memory for each new Node. That is, you cannot create many |
|
691 |
thousands of them. |
|
692 |
||
693 |
</p> |
|
694 |
<p>The <code>execPath</code> property in the <code>options</code> object allows for a process to be |
|
695 |
created for the child rather than the current <code>node</code> executable. This should be |
|
696 |
done with care and by default will talk over the fd represented an |
|
697 |
environmental variable <code>NODE_CHANNEL_FD</code> on the child process. The input and |
|
698 |
output on this fd is expected to be line delimited JSON objects. |
|
699 |
||
700 |
</p> |
|
701 |
||
702 |
</div> |
|
703 |
</div> |
|
704 |
</div> |
|
705 |
<div id="footer"> |
|
|
1.1.16
by Jérémy Lal
Import upstream version 0.10.6~dfsg1 |
706 |
<a href="http://joyent.com" class="joyent-logo">Joyent</a> |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
707 |
<ul class="clearfix"> |
708 |
<li><a href="/">Node.js</a></li> |
|
709 |
<li><a href="/download/">Download</a></li> |
|
710 |
<li><a href="/about/">About</a></li> |
|
|
1.1.16
by Jérémy Lal
Import upstream version 0.10.6~dfsg1 |
711 |
<li><a href="http://npmjs.org/">npm Registry</a></li> |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
712 |
<li><a href="http://nodejs.org/api/">Docs</a></li> |
713 |
<li><a href="http://blog.nodejs.org">Blog</a></li> |
|
714 |
<li><a href="/community/">Community</a></li> |
|
715 |
<li><a href="/logos/">Logos</a></li> |
|
716 |
<li><a href="http://jobs.nodejs.org/">Jobs</a></li> |
|
717 |
<li><a href="http://twitter.com/nodejs" class="twitter">@nodejs</a></li> |
|
718 |
</ul> |
|
719 |
||
|
1.1.23
by Jérémy Lal
Import upstream version 0.10.15~dfsg1 |
720 |
<p>Copyright <a href="http://joyent.com/">Joyent, Inc</a>, Node.js is a <a href="/trademark-policy.pdf">trademark</a> of Joyent, Inc. View <a href="https://raw.github.com/joyent/node/v0.10.15/LICENSE">license</a>.</p> |
|
1.1.13
by Jonas Smedegaard
Import upstream version 0.10.0~dfsg1 |
721 |
</div> |
722 |
||
723 |
<script src="../sh_main.js"></script> |
|
724 |
<script src="../sh_javascript.min.js"></script> |
|
725 |
<script>highlight(undefined, undefined, 'pre');</script> |
|
726 |
<script> |
|
727 |
window._gaq = [['_setAccount', 'UA-10874194-2'], ['_trackPageview']]; |
|
728 |
(function(d, t) { |
|
729 |
var g = d.createElement(t), |
|
730 |
s = d.getElementsByTagName(t)[0]; |
|
731 |
g.src = '//www.google-analytics.com/ga.js'; |
|
732 |
s.parentNode.insertBefore(g, s); |
|
733 |
}(document, 'script')); |
|
734 |
</script> |
|
735 |
</body> |
|
736 |
</html> |
|
737 |