← Back to branch summary

~ubuntu-branches/ubuntu/precise/nodejs/precise

« back to all changes in this revision

Viewing changes to doc/node.1

  • Committer: Bazaar Package Importer
  • Author(s): Jérémy Lal
  • Date: 2010-08-20 11:49:04 UTC
  • mfrom: (7.1.6 sid)
  • Revision ID: james.westby@ubuntu.com-20100820114904-lz22w6fkth7yh179
Tags: 0.2.0-1
New upstream release

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/node.1
1
 
.\" generated with Ronn/v0.4.1
2
 
.\" http://github.com/rtomayko/ronn/
 
1
.\" Generated with Ronnjs/v0.1
 
2
.\" http://github.com/kapouer/ronnjs/
3
3
.
4
 
.TH "NODE" "1" "May 2010" "" ""
 
4
.TH "NODE" "1" "August 2010" "" ""
5
5
.
6
6
.SH "NAME"
7
7
\fBnode\fR \-\- evented I/O for V8 JavaScript
8
8
.
9
9
.SH "Synopsis"
10
 
An example of a web server written with Node which responds with 'Hello
11
 
World':
 
10
An example of a web server written with Node which responds with \'Hello
 
11
World\':
12
12
.
13
13
.IP "" 4
14
14
.
15
15
.nf
16
 
var sys = require('sys'),
17
 
  http = require('http');
18
 
http.createServer(function (request, response) {
19
 
  response.writeHead(200, {'Content\-Type': 'text/plain'});
20
 
  response.end('Hello World\\n');
21
 
}).listen(8000);
22
 
sys.puts('Server running at http://127.0.0.1:8000/');
 
16
var http = require(\'http\');
 
17
http\.createServer(function (request, response) {
 
18
  response\.writeHead(200, {\'Content\-Type\': \'text/plain\'});
 
19
  response\.end(\'Hello World\\n\');
 
20
})\.listen(8124);
 
21
console\.log(\'Server running at http://127\.0\.0\.1:8124/\');
23
22
.
24
23
.fi
25
24
.
26
25
.IP "" 0
27
26
.
28
27
.P
29
 
To run the server, put the code into a file called \fBexample.js\fR and execute
 
28
To run the server, put the code into a file called \fBexample\.js\fR and execute
30
29
it with the node program
31
30
.
32
31
.IP "" 4
33
32
.
34
33
.nf
35
 
> node example.js
36
 
Server running at http://127.0.0.1:8000/
 
34
> node example\.js
 
35
Server running at http://127\.0\.0\.1:8124/
37
36
.
38
37
.fi
39
38
.
40
39
.IP "" 0
41
40
.
42
41
.P
43
 
All of the examples in the documentation can be run similarly.
 
42
All of the examples in the documentation can be run similarly\.
44
43
.
45
44
.SH "Standard Modules"
46
45
Node comes with a number of modules that are compiled in to the process,
47
 
most of which are documented below.  The most common way to use these modules
48
 
is with \fBrequire('name')\fR and then assigning the return value to a local
49
 
variable with the same name as the module.
 
46
most of which are documented below\.  The most common way to use these modules
 
47
is with \fBrequire(\'name\')\fR and then assigning the return value to a local
 
48
variable with the same name as the module\.
50
49
.
51
50
.P
52
51
Example:
54
53
.IP "" 4
55
54
.
56
55
.nf
57
 
var sys = require('sys');
 
56
var sys = require(\'sys\');
58
57
.
59
58
.fi
60
59
.
61
60
.IP "" 0
62
61
.
63
62
.P
64
 
It is possible to extend node with other modules.  See \fB'Modules'\fR
 
63
It is possible to extend node with other modules\.  See \fB\'Modules\'\fR
65
64
.
66
65
.SH "Buffers"
67
 
Pure Javascript is Unicode friendly but not nice to binary data.  When
68
 
dealing with TCP streams or the file system, it's necessary to handle octet
69
 
streams. Node has several strategies for manipulating, creating, and
70
 
consuming octet streams.
 
66
Pure Javascript is Unicode friendly but not nice to binary data\.  When
 
67
dealing with TCP streams or the file system, it\'s necessary to handle octet
 
68
streams\. Node has several strategies for manipulating, creating, and
 
69
consuming octet streams\.
71
70
.
72
71
.P
73
 
Raw data is stored in instances of the \fBBuffer\fR class. A \fBBuffer\fR is similar
 
72
Raw data is stored in instances of the \fBBuffer\fR class\. A \fBBuffer\fR is similar
74
73
to an array of integers but corresponds to a raw memory allocation outside
75
 
the V8 heap. A \fBBuffer\fR cannot be resized.
76
 
Access the class with \fBrequire('buffer').Buffer\fR.
 
74
the V8 heap\. A \fBBuffer\fR cannot be resized\.
 
75
.
 
76
.P
 
77
The \fBBuffer\fR object is global\.
77
78
.
78
79
.P
79
80
Converting between Buffers and JavaScript string objects requires an explicit encoding
80
 
method.  Node supports 3 string encodings: UTF\-8 (\fB'utf8'\fR), ASCII (\fB'ascii'\fR), and
81
 
Binary (\fB'binary'\fR).
82
 
.
83
 
.IP "\(bu" 4
84
 
\fB'ascii'\fR \- for 7 bit ASCII data only.  This encoding method is very fast, and will
85
 
strip the high bit if set.
86
 
.
87
 
.IP "\(bu" 4
88
 
\fB'binary'\fR \- for 8 bit binary data such as images.
89
 
.
90
 
.IP "\(bu" 4
91
 
\fB'utf8'\fR \- Unicode characters.  Many web pages and other document formats use UTF\-8.
 
81
method\.  Here are the different string encodings;
 
82
.
 
83
.IP "\(bu" 4
 
84
\fB\'ascii\'\fR \- for 7 bit ASCII data only\.  This encoding method is very fast, and will
 
85
strip the high bit if set\.
 
86
.
 
87
.IP "\(bu" 4
 
88
\fB\'utf8\'\fR \- Unicode characters\.  Many web pages and other document formats use UTF\-8\.
 
89
.
 
90
.IP "\(bu" 4
 
91
\fB\'base64\'\fR \- Base64 string encoding\.
 
92
.
 
93
.IP "\(bu" 4
 
94
\fB\'binary\'\fR \- A way of encoding raw binary data into strings by using only
 
95
the first 8 bits of each character\. This encoding method is depreciated and
 
96
should be avoided in favor of \fBBuffer\fR objects where possible\. This encoding
 
97
will be removed in future versions of Node\.
92
98
.
93
99
.IP "" 0
94
100
.
95
101
.SS "new Buffer(size)"
96
 
Allocates a new buffer of \fBsize\fR octets.
 
102
Allocates a new buffer of \fBsize\fR octets\.
97
103
.
98
104
.SS "new Buffer(array)"
99
 
Allocates a new buffer using an \fBarray\fR of octets.
100
 
.
101
 
.SS "new Buffer(str, encoding = 'utf8')"
102
 
Allocates a new buffer containing the given \fBstr\fR.
103
 
.
104
 
.SS "buffer.write(string, encoding, offset)"
105
 
Writes \fBstring\fR to the buffer at \fBoffset\fR using the given encoding. Returns
106
 
number of octets written.  If \fBbuffer\fR did not contain enough space to fit
107
 
the entire string it will write a partial amount of the string. In the case
108
 
of \fB'utf8'\fR encoding, the method will not write partial characters.
 
105
Allocates a new buffer using an \fBarray\fR of octets\.
 
106
.
 
107
.SS "new Buffer(str, encoding=\'utf8\')"
 
108
Allocates a new buffer containing the given \fBstr\fR\|\.
 
109
.
 
110
.SS "buffer\.write(string, offset=0, encoding=\'utf8\')"
 
111
Writes \fBstring\fR to the buffer at \fBoffset\fR using the given encoding\. Returns
 
112
number of octets written\.  If \fBbuffer\fR did not contain enough space to fit
 
113
the entire string it will write a partial amount of the string\. In the case
 
114
of \fB\'utf8\'\fR encoding, the method will not write partial characters\.
109
115
.
110
116
.P
111
117
Example: write a utf8 string into a buffer, then print it
113
119
.IP "" 4
114
120
.
115
121
.nf
116
 
var sys = require('sys'),
117
 
  Buffer = require('buffer').Buffer,
118
 
  buf = new Buffer(256),
119
 
  len;
120
 
len = buf.write('\\u00bd + \\u00bc = \\u00be', 'utf8', 0);
121
 
sys.puts(len + " bytes: " + buf.toString('utf8', 0, len));
 
122
buf = new Buffer(256);
 
123
len = buf\.write(\'\\u00bd + \\u00bc = \\u00be\', 0);
 
124
console\.log(len + " bytes: " + buf\.toString(\'utf8\', 0, len));
122
125
// 12 bytes: ½ + ¼ = ¾
123
126
.
124
127
.fi
125
128
.
126
129
.IP "" 0
127
130
.
128
 
.SS "buffer.toString(encoding, start, end)"
 
131
.SS "buffer\.toString(encoding, start=0, end=buffer\.length)"
129
132
Decodes and returns a string from buffer data encoded with \fBencoding\fR
130
 
beginning at \fBstart\fR and ending at \fBend\fR.
 
133
beginning at \fBstart\fR and ending at \fBend\fR\|\.
131
134
.
132
135
.P
133
 
See \fBbuffer.write()\fR example, above.
 
136
See \fBbuffer\.write()\fR example, above\.
134
137
.
135
138
.SS "buffer[index]"
136
 
Get and set the octet at \fBindex\fR. The values refer to individual bytes,
137
 
so the legal range is between \fB0x00\fR and \fB0xFF\fR hex or \fB0\fR and \fB255\fR.
 
139
Get and set the octet at \fBindex\fR\|\. The values refer to individual bytes,
 
140
so the legal range is between \fB0x00\fR and \fB0xFF\fR hex or \fB0\fR and \fB255\fR\|\.
138
141
.
139
142
.P
140
143
Example: copy an ASCII string into a buffer, one byte at a time:
142
145
.IP "" 4
143
146
.
144
147
.nf
145
 
var sys = require('sys'),
146
 
  Buffer = require('buffer').Buffer,
147
 
  str = "node.js",
148
 
  buf = new Buffer(str.length),
149
 
  i;
150
 
for (i = 0; i < str.length ; i += 1) {
151
 
  buf[i] = str.charCodeAt(i);
 
148
str = "node\.js";
 
149
buf = new Buffer(str\.length);
 
150
for (var i = 0; i < str\.length ; i++) {
 
151
  buf[i] = str\.charCodeAt(i);
152
152
}
153
 
sys.puts(buf);
154
 
// node.js
 
153
console\.log(buf);
 
154
// node\.js
155
155
.
156
156
.fi
157
157
.
158
158
.IP "" 0
159
159
.
160
 
.SS "Buffer.byteLength(string, encoding)"
161
 
Gives the actual byte length of a string.  This is not the same as\fBString.prototype.length\fR since that returns the number of \fIcharacters\fR in a
162
 
string.
 
160
.SS "Buffer\.byteLength(string, encoding=\'utf8\')"
 
161
Gives the actual byte length of a string\.  This is not the same as  \fBString\.prototype\.length\fR since that returns the number of \fIcharacters\fR in a
 
162
string\.
163
163
.
164
164
.P
165
165
Example:
167
167
.IP "" 4
168
168
.
169
169
.nf
170
 
var sys = require('sys'),
171
 
  Buffer = require('buffer').Buffer,
172
 
  str = '\\u00bd + \\u00bc = \\u00be';
173
 
sys.puts(str + ": " + str.length + " characters, " +
174
 
  Buffer.byteLength(str, 'utf8') + " bytes");
 
170
str = \'\\u00bd + \\u00bc = \\u00be\';
 
171
console\.log(str + ": " + str\.length + " characters, " +
 
172
  Buffer\.byteLength(str, \'utf8\') + " bytes");
175
173
// ½ + ¼ = ¾: 9 characters, 12 bytes
176
174
.
177
175
.fi
178
176
.
179
177
.IP "" 0
180
178
.
181
 
.SS "buffer.length"
182
 
The size of the buffer in bytes.  Note that this is not necessarily the size
183
 
of the contents. \fBlength\fR refers to the amount of memory allocated for the
184
 
buffer object.  It does not change when the contents of the buffer are changed.
 
179
.SS "buffer\.length"
 
180
The size of the buffer in bytes\.  Note that this is not necessarily the size
 
181
of the contents\. \fBlength\fR refers to the amount of memory allocated for the 
 
182
buffer object\.  It does not change when the contents of the buffer are changed\.
185
183
.
186
184
.IP "" 4
187
185
.
188
186
.nf
189
 
var sys = require('sys'),
190
 
  Buffer = require('buffer').Buffer,
191
 
  buf = new Buffer(1234);
192
 
sys.puts(buf.length);
193
 
buf.write("some string", "ascii", 0);
194
 
sys.puts(buf.length);
 
187
buf = new Buffer(1234);
 
188
console\.log(buf\.length);
 
189
buf\.write("some string", "ascii", 0);
 
190
console\.log(buf\.length);
195
191
// 1234
196
192
// 1234
197
193
.
199
195
.
200
196
.IP "" 0
201
197
.
202
 
.SS "buffer.copy(targetBuffer, targetStart, sourceStart, sourceEnd)"
203
 
Does a memcpy() between buffers.
 
198
.SS "buffer\.copy(targetBuffer, targetStart, sourceStart, sourceEnd=buffer\.length)"
 
199
Does a memcpy() between buffers\.
204
200
.
205
201
.P
206
 
Example: build two Buffers, then copy \fBbuf1\fR from byte 16 through byte 20
207
 
into \fBbuf2\fR, starting at the 8th byte in \fBbuf2\fR.
 
202
Example: build two Buffers, then copy \fBbuf1\fR from byte 16 through byte 19
 
203
into \fBbuf2\fR, starting at the 8th byte in \fBbuf2\fR\|\.
208
204
.
209
205
.IP "" 4
210
206
.
211
207
.nf
212
 
var sys = require('sys'),
213
 
  Buffer = require('buffer').Buffer,
214
 
  buf1 = new Buffer(26),
215
 
  buf2 = new Buffer(26),
216
 
  i;
217
 
for (i = 0 ; i < 26 ; i += 1) {
 
208
buf1 = new Buffer(26);
 
209
buf2 = new Buffer(26);
 
210
for (var i = 0 ; i < 26 ; i++) {
218
211
  buf1[i] = i + 97; // 97 is ASCII a
219
212
  buf2[i] = 33; // ASCII !
220
213
}
221
 
buf1.copy(buf2, 8, 16, 20);
222
 
sys.puts(buf2.toString('ascii', 0, 25));
 
214
buf1\.copy(buf2, 8, 16, 20);
 
215
console\.log(buf2\.toString(\'ascii\', 0, 25));
223
216
// !!!!!!!!qrst!!!!!!!!!!!!!
224
217
.
225
218
.fi
226
219
.
227
220
.IP "" 0
228
221
.
229
 
.SS "buffer.slice(start, end)"
 
222
.SS "buffer\.slice(start, end)"
230
223
Returns a new buffer which references the
231
224
same memory as the old, but offset and cropped by the \fBstart\fR and \fBend\fR
232
 
indexes.
 
225
indexes\.
233
226
.
234
227
.P
235
228
\fBModifying the new buffer slice will modify memory in the original buffer!\fR
236
229
.
237
230
.P
238
231
Example: build a Buffer with the ASCII alphabet, take a slice, then modify one byte
239
 
from the original Buffer.
 
232
from the original Buffer\.
240
233
.
241
234
.IP "" 4
242
235
.
243
236
.nf
244
 
var sys = require('sys'),
245
 
  Buffer = require('buffer').Buffer,
246
 
  buf1 = new Buffer(26), buf2,
247
 
  i;
248
 
for (i = 0 ; i < 26 ; i += 1) {
 
237
var buf1 = new Buffer(26);
 
238
for (var i = 0 ; i < 26 ; i++) {
249
239
  buf1[i] = i + 97; // 97 is ASCII a
250
240
}
251
 
buf2 = buf1.slice(0, 3);
252
 
sys.puts(buf2.toString('ascii', 0, buf2.length));
 
241
var buf2 = buf1\.slice(0, 3);
 
242
console\.log(buf2\.toString(\'ascii\', 0, buf2\.length));
253
243
buf1[0] = 33;
254
 
sys.puts(buf2.toString('ascii', 0, buf2.length));
 
244
console\.log(buf2\.toString(\'ascii\', 0, buf2\.length));
255
245
// abc
256
246
// !bc
257
247
.
261
251
.
262
252
.SH "EventEmitter"
263
253
Many objects in Node emit events: a TCP server emits an event each time
264
 
there is a stream, a child process emits an event when it exits. All
265
 
objects which emit events are instances of \fBevents.EventEmitter\fR.
 
254
there is a stream, a child process emits an event when it exits\. All
 
255
objects which emit events are instances of \fBevents\.EventEmitter\fR\|\.
266
256
.
267
257
.P
268
 
Events are represented by a camel\-cased string. Here are some examples:\fB'stream'\fR, \fB'data'\fR, \fB'messageBegin'\fR.
 
258
Events are represented by a camel\-cased string\. Here are some examples: \fB\'stream\'\fR, \fB\'data\'\fR, \fB\'messageBegin\'\fR\|\.
269
259
.
270
260
.P
271
261
Functions can be then be attached to objects, to be executed when an event
272
 
is emitted. These functions are called \fIlisteners\fR.
273
 
.
274
 
.P
275
 
\fBrequire('events').EventEmitter\fR to access the \fBEventEmitter\fR class.
276
 
.
277
 
.P
278
 
All EventEmitters emit the event \fB'newListener'\fR when new listeners are
279
 
added.
280
 
.
281
 
.P
282
 
When an EventEmitter experiences an error, the typical action is to emit an\fB'error'\fR event.  Error events are special\-\-if there is no handler for them
283
 
they will print a stack trace and exit the program.
284
 
.
285
 
.SS "Event: 'newListener'"
 
262
is emitted\. These functions are called \fIlisteners\fR\|\.
 
263
.
 
264
.P
 
265
\fBrequire(\'events\')\.EventEmitter\fR to access the \fBEventEmitter\fR class\.
 
266
.
 
267
.P
 
268
All EventEmitters emit the event \fB\'newListener\'\fR when new listeners are
 
269
added\.
 
270
.
 
271
.P
 
272
When an \fBEventEmitter\fR experiences an error, the typical action is to emit an \fB\'error\'\fR event\.  Error events are special\-\-if there is no handler for them
 
273
they will print a stack trace and exit the program\.
 
274
.
 
275
.SS "Event: \'newListener\'"
286
276
\fBfunction (event, listener) { }\fR
287
277
.
288
278
.P
289
 
This event is made any time someone adds a new listener.
 
279
This event is emitted any time someone adds a new listener\.
290
280
.
291
 
.SS "Event: 'error'"
 
281
.SS "Event: \'error\'"
292
282
\fBfunction (exception) { }\fR
293
283
.
294
284
.P
295
 
If an error was encountered, then this event is emitted. This event is
 
285
If an error was encountered, then this event is emitted\. This event is
296
286
special \- when there are no listeners to receive the error Node will
297
 
terminate execution and display the exception's stack trace.
298
 
.
299
 
.SS "emitter.addListener(event, listener)"
300
 
Adds a listener to the end of the listeners array for the specified event.
301
 
.
302
 
.IP "" 4
303
 
.
304
 
.nf
305
 
server.addListener('stream', function (stream) {
306
 
  sys.puts('someone connected!');
307
 
});
308
 
.
309
 
.fi
310
 
.
311
 
.IP "" 0
312
 
.
313
 
.SS "emitter.removeListener(event, listener)"
314
 
Remove a listener from the listener array for the specified event.\fBCaution\fR: changes array indices in the listener array behind the listener.
315
 
.
316
 
.SS "emitter.removeAllListeners(event)"
317
 
Removes all listeners from the listener array for the specified event.
318
 
.
319
 
.SS "emitter.listeners(event)"
320
 
Returns an array of listeners for the specified event. This array can be
321
 
manipulated, e.g. to remove listeners.
322
 
.
323
 
.SS "emitter.emit(event, arg1, arg2, ...)"
324
 
Execute each of the listeners in order with the supplied arguments.
 
287
terminate execution and display the exception\'s stack trace\.
 
288
.
 
289
.SS "emitter\.on(event, listener)"
 
290
Adds a listener to the end of the listeners array for the specified event\.
 
291
.
 
292
.IP "" 4
 
293
.
 
294
.nf
 
295
server\.on(\'stream\', function (stream) {
 
296
  console\.log(\'someone connected!\');
 
297
});
 
298
.
 
299
.fi
 
300
.
 
301
.IP "" 0
 
302
.
 
303
.SS "emitter\.removeListener(event, listener)"
 
304
Remove a listener from the listener array for the specified event\. \fBCaution\fR: changes array indices in the listener array behind the listener\.
 
305
.
 
306
.IP "" 4
 
307
.
 
308
.nf
 
309
var callback = function(stream) {
 
310
  console\.log(\'someone connected!\');
 
311
};
 
312
server\.on(\'stream\', callback);
 
313
// \.\.\.
 
314
server\.removeListener(\'stream\', callback);
 
315
.
 
316
.fi
 
317
.
 
318
.IP "" 0
 
319
.
 
320
.SS "emitter\.removeAllListeners(event)"
 
321
Removes all listeners from the listener array for the specified event\.
 
322
.
 
323
.SS "emitter\.listeners(event)"
 
324
Returns an array of listeners for the specified event\. This array can be
 
325
manipulated, e\.g\. to remove listeners\.
 
326
.
 
327
.IP "" 4
 
328
.
 
329
.nf
 
330
server\.on(\'stream\', function (stream) {
 
331
  console\.log(\'someone connected!\');
 
332
});
 
333
console\.log(sys\.inspect(server\.listeners(\'stream\'));
 
334
// [ [Function] ]
 
335
.
 
336
.fi
 
337
.
 
338
.IP "" 0
 
339
.
 
340
.SS "emitter\.emit(event, [arg1], [arg2], [\.\.\.])"
 
341
Execute each of the listeners in order with the supplied arguments\.
325
342
.
326
343
.SH "Streams"
327
 
A stream is an abstract interface implemented by various objects in Node.
328
 
For example a request to an HTTP server is a stream, as is stdout. Streams
329
 
are readable, writable, or both. All streams are instances of \fBEventEmitter\fR.
 
344
A stream is an abstract interface implemented by various objects in Node\.
 
345
For example a request to an HTTP server is a stream, as is stdout\. Streams
 
346
are readable, writable, or both\. All streams are instances of \fBEventEmitter\fR\|\.
330
347
.
331
348
.SH "Readable Stream"
332
 
A \fBreadable stream\fR has the following methods, members, and events.
 
349
A \fBReadable Stream\fR has the following methods, members, and events\.
333
350
.
334
 
.SS "Event: 'data'"
 
351
.SS "Event: \'data\'"
335
352
\fBfunction (data) { }\fR
336
353
.
337
354
.P
338
 
The \fB'data'\fR event emits either a \fBBuffer\fR (by default) or a string if \fBsetEncoding()\fR was used.
 
355
The \fB\'data\'\fR event emits either a \fBBuffer\fR (by default) or a string if \fBsetEncoding()\fR was used\.
339
356
.
340
 
.SS "Event: 'end'"
 
357
.SS "Event: \'end\'"
341
358
\fBfunction () { }\fR
342
359
.
343
360
.P
344
 
Emitted when the stream has received an EOF (FIN in TCP terminology).
345
 
Indicates that no more \fB'data'\fR events will happen. If the stream is also
346
 
writable, it may be possible to continue writing.
 
361
Emitted when the stream has received an EOF (FIN in TCP terminology)\.
 
362
Indicates that no more \fB\'data\'\fR events will happen\. If the stream is also
 
363
writable, it may be possible to continue writing\.
347
364
.
348
 
.SS "Event: 'error'"
 
365
.SS "Event: \'error\'"
349
366
\fBfunction (exception) { }\fR
350
367
.
351
368
.P
352
 
Emitted if there was an error receiving data.
 
369
Emitted if there was an error receiving data\.
353
370
.
354
 
.SS "Event: 'close'"
 
371
.SS "Event: \'close\'"
355
372
\fBfunction () { }\fR
356
373
.
357
374
.P
358
 
Emitted when the underlying file descriptor has be closed. Not all streams
359
 
will emit this.  (For example, an incoming HTTP request will not emit\fB'close'\fR.)
360
 
.
361
 
.SS "stream.setEncoding(encoding)"
362
 
Makes the data event emit a string instead of a \fBBuffer\fR. \fBencoding\fR can be \fB'utf8'\fR, \fB'ascii'\fR, or \fB'binary'\fR.
363
 
.
364
 
.SS "stream.pause()"
365
 
Pauses the incoming \fB'data'\fR events.
366
 
.
367
 
.SS "stream.resume()"
368
 
Resumes the incoming \fB'data'\fR events after a \fBpause()\fR.
369
 
.
370
 
.SS "stream.destroy()"
371
 
Closes the underlying file descriptor. Stream will not emit any more events.
 
375
Emitted when the underlying file descriptor has be closed\. Not all streams
 
376
will emit this\.  (For example, an incoming HTTP request will not emit \fB\'close\'\fR\|\.)
 
377
.
 
378
.SS "Event: \'fd\'"
 
379
\fBfunction (fd) { }\fR
 
380
.
 
381
.P
 
382
Emitted when a file descriptor is received on the stream\. Only UNIX streams
 
383
support this functionality; all others will simply never emit this event\.
 
384
.
 
385
.SS "stream\.readable"
 
386
A boolean that is \fBtrue\fR by default, but turns \fBfalse\fR after an \fB\'error\'\fR
 
387
occured, the stream came to an \fB\'end\'\fR, or \fBdestroy()\fR was called\.
 
388
.
 
389
.SS "stream\.setEncoding(encoding)"
 
390
Makes the data event emit a string instead of a \fBBuffer\fR\|\. \fBencoding\fR can be \fB\'utf8\'\fR, \fB\'ascii\'\fR, or \fB\'base64\'\fR\|\.
 
391
.
 
392
.SS "stream\.pause()"
 
393
Pauses the incoming \fB\'data\'\fR events\.
 
394
.
 
395
.SS "stream\.resume()"
 
396
Resumes the incoming \fB\'data\'\fR events after a \fBpause()\fR\|\.
 
397
.
 
398
.SS "stream\.destroy()"
 
399
Closes the underlying file descriptor\. Stream will not emit any more events\.
372
400
.
373
401
.SH "Writable Stream"
374
 
A \fBwritable stream\fR has the following methods, members, and events.
 
402
A \fBWritable Stream\fR has the following methods, members, and events\.
375
403
.
376
 
.SS "Event: 'drain'"
 
404
.SS "Event: \'drain\'"
377
405
\fBfunction () { }\fR
378
406
.
379
407
.P
380
408
Emitted after a \fBwrite()\fR method was called that returned \fBfalse\fR to
381
 
indicate that it is safe to write again.
 
409
indicate that it is safe to write again\.
382
410
.
383
 
.SS "Event: 'error'"
 
411
.SS "Event: \'error\'"
384
412
\fBfunction (exception) { }\fR
385
413
.
386
414
.P
387
 
Emitted on error with the exception \fBexception\fR.
 
415
Emitted on error with the exception \fBexception\fR\|\.
388
416
.
389
 
.SS "Event: 'close'"
 
417
.SS "Event: \'close\'"
390
418
\fBfunction () { }\fR
391
419
.
392
420
.P
393
 
Emitted when the underlying file descriptor has been closed.
394
 
.
395
 
.SS "stream.write(string, encoding)"
396
 
Writes \fBstring\fR with the given \fBencoding\fR to the stream.  Returns \fBtrue\fR if
397
 
the string has been flushed to the kernel buffer.  Returns \fBfalse\fR to
 
421
Emitted when the underlying file descriptor has been closed\.
 
422
.
 
423
.SS "stream\.writeable"
 
424
A boolean that is \fBtrue\fR by default, but turns \fBfalse\fR after an \fB\'error\'\fR
 
425
occurred or \fBend()\fR / \fBdestroy()\fR was called\.
 
426
.
 
427
.SS "stream\.write(string, encoding=\'utf8\', [fd])"
 
428
Writes \fBstring\fR with the given \fBencoding\fR to the stream\.  Returns \fBtrue\fR if
 
429
the string has been flushed to the kernel buffer\.  Returns \fBfalse\fR to
398
430
indicate that the kernel buffer is full, and the data will be sent out in
399
 
the future. The \fB'drain'\fR event will indicate when the kernel buffer is
400
 
empty again. The \fBencoding\fR defaults to \fB'utf8'\fR.
401
 
.
402
 
.SS "stream.write(buffer)"
403
 
Same as the above except with a raw buffer.
404
 
.
405
 
.SS "stream.end()"
406
 
Terminates the stream with EOF or FIN.
407
 
.
408
 
.SS "stream.end(string, encoding)"
 
431
the future\. The \fB\'drain\'\fR event will indicate when the kernel buffer is
 
432
empty again\. The \fBencoding\fR defaults to \fB\'utf8\'\fR\|\.
 
433
.
 
434
.P
 
435
If the optional \fBfd\fR parameter is specified, it is interpreted as an integral
 
436
file descriptor to be sent over the stream\. This is only supported for UNIX
 
437
streams, and is silently ignored otherwise\. When writing a file descriptor in
 
438
this manner, closing the descriptor before the stream drains risks sending an
 
439
invalid (closed) FD\.
 
440
.
 
441
.SS "stream\.write(buffer)"
 
442
Same as the above except with a raw buffer\.
 
443
.
 
444
.SS "stream\.end()"
 
445
Terminates the stream with EOF or FIN\.
 
446
.
 
447
.SS "stream\.end(string, encoding)"
409
448
Sends \fBstring\fR with the given \fBencoding\fR and terminates the stream with EOF
410
 
or FIN. This is useful to reduce the number of packets sent.
411
 
.
412
 
.SS "stream.end(buffer)"
413
 
Same as above but with a \fBbuffer\fR.
414
 
.
415
 
.SS "stream.destroy()"
416
 
Closes the underlying file descriptor. Stream will not emit any more events.
 
449
or FIN\. This is useful to reduce the number of packets sent\.
 
450
.
 
451
.SS "stream\.end(buffer)"
 
452
Same as above but with a \fBbuffer\fR\|\.
 
453
.
 
454
.SS "stream\.destroy()"
 
455
Closes the underlying file descriptor\. Stream will not emit any more events\.
417
456
.
418
457
.SH "Global Objects"
419
 
These object are available in the global scope and can be accessed from anywhere.
 
458
These object are available in the global scope and can be accessed from anywhere\.
420
459
.
421
460
.SS "global"
422
 
The global namespace object.
 
461
The global namespace object\.
423
462
.
424
463
.SS "process"
425
 
The process object. Most stuff lives in here. See the \fB'process object'\fR
426
 
section.
 
464
The process object\. See the \fB\'process object\'\fR section\.
427
465
.
428
466
.SS "require()"
429
 
To require modules. See the \fB'Modules'\fR section.
 
467
To require modules\. See the \fB\'Modules\'\fR section\.
430
468
.
431
 
.SS "require.paths"
432
 
An array of search paths for \fBrequire()\fR.  This array can be modified to add custom paths.
 
469
.SS "require\.paths"
 
470
An array of search paths for \fBrequire()\fR\|\.  This array can be modified to add custom paths\.
433
471
.
434
472
.P
435
473
Example: add a new path to the beginning of the search list
437
475
.IP "" 4
438
476
.
439
477
.nf
440
 
var sys = require('sys');
441
 
require.paths.unshift('/usr/local/node');
442
 
sys.puts(require.paths);
443
 
// /usr/local/node,/Users/mjr/.node_libraries
 
478
require\.paths\.unshift(\'/usr/local/node\');
 
479
console\.log(require\.paths);
 
480
// /usr/local/node,/Users/mjr/\.node_libraries
444
481
.
445
482
.fi
446
483
.
447
484
.IP "" 0
448
485
.
449
486
.SS "__filename"
450
 
The filename of the script being executed.  This is the absolute path, and not necessarily
451
 
the same filename passed in as a command line argument.
 
487
The filename of the script being executed\.  This is the absolute path, and not necessarily
 
488
the same filename passed in as a command line argument\.
 
489
.
 
490
.P
 
491
Example: running \fBnode example\.js\fR from \fB/Users/mjr\fR
 
492
.
 
493
.IP "" 4
 
494
.
 
495
.nf
 
496
console\.log(__filename);
 
497
// /Users/mjr/example\.js
 
498
.
 
499
.fi
 
500
.
 
501
.IP "" 0
452
502
.
453
503
.SS "__dirname"
454
 
The dirname of the script being executed.
 
504
The dirname of the script being executed\.
455
505
.
456
506
.P
457
 
Example: running \fBnode example.js\fR from \fB/Users/mjr\fR
 
507
Example: running \fBnode example\.js\fR from \fB/Users/mjr\fR
458
508
.
459
509
.IP "" 4
460
510
.
461
511
.nf
462
 
var sys = require('sys');
463
 
sys.puts(__filename);
464
 
sys.puts(__dirname);
465
 
// /Users/mjr/example.js
 
512
console\.log(__dirname);
466
513
// /Users/mjr
467
514
.
468
515
.fi
470
517
.IP "" 0
471
518
.
472
519
.SS "module"
473
 
A reference to the current module (of type \fBprocess.Module\fR). In particular \fBmodule.exports\fR is the same as the \fBexports\fR object. See \fBsrc/process.js\fR
474
 
for more information.
 
520
A reference to the current module (of type \fBprocess\.Module\fR)\. In particular \fBmodule\.exports\fR is the same as the \fBexports\fR object\. See \fBsrc/process\.js\fR
 
521
for more information\.
475
522
.
476
523
.SH "process"
477
 
The \fBprocess\fR object is a global object and can be accessed from anywhere.
478
 
It is an instance of \fBEventEmitter\fR.
 
524
The \fBprocess\fR object is a global object and can be accessed from anywhere\.
 
525
It is an instance of \fBEventEmitter\fR\|\.
479
526
.
480
 
.SS "Event: 'exit'"
 
527
.SS "Event: \'exit\'"
481
528
\fBfunction () {}\fR
482
529
.
483
530
.P
484
 
Emitted when the process is about to exit.  This is a good hook to perform
485
 
constant time checks of the module's state (like for unit tests).  The main
486
 
event loop will no longer be run after the 'exit' callback finishes, so
487
 
timers may not be scheduled.
 
531
Emitted when the process is about to exit\.  This is a good hook to perform
 
532
constant time checks of the module\'s state (like for unit tests)\.  The main
 
533
event loop will no longer be run after the \'exit\' callback finishes, so
 
534
timers may not be scheduled\.
488
535
.
489
536
.P
490
537
Example of listening for \fBexit\fR:
492
539
.IP "" 4
493
540
.
494
541
.nf
495
 
var sys = require('sys');
496
 
process.addListener('exit', function () {
497
 
  process.nextTick(function () {
498
 
   sys.puts('This will not run');
 
542
process\.on(\'exit\', function () {
 
543
  process\.nextTick(function () {
 
544
   console\.log(\'This will not run\');
499
545
  });
500
 
  sys.puts('About to exit.');
 
546
  console\.log(\'About to exit\.\');
501
547
});
502
548
.
503
549
.fi
504
550
.
505
551
.IP "" 0
506
552
.
507
 
.SS "Event: 'uncaughtException'"
 
553
.SS "Event: \'uncaughtException\'"
508
554
\fBfunction (err) { }\fR
509
555
.
510
556
.P
511
 
Emitted when an exception bubbles all the way back to the event loop. If a
 
557
Emitted when an exception bubbles all the way back to the event loop\. If a
512
558
listener is added for this exception, the default action (which is to print
513
 
a stack trace and exit) will not occur.
 
559
a stack trace and exit) will not occur\.
514
560
.
515
561
.P
516
562
Example of listening for \fBuncaughtException\fR:
518
564
.IP "" 4
519
565
.
520
566
.nf
521
 
var sys = require('sys');
522
 
process.addListener('uncaughtException', function (err) {
523
 
  sys.puts('Caught exception: ' + err);
 
567
process\.on(\'uncaughtException\', function (err) {
 
568
  console\.log(\'Caught exception: \' + err);
524
569
});
525
570
setTimeout(function () {
526
 
  sys.puts('This will still run.');
 
571
  console\.log(\'This will still run\.\');
527
572
}, 500);
528
 
// Intentionally cause an exception, but don't catch it.
 
573
// Intentionally cause an exception, but don\'t catch it\.
529
574
nonexistentFunc();
530
 
sys.puts('This will not run.');
 
575
console\.log(\'This will not run\.\');
531
576
.
532
577
.fi
533
578
.
535
580
.
536
581
.P
537
582
Note that \fBuncaughtException\fR is a very crude mechanism for exception
538
 
handling.  Using try / catch in your program will give you more control over
539
 
your program's flow.  Especially for server programs that are designed to
540
 
stay running forever, \fBuncaughtException\fR can be a useful safety mechanism.
 
583
handling\.  Using try / catch in your program will give you more control over
 
584
your program\'s flow\.  Especially for server programs that are designed to
 
585
stay running forever, \fBuncaughtException\fR can be a useful safety mechanism\.
541
586
.
542
587
.SS "Signal Events"
543
588
\fBfunction () {}\fR
544
589
.
545
590
.P
546
 
Emitted when the processes receives a signal. See sigaction(2) for a list of
547
 
standard POSIX signal names such as SIGINT, SIGUSR1, etc.
 
591
Emitted when the processes receives a signal\. See sigaction(2) for a list of
 
592
standard POSIX signal names such as SIGINT, SIGUSR1, etc\.
548
593
.
549
594
.P
550
595
Example of listening for \fBSIGINT\fR:
552
597
.IP "" 4
553
598
.
554
599
.nf
555
 
var sys = require('sys'),
556
 
    stdin = process.openStdin();
557
 
process.addListener('SIGINT', function () {
558
 
  sys.puts('Got SIGINT.  Press Control\-D to exit.');
 
600
var stdin = process\.openStdin();
 
601
process\.on(\'SIGINT\', function () {
 
602
  console\.log(\'Got SIGINT\.  Press Control\-D to exit\.\');
559
603
});
560
604
.
561
605
.fi
564
608
.
565
609
.P
566
610
An easy way to send the \fBSIGINT\fR signal is with \fBControl\-C\fR in most terminal
567
 
programs.
 
611
programs\.
568
612
.
569
 
.SS "process.stdout"
570
 
A writable stream to \fBstdout\fR.
 
613
.SS "process\.stdout"
 
614
A \fBWritable Stream\fR to \fBstdout\fR\|\.
571
615
.
572
616
.P
573
 
Example: the definition of \fBsys.puts\fR
 
617
Example: the definition of \fBconsole\.log\fR
574
618
.
575
619
.IP "" 4
576
620
.
577
621
.nf
578
 
exports.puts = function (d) {
579
 
  process.stdout.write(d + '\\n');
 
622
console\.log = function (d) {
 
623
  process\.stdout\.write(d + \'\\n\');
580
624
};
581
625
.
582
626
.fi
583
627
.
584
628
.IP "" 0
585
629
.
586
 
.SS "process.openStdin()"
587
 
Opens the standard input stream, returns a readable stream.
 
630
.SS "process\.openStdin()"
 
631
Opens the standard input stream, returns a \fBReadable Stream\fR\|\.
588
632
.
589
633
.P
590
634
Example of opening standard input and listening for both events:
592
636
.IP "" 4
593
637
.
594
638
.nf
595
 
var stdin = process.openStdin();
596
 
stdin.setEncoding('utf8');
597
 
stdin.addListener('data', function (chunk) {
598
 
  process.stdout.write('data: ' + chunk);
 
639
var stdin = process\.openStdin();
 
640
stdin\.setEncoding(\'utf8\');
 
641
stdin\.on(\'data\', function (chunk) {
 
642
  process\.stdout\.write(\'data: \' + chunk);
599
643
});
600
 
stdin.addListener('end', function () {
601
 
  process.stdout.write('end');
 
644
stdin\.on(\'end\', function () {
 
645
  process\.stdout\.write(\'end\');
602
646
});
603
647
.
604
648
.fi
605
649
.
606
650
.IP "" 0
607
651
.
608
 
.SS "process.argv"
609
 
An array containing the command line arguments.  The first element will be
610
 
'node', the second element will be the name of the JavaScript file.  The
611
 
next elements will be any additional command line arguments.
 
652
.SS "process\.argv"
 
653
An array containing the command line arguments\.  The first element will be
 
654
\'node\', the second element will be the name of the JavaScript file\.  The
 
655
next elements will be any additional command line arguments\.
612
656
.
613
657
.IP "" 4
614
658
.
615
659
.nf
616
 
// print process.argv
617
 
var sys = require('sys');
618
 
process.argv.forEach(function (val, index, array) {
619
 
  sys.puts(index + ': ' + val);
 
660
// print process\.argv
 
661
process\.argv\.forEach(function (val, index, array) {
 
662
  console\.log(index + \': \' + val);
620
663
});
621
664
.
622
665
.fi
629
672
.IP "" 4
630
673
.
631
674
.nf
632
 
$ node process\-2.js one two=three four
 
675
$ node process\-2\.js one two=three four
633
676
0: node
634
 
1: /Users/mjr/work/node/process\-2.js
 
677
1: /Users/mjr/work/node/process\-2\.js
635
678
2: one
636
679
3: two=three
637
680
4: four
640
683
.
641
684
.IP "" 0
642
685
.
643
 
.SS "process.chdir(directory)"
644
 
Changes the current working directory of the process or throws an exception if that fails.
645
 
.
646
 
.IP "" 4
647
 
.
648
 
.nf
649
 
var sys = require('sys');
650
 
sys.puts('Starting directory: ' + process.cwd());
 
686
.SS "process\.execPath"
 
687
This is the absolute pathname of the executable that started the process\.
 
688
.
 
689
.P
 
690
Example:
 
691
.
 
692
.IP "" 4
 
693
.
 
694
.nf
 
695
/usr/local/bin/node
 
696
.
 
697
.fi
 
698
.
 
699
.IP "" 0
 
700
.
 
701
.SS "process\.chdir(directory)"
 
702
Changes the current working directory of the process or throws an exception if that fails\.
 
703
.
 
704
.IP "" 4
 
705
.
 
706
.nf
 
707
console\.log(\'Starting directory: \' + process\.cwd());
651
708
try {
652
 
  process.chdir('/tmp');
653
 
  sys.puts('New directory: ' + process.cwd());
 
709
  process\.chdir(\'/tmp\');
 
710
  console\.log(\'New directory: \' + process\.cwd());
654
711
}
655
712
catch (err) {
656
 
  sys.puts('chdir: ' + err);
 
713
  console\.log(\'chdir: \' + err);
657
714
}
658
715
.
659
716
.fi
660
717
.
661
718
.IP "" 0
662
719
.
663
 
.SS "process.compile(code, filename)"
 
720
.SS "process\.compile(code, filename)"
664
721
Similar to \fBeval\fR except that you can specify a \fBfilename\fR for better
665
 
error reporting and the \fBcode\fR cannot see the local scope.  The value of \fBfilename\fR
666
 
will be used as a filename if a stack trace is generated by the compiled code.
 
722
error reporting and the \fBcode\fR cannot see the local scope\.  The value of \fBfilename\fR
 
723
will be used as a filename if a stack trace is generated by the compiled code\.
667
724
.
668
725
.P
669
 
Example of using \fBprocess.compile\fR and \fBeval\fR to run the same code:
 
726
Example of using \fBprocess\.compile\fR and \fBeval\fR to run the same code:
670
727
.
671
728
.IP "" 4
672
729
.
673
730
.nf
674
 
var sys = require('sys'),
675
 
    localVar = 123,
 
731
var localVar = 123,
676
732
    compiled, evaled;
677
 
compiled = process.compile('localVar = 1;', 'myfile.js');
678
 
sys.puts('localVar: ' + localVar + ', compiled: ' + compiled);
679
 
evaled = eval('localVar = 1;');
680
 
sys.puts('localVar: ' + localVar + ', evaled: ' + evaled);
 
733
compiled = process\.compile(\'localVar = 1;\', \'myfile\.js\');
 
734
console\.log(\'localVar: \' + localVar + \', compiled: \' + compiled);
 
735
evaled = eval(\'localVar = 1;\');
 
736
console\.log(\'localVar: \' + localVar + \', evaled: \' + evaled);
681
737
// localVar: 123, compiled: 1
682
738
// localVar: 1, evaled: 1
683
739
.
686
742
.IP "" 0
687
743
.
688
744
.P
689
 
\fBprocess.compile\fR does not have access to the local scope, so \fBlocalVar\fR is unchanged. \fBeval\fR does have access to the local scope, so \fBlocalVar\fR is changed.
 
745
\fBprocess\.compile\fR does not have access to the local scope, so \fBlocalVar\fR is unchanged\. \fBeval\fR does have access to the local scope, so \fBlocalVar\fR is changed\.
690
746
.
691
747
.P
692
 
In case of syntax error in \fBcode\fR, \fBprocess.compile\fR exits node.
 
748
In case of syntax error in \fBcode\fR, \fBprocess\.compile\fR exits node\.
693
749
.
694
750
.P
695
751
See also: \fBScript\fR
696
752
.
697
 
.SS "process.cwd()"
698
 
Returns the current working directory of the process.
699
 
.
700
 
.IP "" 4
701
 
.
702
 
.nf
703
 
require('sys').puts('Current directory: ' + process.cwd());
704
 
.
705
 
.fi
706
 
.
707
 
.IP "" 0
708
 
.
709
 
.SS "process.env"
710
 
An object containing the user environment. See environ(7).
711
 
.
712
 
.SS "process.exit(code)"
713
 
Ends the process with the specified \fBcode\fR.  If omitted, exit uses the
714
 
'success' code \fB0\fR.
715
 
.
716
 
.P
717
 
To exit with a 'failure' code:
718
 
.
719
 
.IP "" 4
720
 
.
721
 
.nf
722
 
process.exit(1);
723
 
.
724
 
.fi
725
 
.
726
 
.IP "" 0
727
 
.
728
 
.P
729
 
The shell that executed node should see the exit code as 1.
730
 
.
731
 
.SS "process.getgid(), process.setgid(id)"
732
 
Gets/sets the group identity of the process. (See setgid(2).)  This is the numerical group id, not the group name.
733
 
.
734
 
.IP "" 4
735
 
.
736
 
.nf
737
 
var sys = require('sys');
738
 
sys.puts('Current gid: ' + process.getgid());
739
 
try {
740
 
  process.setgid(501);
741
 
  sys.puts('New gid: ' + process.getgid());
742
 
}
743
 
catch (err) {
744
 
  sys.puts('Failed to set gid: ' + err);
745
 
}
746
 
.
747
 
.fi
748
 
.
749
 
.IP "" 0
750
 
.
751
 
.SS "process.getuid(), process.setuid(id)"
752
 
Gets/sets the user identity of the process. (See setuid(2).)  This is the numerical userid, not the username.
753
 
.
754
 
.IP "" 4
755
 
.
756
 
.nf
757
 
var sys = require('sys');
758
 
sys.puts('Current uid: ' + process.getuid());
759
 
try {
760
 
  process.setuid(501);
761
 
  sys.puts('New uid: ' + process.getuid());
762
 
}
763
 
catch (err) {
764
 
  sys.puts('Failed to set uid: ' + err);
765
 
}
766
 
.
767
 
.fi
768
 
.
769
 
.IP "" 0
770
 
.
771
 
.SS "process.version"
772
 
A compiled\-in property that exposes \fBNODE_VERSION\fR.
773
 
.
774
 
.IP "" 4
775
 
.
776
 
.nf
777
 
require('sys').puts('Version: ' + process.version);
778
 
.
779
 
.fi
780
 
.
781
 
.IP "" 0
782
 
.
783
 
.SS "process.installPrefix"
784
 
A compiled\-in property that exposes \fBNODE_PREFIX\fR.
785
 
.
786
 
.IP "" 4
787
 
.
788
 
.nf
789
 
require('sys').puts('Prefix: ' + process.installPrefix);
790
 
.
791
 
.fi
792
 
.
793
 
.IP "" 0
794
 
.
795
 
.SS "process.kill(pid, signal)"
796
 
Send a signal to a process. \fBpid\fR is the process id and \fBsignal\fR is the
797
 
string describing the signal to send.  Signal names are strings like
798
 
'SIGINT' or 'SIGUSR1'.  If omitted, the signal will be 'SIGINT'.
799
 
See kill(2) for more information.
800
 
.
801
 
.P
802
 
Note that just because the name of this function is \fBprocess.kill\fR, it is
803
 
really just a signal sender, like the \fBkill\fR system call.  The signal sent
804
 
may do something other than kill the target process.
 
753
.SS "process\.cwd()"
 
754
Returns the current working directory of the process\.
 
755
.
 
756
.IP "" 4
 
757
.
 
758
.nf
 
759
console\.log(\'Current directory: \' + process\.cwd());
 
760
.
 
761
.fi
 
762
.
 
763
.IP "" 0
 
764
.
 
765
.SS "process\.env"
 
766
An object containing the user environment\. See environ(7)\.
 
767
.
 
768
.SS "process\.exit(code=0)"
 
769
Ends the process with the specified \fBcode\fR\|\.  If omitted, exit uses the 
 
770
\'success\' code \fB0\fR\|\.
 
771
.
 
772
.P
 
773
To exit with a \'failure\' code:
 
774
.
 
775
.IP "" 4
 
776
.
 
777
.nf
 
778
process\.exit(1);
 
779
.
 
780
.fi
 
781
.
 
782
.IP "" 0
 
783
.
 
784
.P
 
785
The shell that executed node should see the exit code as 1\.
 
786
.
 
787
.SS "process\.getgid()"
 
788
Gets the group identity of the process\. (See getgid(2)\.)  This is the numerical group id, not the group name\.
 
789
.
 
790
.IP "" 4
 
791
.
 
792
.nf
 
793
console\.log(\'Current gid: \' + process\.getgid());
 
794
.
 
795
.fi
 
796
.
 
797
.IP "" 0
 
798
.
 
799
.SS "process\.setgid(id)"
 
800
Sets the group identity of the process\. (See setgid(2)\.)  This accepts either a numerical ID or a groupname string\.  If a groupname is specified, this method blocks while resolving it to a numerical ID\.
 
801
.
 
802
.IP "" 4
 
803
.
 
804
.nf
 
805
console\.log(\'Current gid: \' + process\.getgid());
 
806
try {
 
807
  process\.setgid(501);
 
808
  console\.log(\'New gid: \' + process\.getgid());
 
809
}
 
810
catch (err) {
 
811
  console\.log(\'Failed to set gid: \' + err);
 
812
}
 
813
.
 
814
.fi
 
815
.
 
816
.IP "" 0
 
817
.
 
818
.SS "process\.getuid()"
 
819
Gets the user identity of the process\. (See getuid(2)\.)  This is the numerical userid, not the username\.
 
820
.
 
821
.IP "" 4
 
822
.
 
823
.nf
 
824
console\.log(\'Current uid: \' + process\.getuid());
 
825
.
 
826
.fi
 
827
.
 
828
.IP "" 0
 
829
.
 
830
.SS "process\.setuid(id)"
 
831
Sets the user identity of the process\. (See setuid(2)\.)  This accepts either a numerical ID or a username string\.  If a username is specified, this method blocks while resolving it to a numerical ID\.
 
832
.
 
833
.IP "" 4
 
834
.
 
835
.nf
 
836
console\.log(\'Current uid: \' + process\.getuid());
 
837
try {
 
838
  process\.setuid(501);
 
839
  console\.log(\'New uid: \' + process\.getuid());
 
840
}
 
841
catch (err) {
 
842
  console\.log(\'Failed to set uid: \' + err);
 
843
}
 
844
.
 
845
.fi
 
846
.
 
847
.IP "" 0
 
848
.
 
849
.SS "process\.version"
 
850
A compiled\-in property that exposes \fBNODE_VERSION\fR\|\.
 
851
.
 
852
.IP "" 4
 
853
.
 
854
.nf
 
855
console\.log(\'Version: \' + process\.version);
 
856
.
 
857
.fi
 
858
.
 
859
.IP "" 0
 
860
.
 
861
.SS "process\.installPrefix"
 
862
A compiled\-in property that exposes \fBNODE_PREFIX\fR\|\.
 
863
.
 
864
.IP "" 4
 
865
.
 
866
.nf
 
867
console\.log(\'Prefix: \' + process\.installPrefix);
 
868
.
 
869
.fi
 
870
.
 
871
.IP "" 0
 
872
.
 
873
.SS "process\.kill(pid, signal=\'SIGINT\')"
 
874
Send a signal to a process\. \fBpid\fR is the process id and \fBsignal\fR is the
 
875
string describing the signal to send\.  Signal names are strings like
 
876
\'SIGINT\' or \'SIGUSR1\'\.  If omitted, the signal will be \'SIGINT\'\.
 
877
See kill(2) for more information\.
 
878
.
 
879
.P
 
880
Note that just because the name of this function is \fBprocess\.kill\fR, it is
 
881
really just a signal sender, like the \fBkill\fR system call\.  The signal sent
 
882
may do something other than kill the target process\.
805
883
.
806
884
.P
807
885
Example of sending a signal to yourself:
809
887
.IP "" 4
810
888
.
811
889
.nf
812
 
var sys = require('sys');
813
 
process.addListener('SIGHUP', function () {
814
 
  sys.puts('Got SIGHUP signal.');
 
890
process\.on(\'SIGHUP\', function () {
 
891
  console\.log(\'Got SIGHUP signal\.\');
815
892
});
816
893
setTimeout(function () {
817
 
  sys.puts('Exiting.');
818
 
  process.exit(0);
 
894
  console\.log(\'Exiting\.\');
 
895
  process\.exit(0);
819
896
}, 100);
820
 
process.kill(process.pid, 'SIGHUP');
821
 
.
822
 
.fi
823
 
.
824
 
.IP "" 0
825
 
.
826
 
.SS "process.pid"
827
 
The PID of the process.
828
 
.
829
 
.IP "" 4
830
 
.
831
 
.nf
832
 
require('sys').puts('This process is pid ' + process.pid);
833
 
.
834
 
.fi
835
 
.
836
 
.IP "" 0
837
 
.
838
 
.SS "process.platform"
839
 
What platform you're running on. \fB'linux2'\fR, \fB'darwin'\fR, etc.
840
 
.
841
 
.IP "" 4
842
 
.
843
 
.nf
844
 
require('sys').puts('This platform is ' + process.platform);
845
 
.
846
 
.fi
847
 
.
848
 
.IP "" 0
849
 
.
850
 
.SS "process.memoryUsage()"
851
 
Returns an object describing the memory usage of the Node process.
852
 
.
853
 
.IP "" 4
854
 
.
855
 
.nf
856
 
var sys = require('sys');
857
 
sys.puts(sys.inspect(process.memoryUsage()));
 
897
process\.kill(process\.pid, \'SIGHUP\');
 
898
.
 
899
.fi
 
900
.
 
901
.IP "" 0
 
902
.
 
903
.SS "process\.pid"
 
904
The PID of the process\.
 
905
.
 
906
.IP "" 4
 
907
.
 
908
.nf
 
909
console\.log(\'This process is pid \' + process\.pid);
 
910
.
 
911
.fi
 
912
.
 
913
.IP "" 0
 
914
.
 
915
.SS "process\.title"
 
916
Getter/setter to set what is displayed in \'ps\'\.
 
917
.
 
918
.SS "process\.platform"
 
919
What platform you\'re running on\. \fB\'linux2\'\fR, \fB\'darwin\'\fR, etc\.
 
920
.
 
921
.IP "" 4
 
922
.
 
923
.nf
 
924
console\.log(\'This platform is \' + process\.platform);
 
925
.
 
926
.fi
 
927
.
 
928
.IP "" 0
 
929
.
 
930
.SS "process\.memoryUsage()"
 
931
Returns an object describing the memory usage of the Node process\.
 
932
.
 
933
.IP "" 4
 
934
.
 
935
.nf
 
936
var sys = require(\'sys\');
 
937
console\.log(sys\.inspect(process\.memoryUsage()));
858
938
.
859
939
.fi
860
940
.
877
957
.IP "" 0
878
958
.
879
959
.P
880
 
\fBheapTotal\fR and \fBheapUsed\fR refer to V8's memory usage.
 
960
\fBheapTotal\fR and \fBheapUsed\fR refer to V8\'s memory usage\.
881
961
.
882
 
.SS "process.nextTick(callback)"
883
 
On the next loop around the event loop call this callback.
884
 
This is \fInot\fR a simple alias to \fBsetTimeout(fn, 0)\fR, it's much more
885
 
efficient.
 
962
.SS "process\.nextTick(callback)"
 
963
On the next loop around the event loop call this callback\.
 
964
This is \fInot\fR a simple alias to \fBsetTimeout(fn, 0)\fR, it\'s much more
 
965
efficient\.
886
966
.
887
967
.IP "" 4
888
968
.
889
969
.nf
890
 
var sys = require('sys');
891
 
process.nextTick(function () {
892
 
  sys.puts('nextTick callback');
 
970
process\.nextTick(function () {
 
971
  console\.log(\'nextTick callback\');
893
972
});
894
973
.
895
974
.fi
896
975
.
897
976
.IP "" 0
898
977
.
899
 
.SS "process.umask(mask)"
900
 
Sets or read the process's file mode creation mask. Child processes inherit
901
 
the mask from the parent process. Returns the old mask if \fBmask\fR argument is
902
 
given, otherwise returns the current mask.
 
978
.SS "process\.umask([mask])"
 
979
Sets or reads the process\'s file mode creation mask\. Child processes inherit
 
980
the mask from the parent process\. Returns the old mask if \fBmask\fR argument is
 
981
given, otherwise returns the current mask\.
903
982
.
904
983
.IP "" 4
905
984
.
906
985
.nf
907
 
var sys = require('sys'),
908
 
    oldmask, newmask = 0644;
909
 
oldmask = process.umask(newmask);
910
 
sys.puts('Changed umask from: ' + oldmask.toString(8) +
911
 
         ' to ' + newmask.toString(8));
 
986
var oldmask, newmask = 0644;
 
987
oldmask = process\.umask(newmask);
 
988
console\.log(\'Changed umask from: \' + oldmask\.toString(8) +
 
989
            \' to \' + newmask\.toString(8));
912
990
.
913
991
.fi
914
992
.
915
993
.IP "" 0
916
994
.
917
995
.SH "sys"
918
 
These functions are in the module \fB'sys'\fR. Use \fBrequire('sys')\fR to access
919
 
them.
920
 
.
921
 
.SS "sys.puts(string)"
922
 
Outputs \fBstring\fR and a trailing newline to \fBstdout\fR.
923
 
.
924
 
.IP "" 4
925
 
.
926
 
.nf
927
 
require('sys').puts('String with a newline');
928
 
.
929
 
.fi
930
 
.
931
 
.IP "" 0
932
 
.
933
 
.SS "sys.print(string)"
934
 
Like \fBputs()\fR but without the trailing newline.
935
 
.
936
 
.IP "" 4
937
 
.
938
 
.nf
939
 
require('sys').print('String with no newline');
940
 
.
941
 
.fi
942
 
.
943
 
.IP "" 0
944
 
.
945
 
.SS "sys.debug(string)"
946
 
A synchronous output function. Will block the process and
947
 
output \fBstring\fR immediately to \fBstderr\fR.
948
 
.
949
 
.IP "" 4
950
 
.
951
 
.nf
952
 
require('sys').debug('message on stderr');
953
 
.
954
 
.fi
955
 
.
956
 
.IP "" 0
957
 
.
958
 
.SS "sys.log(string)"
959
 
Output with timestamp on \fBstdout\fR.
960
 
.
961
 
.IP "" 4
962
 
.
963
 
.nf
964
 
require('sys').log('Timestmaped message.');
965
 
.
966
 
.fi
967
 
.
968
 
.IP "" 0
969
 
.
970
 
.SS "sys.inspect(object, showHidden, depth)"
971
 
Return a string representation of \fBobject\fR, which is useful for debugging.
 
996
These functions are in the module \fB\'sys\'\fR\|\. Use \fBrequire(\'sys\')\fR to access
 
997
them\.
 
998
.
 
999
.SS "sys\.print(string)"
 
1000
Like \fBconsole\.log()\fR but without the trailing newline\.
 
1001
.
 
1002
.IP "" 4
 
1003
.
 
1004
.nf
 
1005
require(\'sys\')\.print(\'String with no newline\');
 
1006
.
 
1007
.fi
 
1008
.
 
1009
.IP "" 0
 
1010
.
 
1011
.SS "sys\.debug(string)"
 
1012
A synchronous output function\. Will block the process and
 
1013
output \fBstring\fR immediately to \fBstderr\fR\|\.
 
1014
.
 
1015
.IP "" 4
 
1016
.
 
1017
.nf
 
1018
require(\'sys\')\.debug(\'message on stderr\');
 
1019
.
 
1020
.fi
 
1021
.
 
1022
.IP "" 0
 
1023
.
 
1024
.SS "sys\.log(string)"
 
1025
Output with timestamp on \fBstdout\fR\|\.
 
1026
.
 
1027
.IP "" 4
 
1028
.
 
1029
.nf
 
1030
require(\'sys\')\.log(\'Timestmaped message\.\');
 
1031
.
 
1032
.fi
 
1033
.
 
1034
.IP "" 0
 
1035
.
 
1036
.SS "sys\.inspect(object, showHidden=false, depth=2)"
 
1037
Return a string representation of \fBobject\fR, which is useful for debugging\.
972
1038
.
973
1039
.P
974
 
If \fBshowHidden\fR is \fBtrue\fR, then the object's non\-enumerable properties will be
975
 
shown too.
 
1040
If \fBshowHidden\fR is \fBtrue\fR, then the object\'s non\-enumerable properties will be
 
1041
shown too\.
976
1042
.
977
1043
.P
978
1044
If \fBdepth\fR is provided, it tells \fBinspect\fR how many times to recurse while
979
 
formatting the object. This is useful for inspecting large complicated objects.
 
1045
formatting the object\. This is useful for inspecting large complicated objects\.
980
1046
.
981
1047
.P
982
 
The default is to only recurse twice.  To make it recurse indefinitely, pass
983
 
in \fBnull\fR for \fBdepth\fR.
 
1048
The default is to only recurse twice\.  To make it recurse indefinitely, pass
 
1049
in \fBnull\fR for \fBdepth\fR\|\.
984
1050
.
985
1051
.P
986
1052
Example of inspecting all properties of the \fBsys\fR object:
988
1054
.IP "" 4
989
1055
.
990
1056
.nf
991
 
var sys = require('sys');
992
 
sys.puts(sys.inspect(sys, true, null));
 
1057
var sys = require(\'sys\');
 
1058
console\.log(sys\.inspect(sys, true, null));
993
1059
.
994
1060
.fi
995
1061
.
996
1062
.IP "" 0
997
1063
.
 
1064
.SS "sys\.pump(readableStream, writeableStream, [callback])"
 
1065
Experimental
 
1066
.
 
1067
.P
 
1068
Read the data from \fBreadableStream\fR and send it to the \fBwritableStream\fR\|\.
 
1069
When \fBwriteableStream\.write(data)\fR returns \fBfalse\fR \fBreadableStream\fR will be
 
1070
paused until the \fBdrain\fR event occurs on the \fBwritableStream\fR\|\. \fBcallback\fR is
 
1071
called when \fBwritableStream\fR is closed\.
 
1072
.
998
1073
.SH "Timers"
999
1074
.
1000
 
.SS "setTimeout(callback, delay, [arg, ...])"
1001
 
To schedule execution of \fBcallback\fR after \fBdelay\fR milliseconds. Returns a \fBtimeoutId\fR for possible use with \fBclearTimeout()\fR.
 
1075
.SS "setTimeout(callback, delay, [arg], [\.\.\.])"
 
1076
To schedule execution of \fBcallback\fR after \fBdelay\fR milliseconds\. Returns a \fBtimeoutId\fR for possible use with \fBclearTimeout()\fR\|\. Optionally, you can
 
1077
also pass arguments to the callback\.
1002
1078
.
1003
1079
.SS "clearTimeout(timeoutId)"
1004
 
Prevents a timeout from triggering.
1005
 
.
1006
 
.SS "setInterval(callback, delay, [arg, ...])"
1007
 
To schedule the repeated execution of \fBcallback\fR every \fBdelay\fR milliseconds.
1008
 
Returns a \fBintervalId\fR for possible use with \fBclearInterval()\fR.
1009
 
.
1010
 
.P
1011
 
Optionally, you can also pass arguments to the callback.
 
1080
Prevents a timeout from triggering\.
 
1081
.
 
1082
.SS "setInterval(callback, delay, [arg], [\.\.\.])"
 
1083
To schedule the repeated execution of \fBcallback\fR every \fBdelay\fR milliseconds\.
 
1084
Returns a \fBintervalId\fR for possible use with \fBclearInterval()\fR\|\. Optionally,
 
1085
you can also pass arguments to the callback\.
1012
1086
.
1013
1087
.SS "clearInterval(intervalId)"
1014
 
Stops a interval from triggering.
 
1088
Stops a interval from triggering\.
1015
1089
.
1016
1090
.SH "Child Processes"
1017
1091
Node provides a tri\-directional \fBpopen(3)\fR facility through the \fBChildProcess\fR
1018
 
class.
1019
 
.
1020
 
.P
1021
 
It is possible to stream data through the child's \fBstdin\fR, \fBstdout\fR, and \fBstderr\fR in a fully non\-blocking way.
1022
 
.
1023
 
.P
1024
 
To create a child process use \fBrequire('child_process').spawn()\fR.
1025
 
.
1026
 
.P
1027
 
Child processes always have three streams associated with them. \fBchild.stdin\fR, \fBchild.stdout\fR, and \fBchild.stderr\fR.
1028
 
.
1029
 
.P
1030
 
\fBChildProcess\fR is an EventEmitter.
1031
 
.
1032
 
.SS "Event:  'exit'"
 
1092
class\.
 
1093
.
 
1094
.P
 
1095
It is possible to stream data through the child\'s \fBstdin\fR, \fBstdout\fR, and \fBstderr\fR in a fully non\-blocking way\.
 
1096
.
 
1097
.P
 
1098
To create a child process use \fBrequire(\'child_process\')\.spawn()\fR\|\.
 
1099
.
 
1100
.P
 
1101
Child processes always have three streams associated with them\. \fBchild\.stdin\fR, \fBchild\.stdout\fR, and \fBchild\.stderr\fR\|\.
 
1102
.
 
1103
.P
 
1104
\fBChildProcess\fR is an \fBEventEmitter\fR\|\.
 
1105
.
 
1106
.SS "Event:  \'exit\'"
1033
1107
\fBfunction (code, signal) {}\fR
1034
1108
.
1035
1109
.P
1036
 
This event is emitted after the child process ends. If the process terminated
1037
 
normally, \fBcode\fR is the final exit code of the process, otherwise \fBnull\fR. If
 
1110
This event is emitted after the child process ends\. If the process terminated
 
1111
normally, \fBcode\fR is the final exit code of the process, otherwise \fBnull\fR\|\. If
1038
1112
the process terminated due to receipt of a signal, \fBsignal\fR is the string name
1039
 
of the signal, otherwise \fBnull\fR.
1040
 
.
1041
 
.P
1042
 
After this event is emitted, the \fB'output'\fR and \fB'error'\fR callbacks will no
1043
 
longer be made.
1044
 
.
1045
 
.P
1046
 
See \fBwaitpid(2)\fR.
1047
 
.
1048
 
.SS "child_process.spawn(command, args, env)"
1049
 
Launches a new process with the given \fBcommand\fR, command line arguments, and
1050
 
environment variables.  If omitted, \fBargs\fR defaults to an empty Array, and \fBenv\fR
1051
 
defaults to \fBprocess.env\fR.
 
1113
of the signal, otherwise \fBnull\fR\|\.
 
1114
.
 
1115
.P
 
1116
After this event is emitted, the \fB\'output\'\fR and \fB\'error\'\fR callbacks will no
 
1117
longer be made\.
 
1118
.
 
1119
.P
 
1120
See \fBwaitpid(2)\fR\|\.
 
1121
.
 
1122
.SS "child\.stdin"
 
1123
A \fBWritable Stream\fR that represents the child process\'s \fBstdin\fR\|\.
 
1124
Closing this stream via \fBend()\fR often causes the child process to terminate\.
 
1125
.
 
1126
.SS "child\.stdout"
 
1127
A \fBReadable Stream\fR that represents the child process\'s \fBstdout\fR\|\.
 
1128
.
 
1129
.SS "child\.stderr"
 
1130
A \fBReadable Stream\fR that represents the child process\'s \fBstderr\fR\|\.
 
1131
.
 
1132
.SS "child\.pid"
 
1133
The PID of the child process\.
 
1134
.
 
1135
.P
 
1136
Example:
 
1137
.
 
1138
.IP "" 4
 
1139
.
 
1140
.nf
 
1141
var spawn = require(\'child_process\')\.spawn,
 
1142
    grep  = spawn(\'grep\', [\'ssh\']);
 
1143
console\.log(\'Spawned child pid: \' + grep\.pid);
 
1144
grep\.stdin\.end();
 
1145
.
 
1146
.fi
 
1147
.
 
1148
.IP "" 0
 
1149
.
 
1150
.SS "child_process\.spawn(command, args=[], [options])"
 
1151
Launches a new process with the given \fBcommand\fR, with  command line arguments in \fBargs\fR\|\.
 
1152
If omitted, \fBargs\fR defaults to an empty Array\.
 
1153
.
 
1154
.P
 
1155
The third argument is used to specify additional options, which defaults to:
 
1156
.
 
1157
.IP "" 4
 
1158
.
 
1159
.nf
 
1160
{ cwd: undefined
 
1161
, env: process\.env,
 
1162
, customFds: [\-1, \-1, \-1]
 
1163
}
 
1164
.
 
1165
.fi
 
1166
.
 
1167
.IP "" 0
 
1168
.
 
1169
.P
 
1170
\fBcwd\fR allows you to specify the working directory from which the process is spawned\.
 
1171
Use \fBenv\fR to specify environment variables that will be visible to the new process\.
 
1172
With \fBcustomFds\fR it is possible to hook up the new process\' [stdin, stout, stderr] to
 
1173
existing streams; \fB\-1\fR means that a new stream should be created\.
1052
1174
.
1053
1175
.P
1054
1176
Example of running \fBls \-lh /usr\fR, capturing \fBstdout\fR, \fBstderr\fR, and the exit code:
1056
1178
.IP "" 4
1057
1179
.
1058
1180
.nf
1059
 
var sys   = require('sys'),
1060
 
    spawn = require('child_process').spawn,
1061
 
    ls    = spawn('ls', ['\-lh', '/usr']);
1062
 
ls.stdout.addListener('data', function (data) {
1063
 
  sys.print('stdout: ' + data);
1064
 
});
1065
 
ls.stderr.addListener('data', function (data) {
1066
 
  sys.print('stderr: ' + data);
1067
 
});
1068
 
ls.addListener('exit', function (code) {
1069
 
  sys.puts('child process exited with code ' + code);
 
1181
var sys   = require(\'sys\'),
 
1182
    spawn = require(\'child_process\')\.spawn,
 
1183
    ls    = spawn(\'ls\', [\'\-lh\', \'/usr\']);
 
1184
ls\.stdout\.on(\'data\', function (data) {
 
1185
  sys\.print(\'stdout: \' + data);
 
1186
});
 
1187
ls\.stderr\.on(\'data\', function (data) {
 
1188
  sys\.print(\'stderr: \' + data);
 
1189
});
 
1190
ls\.on(\'exit\', function (code) {
 
1191
  console\.log(\'child process exited with code \' + code);
 
1192
});
 
1193
.
 
1194
.fi
 
1195
.
 
1196
.IP "" 0
 
1197
.
 
1198
.P
 
1199
Example: A very elaborate way to run \'ps ax | grep ssh\'
 
1200
.
 
1201
.IP "" 4
 
1202
.
 
1203
.nf
 
1204
var sys   = require(\'sys\'),
 
1205
    spawn = require(\'child_process\')\.spawn,
 
1206
    ps    = spawn(\'ps\', [\'ax\']),
 
1207
    grep  = spawn(\'grep\', [\'ssh\']);
 
1208
ps\.stdout\.on(\'data\', function (data) {
 
1209
  grep\.stdin\.write(data);
 
1210
});
 
1211
ps\.stderr\.on(\'data\', function (data) {
 
1212
  sys\.print(\'ps stderr: \' + data);
 
1213
});
 
1214
ps\.on(\'exit\', function (code) {
 
1215
  if (code !== 0) {
 
1216
    console\.log(\'ps process exited with code \' + code);
 
1217
  }
 
1218
  grep\.stdin\.end();
 
1219
});
 
1220
grep\.stdout\.on(\'data\', function (data) {
 
1221
  sys\.print(data);
 
1222
});
 
1223
grep\.stderr\.on(\'data\', function (data) {
 
1224
  sys\.print(\'grep stderr: \' + data);
 
1225
});
 
1226
grep\.on(\'exit\', function (code) {
 
1227
  if (code !== 0) {
 
1228
    console\.log(\'grep process exited with code \' + code);
 
1229
  }
1070
1230
});
1071
1231
.
1072
1232
.fi
1079
1239
.IP "" 4
1080
1240
.
1081
1241
.nf
1082
 
var sys   = require('sys'),
1083
 
    spawn = require('child_process').spawn,
1084
 
    child = spawn('bad_command');
1085
 
child.stderr.addListener('data', function (data) {
1086
 
  if (/^execvp\\(\\)/.test(data.asciiSlice(0,data.length))) {
1087
 
    sys.puts('Failed to start child process.');
1088
 
  }
1089
 
});
1090
 
.
1091
 
.fi
1092
 
.
1093
 
.IP "" 0
1094
 
.
1095
 
.P
1096
 
See also: \fBchild_process.exec()\fR
1097
 
.
1098
 
.SS "child.kill(signal)"
1099
 
Send a signal to the child process. If no argument is given, the process will
1100
 
be sent \fB'SIGTERM'\fR. See \fBsignal(7)\fR for a list of available signals.
1101
 
.
1102
 
.IP "" 4
1103
 
.
1104
 
.nf
1105
 
var sys   = require('sys'),
1106
 
    spawn = require('child_process').spawn,
1107
 
    grep  = spawn('grep', ['ssh']);
1108
 
grep.addListener('exit', function (code, signal) {
1109
 
  sys.puts('child process terminated due to receipt of signal '+signal);
1110
 
});
1111
 
// send SIGHUP to process
1112
 
grep.kill('SIGHUP');
1113
 
.
1114
 
.fi
1115
 
.
1116
 
.IP "" 0
1117
 
.
1118
 
.P
1119
 
Note that while the function is called \fBkill\fR, the signal delivered to the child
1120
 
process may not actually kill it.  \fBkill\fR really just sends a signal to a process.
1121
 
.
1122
 
.P
1123
 
See \fBkill(2)\fR
1124
 
.
1125
 
.SS "child.pid"
1126
 
The PID of the child process.
1127
 
.
1128
 
.P
1129
 
Example:
1130
 
.
1131
 
.IP "" 4
1132
 
.
1133
 
.nf
1134
 
var sys   = require('sys'),
1135
 
    spawn = require('child_process').spawn,
1136
 
    grep  = spawn('grep', ['ssh']);
1137
 
sys.puts('Spawned child pid: ' + grep.pid);
1138
 
grep.stdin.end();
1139
 
.
1140
 
.fi
1141
 
.
1142
 
.IP "" 0
1143
 
.
1144
 
.SS "child.stdin.write(data, encoding)"
1145
 
Write data to the child process's \fBstdin\fR. The second argument is optional and
1146
 
specifies the encoding: possible values are \fB'utf8'\fR, \fB'ascii'\fR, and \fB'binary'\fR.
1147
 
.
1148
 
.P
1149
 
Example: A very elaborate way to run 'ps ax | grep ssh'
1150
 
.
1151
 
.IP "" 4
1152
 
.
1153
 
.nf
1154
 
var sys   = require('sys'),
1155
 
    spawn = require('child_process').spawn,
1156
 
    ps    = spawn('ps', ['ax']),
1157
 
    grep  = spawn('grep', ['ssh']);
1158
 
ps.stdout.addListener('data', function (data) {
1159
 
  grep.stdin.write(data);
1160
 
});
1161
 
ps.stderr.addListener('data', function (data) {
1162
 
  sys.print('ps stderr: ' + data);
1163
 
});
1164
 
ps.addListener('exit', function (code) {
1165
 
  if (code !== 0) {
1166
 
    sys.puts('ps process exited with code ' + code);
1167
 
  }
1168
 
  grep.stdin.end();
1169
 
});
1170
 
grep.stdout.addListener('data', function (data) {
1171
 
  sys.print(data);
1172
 
});
1173
 
grep.stderr.addListener('data', function (data) {
1174
 
  sys.print('grep stderr: ' + data);
1175
 
});
1176
 
grep.addListener('exit', function (code) {
1177
 
  if (code !== 0) {
1178
 
    sys.puts('grep process exited with code ' + code);
1179
 
  }
1180
 
});
1181
 
.
1182
 
.fi
1183
 
.
1184
 
.IP "" 0
1185
 
.
1186
 
.SS "child.stdin.end()"
1187
 
Closes the child process's \fBstdin\fR stream.  This often causes the child process to terminate.
1188
 
.
1189
 
.P
1190
 
Example:
1191
 
.
1192
 
.IP "" 4
1193
 
.
1194
 
.nf
1195
 
var sys   = require('sys'),
1196
 
    spawn = require('child_process').spawn,
1197
 
    grep  = spawn('grep', ['ssh']);
1198
 
grep.addListener('exit', function (code) {
1199
 
  sys.puts('child process exited with code ' + code);
1200
 
});
1201
 
grep.stdin.end();
1202
 
.
1203
 
.fi
1204
 
.
1205
 
.IP "" 0
1206
 
.
1207
 
.SS "child_process.exec(command, [options, ] callback)"
 
1242
var spawn = require(\'child_process\')\.spawn,
 
1243
    child = spawn(\'bad_command\');
 
1244
child\.stderr\.on(\'data\', function (data) {
 
1245
  if (/^execvp\\(\\)/\.test(data\.asciiSlice(0,data\.length))) {
 
1246
    console\.log(\'Failed to start child process\.\');
 
1247
  }
 
1248
});
 
1249
.
 
1250
.fi
 
1251
.
 
1252
.IP "" 0
 
1253
.
 
1254
.P
 
1255
See also: \fBchild_process\.exec()\fR
 
1256
.
 
1257
.SS "child_process\.exec(command, [options], callback)"
1208
1258
High\-level way to execute a command as a child process, buffer the
1209
 
output, and return it all in a callback.
 
1259
output, and return it all in a callback\.
1210
1260
.
1211
1261
.IP "" 4
1212
1262
.
1213
1263
.nf
1214
 
var sys   = require('sys'),
1215
 
    exec  = require('child_process').exec,
 
1264
var sys   = require(\'sys\'),
 
1265
    exec  = require(\'child_process\')\.exec,
1216
1266
    child;
1217
 
child = exec('cat *.js bad_file | wc \-l',
 
1267
child = exec(\'cat *\.js bad_file | wc \-l\', 
1218
1268
  function (error, stdout, stderr) {
1219
 
    sys.print('stdout: ' + stdout);
1220
 
    sys.print('stderr: ' + stderr);
 
1269
    sys\.print(\'stdout: \' + stdout);
 
1270
    sys\.print(\'stderr: \' + stderr);
1221
1271
    if (error !== null) {
1222
 
      sys.puts('exec error: ' + error);
 
1272
      console\.log(\'exec error: \' + error);
1223
1273
    }
1224
 
  });
 
1274
});
1225
1275
.
1226
1276
.fi
1227
1277
.
1228
1278
.IP "" 0
1229
1279
.
1230
1280
.P
1231
 
The callback gets the arguments \fB(error, stdout, stderr)\fR. On success, \fBerror\fR
1232
 
will be \fBnull\fR.  On error, \fBerror\fR will be an instance of \fBError\fR and \fBerr.code\fR
1233
 
will be the exit code of the child process, and \fBerr.signal\fR will be set to the
1234
 
signal that terminated the process.
 
1281
The callback gets the arguments \fB(error, stdout, stderr)\fR\|\. On success, \fBerror\fR
 
1282
will be \fBnull\fR\|\.  On error, \fBerror\fR will be an instance of \fBError\fR and \fBerr\.code\fR
 
1283
will be the exit code of the child process, and \fBerr\.signal\fR will be set to the
 
1284
signal that terminated the process\.
1235
1285
.
1236
1286
.P
1237
 
There is a second optional argument to specify several options. The default options are
 
1287
There is a second optional argument to specify several options\. The default options are
1238
1288
.
1239
1289
.IP "" 4
1240
1290
.
1241
1291
.nf
1242
 
{ encoding: 'utf8'
 
1292
{ encoding: \'utf8\'
1243
1293
, timeout: 0
1244
1294
, maxBuffer: 200*1024
1245
 
, killSignal: 'SIGKILL'
 
1295
, killSignal: \'SIGKILL\'
 
1296
, cwd: null
 
1297
, env: null
1246
1298
}
1247
1299
.
1248
1300
.fi
1251
1303
.
1252
1304
.P
1253
1305
If \fBtimeout\fR is greater than 0, then it will kill the child process
1254
 
if it runs longer than \fBtimeout\fR milliseconds. The child process is killed with \fBkillSignal\fR (default: \fB'SIGKILL'\fR). \fBmaxBuffer\fR specifies the largest
 
1306
if it runs longer than \fBtimeout\fR milliseconds\. The child process is killed with \fBkillSignal\fR (default: \fB\'SIGKILL\'\fR)\. \fBmaxBuffer\fR specifies the largest
1255
1307
amount of data allowed on stdout or stderr \- if this value is exceeded then
1256
 
the child process is killed.
 
1308
the child process is killed\.
 
1309
.
 
1310
.SS "child\.kill(signal=\'SIGTERM\')"
 
1311
Send a signal to the child process\. If no argument is given, the process will
 
1312
be sent \fB\'SIGTERM\'\fR\|\. See \fBsignal(7)\fR for a list of available signals\.
 
1313
.
 
1314
.IP "" 4
 
1315
.
 
1316
.nf
 
1317
var spawn = require(\'child_process\')\.spawn,
 
1318
    grep  = spawn(\'grep\', [\'ssh\']);
 
1319
grep\.on(\'exit\', function (code, signal) {
 
1320
  console\.log(\'child process terminated due to receipt of signal \'+signal);
 
1321
});
 
1322
// send SIGHUP to process
 
1323
grep\.kill(\'SIGHUP\');
 
1324
.
 
1325
.fi
 
1326
.
 
1327
.IP "" 0
 
1328
.
 
1329
.P
 
1330
Note that while the function is called \fBkill\fR, the signal delivered to the child
 
1331
process may not actually kill it\.  \fBkill\fR really just sends a signal to a process\.
 
1332
.
 
1333
.P
 
1334
See \fBkill(2)\fR
1257
1335
.
1258
1336
.SH "Script"
1259
 
\fBScript\fR class compiles and runs JavaScript code. You can access this class with:
 
1337
\fBScript\fR class compiles and runs JavaScript code\. You can access this class with:
1260
1338
.
1261
1339
.IP "" 4
1262
1340
.
1263
1341
.nf
1264
 
var Script = process.binding('evals').Script;
 
1342
var Script = process\.binding(\'evals\')\.Script;
1265
1343
.
1266
1344
.fi
1267
1345
.
1268
1346
.IP "" 0
1269
1347
.
1270
1348
.P
1271
 
New JavaScript code can be compiled and run immediately or compiled, saved, and run later.
 
1349
New JavaScript code can be compiled and run immediately or compiled, saved, and run later\.
1272
1350
.
1273
 
.SS "Script.runInThisContext(code, filename)"
1274
 
Similar to \fBprocess.compile\fR.  \fBScript.runInThisContext\fR compiles \fBcode\fR as if it were loaded from \fBfilename\fR,
1275
 
runs it and returns the result. Running code does not have access to local scope. \fBfilename\fR is optional.
 
1351
.SS "Script\.runInThisContext(code, [filename])"
 
1352
Similar to \fBprocess\.compile\fR\|\.  \fBScript\.runInThisContext\fR compiles \fBcode\fR as if it were loaded from \fBfilename\fR,
 
1353
runs it and returns the result\. Running code does not have access to local scope\. \fBfilename\fR is optional\.
1276
1354
.
1277
1355
.P
1278
 
Example of using \fBScript.runInThisContext\fR and \fBeval\fR to run the same code:
 
1356
Example of using \fBScript\.runInThisContext\fR and \fBeval\fR to run the same code:
1279
1357
.
1280
1358
.IP "" 4
1281
1359
.
1282
1360
.nf
1283
 
var sys = require('sys'),
1284
 
    localVar = 123,
 
1361
var localVar = 123,
1285
1362
    usingscript, evaled,
1286
 
    Script = process.binding('evals').Script;
1287
 
usingscript = Script.runInThisContext('localVar = 1;',
1288
 
  'myfile.js');
1289
 
sys.puts('localVar: ' + localVar + ', usingscript: ' +
 
1363
    Script = process\.binding(\'evals\')\.Script;
 
1364
usingscript = Script\.runInThisContext(\'localVar = 1;\',
 
1365
  \'myfile\.js\');
 
1366
console\.log(\'localVar: \' + localVar + \', usingscript: \' +
1290
1367
  usingscript);
1291
 
evaled = eval('localVar = 1;');
1292
 
sys.puts('localVar: ' + localVar + ', evaled: ' +
 
1368
evaled = eval(\'localVar = 1;\');
 
1369
console\.log(\'localVar: \' + localVar + \', evaled: \' +
1293
1370
  evaled);
1294
1371
// localVar: 123, usingscript: 1
1295
1372
// localVar: 1, evaled: 1
1299
1376
.IP "" 0
1300
1377
.
1301
1378
.P
1302
 
\fBScript.runInThisContext\fR does not have access to the local scope, so \fBlocalVar\fR is unchanged. \fBeval\fR does have access to the local scope, so \fBlocalVar\fR is changed.
1303
 
.
1304
 
.P
1305
 
In case of syntax error in \fBcode\fR, \fBScript.runInThisContext\fR emits the syntax error to stderr
1306
 
and throws.an exception.
1307
 
.
1308
 
.SS "Script.runInNewContext(code, sandbox, filename)"
1309
 
\fBScript.runInNewContext\fR compiles \fBcode\fR to run in \fBsandbox\fR as if it were loaded from \fBfilename\fR,
1310
 
then runs it and returns the result. Running code does not have access to local scope and
1311
 
the object \fBsandbox\fR will be used as the global object for \fBcode\fR. \fBsandbox\fR and \fBfilename\fR are optional.
1312
 
.
1313
 
.P
1314
 
Example: compile and execute code that increments a global variable and sets a new one.
1315
 
These globals are contained in the sandbox.
 
1379
\fBScript\.runInThisContext\fR does not have access to the local scope, so \fBlocalVar\fR is unchanged\. \fBeval\fR does have access to the local scope, so \fBlocalVar\fR is changed\.
 
1380
.
 
1381
.P
 
1382
In case of syntax error in \fBcode\fR, \fBScript\.runInThisContext\fR emits the syntax error to stderr
 
1383
and throws\.an exception\.
 
1384
.
 
1385
.SS "Script\.runInNewContext(code, [sandbox], [filename])"
 
1386
\fBScript\.runInNewContext\fR compiles \fBcode\fR to run in \fBsandbox\fR as if it were loaded from \fBfilename\fR,
 
1387
then runs it and returns the result\. Running code does not have access to local scope and
 
1388
the object \fBsandbox\fR will be used as the global object for \fBcode\fR\|\. \fBsandbox\fR and \fBfilename\fR are optional\.
 
1389
.
 
1390
.P
 
1391
Example: compile and execute code that increments a global variable and sets a new one\.
 
1392
These globals are contained in the sandbox\.
1316
1393
.
1317
1394
.IP "" 4
1318
1395
.
1319
1396
.nf
1320
 
var sys = require('sys'),
1321
 
    Script = process.binding('evals').Script,
 
1397
var sys = require(\'sys\'),
 
1398
    Script = process\.binding(\'evals\')\.Script,
1322
1399
    sandbox = {
1323
 
      animal: 'cat',
 
1400
      animal: \'cat\',
1324
1401
      count: 2
1325
1402
    };
1326
 
Script.runInNewContext(
1327
 
  'count += 1; name = "kitty"', sandbox, 'myfile.js');
1328
 
sys.puts(sys.inspect(sandbox));
1329
 
// { animal: 'cat', count: 3, name: 'kitty' }
 
1403
Script\.runInNewContext(
 
1404
  \'count += 1; name = "kitty"\', sandbox, \'myfile\.js\');
 
1405
console\.log(sys\.inspect(sandbox));
 
1406
// { animal: \'cat\', count: 3, name: \'kitty\' }
1330
1407
.
1331
1408
.fi
1332
1409
.
1333
1410
.IP "" 0
1334
1411
.
1335
1412
.P
1336
 
Note that running untrusted code is a tricky business requiring great care.  To prevent accidental
1337
 
global variable leakage, \fBScript.runInNewContext\fR is quite useful, but safely running untrusted code
1338
 
requires a separate process.
 
1413
Note that running untrusted code is a tricky business requiring great care\.  To prevent accidental
 
1414
global variable leakage, \fBScript\.runInNewContext\fR is quite useful, but safely running untrusted code
 
1415
requires a separate process\.
1339
1416
.
1340
1417
.P
1341
 
In case of syntax error in \fBcode\fR, \fBScript.runInThisContext\fR emits the syntax error to stderr
1342
 
and throws an exception.
 
1418
In case of syntax error in \fBcode\fR, \fBScript\.runInThisContext\fR emits the syntax error to stderr
 
1419
and throws an exception\.
1343
1420
.
1344
 
.SS "new Script(code, filename)"
 
1421
.SS "new Script(code, [filename])"
1345
1422
\fBnew Script\fR compiles \fBcode\fR as if it were loaded from \fBfilename\fR,
1346
 
but does not run it. Instead, it returns a \fBScript\fR object representing this compiled code.
1347
 
This script can be run later many times using methods below.
1348
 
The returned script is not bound to any global object.
1349
 
It is bound before each run, just for that run. \fBfilename\fR is optional.
 
1423
but does not run it\. Instead, it returns a \fBScript\fR object representing this compiled code\.
 
1424
This script can be run later many times using methods below\.
 
1425
The returned script is not bound to any global object\.
 
1426
It is bound before each run, just for that run\. \fBfilename\fR is optional\.
1350
1427
.
1351
1428
.P
1352
1429
In case of syntax error in \fBcode\fR, \fBnew Script\fR emits the syntax error to stderr
1353
 
and throws an exception.
 
1430
and throws an exception\.
1354
1431
.
1355
 
.SS "script.runInThisContext()"
1356
 
Similar to \fBScript.runInThisContext\fR (note capital 'S'), but now being a method of a precompiled Script object. \fBscript.runInThisContext\fR runs the code of \fBscript\fR and returns the result.
 
1432
.SS "script\.runInThisContext()"
 
1433
Similar to \fBScript\.runInThisContext\fR (note capital \'S\'), but now being a method of a precompiled Script object\. \fBscript\.runInThisContext\fR runs the code of \fBscript\fR and returns the result\.
1357
1434
Running code does not have access to local scope, but does have access to the \fBglobal\fR object
1358
 
(v8: in actual context).
 
1435
(v8: in actual context)\.
1359
1436
.
1360
1437
.P
1361
 
Example of using \fBscript.runInThisContext\fR to compile code once and run it multiple times:
 
1438
Example of using \fBscript\.runInThisContext\fR to compile code once and run it multiple times:
1362
1439
.
1363
1440
.IP "" 4
1364
1441
.
1365
1442
.nf
1366
 
var sys = require('sys'),
1367
 
    Script = process.binding('evals').Script,
 
1443
var Script = process\.binding(\'evals\')\.Script,
1368
1444
    scriptObj, i;
1369
1445
globalVar = 0;
1370
 
scriptObj = new Script('globalVar += 1', 'myfile.js');
 
1446
scriptObj = new Script(\'globalVar += 1\', \'myfile\.js\');
1371
1447
for (i = 0; i < 1000 ; i += 1) {
1372
 
  scriptObj.runInThisContext();
 
1448
  scriptObj\.runInThisContext();
1373
1449
}
1374
 
sys.puts(globalVar);
 
1450
console\.log(globalVar);
1375
1451
// 1000
1376
1452
.
1377
1453
.fi
1378
1454
.
1379
1455
.IP "" 0
1380
1456
.
1381
 
.SS "script.runInNewContext(sandbox)"
1382
 
Similar to \fBScript.runInNewContext\fR (note capital 'S'), but now being a method of a precompiled Script object. \fBscript.runInNewContext\fR runs the code of \fBscript\fR with \fBsandbox\fR as the global object and returns the result.
1383
 
Running code does not have access to local scope. \fBsandbox\fR is optional.
 
1457
.SS "script\.runInNewContext([sandbox])"
 
1458
Similar to \fBScript\.runInNewContext\fR (note capital \'S\'), but now being a method of a precompiled Script object\. \fBscript\.runInNewContext\fR runs the code of \fBscript\fR with \fBsandbox\fR as the global object and returns the result\.
 
1459
Running code does not have access to local scope\. \fBsandbox\fR is optional\.
1384
1460
.
1385
1461
.P
1386
 
Example: compile code that increments a global variable and sets one, then execute this code multiple times.
1387
 
These globals are contained in the sandbox.
 
1462
Example: compile code that increments a global variable and sets one, then execute this code multiple times\.
 
1463
These globals are contained in the sandbox\.
1388
1464
.
1389
1465
.IP "" 4
1390
1466
.
1391
1467
.nf
1392
 
var sys = require('sys'),
1393
 
    Script = process.binding('evals').Script,
 
1468
var sys = require(\'sys\'),
 
1469
    Script = process\.binding(\'evals\')\.Script,
1394
1470
    scriptObj, i,
1395
1471
    sandbox = {
1396
 
      animal: 'cat',
 
1472
      animal: \'cat\',
1397
1473
      count: 2
1398
1474
    };
1399
1475
scriptObj = new Script(
1400
 
    'count += 1; name = "kitty"', 'myfile.js');
 
1476
    \'count += 1; name = "kitty"\', \'myfile\.js\');
1401
1477
for (i = 0; i < 10 ; i += 1) {
1402
 
  scriptObj.runInNewContext(sandbox);
 
1478
  scriptObj\.runInNewContext(sandbox);
1403
1479
}
1404
 
sys.puts(sys.inspect(sandbox));
1405
 
// { animal: 'cat', count: 12, name: 'kitty' }
 
1480
console\.log(sys\.inspect(sandbox));
 
1481
// { animal: \'cat\', count: 12, name: \'kitty\' }
1406
1482
.
1407
1483
.fi
1408
1484
.
1409
1485
.IP "" 0
1410
1486
.
1411
1487
.P
1412
 
Note that running untrusted code is a tricky business requiring great care.  To prevent accidental
1413
 
global variable leakage, \fBscript.runInNewContext\fR is quite useful, but safely running untrusted code
1414
 
requires a separate process.
 
1488
Note that running untrusted code is a tricky business requiring great care\.  To prevent accidental
 
1489
global variable leakage, \fBscript\.runInNewContext\fR is quite useful, but safely running untrusted code
 
1490
requires a separate process\.
1415
1491
.
1416
1492
.SH "File System"
1417
 
File I/O is provided by simple wrappers around standard POSIX functions.  To
1418
 
use this module do \fBrequire('fs')\fR. All the methods have asynchronous and
1419
 
synchronous forms.
 
1493
File I/O is provided by simple wrappers around standard POSIX functions\.  To
 
1494
use this module do \fBrequire(\'fs\')\fR\|\. All the methods have asynchronous and
 
1495
synchronous forms\. 
1420
1496
.
1421
1497
.P
1422
 
The asynchronous form always take a completion callback as its last argument.
 
1498
The asynchronous form always take a completion callback as its last argument\.
1423
1499
The arguments passed to the completion callback depend on the method, but the
1424
 
first argument is always reserved for an exception. If the operation was
1425
 
completed successfully, then the first argument will be \fBnull\fR or \fBundefined\fR.
 
1500
first argument is always reserved for an exception\. If the operation was
 
1501
completed successfully, then the first argument will be \fBnull\fR or \fBundefined\fR\|\.
1426
1502
.
1427
1503
.P
1428
1504
Here is an example of the asynchronous version:
1430
1506
.IP "" 4
1431
1507
.
1432
1508
.nf
1433
 
var fs = require('fs'),
1434
 
    sys = require('sys');
1435
 
fs.unlink('/tmp/hello', function (err) {
 
1509
var fs = require(\'fs\');
 
1510
fs\.unlink(\'/tmp/hello\', function (err) {
1436
1511
  if (err) throw err;
1437
 
  sys.puts('successfully deleted /tmp/hello');
 
1512
  console\.log(\'successfully deleted /tmp/hello\');
1438
1513
});
1439
1514
.
1440
1515
.fi
1447
1522
.IP "" 4
1448
1523
.
1449
1524
.nf
1450
 
var fs = require('fs'),
1451
 
    sys = require('sys');
1452
 
fs.unlinkSync('/tmp/hello')
1453
 
sys.puts('successfully deleted /tmp/hello');
 
1525
var fs = require(\'fs\');
 
1526
fs\.unlinkSync(\'/tmp/hello\')
 
1527
console\.log(\'successfully deleted /tmp/hello\');
1454
1528
.
1455
1529
.fi
1456
1530
.
1457
1531
.IP "" 0
1458
1532
.
1459
1533
.P
1460
 
With the asynchronous methods there is no guaranteed ordering. So the
 
1534
With the asynchronous methods there is no guaranteed ordering\. So the
1461
1535
following is prone to error:
1462
1536
.
1463
1537
.IP "" 4
1464
1538
.
1465
1539
.nf
1466
 
fs.rename('/tmp/hello', '/tmp/world', function (err) {
 
1540
fs\.rename(\'/tmp/hello\', \'/tmp/world\', function (err) {
1467
1541
  if (err) throw err;
1468
 
  sys.puts('renamed complete');
 
1542
  console\.log(\'renamed complete\');
1469
1543
});
1470
 
fs.stat('/tmp/world', function (err, stats) {
 
1544
fs\.stat(\'/tmp/world\', function (err, stats) {
1471
1545
  if (err) throw err;
1472
 
  sys.puts('stats: ' + JSON.stringify(stats));
 
1546
  console\.log(\'stats: \' + JSON\.stringify(stats));
1473
1547
});
1474
1548
.
1475
1549
.fi
1477
1551
.IP "" 0
1478
1552
.
1479
1553
.P
1480
 
It could be that \fBfs.stat\fR is executed before \fBfs.rename\fR.
1481
 
The correct way to do this is to chain the callbacks.
 
1554
It could be that \fBfs\.stat\fR is executed before \fBfs\.rename\fR\|\.
 
1555
The correct way to do this is to chain the callbacks\.
1482
1556
.
1483
1557
.IP "" 4
1484
1558
.
1485
1559
.nf
1486
 
fs.rename('/tmp/hello', '/tmp/world', function (err) {
 
1560
fs\.rename(\'/tmp/hello\', \'/tmp/world\', function (err) {
1487
1561
  if (err) throw err;
1488
 
  fs.stat('/tmp/world', function (err, stats) {
 
1562
  fs\.stat(\'/tmp/world\', function (err, stats) {
1489
1563
    if (err) throw err;
1490
 
    sys.puts('stats: ' + JSON.stringify(stats));
 
1564
    console\.log(\'stats: \' + JSON\.stringify(stats));
1491
1565
  });
1492
1566
});
1493
1567
.
1497
1571
.
1498
1572
.P
1499
1573
In busy processes, the programmer is \fIstrongly encouraged\fR to use the
1500
 
asynchronous versions of these calls. The synchronous versions will block
1501
 
the entire process until they complete\-\-halting all connections.
1502
 
.
1503
 
.SS "fs.rename(path1, path2, callback)"
1504
 
Asynchronous rename(2). No arguments other than a possible exception are given to the completion callback.
1505
 
.
1506
 
.SS "fs.renameSync(path1, path2)"
1507
 
Synchronous rename(2).
1508
 
.
1509
 
.SS "fs.truncate(fd, len, callback)"
1510
 
Asynchronous ftruncate(2). No arguments other than a possible exception are given to the completion callback.
1511
 
.
1512
 
.SS "fs.truncateSync(fd, len)"
1513
 
Synchronous ftruncate(2).
1514
 
.
1515
 
.SS "fs.chmod(path, mode, callback)"
1516
 
Asynchronous chmod(2). No arguments other than a possible exception are given to the completion callback.
1517
 
.
1518
 
.SS "fs.chmodSync(path, mode)"
1519
 
Synchronous chmod(2).
1520
 
.
1521
 
.SS "fs.stat(path, callback), fs.lstat(path, callback), fs.fstat(fd, callback)"
1522
 
Asynchronous stat(2), lstat(2) or fstat(2). The callback gets two arguments \fB(err, stats)\fR where \fBstats\fR is a \fBfs.Stats\fR object. It looks like this:
 
1574
asynchronous versions of these calls\. The synchronous versions will block
 
1575
the entire process until they complete\-\-halting all connections\.
 
1576
.
 
1577
.SS "fs\.rename(path1, path2, [callback])"
 
1578
Asynchronous rename(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1579
.
 
1580
.SS "fs\.renameSync(path1, path2)"
 
1581
Synchronous rename(2)\.
 
1582
.
 
1583
.SS "fs\.truncate(fd, len, [callback])"
 
1584
Asynchronous ftruncate(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1585
.
 
1586
.SS "fs\.truncateSync(fd, len)"
 
1587
Synchronous ftruncate(2)\.
 
1588
.
 
1589
.SS "fs\.chmod(path, mode, [callback])"
 
1590
Asynchronous chmod(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1591
.
 
1592
.SS "fs\.chmodSync(path, mode)"
 
1593
Synchronous chmod(2)\.
 
1594
.
 
1595
.SS "fs\.stat(path, [callback])"
 
1596
Asynchronous stat(2)\. The callback gets two arguments \fB(err, stats)\fR where \fBstats\fR is a \fBfs\.Stats\fR object\. It looks like this:
1523
1597
.
1524
1598
.IP "" 4
1525
1599
.
1534
1608
, size: 4096
1535
1609
, blksize: 4096
1536
1610
, blocks: 8
1537
 
, atime: '2009\-06\-29T11:11:55Z'
1538
 
, mtime: '2009\-06\-29T11:11:40Z'
1539
 
, ctime: '2009\-06\-29T11:11:40Z'
 
1611
, atime: \'2009\-06\-29T11:11:55Z\'
 
1612
, mtime: \'2009\-06\-29T11:11:40Z\'
 
1613
, ctime: \'2009\-06\-29T11:11:40Z\' 
1540
1614
}
1541
1615
.
1542
1616
.fi
1544
1618
.IP "" 0
1545
1619
.
1546
1620
.P
1547
 
See the \fBfs.Stats\fR section below for more information.
1548
 
.
1549
 
.SS "fs.statSync(path), fs.lstatSync(path), fs.fstatSync(fd)"
1550
 
Synchronous stat(2), lstat(2) or fstat(2). Returns an instance of \fBfs.Stats\fR.
1551
 
.
1552
 
.SS "fs.link(srcpath, dstpath, callback)"
1553
 
Asynchronous link(2). No arguments other than a possible exception are given to the completion callback.
1554
 
.
1555
 
.SS "fs.linkSync(dstpath, srcpath)"
1556
 
Synchronous link(2).
1557
 
.
1558
 
.SS "fs.symlink(linkdata, path, callback)"
1559
 
Asynchronous symlink(2). No arguments other than a possible exception are given to the completion callback.
1560
 
.
1561
 
.SS "fs.symlinkSync(linkdata, path)"
1562
 
Synchronous symlink(2).
1563
 
.
1564
 
.SS "fs.readlink(path, callback)"
1565
 
Asynchronous readlink(2). The callback gets two arguments \fB(err, resolvedPath)\fR.
1566
 
.
1567
 
.SS "fs.readlinkSync(path)"
1568
 
Synchronous readlink(2). Returns the resolved path.
1569
 
.
1570
 
.SS "fs.realpath(path, callback)"
1571
 
Asynchronous realpath(2).  The callback gets two arguments \fB(err, resolvedPath)\fR.
1572
 
.
1573
 
.SS "fs.realpathSync(path)"
1574
 
Synchronous realpath(2). Returns the resolved path.
1575
 
.
1576
 
.SS "fs.unlink(path, callback)"
1577
 
Asynchronous unlink(2). No arguments other than a possible exception are given to the completion callback.
1578
 
.
1579
 
.SS "fs.unlinkSync(path)"
1580
 
Synchronous unlink(2).
1581
 
.
1582
 
.SS "fs.rmdir(path, callback)"
1583
 
Asynchronous rmdir(2). No arguments other than a possible exception are given to the completion callback.
1584
 
.
1585
 
.SS "fs.rmdirSync(path)"
1586
 
Synchronous rmdir(2).
1587
 
.
1588
 
.SS "fs.mkdir(path, mode, callback)"
1589
 
Asynchronous mkdir(2). No arguments other than a possible exception are given to the completion callback.
1590
 
.
1591
 
.SS "fs.mkdirSync(path, mode)"
1592
 
Synchronous mkdir(2).
1593
 
.
1594
 
.SS "fs.readdir(path, callback)"
1595
 
Asynchronous readdir(3).  Reads the contents of a directory.
 
1621
See the \fBfs\.Stats\fR section below for more information\.
 
1622
.
 
1623
.SS "fs\.lstat(path, [callback])"
 
1624
Asynchronous lstat(2)\. The callback gets two arguments \fB(err, stats)\fR where \fBstats\fR is a \fBfs\.Stats\fR object\.
 
1625
.
 
1626
.SS "fs\.fstat(fd, [callback])"
 
1627
Asynchronous fstat(2)\. The callback gets two arguments \fB(err, stats)\fR where \fBstats\fR is a \fBfs\.Stats\fR object\.
 
1628
.
 
1629
.SS "fs\.statSync(path)"
 
1630
Synchronous stat(2)\. Returns an instance of \fBfs\.Stats\fR\|\.
 
1631
.
 
1632
.SS "fs\.lstatSync(path)"
 
1633
Synchronous lstat(2)\. Returns an instance of \fBfs\.Stats\fR\|\.
 
1634
.
 
1635
.SS "fs\.fstatSync(fd)"
 
1636
Synchronous fstat(2)\. Returns an instance of \fBfs\.Stats\fR\|\.
 
1637
.
 
1638
.SS "fs\.link(srcpath, dstpath, [callback])"
 
1639
Asynchronous link(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1640
.
 
1641
.SS "fs\.linkSync(dstpath, srcpath)"
 
1642
Synchronous link(2)\.
 
1643
.
 
1644
.SS "fs\.symlink(linkdata, path, [callback])"
 
1645
Asynchronous symlink(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1646
.
 
1647
.SS "fs\.symlinkSync(linkdata, path)"
 
1648
Synchronous symlink(2)\.
 
1649
.
 
1650
.SS "fs\.readlink(path, [callback])"
 
1651
Asynchronous readlink(2)\. The callback gets two arguments \fB(err, resolvedPath)\fR\|\. 
 
1652
.
 
1653
.SS "fs\.readlinkSync(path)"
 
1654
Synchronous readlink(2)\. Returns the resolved path\.
 
1655
.
 
1656
.SS "fs\.realpath(path, [callback])"
 
1657
Asynchronous realpath(2)\.  The callback gets two arguments \fB(err, resolvedPath)\fR\|\.
 
1658
.
 
1659
.SS "fs\.realpathSync(path)"
 
1660
Synchronous realpath(2)\. Returns the resolved path\.
 
1661
.
 
1662
.SS "fs\.unlink(path, [callback])"
 
1663
Asynchronous unlink(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1664
.
 
1665
.SS "fs\.unlinkSync(path)"
 
1666
Synchronous unlink(2)\.
 
1667
.
 
1668
.SS "fs\.rmdir(path, [callback])"
 
1669
Asynchronous rmdir(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1670
.
 
1671
.SS "fs\.rmdirSync(path)"
 
1672
Synchronous rmdir(2)\.
 
1673
.
 
1674
.SS "fs\.mkdir(path, mode, [callback])"
 
1675
Asynchronous mkdir(2)\. No arguments other than a possible exception are given to the completion callback\.
 
1676
.
 
1677
.SS "fs\.mkdirSync(path, mode)"
 
1678
Synchronous mkdir(2)\.
 
1679
.
 
1680
.SS "fs\.readdir(path, [callback])"
 
1681
Asynchronous readdir(3)\.  Reads the contents of a directory\.
1596
1682
The callback gets two arguments \fB(err, files)\fR where \fBfiles\fR is an array of
1597
 
the names of the files in the directory excluding \fB'.'\fR and \fB'..'\fR.
1598
 
.
1599
 
.SS "fs.readdirSync(path)"
1600
 
Synchronous readdir(3). Returns an array of filenames excluding \fB'.'\fR and \fB'..'\fR.
1601
 
.
1602
 
.SS "fs.close(fd, callback)"
1603
 
Asynchronous close(2).  No arguments other than a possible exception are given to the completion callback.
1604
 
.
1605
 
.SS "fs.closeSync(fd)"
1606
 
Synchronous close(2).
1607
 
.
1608
 
.SS "fs.open(path, flags, mode, callback)"
1609
 
Asynchronous file open. See open(2). Flags can be 'r', 'r+', 'w', 'w+', 'a',
1610
 
or 'a+'. The callback gets two arguments \fB(err, fd)\fR.
1611
 
.
1612
 
.SS "fs.openSync(path, flags, mode)"
1613
 
Synchronous open(2).
1614
 
.
1615
 
.SS "fs.write(fd, buffer, offset, length, position, callback)"
1616
 
Write \fBbuffer\fR to the file specified by \fBfd\fR.
1617
 
.
1618
 
.P
1619
 
\fBoffset\fR and \fBlength\fR determine the part of the buffer to be written.
1620
 
.
1621
 
.P
1622
 
\fBposition\fR refers to the offset from the beginning of the file where this data
1623
 
should be written. If \fBposition\fR is \fBnull\fR, the data will be written at the
1624
 
current position.
1625
 
See pwrite(2).
1626
 
.
1627
 
.P
1628
 
The callback will be given two arguments \fB(err, written)\fR where \fBwritten\fR
1629
 
specifies how many \fIbytes\fR were written.
1630
 
.
1631
 
.SS "fs.writeSync(fd, data, position, encoding)"
1632
 
Synchronous version of \fBfs.write()\fR. Returns the number of bytes written.
1633
 
.
1634
 
.SS "fs.read(fd, buffer, offset, length, position, callback)"
1635
 
Read data from the file specified by \fBfd\fR.
1636
 
.
1637
 
.P
1638
 
\fBbuffer\fR is the buffer that the data will be written to.
1639
 
.
1640
 
.P
1641
 
\fBoffset\fR is offset within the buffer where writing will start.
1642
 
.
1643
 
.P
1644
 
\fBlength\fR is an integer specifying the number of bytes to read.
1645
 
.
1646
 
.P
1647
 
\fBposition\fR is an integer specifying where to begin reading from in the file.
1648
 
If \fBposition\fR is \fBnull\fR, data will be read from the current file position.
1649
 
.
1650
 
.P
1651
 
The callback is given the two arguments, \fB(err, bytesRead)\fR.
1652
 
.
1653
 
.SS "fs.readSync(fd, buffer, offset, length, position)"
1654
 
Synchronous version of \fBfs.read\fR. Returns the number of \fBbytesRead\fR.
1655
 
.
1656
 
.SS "fs.readFile(filename, [encoding,] callback)"
1657
 
Asynchronously reads the entire contents of a file. Example:
 
1683
the names of the files in the directory excluding \fB\'\.\'\fR and \fB\'\.\.\'\fR\|\.
 
1684
.
 
1685
.SS "fs\.readdirSync(path)"
 
1686
Synchronous readdir(3)\. Returns an array of filenames excluding \fB\'\.\'\fR and \fB\'\.\.\'\fR\|\.
 
1687
.
 
1688
.SS "fs\.close(fd, [callback])"
 
1689
Asynchronous close(2)\.  No arguments other than a possible exception are given to the completion callback\.
 
1690
.
 
1691
.SS "fs\.closeSync(fd)"
 
1692
Synchronous close(2)\.
 
1693
.
 
1694
.SS "fs\.open(path, flags, mode=0666, [callback])"
 
1695
Asynchronous file open\. See open(2)\. Flags can be \'r\', \'r+\', \'w\', \'w+\', \'a\',
 
1696
or \'a+\'\. The callback gets two arguments \fB(err, fd)\fR\|\. 
 
1697
.
 
1698
.SS "fs\.openSync(path, flags, mode=0666)"
 
1699
Synchronous open(2)\. 
 
1700
.
 
1701
.SS "fs\.write(fd, buffer, offset, length, position, [callback])"
 
1702
Write \fBbuffer\fR to the file specified by \fBfd\fR\|\.
 
1703
.
 
1704
.P
 
1705
\fBoffset\fR and \fBlength\fR determine the part of the buffer to be written\.
 
1706
.
 
1707
.P
 
1708
\fBposition\fR refers to the offset from the beginning of the file where this data
 
1709
should be written\. If \fBposition\fR is \fBnull\fR, the data will be written at the
 
1710
current position\.
 
1711
See pwrite(2)\.
 
1712
.
 
1713
.P
 
1714
The callback will be given two arguments \fB(err, written)\fR where \fBwritten\fR
 
1715
specifies how many \fIbytes\fR were written\.
 
1716
.
 
1717
.SS "fs\.write(fd, str, position, encoding=\'utf8\', [callback])"
 
1718
Write the entire string \fBstr\fR using the given \fBencoding\fR to the file specified
 
1719
by \fBfd\fR\|\.
 
1720
.
 
1721
.P
 
1722
\fBposition\fR refers to the offset from the beginning of the file where this data
 
1723
should be written\. If \fBposition\fR is \fBnull\fR, the data will be written at the
 
1724
current position\.
 
1725
See pwrite(2)\.
 
1726
.
 
1727
.P
 
1728
The callback will be given two arguments \fB(err, written)\fR where \fBwritten\fR
 
1729
specifies how many \fIbytes\fR were written\.
 
1730
.
 
1731
.SS "fs\.writeSync(fd, buffer, offset, length, position)"
 
1732
Synchronous version of buffer\-based \fBfs\.write()\fR\|\. Returns the number of bytes written\.
 
1733
.
 
1734
.SS "fs\.writeSync(fd, str, position, encoding=\'utf8\')"
 
1735
Synchronous version of string\-based \fBfs\.write()\fR\|\. Returns the number of bytes written\.
 
1736
.
 
1737
.SS "fs\.read(fd, buffer, offset, length, position, [callback])"
 
1738
Read data from the file specified by \fBfd\fR\|\.
 
1739
.
 
1740
.P
 
1741
\fBbuffer\fR is the buffer that the data will be written to\.
 
1742
.
 
1743
.P
 
1744
\fBoffset\fR is offset within the buffer where writing will start\.
 
1745
.
 
1746
.P
 
1747
\fBlength\fR is an integer specifying the number of bytes to read\.
 
1748
.
 
1749
.P
 
1750
\fBposition\fR is an integer specifying where to begin reading from in the file\.
 
1751
If \fBposition\fR is \fBnull\fR, data will be read from the current file position\.
 
1752
.
 
1753
.P
 
1754
The callback is given the two arguments, \fB(err, bytesRead)\fR\|\.
 
1755
.
 
1756
.SS "fs\.read(fd, length, position, encoding, [callback])"
 
1757
Read data from the file specified by \fBfd\fR\|\.
 
1758
.
 
1759
.P
 
1760
\fBlength\fR is an integer specifying the number of bytes to read\.
 
1761
.
 
1762
.P
 
1763
\fBposition\fR is an integer specifying where to begin reading from in the file\.
 
1764
If \fBposition\fR is \fBnull\fR, data will be read from the current file position\.
 
1765
.
 
1766
.P
 
1767
\fBencoding\fR is the desired encoding of the string of data read in from \fBfd\fR\|\.
 
1768
.
 
1769
.P
 
1770
The callback is given the three arguments, \fB(err, str, bytesRead)\fR\|\.
 
1771
.
 
1772
.SS "fs\.readSync(fd, buffer, offset, length, position)"
 
1773
Synchronous version of buffer\-based \fBfs\.read\fR\|\. Returns the number of \fBbytesRead\fR\|\.
 
1774
.
 
1775
.SS "fs\.readSync(fd, length, position, encoding)"
 
1776
Synchronous version of string\-based \fBfs\.read\fR\|\. Returns the number of \fBbytesRead\fR\|\.
 
1777
.
 
1778
.SS "fs\.readFile(filename, [encoding], [callback])"
 
1779
Asynchronously reads the entire contents of a file\. Example:
1658
1780
.
1659
1781
.IP "" 4
1660
1782
.
1661
1783
.nf
1662
 
fs.readFile('/etc/passwd', function (err, data) {
 
1784
fs\.readFile(\'/etc/passwd\', function (err, data) {
1663
1785
  if (err) throw err;
1664
 
  sys.puts(data);
 
1786
  console\.log(data);
1665
1787
});
1666
1788
.
1667
1789
.fi
1670
1792
.
1671
1793
.P
1672
1794
The callback is passed two arguments \fB(err, data)\fR, where \fBdata\fR is the
1673
 
contents of the file.
1674
 
.
1675
 
.P
1676
 
If no encoding is specified, then the raw buffer is returned.
1677
 
.
1678
 
.SS "fs.readFileSync(filename [, encoding])"
1679
 
Synchronous version of \fBfs.readFile\fR. Returns the contents of the \fBfilename\fR.
1680
 
.
1681
 
.P
1682
 
If \fBencoding\fR is specified then this function returns a string. Otherwise it
1683
 
returns a buffer.
1684
 
.
1685
 
.SS "fs.writeFile(filename, data, encoding='utf8', callback)"
1686
 
Asynchronously writes data to a file. Example:
 
1795
contents of the file\.
 
1796
.
 
1797
.P
 
1798
If no encoding is specified, then the raw buffer is returned\.
 
1799
.
 
1800
.SS "fs\.readFileSync(filename, [encoding])"
 
1801
Synchronous version of \fBfs\.readFile\fR\|\. Returns the contents of the \fBfilename\fR\|\.
 
1802
.
 
1803
.P
 
1804
If \fBencoding\fR is specified then this function returns a string\. Otherwise it
 
1805
returns a buffer\.
 
1806
.
 
1807
.SS "fs\.writeFile(filename, data, encoding=\'utf8\', [callback])"
 
1808
Asynchronously writes data to a file\. \fBdata\fR can be a string or a buffer\.
 
1809
.
 
1810
.P
 
1811
Example:
1687
1812
.
1688
1813
.IP "" 4
1689
1814
.
1690
1815
.nf
1691
 
fs.writeFile('message.txt', 'Hello Node', function (err) {
 
1816
fs\.writeFile(\'message\.txt\', \'Hello Node\', function (err) {
1692
1817
  if (err) throw err;
1693
 
  sys.puts('It\\'s saved!');
 
1818
  console\.log(\'It\\\'s saved!\');
1694
1819
});
1695
1820
.
1696
1821
.fi
1697
1822
.
1698
1823
.IP "" 0
1699
1824
.
1700
 
.SS "fs.writeFileSync(filename, data, encoding='utf8')"
1701
 
The synchronous version of \fBfs.writeFile\fR.
 
1825
.SS "fs\.writeFileSync(filename, data, encoding=\'utf8\')"
 
1826
The synchronous version of \fBfs\.writeFile\fR\|\.
1702
1827
.
1703
 
.SS "fs.watchFile(filename, [options,] listener)"
1704
 
Watch for changes on \fBfilename\fR. The callback \fBlistener\fR will be called each
1705
 
time the file changes.
 
1828
.SS "fs\.watchFile(filename, [options], listener)"
 
1829
Watch for changes on \fBfilename\fR\|\. The callback \fBlistener\fR will be called each
 
1830
time the file changes\.
1706
1831
.
1707
1832
.P
1708
 
The second argument is optional. The \fBoptions\fR if provided should be an object
 
1833
The second argument is optional\. The \fBoptions\fR if provided should be an object
1709
1834
containing two members a boolean, \fBpersistent\fR, and \fBinterval\fR, a polling
1710
 
value in milliseconds. The default is \fB{persistent: true, interval: 0}\fR.
 
1835
value in milliseconds\. The default is \fB{persistent: true, interval: 0}\fR\|\.
1711
1836
.
1712
1837
.P
1713
1838
The \fBlistener\fR gets two arguments the current stat object and the previous
1716
1841
.IP "" 4
1717
1842
.
1718
1843
.nf
1719
 
fs.watchFile(f, function (curr, prev) {
1720
 
  sys.puts('the current mtime is: ' + curr.mtime);
1721
 
  sys.puts('the previous mtime was: ' + prev.mtime);
 
1844
fs\.watchFile(f, function (curr, prev) {
 
1845
  console\.log(\'the current mtime is: \' + curr\.mtime);
 
1846
  console\.log(\'the previous mtime was: \' + prev\.mtime);
1722
1847
});
1723
1848
.
1724
1849
.fi
1726
1851
.IP "" 0
1727
1852
.
1728
1853
.P
1729
 
These stat objects are instances of \fBfs.Stat\fR.
1730
 
.
1731
 
.SS "fs.unwatchFile(filename)"
1732
 
Stop watching for changes on \fBfilename\fR.
1733
 
.
1734
 
.SH "fs.Stats"
1735
 
Objects returned from \fBfs.stat()\fR and \fBfs.lstat()\fR are of this type.
1736
 
.
1737
 
.IP "\(bu" 4
1738
 
\fBstats.isFile()\fR
1739
 
.
1740
 
.IP "\(bu" 4
1741
 
\fBstats.isDirectory()\fR
1742
 
.
1743
 
.IP "\(bu" 4
1744
 
\fBstats.isBlockDevice()\fR
1745
 
.
1746
 
.IP "\(bu" 4
1747
 
\fBstats.isCharacterDevice()\fR
1748
 
.
1749
 
.IP "\(bu" 4
1750
 
\fBstats.isSymbolicLink()\fR
1751
 
.
1752
 
.IP "\(bu" 4
1753
 
\fBstats.isFIFO()\fR
1754
 
.
1755
 
.IP "\(bu" 4
1756
 
\fBstats.isSocket()\fR
1757
 
.
1758
 
.IP "" 0
1759
 
.
1760
 
.SH "fs.ReadStream"
1761
 
\fBReadStream\fR is a readable stream.
1762
 
.
1763
 
.SS "fs.createReadStream(path, [options])"
1764
 
Returns a new ReadStream object.
1765
 
.
1766
 
.P
1767
 
\fBoptions\fR is an object with the following defaults:
1768
 
.
1769
 
.IP "" 4
1770
 
.
1771
 
.nf
1772
 
{ 'flags': 'r'
1773
 
, 'encoding': 'binary'
1774
 
, 'mode': 0666
1775
 
, 'bufferSize': 4 * 1024
1776
 
}
1777
 
.
1778
 
.fi
1779
 
.
1780
 
.IP "" 0
1781
 
.
1782
 
.SS "readStream.readable"
1783
 
A boolean that is \fBtrue\fR by default, but turns \fBfalse\fR after an \fB'error'\fR
1784
 
occured, the stream came to an \fB'end'\fR, or \fBdestroy()\fR was called.
1785
 
.
1786
 
.SS "readStream.pause()"
1787
 
Stops the stream from reading further data. No \fB'data'\fR event will be fired
1788
 
until the stream is resumed.
1789
 
.
1790
 
.SS "readStream.resume()"
1791
 
Resumes the stream. Together with \fBpause()\fR this useful to throttle reading.
1792
 
.
1793
 
.SS "readStream.destroy()"
1794
 
Allows to close the stream before the \fB'end'\fR is reached. No more events other
1795
 
than \fB'close'\fR will be fired after this method has been called.
1796
 
.
1797
 
.SH "fs.WriteStream"
1798
 
\fBWriteStream\fR is a writable stream.
1799
 
.
1800
 
.SS "fs.createWriteStream(path, [options])"
1801
 
Returns a new WriteStream object.\fBoptions\fR is an object with the following defaults:
1802
 
.
1803
 
.IP "" 4
1804
 
.
1805
 
.nf
1806
 
{ 'flags': 'w'
1807
 
, 'encoding': 'binary'
1808
 
, 'mode': 0666
1809
 
}
1810
 
.
1811
 
.fi
1812
 
.
1813
 
.IP "" 0
1814
 
.
1815
 
.SS "writeStream.writeable"
1816
 
A boolean that is \fBtrue\fR by default, but turns \fBfalse\fR after an \fB'error'\fR
1817
 
occurred or \fBend()\fR / \fBdestroy()\fR was called.
1818
 
.
1819
 
.SS "writeStream.write(data, encoding='utf8')"
1820
 
Returns \fBtrue\fR if the data was flushed to the kernel, and \fBfalse\fR if it was
1821
 
queued up for being written later. A \fB'drain'\fR will fire after all queued data
1822
 
has been written.
1823
 
.
1824
 
.P
1825
 
The second optional parameter specifies the encoding of for the string.
1826
 
.
1827
 
.SS "writeStream.end()"
1828
 
Closes the stream right after all queued \fBwrite()\fR calls have finished.
1829
 
.
1830
 
.SS "writeStream.destroy()"
1831
 
Allows to close the stream regardless of its current state.
 
1854
These stat objects are instances of \fBfs\.Stat\fR\|\. 
 
1855
.
 
1856
.SS "fs\.unwatchFile(filename)"
 
1857
Stop watching for changes on \fBfilename\fR\|\.
 
1858
.
 
1859
.SH "fs\.Stats"
 
1860
Objects returned from \fBfs\.stat()\fR and \fBfs\.lstat()\fR are of this type\.
 
1861
.
 
1862
.IP "\(bu" 4
 
1863
\fBstats\.isFile()\fR
 
1864
.
 
1865
.IP "\(bu" 4
 
1866
\fBstats\.isDirectory()\fR
 
1867
.
 
1868
.IP "\(bu" 4
 
1869
\fBstats\.isBlockDevice()\fR
 
1870
.
 
1871
.IP "\(bu" 4
 
1872
\fBstats\.isCharacterDevice()\fR
 
1873
.
 
1874
.IP "\(bu" 4
 
1875
\fBstats\.isSymbolicLink()\fR (only valid with  \fBfs\.lstat()\fR)
 
1876
.
 
1877
.IP "\(bu" 4
 
1878
\fBstats\.isFIFO()\fR
 
1879
.
 
1880
.IP "\(bu" 4
 
1881
\fBstats\.isSocket()\fR
 
1882
.
 
1883
.IP "" 0
 
1884
.
 
1885
.SH "fs\.ReadStream"
 
1886
\fBReadStream\fR is a \fBReadable Stream\fR\|\.
 
1887
.
 
1888
.SS "fs\.createReadStream(path, [options])"
 
1889
Returns a new ReadStream object (See \fBReadable Stream\fR)\.
 
1890
.
 
1891
.P
 
1892
\fBoptions\fR is an object with the following defaults:
 
1893
.
 
1894
.IP "" 4
 
1895
.
 
1896
.nf
 
1897
{ \'flags\': \'r\'
 
1898
, \'encoding\': null
 
1899
, \'mode\': 0666
 
1900
, \'bufferSize\': 4 * 1024
 
1901
}
 
1902
.
 
1903
.fi
 
1904
.
 
1905
.IP "" 0
 
1906
.
 
1907
.P
 
1908
\fBoptions\fR can include \fBstart\fR and \fBend\fR values to read a range of bytes from
 
1909
the file instead of the entire file\.  Both \fBstart\fR and \fBend\fR are inclusive and
 
1910
start at 0\.  When used, both the limits must be specified always\.
 
1911
.
 
1912
.P
 
1913
An example to read the last 10 bytes of a file which is 100 bytes long:
 
1914
.
 
1915
.IP "" 4
 
1916
.
 
1917
.nf
 
1918
fs\.createReadStream(\'sample\.txt\', {start: 90, end: 99});
 
1919
.
 
1920
.fi
 
1921
.
 
1922
.IP "" 0
 
1923
.
 
1924
.SH "fs\.WriteStream"
 
1925
\fBWriteStream\fR is a \fBWritable Stream\fR\|\.
 
1926
.
 
1927
.SS "fs\.createWriteStream(path, [options])"
 
1928
Returns a new WriteStream object (See \fBWritable Stream\fR)\.
 
1929
.
 
1930
.P
 
1931
\fBoptions\fR is an object with the following defaults:
 
1932
.
 
1933
.IP "" 4
 
1934
.
 
1935
.nf
 
1936
{ \'flags\': \'w\'
 
1937
, \'encoding\': null
 
1938
, \'mode\': 0666
 
1939
}
 
1940
.
 
1941
.fi
 
1942
.
 
1943
.IP "" 0
1832
1944
.
1833
1945
.SH "HTTP"
1834
 
To use the HTTP server and client one must \fBrequire('http')\fR.
 
1946
To use the HTTP server and client one must \fBrequire(\'http\')\fR\|\.
1835
1947
.
1836
1948
.P
1837
1949
The HTTP interfaces in Node are designed to support many features
1838
 
of the protocol which have been traditionally difficult to use.
1839
 
In particular, large, possibly chunk\-encoded, messages. The interface is
 
1950
of the protocol which have been traditionally difficult to use\.
 
1951
In particular, large, possibly chunk\-encoded, messages\. The interface is
1840
1952
careful to never buffer entire requests or responses\-\-the
1841
 
user is able to stream data.
 
1953
user is able to stream data\.
1842
1954
.
1843
1955
.P
1844
1956
HTTP message headers are represented by an object like this:
1846
1958
.IP "" 4
1847
1959
.
1848
1960
.nf
1849
 
{ 'content\-length': '123'
1850
 
, 'content\-type': 'text/plain'
1851
 
, 'stream': 'keep\-alive'
1852
 
, 'accept': '*/*'
 
1961
{ \'content\-length\': \'123\'
 
1962
, \'content\-type\': \'text/plain\'
 
1963
, \'stream\': \'keep\-alive\'
 
1964
, \'accept\': \'*/*\'
1853
1965
}
1854
1966
.
1855
1967
.fi
1857
1969
.IP "" 0
1858
1970
.
1859
1971
.P
1860
 
Keys are lowercased. Values are not modified.
1861
 
.
1862
 
.P
1863
 
In order to support the full spectrum of possible HTTP applications, Node's
1864
 
HTTP API is very low\-level. It deals with stream handling and message
1865
 
parsing only. It parses a message into headers and body but it does not
1866
 
parse the actual headers or the body.
1867
 
.
1868
 
.P
1869
 
HTTPS is supported if OpenSSL is available on the underlying platform.
1870
 
.
1871
 
.SH "http.Server"
1872
 
This is an EventEmitter with the following events:
1873
 
.
1874
 
.SS "Event: 'request'"
 
1972
Keys are lowercased\. Values are not modified\.
 
1973
.
 
1974
.P
 
1975
In order to support the full spectrum of possible HTTP applications, Node\'s
 
1976
HTTP API is very low\-level\. It deals with stream handling and message
 
1977
parsing only\. It parses a message into headers and body but it does not
 
1978
parse the actual headers or the body\.
 
1979
.
 
1980
.P
 
1981
HTTPS is supported if OpenSSL is available on the underlying platform\.
 
1982
.
 
1983
.SH "http\.Server"
 
1984
This is an \fBEventEmitter\fR with the following events:
 
1985
.
 
1986
.SS "Event: \'request\'"
1875
1987
\fBfunction (request, response) { }\fR
1876
1988
.
1877
1989
.P
1878
 
 \fBrequest\fR is an instance of \fBhttp.ServerRequest\fR and \fBresponse\fR is
1879
 
 an instance of \fBhttp.ServerResponse\fR
 
1990
 \fBrequest\fR is an instance of \fBhttp\.ServerRequest\fR and \fBresponse\fR is
 
1991
 an instance of \fBhttp\.ServerResponse\fR
1880
1992
.
1881
 
.SS "Event: 'connection'"
 
1993
.SS "Event: \'connection\'"
1882
1994
\fBfunction (stream) { }\fR
1883
1995
.
1884
1996
.P
1885
 
 When a new TCP stream is established. \fBstream\fR is an object of type
1886
 
 \fBnet.Stream\fR. Usually users will not want to access this event. The
1887
 
 \fBstream\fR can also be accessed at \fBrequest.connection\fR.
 
1997
 When a new TCP stream is established\. \fBstream\fR is an object of type
 
1998
 \fBnet\.Stream\fR\|\. Usually users will not want to access this event\. The
 
1999
 \fBstream\fR can also be accessed at \fBrequest\.connection\fR\|\.
1888
2000
.
1889
 
.SS "Event: 'close'"
 
2001
.SS "Event: \'close\'"
1890
2002
\fBfunction (errno) { }\fR
1891
2003
.
1892
2004
.P
1893
 
 Emitted when the server closes.
1894
 
.
1895
 
.SS "http.createServer(requestListener, [options])"
1896
 
Returns a new web server object.
1897
 
.
1898
 
.P
1899
 
The \fBoptions\fR argument is optional. The \fBoptions\fR argument accepts the same values as the
1900
 
options argument for \fBnet.Server\fR.
1901
 
.
1902
 
.P
1903
 
The \fBrequestListener\fR is a function which is automatically
1904
 
added to the \fB'request'\fR event.
1905
 
.
1906
 
.SS "Event: 'request'"
 
2005
 Emitted when the server closes\. 
 
2006
.
 
2007
.SS "Event: \'request\'"
1907
2008
\fBfunction (request, response) {}\fR
1908
2009
.
1909
2010
.P
1910
 
Emitted each time there is request. Note that there may be multiple requests
1911
 
per connection (in the case of keep\-alive connections).
 
2011
Emitted each time there is request\. Note that there may be multiple requests
 
2012
per connection (in the case of keep\-alive connections)\.
1912
2013
.
1913
 
.SS "Event: 'upgrade'"
 
2014
.SS "Event: \'upgrade\'"
1914
2015
\fBfunction (request, socket, head)\fR
1915
2016
.
1916
2017
.P
1917
 
Emitted each time a client requests a http upgrade. If this event isn't
 
2018
Emitted each time a client requests a http upgrade\. If this event isn\'t
1918
2019
listened for, then clients requesting an upgrade will have their connections
1919
 
closed.
1920
 
.
1921
 
.IP "\(bu" 4
1922
 
\fBrequest\fR is the arguments for the http request, as it is in the request event.
1923
 
.
1924
 
.IP "\(bu" 4
1925
 
\fBsocket\fR is the network socket between the server and client.
1926
 
.
1927
 
.IP "\(bu" 4
1928
 
\fBhead\fR is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
 
2020
closed\.
 
2021
.
 
2022
.IP "\(bu" 4
 
2023
\fBrequest\fR is the arguments for the http request, as it is in the request event\.
 
2024
.
 
2025
.IP "\(bu" 4
 
2026
\fBsocket\fR is the network socket between the server and client\.
 
2027
.
 
2028
.IP "\(bu" 4
 
2029
\fBhead\fR is an instance of Buffer, the first packet of the upgraded stream, this may be empty\.
1929
2030
.
1930
2031
.IP "" 0
1931
2032
.
1932
2033
.P
1933
 
After this event is emitted, the request's socket will not have a \fBdata\fR
 
2034
After this event is emitted, the request\'s socket will not have a \fBdata\fR
1934
2035
event listener, meaning you will need to bind to it in order to handle data
1935
 
sent to the server on that socket.
 
2036
sent to the server on that socket\.
1936
2037
.
1937
 
.SS "Event: 'clientError'"
 
2038
.SS "Event: \'clientError\'"
1938
2039
\fBfunction (exception) {}\fR
1939
2040
.
1940
2041
.P
1941
 
If a client connection emits an 'error' event \- it will forwarded here.
1942
 
.
1943
 
.SS "server.listen(port, hostname)"
1944
 
Begin accepting connections on the specified port and hostname.  If the
 
2042
If a client connection emits an \'error\' event \- it will forwarded here\.
 
2043
.
 
2044
.SS "http\.createServer(requestListener)"
 
2045
Returns a new web server object\.
 
2046
.
 
2047
.P
 
2048
The \fBrequestListener\fR is a function which is automatically
 
2049
added to the \fB\'request\'\fR event\.
 
2050
.
 
2051
.SS "server\.listen(port, [hostname], [callback])"
 
2052
Begin accepting connections on the specified port and hostname\.  If the
1945
2053
hostname is omitted, the server will accept connections directed to any
1946
 
address.
1947
 
.
1948
 
.P
1949
 
To listen to a unix socket, supply a filename instead of port and hostname.
1950
 
.
1951
 
.P
1952
 
\fBIf you give a port number as a string, the system will interpret it as a filename in the current directory and create a unix socket.\fR
1953
 
.
1954
 
.P
1955
 
This function is asynchronous. \fBlistening\fR will be emitted when the server
1956
 
is ready to accept connections.
1957
 
.
1958
 
.SS "server.listen(path)"
1959
 
Start a UNIX socket server listening for connections on the given \fBpath\fR.
1960
 
This function is asynchronous. \fBlistening\fR will be emitted when the server
1961
 
is ready to accept connections.
1962
 
.
1963
 
.SS "server.setSecure(credentials)"
1964
 
Enables HTTPS support for the server, with the crypto module credentials specifying the private key and certificate of the server, and optionally the CA certificates for use in client authentication.
1965
 
.
1966
 
.P
1967
 
If the credentials hold one or more CA certificates, then the server will request for the client to submit a client certificate as part of the HTTPS connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate() from the server's request.connection.
1968
 
.
1969
 
.SS "server.close()"
1970
 
Stops the server from accepting new connections.
1971
 
.
1972
 
.SH "http.ServerRequest"
 
2054
IPv4 address (\fBINADDR_ANY\fR)\.
 
2055
.
 
2056
.P
 
2057
To listen to a unix socket, supply a filename instead of port and hostname\.
 
2058
.
 
2059
.P
 
2060
This function is asynchronous\. The last parameter \fBcallback\fR will be called
 
2061
when the server has been bound to the port\.
 
2062
.
 
2063
.SS "server\.listen(path, [callback])"
 
2064
Start a UNIX socket server listening for connections on the given \fBpath\fR\|\.
 
2065
.
 
2066
.P
 
2067
This function is asynchronous\. The last parameter \fBcallback\fR will be called
 
2068
when the server has been bound\.
 
2069
.
 
2070
.SS "server\.setSecure(credentials)"
 
2071
Enables HTTPS support for the server, with the crypto module credentials specifying the private key and certificate of the server, and optionally the CA certificates for use in client authentication\.
 
2072
.
 
2073
.P
 
2074
If the credentials hold one or more CA certificates, then the server will request for the client to submit a client certificate as part of the HTTPS connection handshake\. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate() from the server\'s request\.connection\.
 
2075
.
 
2076
.SS "server\.close()"
 
2077
Stops the server from accepting new connections\.
 
2078
.
 
2079
.SH "http\.ServerRequest"
1973
2080
This object is created internally by a HTTP server\-\-not by
1974
 
the user\-\-and passed as the first argument to a \fB'request'\fR listener.
 
2081
the user\-\-and passed as the first argument to a \fB\'request\'\fR listener\.
1975
2082
.
1976
2083
.P
1977
 
This is an EventEmitter with the following events:
 
2084
This is an \fBEventEmitter\fR with the following events:
1978
2085
.
1979
 
.SS "Event: 'data'"
 
2086
.SS "Event: \'data\'"
1980
2087
\fBfunction (chunk) { }\fR
1981
2088
.
1982
2089
.P
1983
 
Emitted when a piece of the message body is received.
 
2090
Emitted when a piece of the message body is received\.
1984
2091
.
1985
2092
.P
1986
2093
Example: A chunk of the body is given as the single
1987
 
argument. The transfer\-encoding has been decoded.  The
1988
 
body chunk is a string.  The body encoding is set with\fBrequest.setBodyEncoding()\fR.
 
2094
argument\. The transfer\-encoding has been decoded\.  The
 
2095
body chunk is a string\.  The body encoding is set with \fBrequest\.setBodyEncoding()\fR\|\.
1989
2096
.
1990
 
.SS "Event: 'end'"
 
2097
.SS "Event: \'end\'"
1991
2098
\fBfunction () { }\fR
1992
2099
.
1993
2100
.P
1994
 
Emitted exactly once for each message. No arguments.  After
1995
 
emitted no other events will be emitted on the request.
1996
 
.
1997
 
.SS "request.method"
1998
 
The request method as a string. Read only. Example:\fB'GET'\fR, \fB'DELETE'\fR.
1999
 
.
2000
 
.SS "request.url"
2001
 
Request URL string. This contains only the URL that is
2002
 
present in the actual HTTP request. If the request is:
 
2101
Emitted exactly once for each message\. No arguments\.  After
 
2102
emitted no other events will be emitted on the request\.
 
2103
.
 
2104
.SS "request\.method"
 
2105
The request method as a string\. Read only\. Example: \fB\'GET\'\fR, \fB\'DELETE\'\fR\|\.
 
2106
.
 
2107
.SS "request\.url"
 
2108
Request URL string\. This contains only the URL that is
 
2109
present in the actual HTTP request\. If the request is:
2003
2110
.
2004
2111
.IP "" 4
2005
2112
.
2006
2113
.nf
2007
 
GET /status?name=ryan HTTP/1.1\\r\\n
 
2114
GET /status?name=ryan HTTP/1\.1\\r\\n
2008
2115
Accept: text/plain\\r\\n
2009
2116
\\r\\n
2010
2117
.
2013
2120
.IP "" 0
2014
2121
.
2015
2122
.P
2016
 
Then \fBrequest.url\fR will be:
 
2123
Then \fBrequest\.url\fR will be:
2017
2124
.
2018
2125
.IP "" 4
2019
2126
.
2020
2127
.nf
2021
 
'/status?name=ryan'
 
2128
\'/status?name=ryan\'
2022
2129
.
2023
2130
.fi
2024
2131
.
2025
2132
.IP "" 0
2026
2133
.
2027
2134
.P
2028
 
If you would like to parse the URL into its parts, you can use\fBrequire('url').parse(request.url)\fR.  Example:
 
2135
If you would like to parse the URL into its parts, you can use \fBrequire(\'url\')\.parse(request\.url)\fR\|\.  Example:
2029
2136
.
2030
2137
.IP "" 4
2031
2138
.
2032
2139
.nf
2033
 
node> require('url').parse('/status?name=ryan')
2034
 
{ href: '/status?name=ryan'
2035
 
, search: '?name=ryan'
2036
 
, query: 'name=ryan'
2037
 
, pathname: '/status'
 
2140
node> require(\'url\')\.parse(\'/status?name=ryan\')
 
2141
{ href: \'/status?name=ryan\'
 
2142
, search: \'?name=ryan\'
 
2143
, query: \'name=ryan\'
 
2144
, pathname: \'/status\'
2038
2145
}
2039
2146
.
2040
2147
.fi
2043
2150
.
2044
2151
.P
2045
2152
If you would like to extract the params from the query string,
2046
 
you can use the \fBrequire('querystring').parse\fR function, or pass \fBtrue\fR as the second argument to \fBrequire('url').parse\fR.  Example:
 
2153
you can use the \fBrequire(\'querystring\')\.parse\fR function, or pass \fBtrue\fR as the second argument to \fBrequire(\'url\')\.parse\fR\|\.  Example:
2047
2154
.
2048
2155
.IP "" 4
2049
2156
.
2050
2157
.nf
2051
 
node> require('url').parse('/status?name=ryan', true)
2052
 
{ href: '/status?name=ryan'
2053
 
, search: '?name=ryan'
2054
 
, query: { name: 'ryan' }
2055
 
, pathname: '/status'
 
2158
node> require(\'url\')\.parse(\'/status?name=ryan\', true)
 
2159
{ href: \'/status?name=ryan\'
 
2160
, search: \'?name=ryan\'
 
2161
, query: { name: \'ryan\' }
 
2162
, pathname: \'/status\'
2056
2163
}
2057
2164
.
2058
2165
.fi
2059
2166
.
2060
2167
.IP "" 0
2061
2168
.
2062
 
.SS "request.headers"
2063
 
Read only.
2064
 
.
2065
 
.SS "request.httpVersion"
2066
 
The HTTP protocol version as a string. Read only. Examples:\fB'1.1'\fR, \fB'1.0'\fR.
2067
 
Also \fBrequest.httpVersionMajor\fR is the first integer and \fBrequest.httpVersionMinor\fR is the second.
2068
 
.
2069
 
.SS "request.setEncoding(encoding='binary')"
2070
 
Set the encoding for the request body. Either \fB'utf8'\fR or \fB'binary'\fR. Defaults
2071
 
to \fB'binary'\fR.
2072
 
.
2073
 
.SS "request.pause()"
2074
 
Pauses request from emitting events.  Useful to throttle back an upload.
2075
 
.
2076
 
.SS "request.resume()"
2077
 
Resumes a paused request.
2078
 
.
2079
 
.SS "request.connection"
2080
 
The \fBnet.Stream\fR object assocated with the connection.
 
2169
.SS "request\.headers"
 
2170
Read only\.
 
2171
.
 
2172
.SS "request\.httpVersion"
 
2173
The HTTP protocol version as a string\. Read only\. Examples: \fB\'1\.1\'\fR, \fB\'1\.0\'\fR\|\.
 
2174
Also \fBrequest\.httpVersionMajor\fR is the first integer and \fBrequest\.httpVersionMinor\fR is the second\.
 
2175
.
 
2176
.SS "request\.setEncoding(encoding=null)"
 
2177
Set the encoding for the request body\. Either \fB\'utf8\'\fR or \fB\'binary\'\fR\|\. Defaults
 
2178
to \fBnull\fR, which means that the \fB\'data\'\fR event will emit a \fBBuffer\fR object\.\.
 
2179
.
 
2180
.SS "request\.pause()"
 
2181
Pauses request from emitting events\.  Useful to throttle back an upload\.
 
2182
.
 
2183
.SS "request\.resume()"
 
2184
Resumes a paused request\.
 
2185
.
 
2186
.SS "request\.connection"
 
2187
The \fBnet\.Stream\fR object associated with the connection\.
2081
2188
.
2082
2189
.P
2083
 
With HTTPS support, use request.connection.verifyPeer() and
2084
 
request.connection.getPeerCertificate() to obtain the client's
2085
 
authentication details.
2086
 
.
2087
 
.SH "http.ServerResponse"
2088
 
This object is created internally by a HTTP server\-\-not by the user. It is
2089
 
passed as the second parameter to the \fB'request'\fR event. It is a writable stream.
2090
 
.
2091
 
.SS "response.writeHead(statusCode[, reasonPhrase] , headers)"
2092
 
Sends a response header to the request. The status code is a 3\-digit HTTP
2093
 
status code, like \fB404\fR. The last argument, \fBheaders\fR, are the response headers.
 
2190
With HTTPS support, use request\.connection\.verifyPeer() and
 
2191
request\.connection\.getPeerCertificate() to obtain the client\'s
 
2192
authentication details\.
 
2193
.
 
2194
.SH "http\.ServerResponse"
 
2195
This object is created internally by a HTTP server\-\-not by the user\. It is
 
2196
passed as the second parameter to the \fB\'request\'\fR event\. It is a \fBWritable Stream\fR\|\.
 
2197
.
 
2198
.SS "response\.writeHead(statusCode, [reasonPhrase], [headers])"
 
2199
Sends a response header to the request\. The status code is a 3\-digit HTTP
 
2200
status code, like \fB404\fR\|\. The last argument, \fBheaders\fR, are the response headers\.
2094
2201
Optionally one can give a human\-readable \fBreasonPhrase\fR as the second
2095
 
argument.
 
2202
argument\.
2096
2203
.
2097
2204
.P
2098
2205
Example:
2100
2207
.IP "" 4
2101
2208
.
2102
2209
.nf
2103
 
var body = 'hello world';
2104
 
response.writeHead(200, {
2105
 
  'Content\-Length': body.length,
2106
 
  'Content\-Type': 'text/plain'
 
2210
var body = \'hello world\';
 
2211
response\.writeHead(200, {
 
2212
  \'Content\-Length\': body\.length,
 
2213
  \'Content\-Type\': \'text/plain\'
2107
2214
});
2108
2215
.
2109
2216
.fi
2112
2219
.
2113
2220
.P
2114
2221
This method must only be called once on a message and it must
2115
 
be called before \fBresponse.end()\fR is called.
 
2222
be called before \fBresponse\.end()\fR is called\.
2116
2223
.
2117
 
.SS "response.write(chunk, encoding)"
 
2224
.SS "response\.write(chunk, encoding=\'ascii\')"
2118
2225
This method must be called after \fBwriteHead\fR was
2119
 
called. It sends a chunk of the response body. This method may
2120
 
be called multiple times to provide successive parts of the body.
 
2226
called\. It sends a chunk of the response body\. This method may
 
2227
be called multiple times to provide successive parts of the body\.
2121
2228
.
2122
2229
.P
2123
 
If \fBchunk\fR is a string, the second parameter
2124
 
specifies how to encode it into a byte stream. By default the \fBencoding\fR is \fB'ascii'\fR.
 
2230
\fBchunk\fR can be a string or a buffer\. If \fBchunk\fR is a string,
 
2231
the second parameter specifies how to encode it into a byte stream\.
 
2232
By default the \fBencoding\fR is \fB\'ascii\'\fR\|\.
2125
2233
.
2126
2234
.P
2127
2235
\fBNote\fR: This is the raw HTTP body and has nothing to do with
2128
 
higher\-level multi\-part body encodings that may be used.
 
2236
higher\-level multi\-part body encodings that may be used\.
2129
2237
.
2130
2238
.P
2131
 
The first time \fBresponse.write()\fR is called, it will send the buffered
2132
 
header information and the first body to the client. The second time \fBresponse.write()\fR is called, Node assumes you're going to be streaming
2133
 
data, and sends that separately. That is, the response is buffered up to the
2134
 
first chunk of body.
 
2239
The first time \fBresponse\.write()\fR is called, it will send the buffered
 
2240
header information and the first body to the client\. The second time \fBresponse\.write()\fR is called, Node assumes you\'re going to be streaming
 
2241
data, and sends that separately\. That is, the response is buffered up to the
 
2242
first chunk of body\.
2135
2243
.
2136
 
.SS "response.end()"
 
2244
.SS "response\.end([data], [encoding])"
2137
2245
This method signals to the server that all of the response headers and body
2138
 
has been sent; that server should consider this message complete.
2139
 
The method, \fBresponse.end()\fR, MUST be called on each
2140
 
response.
2141
 
.
2142
 
.SH "http.Client"
 
2246
has been sent; that server should consider this message complete\.
 
2247
The method, \fBresponse\.end()\fR, MUST be called on each
 
2248
response\.
 
2249
.
 
2250
.P
 
2251
If \fBdata\fR is specified, it is equivalent to calling \fBresponse\.write(data, encoding)\fR
 
2252
followed by \fBresponse\.end()\fR\|\.
 
2253
.
 
2254
.SH "http\.Client"
2143
2255
An HTTP client is constructed with a server address as its
2144
2256
argument, the returned handle is then used to issue one or more
2145
 
requests.  Depending on the server connected to, the client might
 
2257
requests\.  Depending on the server connected to, the client might
2146
2258
pipeline the requests or reestablish the stream after each
2147
 
stream. \fICurrently the implementation does not pipeline requests.\fR
 
2259
stream\. \fICurrently the implementation does not pipeline requests\.\fR
2148
2260
.
2149
2261
.P
2150
 
Example of connecting to \fBgoogle.com\fR:
 
2262
Example of connecting to \fBgoogle\.com\fR:
2151
2263
.
2152
2264
.IP "" 4
2153
2265
.
2154
2266
.nf
2155
 
var sys = require('sys'),
2156
 
   http = require('http');
2157
 
var google = http.createClient(80, 'www.google.com');
2158
 
var request = google.request('GET', '/',
2159
 
  {'host': 'www.google.com'});
2160
 
request.addListener('response', function (response) {
2161
 
  sys.puts('STATUS: ' + response.statusCode);
2162
 
  sys.puts('HEADERS: ' + JSON.stringify(response.headers));
2163
 
  response.setEncoding('utf8');
2164
 
  response.addListener('data', function (chunk) {
2165
 
    sys.puts('BODY: ' + chunk);
 
2267
var http = require(\'http\');
 
2268
var google = http\.createClient(80, \'www\.google\.com\');
 
2269
var request = google\.request(\'GET\', \'/\',
 
2270
  {\'host\': \'www\.google\.com\'});
 
2271
request\.end();
 
2272
request\.on(\'response\', function (response) {
 
2273
  console\.log(\'STATUS: \' + response\.statusCode);
 
2274
  console\.log(\'HEADERS: \' + JSON\.stringify(response\.headers));
 
2275
  response\.setEncoding(\'utf8\');
 
2276
  response\.on(\'data\', function (chunk) {
 
2277
    console\.log(\'BODY: \' + chunk);
2166
2278
  });
2167
2279
});
2168
 
request.end();
2169
2280
.
2170
2281
.fi
2171
2282
.
2172
2283
.IP "" 0
2173
2284
.
2174
 
.SS "http.createClient(port, host, secure, credentials)"
2175
 
Constructs a new HTTP client. \fBport\fR and \fBhost\fR refer to the server to be connected to. A
2176
 
stream is not established until a request is issued.
2177
 
.
2178
 
.P
2179
 
\fBsecure\fR is an optional boolean flag to enable https support and \fBcredentials\fR is an optional credentials object from the crypto module, which may hold the client's private key, certificate, and a list of trusted CA certificates.
2180
 
.
2181
 
.P
2182
 
If the connection is secure, but no explicit CA certificates are passed in the credentials, then node.js will default to the publicly trusted list of CA certificates, as given in http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
2183
 
.
2184
 
.SS "client.request([method], path, [request_headers])"
2185
 
Issues a request; if necessary establishes stream. Returns a \fBhttp.ClientRequest\fR instance.
2186
 
.
2187
 
.P
2188
 
\fBmethod\fR is optional and defaults to 'GET' if omitted.
2189
 
.
2190
 
.P
2191
 
\fBrequest_headers\fR is optional.
 
2285
.P
 
2286
There are a few special headers that should be noted\.
 
2287
.
 
2288
.IP "\(bu" 4
 
2289
The \'Host\' header is not added by Node, and is usually required by
 
2290
website\.
 
2291
.
 
2292
.IP "\(bu" 4
 
2293
Sending a \'Connection: keep\-alive\' will notify Node that the connection to
 
2294
the server should be persisted until the next request\.
 
2295
.
 
2296
.IP "\(bu" 4
 
2297
Sending a \'Content\-length\' header will disable the default chunked encoding\.
 
2298
.
 
2299
.IP "" 0
 
2300
.
 
2301
.SS "Event: \'upgrade\'"
 
2302
\fBfunction (request, socket, head)\fR
 
2303
.
 
2304
.P
 
2305
Emitted each time a server responds to a request with an upgrade\. If this event
 
2306
isn\'t being listened for, clients receiving an upgrade header will have their
 
2307
connections closed\.
 
2308
.
 
2309
.P
 
2310
See the description of the \fBupgrade\fR event for \fBhttp\.Server\fR for further details\.
 
2311
.
 
2312
.SS "http\.createClient(port, host=\'localhost\', secure=false, [credentials])"
 
2313
Constructs a new HTTP client\. \fBport\fR and \fBhost\fR refer to the server to be connected to\. A
 
2314
stream is not established until a request is issued\.
 
2315
.
 
2316
.P
 
2317
\fBsecure\fR is an optional boolean flag to enable https support and \fBcredentials\fR is an optional credentials object from the crypto module, which may hold the client\'s private key, certificate, and a list of trusted CA certificates\.
 
2318
.
 
2319
.P
 
2320
If the connection is secure, but no explicit CA certificates are passed in the credentials, then node\.js will default to the publicly trusted list of CA certificates, as given in http://mxr\.mozilla\.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata\.txt
 
2321
.
 
2322
.SS "client\.request(method=\'GET\', path, [request_headers])"
 
2323
Issues a request; if necessary establishes stream\. Returns a \fBhttp\.ClientRequest\fR instance\.
 
2324
.
 
2325
.P
 
2326
\fBmethod\fR is optional and defaults to \'GET\' if omitted\.
 
2327
.
 
2328
.P
 
2329
\fBrequest_headers\fR is optional\.
2192
2330
Additional request headers might be added internally
2193
 
by Node. Returns a \fBClientRequest\fR object.
 
2331
by Node\. Returns a \fBClientRequest\fR object\.
2194
2332
.
2195
2333
.P
2196
2334
Do remember to include the \fBContent\-Length\fR header if you
2197
 
plan on sending a body. If you plan on streaming the body, perhaps
2198
 
set \fBTransfer\-Encoding: chunked\fR.
 
2335
plan on sending a body\. If you plan on streaming the body, perhaps
 
2336
set \fBTransfer\-Encoding: chunked\fR\|\.
2199
2337
.
2200
2338
.P
2201
 
\fINOTE\fR: the request is not complete. This method only sends the header of
2202
 
the request. One needs to call \fBrequest.end()\fR to finalize the request and
2203
 
retrieve the response.  (This sounds convoluted but it provides a chance for
2204
 
the user to stream a body to the server with \fBrequest.write()\fR.)
2205
 
.
2206
 
.SS "client.verifyPeer()"
2207
 
Returns true or false depending on the validity of the server's certificate in the context of the defined or default list of trusted CA certificates.
2208
 
.
2209
 
.SS "client.getPeerCertificate()"
2210
 
Returns a JSON structure detailing the server's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid_from' and 'valid_to'
2211
 
.
2212
 
.SH "http.ClientRequest"
 
2339
\fINOTE\fR: the request is not complete\. This method only sends the header of
 
2340
the request\. One needs to call \fBrequest\.end()\fR to finalize the request and
 
2341
retrieve the response\.  (This sounds convoluted but it provides a chance for
 
2342
the user to stream a body to the server with \fBrequest\.write()\fR\|\.)
 
2343
.
 
2344
.SS "client\.verifyPeer()"
 
2345
Returns true or false depending on the validity of the server\'s certificate in the context of the defined or default list of trusted CA certificates\.
 
2346
.
 
2347
.SS "client\.getPeerCertificate()"
 
2348
Returns a JSON structure detailing the server\'s certificate, containing a dictionary with keys for the certificate \'subject\', \'issuer\', \'valid_from\' and \'valid_to\'
 
2349
.
 
2350
.SH "http\.ClientRequest"
2213
2351
This object is created internally and returned from the \fBrequest()\fR method
2214
 
of a \fBhttp.Client\fR. It represents an \fIin\-progress\fR request whose header has
2215
 
already been sent.
2216
 
.
2217
 
.P
2218
 
To get the response, add a listener for \fB'response'\fR to the request object. \fB'response'\fR will be emitted from the request object when the response
2219
 
headers have been received.  The \fB'response'\fR event is executed with one
2220
 
argument which is an instance of \fBhttp.ClientResponse\fR.
2221
 
.
2222
 
.P
2223
 
During the \fB'response'\fR event, one can add listeners to the
2224
 
response object; particularly to listen for the \fB'data'\fR event. Note that
2225
 
the \fB'response'\fR event is called before any part of the response body is received,
 
2352
of a \fBhttp\.Client\fR\|\. It represents an \fIin\-progress\fR request whose header has
 
2353
already been sent\.
 
2354
.
 
2355
.P
 
2356
To get the response, add a listener for \fB\'response\'\fR to the request object\. \fB\'response\'\fR will be emitted from the request object when the response
 
2357
headers have been received\.  The \fB\'response\'\fR event is executed with one
 
2358
argument which is an instance of \fBhttp\.ClientResponse\fR\|\.
 
2359
.
 
2360
.P
 
2361
During the \fB\'response\'\fR event, one can add listeners to the
 
2362
response object; particularly to listen for the \fB\'data\'\fR event\. Note that
 
2363
the \fB\'response\'\fR event is called before any part of the response body is received,
2226
2364
so there is no need to worry about racing to catch the first part of the
2227
 
body. As long as a listener for \fB'data'\fR is added during the \fB'response'\fR
2228
 
event, the entire body will be caught.
 
2365
body\. As long as a listener for \fB\'data\'\fR is added during the \fB\'response\'\fR
 
2366
event, the entire body will be caught\.
2229
2367
.
2230
2368
.IP "" 4
2231
2369
.
2232
2370
.nf
2233
2371
// Good
2234
 
request.addListener('response', function (response) {
2235
 
  response.addListener('data', function (chunk) {
2236
 
    sys.puts('BODY: ' + chunk);
 
2372
request\.on(\'response\', function (response) {
 
2373
  response\.on(\'data\', function (chunk) {
 
2374
    console\.log(\'BODY: \' + chunk);
2237
2375
  });
2238
2376
});
2239
2377
// Bad \- misses all or part of the body
2240
 
request.addListener('response', function (response) {
 
2378
request\.on(\'response\', function (response) {
2241
2379
  setTimeout(function () {
2242
 
    response.addListener('data', function (chunk) {
2243
 
      sys.puts('BODY: ' + chunk);
 
2380
    response\.on(\'data\', function (chunk) {
 
2381
      console\.log(\'BODY: \' + chunk);
2244
2382
    });
2245
2383
  }, 10);
2246
2384
});
2250
2388
.IP "" 0
2251
2389
.
2252
2390
.P
2253
 
This is a writable stream.
 
2391
This is a \fBWritable Stream\fR\|\.
2254
2392
.
2255
2393
.P
2256
2394
This is an \fBEventEmitter\fR with the following events:
2257
2395
.
2258
 
.SS "Event 'response'"
 
2396
.SS "Event \'response\'"
2259
2397
\fBfunction (response) { }\fR
2260
2398
.
2261
2399
.P
2262
 
Emitted when a response is received to this request. This event is emitted only once. The\fBresponse\fR argument will be an instance of \fBhttp.ClientResponse\fR.
 
2400
Emitted when a response is received to this request\. This event is emitted only once\. The \fBresponse\fR argument will be an instance of \fBhttp\.ClientResponse\fR\|\.
2263
2401
.
2264
 
.SS "request.write(chunk, encoding='ascii')"
2265
 
Sends a chunk of the body.  By calling this method
 
2402
.SS "request\.write(chunk, encoding=\'ascii\')"
 
2403
Sends a chunk of the body\.  By calling this method
2266
2404
many times, the user can stream a request body to a
2267
 
server\-\-in that case it is suggested to use the\fB['Transfer\-Encoding', 'chunked']\fR header line when
2268
 
creating the request.
 
2405
server\-\-in that case it is suggested to use the \fB[\'Transfer\-Encoding\', \'chunked\']\fR header line when
 
2406
creating the request\.
2269
2407
.
2270
2408
.P
2271
2409
The \fBchunk\fR argument should be an array of integers
2272
 
or a string.
 
2410
or a string\.
2273
2411
.
2274
2412
.P
2275
2413
The \fBencoding\fR argument is optional and only
2276
 
applies when \fBchunk\fR is a string. The encoding
2277
 
argument should be either \fB'utf8'\fR or \fB'ascii'\fR. By default the body uses ASCII encoding,
2278
 
as it is faster.
2279
 
.
2280
 
.SS "request.end()"
2281
 
Finishes sending the request. If any parts of the body are
2282
 
unsent, it will flush them to the stream. If the request is
2283
 
chunked, this will send the terminating \fB'0\\r\\n\\r\\n'\fR.
2284
 
.
2285
 
.SH "http.ClientResponse"
2286
 
This object is created when making a request with \fBhttp.Client\fR. It is
2287
 
passed to the \fB'response'\fR event of the request object.
2288
 
.
2289
 
.P
2290
 
The response implements the \fBreadable stream\fR interface.
2291
 
.
2292
 
.SS "Event: 'data'"
 
2414
applies when \fBchunk\fR is a string\. The encoding
 
2415
argument should be either \fB\'utf8\'\fR or \fB\'ascii\'\fR\|\. By default the body uses ASCII encoding,
 
2416
as it is faster\.
 
2417
.
 
2418
.SS "request\.end([data], [encoding])"
 
2419
Finishes sending the request\. If any parts of the body are
 
2420
unsent, it will flush them to the stream\. If the request is
 
2421
chunked, this will send the terminating \fB\'0\\r\\n\\r\\n\'\fR\|\.
 
2422
.
 
2423
.P
 
2424
If \fBdata\fR is specified, it is equivalent to calling \fBrequest\.write(data, encoding)\fR
 
2425
followed by \fBrequest\.end()\fR\|\.
 
2426
.
 
2427
.SH "http\.ClientResponse"
 
2428
This object is created when making a request with \fBhttp\.Client\fR\|\. It is
 
2429
passed to the \fB\'response\'\fR event of the request object\.
 
2430
.
 
2431
.P
 
2432
The response implements the \fBReadable Stream\fR interface\.
 
2433
.
 
2434
.SS "Event: \'data\'"
2293
2435
\fBfunction (chunk) {}\fR
2294
2436
.
2295
2437
.P
2296
 
Emitted when a piece of the message body is received.
 
2438
Emitted when a piece of the message body is received\.
2297
2439
.
2298
2440
.IP "" 4
2299
2441
.
2300
2442
.nf
2301
2443
Example: A chunk of the body is given as the single
2302
 
argument. The transfer\-encoding has been decoded.  The
2303
 
body chunk a String.  The body encoding is set with
2304
 
`response.setBodyEncoding()`.
 
2444
argument\. The transfer\-encoding has been decoded\.  The
 
2445
body chunk a String\.  The body encoding is set with
 
2446
`response\.setBodyEncoding()`\.
2305
2447
.
2306
2448
.fi
2307
2449
.
2308
2450
.IP "" 0
2309
2451
.
2310
 
.SS "Event: 'end'"
 
2452
.SS "Event: \'end\'"
2311
2453
\fBfunction () {}\fR
2312
2454
.
2313
2455
.P
2314
 
Emitted exactly once for each message. No arguments. After
2315
 
emitted no other events will be emitted on the response.
2316
 
.
2317
 
.SS "response.statusCode"
2318
 
The 3\-digit HTTP response status code. E.G. \fB404\fR.
2319
 
.
2320
 
.SS "response.httpVersion"
2321
 
The HTTP version of the connected\-to server. Probably either\fB'1.1'\fR or \fB'1.0'\fR.
2322
 
Also \fBresponse.httpVersionMajor\fR is the first integer and \fBresponse.httpVersionMinor\fR is the second.
2323
 
.
2324
 
.SS "response.headers"
2325
 
The response headers.
2326
 
.
2327
 
.SS "response.setEncoding(encoding)"
2328
 
Set the encoding for the response body. Either \fB'utf8'\fR or \fB'binary'\fR.
2329
 
Defaults to \fB'binary'\fR.
2330
 
.
2331
 
.SS "response.pause()"
2332
 
Pauses response from emitting events.  Useful to throttle back a download.
2333
 
.
2334
 
.SS "response.resume()"
2335
 
Resumes a paused response.
2336
 
.
2337
 
.SS "response.client"
2338
 
A reference to the \fBhttp.Client\fR that this response belongs to.
2339
 
.
2340
 
.SH "net.Server"
2341
 
This class is used to create a TCP or UNIX server.
 
2456
Emitted exactly once for each message\. No arguments\. After
 
2457
emitted no other events will be emitted on the response\.
 
2458
.
 
2459
.SS "response\.statusCode"
 
2460
The 3\-digit HTTP response status code\. E\.G\. \fB404\fR\|\.
 
2461
.
 
2462
.SS "response\.httpVersion"
 
2463
The HTTP version of the connected\-to server\. Probably either \fB\'1\.1\'\fR or \fB\'1\.0\'\fR\|\.
 
2464
Also \fBresponse\.httpVersionMajor\fR is the first integer and \fBresponse\.httpVersionMinor\fR is the second\.
 
2465
.
 
2466
.SS "response\.headers"
 
2467
The response headers object\.
 
2468
.
 
2469
.SS "response\.setEncoding(encoding=null)"
 
2470
Set the encoding for the response body\. Either \fB\'utf8\'\fR, \fB\'ascii\'\fR, or \fB\'base64\'\fR\|\.
 
2471
Defaults to \fBnull\fR, which means that the \fB\'data\'\fR event will emit a \fBBuffer\fR object\.\.
 
2472
.
 
2473
.SS "response\.pause()"
 
2474
Pauses response from emitting events\.  Useful to throttle back a download\.
 
2475
.
 
2476
.SS "response\.resume()"
 
2477
Resumes a paused response\.
 
2478
.
 
2479
.SS "response\.client"
 
2480
A reference to the \fBhttp\.Client\fR that this response belongs to\.
 
2481
.
 
2482
.SH "net\.Server"
 
2483
This class is used to create a TCP or UNIX server\.
2342
2484
.
2343
2485
.P
2344
2486
Here is an example of a echo server which listens for connections
2345
 
on port 7000:
 
2487
on port 8124:
2346
2488
.
2347
2489
.IP "" 4
2348
2490
.
2349
2491
.nf
2350
 
var net = require('net');
2351
 
var server = net.createServer(function (stream) {
2352
 
  stream.setEncoding('utf8');
2353
 
  stream.addListener('connect', function () {
2354
 
    stream.write('hello\\r\\n');
2355
 
  });
2356
 
  stream.addListener('data', function (data) {
2357
 
    stream.write(data);
2358
 
  });
2359
 
  stream.addListener('end', function () {
2360
 
    stream.write('goodbye\\r\\n');
2361
 
    stream.end();
 
2492
var net = require(\'net\');
 
2493
var server = net\.createServer(function (stream) {
 
2494
  stream\.setEncoding(\'utf8\');
 
2495
  stream\.on(\'connect\', function () {
 
2496
    stream\.write(\'hello\\r\\n\');
 
2497
  });
 
2498
  stream\.on(\'data\', function (data) {
 
2499
    stream\.write(data);
 
2500
  });
 
2501
  stream\.on(\'end\', function () {
 
2502
    stream\.write(\'goodbye\\r\\n\');
 
2503
    stream\.end();
2362
2504
  });
2363
2505
});
2364
 
server.listen(7000, 'localhost');
 
2506
server\.listen(8124, \'localhost\');
2365
2507
.
2366
2508
.fi
2367
2509
.
2368
2510
.IP "" 0
2369
2511
.
2370
2512
.P
2371
 
To listen on the socket \fB'/tmp/echo.sock'\fR, the last line would just be
 
2513
To listen on the socket \fB\'/tmp/echo\.sock\'\fR, the last line would just be
2372
2514
changed to
2373
2515
.
2374
2516
.IP "" 4
2375
2517
.
2376
2518
.nf
2377
 
server.listen('/tmp/echo.sock');
 
2519
server\.listen(\'/tmp/echo\.sock\');
2378
2520
.
2379
2521
.fi
2380
2522
.
2381
2523
.IP "" 0
2382
2524
.
2383
2525
.P
2384
 
This is an EventEmitter with the following events:
2385
 
.
2386
 
.SS "Event: 'listening'"
2387
 
\fBfunction () {}\fR
2388
 
.
2389
 
.P
2390
 
After \fBlisten()\fR is called, this event will notify that the server is ready
2391
 
to accept connections.
2392
 
.
2393
 
.SS "Event: 'connection'"
 
2526
This is an \fBEventEmitter\fR with the following events:
 
2527
.
 
2528
.SS "Event: \'connection\'"
2394
2529
\fBfunction (stream) {}\fR
2395
2530
.
2396
2531
.P
2397
 
Emitted when a new connection is made. \fBstream\fR is an instance of \fBnet.Stream\fR.
 
2532
Emitted when a new connection is made\. \fBstream\fR is an instance of \fBnet\.Stream\fR\|\.
2398
2533
.
2399
 
.SS "Event: 'close'"
 
2534
.SS "Event: \'close\'"
2400
2535
\fBfunction () {}\fR
2401
2536
.
2402
2537
.P
2403
 
Emitted when the server closes.
2404
 
.
2405
 
.SS "net.createServer(connectionListener)"
2406
 
Creates a new TCP server. The \fBconnection_listener\fR argument is
2407
 
automatically set as a listener for the \fB'connection'\fR event.
2408
 
.
2409
 
.SS "server.listen(port, host=null)"
2410
 
Tells the server to listen for TCP connections to \fBport\fR and \fBhost\fR.
2411
 
.
2412
 
.P
2413
 
\fBhost\fR is optional. If \fBhost\fR is not specified the server will accept client
2414
 
connections on any network address.
2415
 
.
2416
 
.P
2417
 
This function is asynchronous. The server will emit \fB'listening'\fR when it is
2418
 
safe to connect to it.
2419
 
.
2420
 
.SS "server.close()"
2421
 
Stops the server from accepting new connections. This function is
2422
 
asynchronous, the server is finally closed when the server emits a \fB'close'\fR
2423
 
event.
2424
 
.
2425
 
.SH "net.Stream"
2426
 
This object is an abstraction of of a TCP or UNIX socket.  \fBnet.Stream\fR
2427
 
instance implement a duplex stream interface.  They can be created by the
 
2538
Emitted when the server closes\.
 
2539
.
 
2540
.SS "net\.createServer(connectionListener)"
 
2541
Creates a new TCP server\. The \fBconnectionListener\fR argument is
 
2542
automatically set as a listener for the \fB\'connection\'\fR event\.
 
2543
.
 
2544
.SS "server\.listen(port, [host], [callback])"
 
2545
Begin accepting connections on the specified \fBport\fR and \fBhost\fR\|\.  If the \fBhost\fR is omitted, the server will accept connections directed to any
 
2546
IPv4 address (\fBINADDR_ANY\fR)\.
 
2547
.
 
2548
.P
 
2549
This function is asynchronous\. The last parameter \fBcallback\fR will be called
 
2550
when the server has been bound\.
 
2551
.
 
2552
.SS "server\.listen(path, [callback])"
 
2553
Start a UNIX socket server listening for connections on the given \fBpath\fR\|\.
 
2554
.
 
2555
.P
 
2556
This function is asynchronous\. The last parameter \fBcallback\fR will be called
 
2557
when the server has been bound\.
 
2558
.
 
2559
.SS "server\.listenFD(fd)"
 
2560
Start a server listening for connections on the given file descriptor\.
 
2561
.
 
2562
.P
 
2563
This file descriptor must have already had the \fBbind(2)\fR and \fBlisten(2)\fR system
 
2564
calls invoked on it\.
 
2565
.
 
2566
.SS "server\.close()"
 
2567
Stops the server from accepting new connections\. This function is
 
2568
asynchronous, the server is finally closed when the server emits a \fB\'close\'\fR
 
2569
event\.
 
2570
.
 
2571
.SS "server\.maxConnections"
 
2572
Set this property to reject connections when the server\'s connection count gets high\.
 
2573
.
 
2574
.SS "server\.connections"
 
2575
The number of concurrent connections on the server\.
 
2576
.
 
2577
.SH "net\.Stream"
 
2578
This object is an abstraction of of a TCP or UNIX socket\.  \fBnet\.Stream\fR
 
2579
instance implement a duplex stream interface\.  They can be created by the
2428
2580
user and used as a client (with \fBconnect()\fR) or they can be created by Node
2429
 
and passed to the user through the \fB'connection'\fR event of a server.
2430
 
.
2431
 
.P
2432
 
\fBnet.Stream\fR instances are an EventEmitters with the following events:
2433
 
.
2434
 
.SS "Event: 'connect'"
2435
 
\fBfunction () { }\fR
2436
 
.
2437
 
.P
2438
 
Emitted when a stream connection successfully is established.
2439
 
See \fBconnect()\fR.
2440
 
.
2441
 
.SS "Event: 'secure'"
2442
 
\fBfunction () { }\fR
2443
 
.
2444
 
.P
2445
 
Emitted when a stream connection successfully establishes a HTTPS handshake with its peer.
2446
 
.
2447
 
.SS "Event: 'data'"
 
2581
and passed to the user through the \fB\'connection\'\fR event of a server\.
 
2582
.
 
2583
.P
 
2584
\fBnet\.Stream\fR instances are EventEmitters with the following events:
 
2585
.
 
2586
.SS "Event: \'connect\'"
 
2587
\fBfunction () { }\fR
 
2588
.
 
2589
.P
 
2590
Emitted when a stream connection successfully is established\.
 
2591
See \fBconnect()\fR\|\.
 
2592
.
 
2593
.SS "Event: \'secure\'"
 
2594
\fBfunction () { }\fR
 
2595
.
 
2596
.P
 
2597
Emitted when a stream connection successfully establishes a HTTPS handshake with its peer\.
 
2598
.
 
2599
.SS "Event: \'data\'"
2448
2600
\fBfunction (data) { }\fR
2449
2601
.
2450
2602
.P
2451
 
Emitted when data is received.  The argument \fBdata\fR will be a \fBBuffer\fR or \fBString\fR.  Encoding of data is set by \fBstream.setEncoding()\fR.
2452
 
(See the section on Readable Streams for more infromation.)
2453
 
.
2454
 
.SS "Event: 'end'"
2455
 
\fBfunction () { }\fR
2456
 
.
2457
 
.P
2458
 
Emitted when the other end of the stream sends a FIN packet. After this is
2459
 
emitted the \fBreadyState\fR will be \fB'writeOnly'\fR. One should probably just
2460
 
call \fBstream.end()\fR when this event is emitted.
2461
 
.
2462
 
.SS "Event: 'timeout'"
2463
 
\fBfunction () { }\fR
2464
 
.
2465
 
.P
2466
 
Emitted if the stream times out from inactivity. This is only to notify that
2467
 
the stream has been idle. The user must manually close the connection.
2468
 
.
2469
 
.P
2470
 
See also: \fBstream.setTimeout()\fR
2471
 
.
2472
 
.SS "Event: 'drain'"
2473
 
\fBfunction () { }\fR
2474
 
.
2475
 
.P
2476
 
Emitted when the write buffer becomes empty. Can be used to throttle uploads.
2477
 
.
2478
 
.SS "Event: 'error'"
 
2603
Emitted when data is received\.  The argument \fBdata\fR will be a \fBBuffer\fR or \fBString\fR\|\.  Encoding of data is set by \fBstream\.setEncoding()\fR\|\.
 
2604
(See the section on \fBReadable Stream\fR for more information\.)
 
2605
.
 
2606
.SS "Event: \'end\'"
 
2607
\fBfunction () { }\fR
 
2608
.
 
2609
.P
 
2610
Emitted when the other end of the stream sends a FIN packet\. After this is
 
2611
emitted the \fBreadyState\fR will be \fB\'writeOnly\'\fR\|\. One should probably just
 
2612
call \fBstream\.end()\fR when this event is emitted\.
 
2613
.
 
2614
.SS "Event: \'timeout\'"
 
2615
\fBfunction () { }\fR
 
2616
.
 
2617
.P
 
2618
Emitted if the stream times out from inactivity\. This is only to notify that
 
2619
the stream has been idle\. The user must manually close the connection\.
 
2620
.
 
2621
.P
 
2622
See also: \fBstream\.setTimeout()\fR
 
2623
.
 
2624
.SS "Event: \'drain\'"
 
2625
\fBfunction () { }\fR
 
2626
.
 
2627
.P
 
2628
Emitted when the write buffer becomes empty\. Can be used to throttle uploads\.
 
2629
.
 
2630
.SS "Event: \'error\'"
2479
2631
\fBfunction (exception) { }\fR
2480
2632
.
2481
2633
.P
2482
 
Emitted when an error occurs.  The \fB'close'\fR event will be called directly
2483
 
following this event.
 
2634
Emitted when an error occurs\.  The \fB\'close\'\fR event will be called directly
 
2635
following this event\.
2484
2636
.
2485
 
.SS "Event: 'close'"
2486
 
\fBfunction () { }\fR
 
2637
.SS "Event: \'close\'"
 
2638
\fBfunction (had_error) { }\fR
2487
2639
.
2488
2640
.P
2489
 
Emitted once the stream is fully closed. The argument \fBhad_error\fR is a boolean which says if
 
2641
Emitted once the stream is fully closed\. The argument \fBhad_error\fR is a boolean which says if
2490
2642
the stream was closed due to a transmission
2491
 
error.
 
2643
error\.
2492
2644
.
2493
 
.SS "net.createConnection(port, host='127.0.0.1')"
 
2645
.SS "net\.createConnection(port, host=\'127\.0\.0\.1\')"
2494
2646
Construct a new stream object and opens a stream to the specified \fBport\fR
2495
 
and \fBhost\fR. If the second parameter is omitted, localhost is assumed.
 
2647
and \fBhost\fR\|\. If the second parameter is omitted, localhost is assumed\.
2496
2648
.
2497
2649
.P
2498
 
When the stream is established the \fB'connect'\fR event will be emitted.
 
2650
When the stream is established the \fB\'connect\'\fR event will be emitted\.
2499
2651
.
2500
 
.SS "stream.connect(port, host='127.0.0.1')"
2501
 
Opens a stream to the specified \fBport\fR and \fBhost\fR. \fBcreateConnection()\fR
2502
 
also opens a stream; normally this method is not needed. Use this only if
 
2652
.SS "stream\.connect(port, host=\'127\.0\.0\.1\')"
 
2653
Opens a stream to the specified \fBport\fR and \fBhost\fR\|\. \fBcreateConnection()\fR
 
2654
also opens a stream; normally this method is not needed\. Use this only if
2503
2655
a stream is closed and you want to reuse the object to connect to another
2504
 
server.
2505
 
.
2506
 
.P
2507
 
This function is asynchronous. When the \fB'connect'\fR event is emitted the
2508
 
stream is established. If there is a problem connecting, the \fB'connect'\fR
2509
 
event will not be emitted, the \fB'error'\fR event will be emitted with
2510
 
the exception.
2511
 
.
2512
 
.SS "stream.remoteAddress"
2513
 
The string representation of the remote IP address. For example,\fB'74.125.127.100'\fR or \fB'2001:4860:a005::68'\fR.
2514
 
.
2515
 
.P
2516
 
This member is only present in server\-side connections.
2517
 
.
2518
 
.SS "stream.readyState"
2519
 
Either \fB'closed'\fR, \fB'open'\fR, \fB'opening'\fR, \fB'readOnly'\fR, or \fB'writeOnly'\fR.
2520
 
.
2521
 
.SS "stream.setEncoding(encoding)"
2522
 
Sets the encoding (either \fB'ascii'\fR, \fB'utf8'\fR, or \fB'binary'\fR) for data that is
2523
 
received.
2524
 
.
2525
 
.SS "stream.setSecure(credentials)"
2526
 
Enables HTTPS support for the stream, with the crypto module credentials specifying the private key and certificate of the stream, and optionally the CA certificates for use in peer authentication.
2527
 
.
2528
 
.P
2529
 
If the credentials hold one ore more CA certificates, then the stream will request for the peer to submit a client certificate as part of the HTTPS connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate().
2530
 
.
2531
 
.SS "stream.verifyPeer()"
2532
 
Returns true or false depending on the validity of the peers's certificate in the context of the defined or default list of trusted CA certificates.
2533
 
.
2534
 
.SS "stream.getPeerCertificate()"
2535
 
Returns a JSON structure detailing the peer's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid_from' and 'valid_to'
2536
 
.
2537
 
.SS "stream.write(data, encoding='ascii')"
2538
 
Sends data on the stream. The second parameter specifies the encoding in
 
2656
server\.
 
2657
.
 
2658
.P
 
2659
This function is asynchronous\. When the \fB\'connect\'\fR event is emitted the
 
2660
stream is established\. If there is a problem connecting, the \fB\'connect\'\fR
 
2661
event will not be emitted, the \fB\'error\'\fR event will be emitted with 
 
2662
the exception\.
 
2663
.
 
2664
.SS "stream\.remoteAddress"
 
2665
The string representation of the remote IP address\. For example, \fB\'74\.125\.127\.100\'\fR or \fB\'2001:4860:a005::68\'\fR\|\.
 
2666
.
 
2667
.P
 
2668
This member is only present in server\-side connections\.
 
2669
.
 
2670
.SS "stream\.readyState"
 
2671
Either \fB\'closed\'\fR, \fB\'open\'\fR, \fB\'opening\'\fR, \fB\'readOnly\'\fR, or \fB\'writeOnly\'\fR\|\.
 
2672
.
 
2673
.SS "stream\.setEncoding(encoding=null)"
 
2674
Sets the encoding (either \fB\'ascii\'\fR, \fB\'utf8\'\fR, or \fB\'base64\'\fR) for data that is
 
2675
received\.
 
2676
.
 
2677
.SS "stream\.setSecure([credentials])"
 
2678
Enables HTTPS support for the stream, with the crypto module credentials specifying the private key and certificate of the stream, and optionally the CA certificates for use in peer authentication\.
 
2679
.
 
2680
.P
 
2681
If the credentials hold one ore more CA certificates, then the stream will request for the peer to submit a client certificate as part of the HTTPS connection handshake\. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate()\.
 
2682
.
 
2683
.SS "stream\.verifyPeer()"
 
2684
Returns true or false depending on the validity of the peers\'s certificate in the context of the defined or default list of trusted CA certificates\.
 
2685
.
 
2686
.SS "stream\.getPeerCertificate()"
 
2687
Returns a JSON structure detailing the peer\'s certificate, containing a dictionary with keys for the certificate \'subject\', \'issuer\', \'valid_from\' and \'valid_to\'
 
2688
.
 
2689
.SS "stream\.write(data, encoding=\'ascii\')"
 
2690
Sends data on the stream\. The second parameter specifies the encoding in
2539
2691
the case of a string\-\-it defaults to ASCII because encoding to UTF8 is rather
2540
 
slow.
 
2692
slow\.
2541
2693
.
2542
2694
.P
2543
2695
Returns \fBtrue\fR if the entire data was flushed successfully to the kernel
2544
 
buffer. Returns \fBfalse\fR if all or part of the data was queued in user memory. \fB'drain'\fR will be emitted when the buffer is again free.
2545
 
.
2546
 
.SS "stream.end()"
2547
 
Half\-closes the stream. I.E., it sends a FIN packet. It is possible the
2548
 
server will still send some data. After calling this \fBreadyState\fR will be \fB'readOnly'\fR.
2549
 
.
2550
 
.SS "stream.destroy()"
2551
 
Ensures that no more I/O activity happens on this stream. Only necessary in
2552
 
case of errors (parse error or so).
2553
 
.
2554
 
.SS "stream.pause()"
2555
 
Pauses the reading of data. That is, \fB'data'\fR events will not be emitted.
2556
 
Useful to throttle back an upload.
2557
 
.
2558
 
.SS "stream.resume()"
2559
 
Resumes reading after a call to \fBpause()\fR.
2560
 
.
2561
 
.SS "stream.setTimeout(timeout)"
 
2696
buffer\. Returns \fBfalse\fR if all or part of the data was queued in user memory\. \fB\'drain\'\fR will be emitted when the buffer is again free\.
 
2697
.
 
2698
.SS "stream\.end([data], [encoding])"
 
2699
Half\-closes the stream\. I\.E\., it sends a FIN packet\. It is possible the
 
2700
server will still send some data\. After calling this \fBreadyState\fR will be \fB\'readOnly\'\fR\|\.
 
2701
.
 
2702
.P
 
2703
If \fBdata\fR is specified, it is equivalent to calling \fBstream\.write(data, encoding)\fR
 
2704
followed by \fBstream\.end()\fR\|\.
 
2705
.
 
2706
.SS "stream\.destroy()"
 
2707
Ensures that no more I/O activity happens on this stream\. Only necessary in
 
2708
case of errors (parse error or so)\.
 
2709
.
 
2710
.SS "stream\.pause()"
 
2711
Pauses the reading of data\. That is, \fB\'data\'\fR events will not be emitted\.
 
2712
Useful to throttle back an upload\.
 
2713
.
 
2714
.SS "stream\.resume()"
 
2715
Resumes reading after a call to \fBpause()\fR\|\.
 
2716
.
 
2717
.SS "stream\.setTimeout(timeout)"
2562
2718
Sets the stream to timeout after \fBtimeout\fR milliseconds of inactivity on
2563
 
the stream. By default \fBnet.Stream\fR do not have a timeout.
2564
 
.
2565
 
.P
2566
 
When an idle timeout is triggered the stream will receive a \fB'timeout'\fR
2567
 
event but the connection will not be severed. The user must manually \fBend()\fR
2568
 
or \fBdestroy()\fR the stream.
2569
 
.
2570
 
.P
2571
 
If \fBtimeout\fR is 0, then the existing idle timeout is disabled.
2572
 
.
2573
 
.SS "stream.setNoDelay(noDelay=true)"
2574
 
Disables the Nagle algorithm. By default TCP connections use the Nagle
2575
 
algorithm, they buffer data before sending it off. Setting \fBnoDelay\fR will
2576
 
immediately fire off data each time \fBstream.write()\fR is called.
2577
 
.
2578
 
.SS "stream.setKeepAlive(enable=false, initialDelay)"
 
2719
the stream\. By default \fBnet\.Stream\fR do not have a timeout\.
 
2720
.
 
2721
.P
 
2722
When an idle timeout is triggered the stream will receive a \fB\'timeout\'\fR
 
2723
event but the connection will not be severed\. The user must manually \fBend()\fR
 
2724
or \fBdestroy()\fR the stream\.
 
2725
.
 
2726
.P
 
2727
If \fBtimeout\fR is 0, then the existing idle timeout is disabled\.
 
2728
.
 
2729
.SS "stream\.setNoDelay(noDelay=true)"
 
2730
Disables the Nagle algorithm\. By default TCP connections use the Nagle
 
2731
algorithm, they buffer data before sending it off\. Setting \fBnoDelay\fR will
 
2732
immediately fire off data each time \fBstream\.write()\fR is called\.
 
2733
.
 
2734
.SS "stream\.setKeepAlive(enable=false, [initialDelay])"
2579
2735
Enable/disable keep\-alive functionality, and optionally set the initial
2580
 
delay before the first keepalive probe is sent on an idle stream.
 
2736
delay before the first keepalive probe is sent on an idle stream\.
2581
2737
Set \fBinitialDelay\fR (in milliseconds) to set the delay between the last
2582
 
data packet received and the first keepalive probe. Setting 0 for
 
2738
data packet received and the first keepalive probe\. Setting 0 for
2583
2739
initialDelay will leave the value unchanged from the default
2584
 
(or previous) setting.
 
2740
(or previous) setting\.
2585
2741
.
2586
2742
.SH "Crypto"
2587
 
Use \fBrequire('crypto')\fR to access this module.
2588
 
.
2589
 
.P
2590
 
The crypto module requires OpenSSL to be available on the underlying platform. It offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or http connection.
2591
 
.
2592
 
.P
2593
 
It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.
2594
 
.
2595
 
.SS "crypto.createCredentials(details)"
 
2743
Use \fBrequire(\'crypto\')\fR to access this module\.
 
2744
.
 
2745
.P
 
2746
The crypto module requires OpenSSL to be available on the underlying platform\. It offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or http connection\.
 
2747
.
 
2748
.P
 
2749
It also offers a set of wrappers for OpenSSL\'s hash, hmac, cipher, decipher, sign and verify methods\.
 
2750
.
 
2751
.SS "crypto\.createCredentials(details)"
2596
2752
Creates a credentials object, with the optional details being a dictionary with keys:
2597
2753
.
2598
2754
.P
2602
2758
\fBcert\fR : a string holding the PEM encoded certificate
2603
2759
.
2604
2760
.P
2605
 
\fBca\fR : either a string or list of strings of PEM encoded CA certificates to trust.
2606
 
.
2607
 
.P
2608
 
If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in
2609
 
http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
2610
 
.
2611
 
.SS "crypto.createHash(algorithm)"
2612
 
Creates and returns a hash object, a cryptographic hash with the given algorithm which can be used to generate hash digests.
2613
 
.
2614
 
.P
2615
 
\fBalgorithm\fR is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are sha1, md5, sha256, sha512, etc. On recent releases, \fBopenssl list\-message\-digest\-algorithms\fR will display the available digest algorithms.
2616
 
.
2617
 
.SS "hash.update(data)"
2618
 
Updates the hash content with the given \fBdata\fR. This can be called many times with new data as it is streamed.
2619
 
.
2620
 
.SS "hash.digest(encoding)"
2621
 
Calculates the digest of all of the passed data to be hashed. The \fBencoding\fR can be 'hex', 'binary' or 'base64'.
2622
 
.
2623
 
.SS "crypto.createHmac(algorithm, key)"
2624
 
Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.
2625
 
.
2626
 
.P
2627
 
\fBalgorithm\fR is dependent on the available algorithms supported by OpenSSL \- see createHash above. \fBkey\fR is the hmac key to be used.
2628
 
.
2629
 
.SS "hmac.update(data)"
2630
 
Update the hmac content with the given \fBdata\fR. This can be called many times with new data as it is streamed.
2631
 
.
2632
 
.SS "hmac.digest(encoding)"
2633
 
Calculates the digest of all of the passed data to the hmac. The \fBencoding\fR can be 'hex', 'binary' or 'base64'.
2634
 
.
2635
 
.SS "crypto.createCipher(algorithm, key)"
2636
 
Creates and returns a cipher object, with the given algorithm and key.
2637
 
.
2638
 
.P
2639
 
\fBalgorithm\fR is dependent on OpenSSL, examples are aes192, etc. On recent releases, \fBopenssl list\-cipher\-algorithms\fR will display the available cipher algorithms.
2640
 
.
2641
 
.SS "cipher.update(data, input_encoding, output_encoding)"
2642
 
Updates the cipher with \fBdata\fR, the encoding of which is given in \fBinput_encoding\fR and can be 'utf8', 'ascii' or 'binary'. The \fBoutput_encoding\fR specifies the output format of the enciphered data, and can be 'binary', 'base64'  or 'hex'.
2643
 
.
2644
 
.P
2645
 
Returns the enciphered contents, and can be called many times with new data as it is streamed.
2646
 
.
2647
 
.SS "cipher.final(output_encoding)"
2648
 
Returns any remaining enciphered contents, with \fBoutput_encoding\fR as update above.
2649
 
.
2650
 
.SS "crypto.createDecipher(algorithm, key)"
2651
 
Creates and returns a decipher object, with the given algorithm and key. This is the mirror of the cipher object above.
2652
 
.
2653
 
.SS "decipher.update(data, input_encoding, output_encoding)"
2654
 
Updates the decipher with \fBdata\fR, which is encoded in 'binary', 'base64' or 'hex'. The \fBoutput_decoding\fR specifies in what format to return the deciphered plaintext \- either 'binary', 'ascii' or 'utf8'.
2655
 
.
2656
 
.SS "decipher.final(output_encoding)"
2657
 
Returns any remaining plaintext which is deciphered, with `output_encoding' as update above.
2658
 
.
2659
 
.SS "crypto.createSign(algorithm)"
2660
 
Creates and returns a signing object, with the given algorithm. On recent OpenSSL releases, \fBopenssl list\-public\-key\-algorithms\fR will display the available signing algorithms. Examples are 'RSA\-SHA256'.
2661
 
.
2662
 
.SS "signer.update(data)"
2663
 
Updates the signer object with data. This can be called many times with new data as it is streamed.
2664
 
.
2665
 
.SS "signer.sign(private_key, output_format)"
2666
 
Calculates the signature on all the updated data passed through the signer. \fBprivate_key\fR is a string containing the PEM encoded private key for signing.
2667
 
.
2668
 
.P
2669
 
Returns the signature in \fBoutput_format\fR which can be 'binary', 'hex' or 'base64'
2670
 
.
2671
 
.SS "crypto.createVerify(algorithm)"
2672
 
Creates and returns a verification object, with the given algorithm. This is the mirror of the signing object above.
2673
 
.
2674
 
.SS "verifier.update(data)"
2675
 
Updates the verifyer object with data. This can be called many times with new data as it is streamed.
2676
 
.
2677
 
.SS "verifier.verify(public_key, signature, signature_format)"
2678
 
Verifies the signed data by using the \fBpublic_key\fR which is a string containing the PEM encoded public key, and \fBsignature\fR, which is the previously calculates signature for the data, in the \fBsignature_format\fR which can be 'binary', 'hex' or 'base64'.
2679
 
.
2680
 
.P
2681
 
Returns true or false depending on the validity of the signature for the data and public key.
 
2761
\fBca\fR : either a string or list of strings of PEM encoded CA certificates to trust\.
 
2762
.
 
2763
.P
 
2764
If no \'ca\' details are given, then node\.js will use the default publicly trusted list of CAs as given in 
 
2765
http://mxr\.mozilla\.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata\.txt
 
2766
.
 
2767
.SS "crypto\.createHash(algorithm)"
 
2768
Creates and returns a hash object, a cryptographic hash with the given algorithm which can be used to generate hash digests\.
 
2769
.
 
2770
.P
 
2771
\fBalgorithm\fR is dependent on the available algorithms supported by the version of OpenSSL on the platform\. Examples are sha1, md5, sha256, sha512, etc\. On recent releases, \fBopenssl list\-message\-digest\-algorithms\fR will display the available digest algorithms\.
 
2772
.
 
2773
.SS "hash\.update(data)"
 
2774
Updates the hash content with the given \fBdata\fR\|\. This can be called many times with new data as it is streamed\.
 
2775
.
 
2776
.SS "hash\.digest(encoding=\'binary\')"
 
2777
Calculates the digest of all of the passed data to be hashed\. The \fBencoding\fR can be \'hex\', \'binary\' or \'base64\'\.
 
2778
.
 
2779
.SS "crypto\.createHmac(algorithm, key)"
 
2780
Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key\.
 
2781
.
 
2782
.P
 
2783
\fBalgorithm\fR is dependent on the available algorithms supported by OpenSSL \- see createHash above\. \fBkey\fR is the hmac key to be used\.
 
2784
.
 
2785
.SS "hmac\.update(data)"
 
2786
Update the hmac content with the given \fBdata\fR\|\. This can be called many times with new data as it is streamed\.
 
2787
.
 
2788
.SS "hmac\.digest(encoding=\'binary\')"
 
2789
Calculates the digest of all of the passed data to the hmac\. The \fBencoding\fR can be \'hex\', \'binary\' or \'base64\'\.
 
2790
.
 
2791
.SS "crypto\.createCipher(algorithm, key)"
 
2792
Creates and returns a cipher object, with the given algorithm and key\.
 
2793
.
 
2794
.P
 
2795
\fBalgorithm\fR is dependent on OpenSSL, examples are aes192, etc\. On recent releases, \fBopenssl list\-cipher\-algorithms\fR will display the available cipher algorithms\.
 
2796
.
 
2797
.SS "cipher\.update(data, input_encoding=\'binary\', output_encoding=\'binary\')"
 
2798
Updates the cipher with \fBdata\fR, the encoding of which is given in \fBinput_encoding\fR and can be \'utf8\', \'ascii\' or \'binary\'\. The \fBoutput_encoding\fR specifies the output format of the enciphered data, and can be \'binary\', \'base64\'  or \'hex\'\.
 
2799
.
 
2800
.P
 
2801
Returns the enciphered contents, and can be called many times with new data as it is streamed\.
 
2802
.
 
2803
.SS "cipher\.final(output_encoding=\'binary\')"
 
2804
Returns any remaining enciphered contents, with \fBoutput_encoding\fR being one of: \'binary\', \'ascii\' or \'utf8\'\.
 
2805
.
 
2806
.SS "crypto\.createDecipher(algorithm, key)"
 
2807
Creates and returns a decipher object, with the given algorithm and key\. This is the mirror of the cipher object above\.
 
2808
.
 
2809
.SS "decipher\.update(data, input_encoding=\'binary\', output_encoding=\'binary\')"
 
2810
Updates the decipher with \fBdata\fR, which is encoded in \'binary\', \'base64\' or \'hex\'\. The \fBoutput_decoding\fR specifies in what format to return the deciphered plaintext \- either \'binary\', \'ascii\' or \'utf8\'\.
 
2811
.
 
2812
.SS "decipher\.final(output_encoding=\'binary\')"
 
2813
Returns any remaining plaintext which is deciphered, with `output_encoding\' being one of: \'binary\', \'ascii\' or \'utf8\'\.
 
2814
.
 
2815
.SS "crypto\.createSign(algorithm)"
 
2816
Creates and returns a signing object, with the given algorithm\. On recent OpenSSL releases, \fBopenssl list\-public\-key\-algorithms\fR will display the available signing algorithms\. Examples are \'RSA\-SHA256\'\.
 
2817
.
 
2818
.SS "signer\.update(data)"
 
2819
Updates the signer object with data\. This can be called many times with new data as it is streamed\.
 
2820
.
 
2821
.SS "signer\.sign(private_key, output_format=\'binary\')"
 
2822
Calculates the signature on all the updated data passed through the signer\. \fBprivate_key\fR is a string containing the PEM encoded private key for signing\.
 
2823
.
 
2824
.P
 
2825
Returns the signature in \fBoutput_format\fR which can be \'binary\', \'hex\' or \'base64\'
 
2826
.
 
2827
.SS "crypto\.createVerify(algorithm)"
 
2828
Creates and returns a verification object, with the given algorithm\. This is the mirror of the signing object above\.
 
2829
.
 
2830
.SS "verifier\.update(data)"
 
2831
Updates the verifyer object with data\. This can be called many times with new data as it is streamed\.
 
2832
.
 
2833
.SS "verifier\.verify(public_key, signature, signature_format=\'binary\')"
 
2834
Verifies the signed data by using the \fBpublic_key\fR which is a string containing the PEM encoded public key, and \fBsignature\fR, which is the previously calculates signature for the data, in the \fBsignature_format\fR which can be \'binary\', \'hex\' or \'base64\'\.
 
2835
.
 
2836
.P
 
2837
Returns true or false depending on the validity of the signature for the data and public key\.
2682
2838
.
2683
2839
.SH "DNS"
2684
 
Use \fBrequire('dns')\fR to access this module.
 
2840
Use \fBrequire(\'dns\')\fR to access this module\.
2685
2841
.
2686
2842
.P
2687
 
Here is an example which resolves \fB'www.google.com'\fR then reverse
2688
 
resolves the IP addresses which are returned.
 
2843
Here is an example which resolves \fB\'www\.google\.com\'\fR then reverse
 
2844
resolves the IP addresses which are returned\.
2689
2845
.
2690
2846
.IP "" 4
2691
2847
.
2692
2848
.nf
2693
 
var dns = require('dns'),
2694
 
    sys = require('sys');
2695
 
dns.resolve4('www.google.com', function (err, addresses) {
 
2849
var dns = require(\'dns\');
 
2850
dns\.resolve4(\'www\.google\.com\', function (err, addresses) {
2696
2851
  if (err) throw err;
2697
 
  sys.puts('addresses: ' + JSON.stringify(addresses));
2698
 
  for (var i = 0; i < addresses.length; i++) {
2699
 
    var a = addresses[i];
2700
 
    dns.reverse(a, function (err, domains) {
 
2852
  console\.log(\'addresses: \' + JSON\.stringify(addresses));
 
2853
  addresses\.forEach(function (a) {
 
2854
    dns\.reverse(a, function (err, domains) {
2701
2855
      if (err) {
2702
 
        sys.puts('reverse for ' + a + ' failed: ' +
2703
 
          err.message);
 
2856
        console\.log(\'reverse for \' + a + \' failed: \' +
 
2857
          err\.message);
2704
2858
      } else {
2705
 
        sys.puts('reverse for ' + a + ': ' +
2706
 
          JSON.stringify(domains));
 
2859
        console\.log(\'reverse for \' + a + \': \' +
 
2860
          JSON\.stringify(domains));
2707
2861
      }
2708
2862
    });
2709
 
  }
 
2863
  });
2710
2864
});
2711
2865
.
2712
2866
.fi
2713
2867
.
2714
2868
.IP "" 0
2715
2869
.
2716
 
.SS "dns.resolve(domain, rrtype = 'A', callback)"
2717
 
Resolves a domain (e.g. \fB'google.com'\fR) into an array of the record types
2718
 
specified by rrtype. Valid rrtypes are \fBA\fR (IPV4 addresses), \fBAAAA\fR (IPV6
 
2870
.SS "dns\.lookup(domain, family=null, callback)"
 
2871
Resolves a domain (e\.g\. \fB\'google\.com\'\fR) into the first found A (IPv4) or
 
2872
AAAA (IPv6) record\.
 
2873
.
 
2874
.P
 
2875
The callback has arguments \fB(err, address, family)\fR\|\.  The \fBaddress\fR argument
 
2876
is a string representation of a IP v4 or v6 address\. The \fBfamily\fR argument
 
2877
is either the integer 4 or 6 and denotes the family of \fBaddress\fR (not
 
2878
neccessarily the value initially passed to \fBlookup\fR)\.
 
2879
.
 
2880
.SS "dns\.resolve(domain, rrtype=\'A\', callback)"
 
2881
Resolves a domain (e\.g\. \fB\'google\.com\'\fR) into an array of the record types
 
2882
specified by rrtype\. Valid rrtypes are \fBA\fR (IPV4 addresses), \fBAAAA\fR (IPV6
2719
2883
addresses), \fBMX\fR (mail exchange records), \fBTXT\fR (text records), \fBSRV\fR (SRV
2720
 
records), and \fBPTR\fR (used for reverse IP lookups).
 
2884
records), and \fBPTR\fR (used for reverse IP lookups)\.
2721
2885
.
2722
2886
.P
2723
 
The callback has arguments \fB(err, addresses)\fR.  The type of each item
 
2887
The callback has arguments \fB(err, addresses)\fR\|\.  The type of each item
2724
2888
in \fBaddresses\fR is determined by the record type, and described in the
2725
 
documentation for the corresponding lookup methods below.
 
2889
documentation for the corresponding lookup methods below\.
2726
2890
.
2727
2891
.P
2728
 
On error, \fBerr\fR would be an instanceof \fBError\fR object, where \fBerr.errno\fR is
2729
 
one of the error codes listed below and \fBerr.message\fR is a string describing
2730
 
the error in English.
 
2892
On error, \fBerr\fR would be an instanceof \fBError\fR object, where \fBerr\.errno\fR is
 
2893
one of the error codes listed below and \fBerr\.message\fR is a string describing
 
2894
the error in English\.
2731
2895
.
2732
 
.SS "dns.resolve4(domain, callback)"
2733
 
The same as \fBdns.resolve()\fR, but only for IPv4 queries (\fBA\fR records). \fBaddresses\fR is an array of IPv4 addresses (e.g.
 
2896
.SS "dns\.resolve4(domain, callback)"
 
2897
The same as \fBdns\.resolve()\fR, but only for IPv4 queries (\fBA\fR records)\.  \fBaddresses\fR is an array of IPv4 addresses (e\.g\.
2734
2898
.
2735
2899
.br
2736
 
\fB['74.125.79.104', '74.125.79.105', '74.125.79.106']\fR).
2737
 
.
2738
 
.SS "dns.resolve6(domain, callback)"
2739
 
The same as \fBdns.resolve4()\fR except for IPv6 queries (an \fBAAAA\fR query).
2740
 
.
2741
 
.SS "dns.resolveMx(domain, callback)"
2742
 
The same as \fBdns.resolve()\fR, but only for mail exchange queries (\fBMX\fR records).
 
2900
\fB[\'74\.125\.79\.104\', \'74\.125\.79\.105\', \'74\.125\.79\.106\']\fR)\.
 
2901
.
 
2902
.SS "dns\.resolve6(domain, callback)"
 
2903
The same as \fBdns\.resolve4()\fR except for IPv6 queries (an \fBAAAA\fR query)\.
 
2904
.
 
2905
.SS "dns\.resolveMx(domain, callback)"
 
2906
The same as \fBdns\.resolve()\fR, but only for mail exchange queries (\fBMX\fR records)\.
2743
2907
.
2744
2908
.P
2745
2909
\fBaddresses\fR is an array of MX records, each with a priority and an exchange
2746
 
attribute (e.g. \fB[{'priority': 10, 'exchange': 'mx.example.com'},...]\fR).
2747
 
.
2748
 
.SS "dns.resolveTxt(domain, callback)"
2749
 
The same as \fBdns.resolve()\fR, but only for text queries (\fBTXT\fR records). \fBaddresses\fR is an array of the text records available for \fBdomain\fR (e.g., \fB['v=spf1 ip4:0.0.0.0 ~all']\fR).
2750
 
.
2751
 
.SS "dns.resolveSrv(domain, callback)"
2752
 
The same as \fBdns.resolve()\fR, but only for service records (\fBSRV\fR records). \fBaddresses\fR is an array of the SRV records available for \fBdomain\fR. Properties
2753
 
of SRV records are priority, weight, port, and name (e.g., \fB[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]\fR).
2754
 
.
2755
 
.SS "dns.reverse(ip, callback)"
2756
 
Reverse resolves an ip address to an array of domain names.
 
2910
attribute (e\.g\. \fB[{\'priority\': 10, \'exchange\': \'mx\.example\.com\'},\.\.\.]\fR)\.
 
2911
.
 
2912
.SS "dns\.resolveTxt(domain, callback)"
 
2913
The same as \fBdns\.resolve()\fR, but only for text queries (\fBTXT\fR records)\. \fBaddresses\fR is an array of the text records available for \fBdomain\fR (e\.g\., \fB[\'v=spf1 ip4:0\.0\.0\.0 ~all\']\fR)\.
 
2914
.
 
2915
.SS "dns\.resolveSrv(domain, callback)"
 
2916
The same as \fBdns\.resolve()\fR, but only for service records (\fBSRV\fR records)\. \fBaddresses\fR is an array of the SRV records available for \fBdomain\fR\|\. Properties
 
2917
of SRV records are priority, weight, port, and name (e\.g\.,  \fB[{\'priority\': 10, {\'weight\': 5, \'port\': 21223, \'name\': \'service\.example\.com\'}, \.\.\.]\fR)\.
 
2918
.
 
2919
.SS "dns\.reverse(ip, callback)"
 
2920
Reverse resolves an ip address to an array of domain names\.
2757
2921
.
2758
2922
.P
2759
 
The callback has arguments \fB(err, domains)\fR.
 
2923
The callback has arguments \fB(err, domains)\fR\|\. 
2760
2924
.
2761
2925
.P
2762
2926
If there an an error, \fBerr\fR will be non\-null and an instanceof the Error
2763
 
object.
2764
 
.
2765
 
.P
2766
 
Each DNS query can return an error code.
2767
 
.
2768
 
.IP "\(bu" 4
2769
 
\fBdns.TEMPFAIL\fR: timeout, SERVFAIL or similar.
2770
 
.
2771
 
.IP "\(bu" 4
2772
 
\fBdns.PROTOCOL\fR: got garbled reply.
2773
 
.
2774
 
.IP "\(bu" 4
2775
 
\fBdns.NXDOMAIN\fR: domain does not exists.
2776
 
.
2777
 
.IP "\(bu" 4
2778
 
\fBdns.NODATA\fR: domain exists but no data of reqd type.
2779
 
.
2780
 
.IP "\(bu" 4
2781
 
\fBdns.NOMEM\fR: out of memory while processing.
2782
 
.
2783
 
.IP "\(bu" 4
2784
 
\fBdns.BADQUERY\fR: the query is malformed.
2785
 
.
2786
 
.IP "" 0
 
2927
object\.
 
2928
.
 
2929
.P
 
2930
Each DNS query can return an error code\.
 
2931
.
 
2932
.IP "\(bu" 4
 
2933
\fBdns\.TEMPFAIL\fR: timeout, SERVFAIL or similar\.
 
2934
.
 
2935
.IP "\(bu" 4
 
2936
\fBdns\.PROTOCOL\fR: got garbled reply\.
 
2937
.
 
2938
.IP "\(bu" 4
 
2939
\fBdns\.NXDOMAIN\fR: domain does not exists\.
 
2940
.
 
2941
.IP "\(bu" 4
 
2942
\fBdns\.NODATA\fR: domain exists but no data of reqd type\.
 
2943
.
 
2944
.IP "\(bu" 4
 
2945
\fBdns\.NOMEM\fR: out of memory while processing\.
 
2946
.
 
2947
.IP "\(bu" 4
 
2948
\fBdns\.BADQUERY\fR: the query is malformed\.
 
2949
.
 
2950
.IP "" 0
 
2951
.
 
2952
.SH "dgram"
 
2953
Datagram sockets are available through \fBrequire(\'dgram\')\fR\|\.  Datagrams are most commonly 
 
2954
handled as IP/UDP messages, but they can also be used over Unix domain sockets\.
 
2955
.
 
2956
.SS "Event: \'message\'"
 
2957
\fBfunction (msg, rinfo) { }\fR
 
2958
.
 
2959
.P
 
2960
Emitted when a new datagram is available on a socket\.  \fBmsg\fR is a \fBBuffer\fR and \fBrinfo\fR is
 
2961
an object with the sender\'s address information and the number of bytes in the datagram\.
 
2962
.
 
2963
.SS "Event: \'listening\'"
 
2964
\fBfunction () { }\fR
 
2965
.
 
2966
.P
 
2967
Emitted when a socket starts listening for datagrams\.  This happens as soon as UDP sockets
 
2968
are created\.  Unix domain sockets do not start listening until calling \fBbind()\fR on them\.
 
2969
.
 
2970
.SS "Event: \'close\'"
 
2971
\fBfunction () { }\fR
 
2972
.
 
2973
.P
 
2974
Emitted when a socket is closed with \fBclose()\fR\|\.  No new \fBmessage\fR events will be emitted
 
2975
on this socket\.
 
2976
.
 
2977
.SS "dgram\.createSocket(type, [callback])"
 
2978
Creates a datagram socket of the specified types\.  Valid types are: \fBudp4\fR, \fBudp6\fR, and \fBunix_dgram\fR\|\.  
 
2979
.
 
2980
.P
 
2981
Takes an optional callback which is added as a listener for \fBmessage\fR events\.
 
2982
.
 
2983
.SS "dgram\.send(buf, offset, length, path, [callback])"
 
2984
For Unix domain datagram sockets, the destination address is a pathname in the filesystem\.
 
2985
An optional callback may be supplied that is invoked after the \fBsendto\fR call is completed
 
2986
by the OS\.  It is not safe to re\-use \fBbuf\fR until the callback is invoked\.  Note that 
 
2987
unless the socket is bound to a pathname with \fBbind()\fR there is no way to receive messages
 
2988
on this socket\.
 
2989
.
 
2990
.P
 
2991
Example of sending a message to syslogd on OSX via Unix domain socket \fB/var/run/syslog\fR:
 
2992
.
 
2993
.IP "" 4
 
2994
.
 
2995
.nf
 
2996
var dgram = require(\'dgram\');
 
2997
var message = new Buffer("A message to log\.");
 
2998
var client = dgram\.createSocket("unix_dgram");
 
2999
client\.send(message, 0, message\.length, "/var/run/syslog",
 
3000
  function (err, bytes) {
 
3001
    if (err) {
 
3002
      throw err;
 
3003
    }
 
3004
    console\.log("Wrote " + bytes + " bytes to socket\.");
 
3005
});
 
3006
.
 
3007
.fi
 
3008
.
 
3009
.IP "" 0
 
3010
.
 
3011
.SS "dgram\.send(buf, offset, length, port, address, [callback])"
 
3012
For UDP sockets, the destination port and IP address must be specified\.  A string
 
3013
may be supplied for the \fBaddress\fR parameter, and it will be resolved with DNS\.  An 
 
3014
optional callback may be specified to detect any DNS errors and when \fBbuf\fR may be
 
3015
re\-used\.  Note that DNS lookups will delay the time that a send takes place, at
 
3016
least until the next tick\.  The only way to know for sure that a send has taken place
 
3017
is to use the callback\.
 
3018
.
 
3019
.P
 
3020
Example of sending a UDP packet to a random port on \fBlocalhost\fR;
 
3021
.
 
3022
.IP "" 4
 
3023
.
 
3024
.nf
 
3025
var dgram = require(\'dgram\');
 
3026
var message = new Buffer("Some bytes");
 
3027
var client = dgram\.createSocket("udp4");
 
3028
client\.send(message, 0, message\.length, 41234, "localhost");
 
3029
client\.close();
 
3030
.
 
3031
.fi
 
3032
.
 
3033
.IP "" 0
 
3034
.
 
3035
.SS "dgram\.bind(path)"
 
3036
For Unix domain datagram sockets, start listening for incoming datagrams on a
 
3037
socket specified by \fBpath\fR\|\. Note that clients may \fBsend()\fR without \fBbind()\fR,
 
3038
but no datagrams will be received without a \fBbind()\fR\|\.
 
3039
.
 
3040
.P
 
3041
Example of a Unix domain datagram server that echoes back all messages it receives:
 
3042
.
 
3043
.IP "" 4
 
3044
.
 
3045
.nf
 
3046
var dgram = require("dgram");
 
3047
var serverPath = "/tmp/dgram_server_sock";
 
3048
var server = dgram\.createSocket("unix_dgram");
 
3049
server\.on("message", function (msg, rinfo) {
 
3050
  console\.log("got: " + msg + " from " + rinfo\.address);
 
3051
  server\.send(msg, 0, msg\.length, rinfo\.address);
 
3052
});
 
3053
server\.on("listening", function () {
 
3054
  console\.log("server listening " + server\.address()\.address);
 
3055
})
 
3056
server\.bind(serverPath);
 
3057
.
 
3058
.fi
 
3059
.
 
3060
.IP "" 0
 
3061
.
 
3062
.P
 
3063
Example of a Unix domain datagram client that talks to this server:
 
3064
.
 
3065
.IP "" 4
 
3066
.
 
3067
.nf
 
3068
var dgram = require("dgram");
 
3069
var serverPath = "/tmp/dgram_server_sock";
 
3070
var clientPath = "/tmp/dgram_client_sock";
 
3071
var message = new Buffer("A message at " + (new Date()));
 
3072
var client = dgram\.createSocket("unix_dgram");
 
3073
client\.on("message", function (msg, rinfo) {
 
3074
  console\.log("got: " + msg + " from " + rinfo\.address);
 
3075
});
 
3076
client\.on("listening", function () {
 
3077
  console\.log("client listening " + client\.address()\.address);
 
3078
  client\.send(message, 0, message\.length, serverPath);
 
3079
});
 
3080
client\.bind(clientPath);
 
3081
.
 
3082
.fi
 
3083
.
 
3084
.IP "" 0
 
3085
.
 
3086
.SS "dgram\.bind(port, [address])"
 
3087
For UDP sockets, listen for datagrams on a named \fBport\fR and optional \fBaddress\fR\|\.  If \fBaddress\fR is not specified, the OS will try to listen on all addresses\.
 
3088
.
 
3089
.P
 
3090
Example of a UDP server listening on port 41234:
 
3091
.
 
3092
.IP "" 4
 
3093
.
 
3094
.nf
 
3095
var dgram = require("dgram");
 
3096
var server = dgram\.createSocket("udp4");
 
3097
var messageToSend = new Buffer("A message to send");
 
3098
server\.on("message", function (msg, rinfo) {
 
3099
  console\.log("server got: " + msg + " from " +
 
3100
    rinfo\.address + ":" + rinfo\.port);
 
3101
});
 
3102
server\.on("listening", function () {
 
3103
  var address = server\.address();
 
3104
  console\.log("server listening " +
 
3105
      address\.address + ":" + address\.port);
 
3106
});
 
3107
server\.bind(41234);
 
3108
// server listening 0\.0\.0\.0:41234
 
3109
.
 
3110
.fi
 
3111
.
 
3112
.IP "" 0
 
3113
.
 
3114
.SS "dgram\.close()"
 
3115
Close the underlying socket and stop listening for data on it\.  UDP sockets 
 
3116
automatically listen for messages, even if they did not call \fBbind()\fR\|\.
 
3117
.
 
3118
.SS "dgram\.address()"
 
3119
Returns an object containing the address information for a socket\.  For UDP sockets, 
 
3120
this object will contain \fBaddress\fR and \fBport\fR\|\.  For Unix domain sockets, it will contain
 
3121
only \fBaddress\fR\|\.
 
3122
.
 
3123
.SS "dgram\.setBroadcast(flag)"
 
3124
Sets or clears the \fBSO_BROADCAST\fR socket option\.  When this option is set, UDP packets
 
3125
may be sent to a local interface\'s broadcast address\.
 
3126
.
 
3127
.SS "dgram\.setTTL(ttl)"
 
3128
Sets the \fBIP_TTL\fR socket option\.  TTL stands for "Time to Live," but in this context it
 
3129
specifies the number of IP hops that a packet is allowed to go through\.  Each router or 
 
3130
gateway that forwards a packet decrements the TTL\.  If the TTL is decremented to 0 by a
 
3131
router, it will not be forwarded\.  Changing TTL values is typically done for network 
 
3132
probes or when multicasting\.
 
3133
.
 
3134
.P
 
3135
The argument to \fBsetTTL()\fR is a number of hops between 1 and 255\.  The default on most
 
3136
systems is 64\.
2787
3137
.
2788
3138
.SH "Assert"
2789
3139
This module is used for writing unit tests for your applications, you can
2790
 
access it with \fBrequire('assert')\fR.
2791
 
.
2792
 
.SS "assert.fail(actual, expected, message, operator)"
2793
 
Tests if \fBactual\fR is equal to \fBexpected\fR using the operator provided.
2794
 
.
2795
 
.SS "assert.ok(value, message)"
2796
 
Tests if value is a \fBtrue\fR value, it is equivalent to \fBassert.equal(true, value, message);\fR
2797
 
.
2798
 
.SS "assert.equal(actual, expected, message)"
2799
 
Tests shallow, coercive equality with the equal comparison operator ( \fB==\fR ).
2800
 
.
2801
 
.SS "assert.notEqual(actual, expected, message)"
2802
 
Tests shallow, coercive non\-equality with the not equal comparison operator ( \fB!=\fR ).
2803
 
.
2804
 
.SS "assert.deepEqual(actual, expected, message)"
2805
 
Tests for deep equality.
2806
 
.
2807
 
.SS "assert.notDeepEqual(actual, expected, message)"
2808
 
Tests for any deep inequality.
2809
 
.
2810
 
.SS "assert.strictEqual(actual, expected, message)"
2811
 
Tests strict equality, as determined by the strict equality operator ( \fB===\fR )
2812
 
.
2813
 
.SS "assert.notStrictEqual(actual, expected, message)"
2814
 
Tests strict non\-equality, as determined by the strict not equal operator ( \fB!==\fR )
2815
 
.
2816
 
.SS "assert.throws(block, error, message)"
2817
 
Expects \fBblock\fR to throw an error.
2818
 
.
2819
 
.SS "assert.doesNotThrow(block, error, message)"
2820
 
Expects \fBblock\fR not to throw an error.
2821
 
.
2822
 
.SS "assert.ifError(value)"
2823
 
Tests if value is not a false value, throws if it is a true value. Useful when testing the first argument, \fBerror\fR in callbacks.
 
3140
access it with \fBrequire(\'assert\')\fR\|\.
 
3141
.
 
3142
.SS "assert\.fail(actual, expected, message, operator)"
 
3143
Tests if \fBactual\fR is equal to \fBexpected\fR using the operator provided\.
 
3144
.
 
3145
.SS "assert\.ok(value, [message])"
 
3146
Tests if value is a \fBtrue\fR value, it is equivalent to \fBassert\.equal(true, value, message);\fR
 
3147
.
 
3148
.SS "assert\.equal(actual, expected, [message])"
 
3149
Tests shallow, coercive equality with the equal comparison operator ( \fB==\fR )\. 
 
3150
.
 
3151
.SS "assert\.notEqual(actual, expected, [message])"
 
3152
Tests shallow, coercive non\-equality with the not equal comparison operator ( \fB!=\fR )\.
 
3153
.
 
3154
.SS "assert\.deepEqual(actual, expected, [message])"
 
3155
Tests for deep equality\.
 
3156
.
 
3157
.SS "assert\.notDeepEqual(actual, expected, [message])"
 
3158
Tests for any deep inequality\. 
 
3159
.
 
3160
.SS "assert\.strictEqual(actual, expected, [message])"
 
3161
Tests strict equality, as determined by the strict equality operator ( \fB===\fR ) 
 
3162
.
 
3163
.SS "assert\.notStrictEqual(actual, expected, [message])"
 
3164
Tests strict non\-equality, as determined by the strict not equal operator ( \fB!==\fR ) 
 
3165
.
 
3166
.SS "assert\.throws(block, [error], [message])"
 
3167
Expects \fBblock\fR to throw an error\.
 
3168
.
 
3169
.SS "assert\.doesNotThrow(block, [error], [message])"
 
3170
Expects \fBblock\fR not to throw an error\.
 
3171
.
 
3172
.SS "assert\.ifError(value)"
 
3173
Tests if value is not a false value, throws if it is a true value\. Useful when testing the first argument, \fBerror\fR in callbacks\.
2824
3174
.
2825
3175
.SH "Path"
2826
 
This module contains utilities for dealing with file paths.  Use\fBrequire('path')\fR to use it.  It provides the following methods:
2827
 
.
2828
 
.SS "path.join(/<em> path1, path2, ... </em>/)"
2829
 
Join all arguments together and resolve the resulting path.  Example:
2830
 
.
2831
 
.IP "" 4
2832
 
.
2833
 
.nf
2834
 
node> require('path').join(
2835
 
...   '/foo', 'bar', 'baz/asdf', 'quux', '..')
2836
 
'/foo/bar/baz/asdf'
2837
 
.
2838
 
.fi
2839
 
.
2840
 
.IP "" 0
2841
 
.
2842
 
.SS "path.normalizeArray(arr)"
2843
 
Normalize an array of path parts, taking care of \fB'..'\fR and \fB'.'\fR parts.  Example:
2844
 
.
2845
 
.IP "" 4
2846
 
.
2847
 
.nf
2848
 
path.normalizeArray(['',
2849
 
  'foo', 'bar', 'baz', 'asdf', 'quux', '..'])
2850
 
// returns
2851
 
[ '', 'foo', 'bar', 'baz', 'asdf' ]
2852
 
.
2853
 
.fi
2854
 
.
2855
 
.IP "" 0
2856
 
.
2857
 
.SS "path.normalize(p)"
2858
 
Normalize a string path, taking care of \fB'..'\fR and \fB'.'\fR parts.  Example:
2859
 
.
2860
 
.IP "" 4
2861
 
.
2862
 
.nf
2863
 
path.normalize('/foo/bar/baz/asdf/quux/..')
2864
 
// returns
2865
 
'/foo/bar/baz/asdf'
2866
 
.
2867
 
.fi
2868
 
.
2869
 
.IP "" 0
2870
 
.
2871
 
.SS "path.dirname(p)"
2872
 
Return the directory name of a path.  Similar to the Unix \fBdirname\fR command.  Example:
2873
 
.
2874
 
.IP "" 4
2875
 
.
2876
 
.nf
2877
 
path.dirname('/foo/bar/baz/asdf/quux')
2878
 
// returns
2879
 
'/foo/bar/baz/asdf'
2880
 
.
2881
 
.fi
2882
 
.
2883
 
.IP "" 0
2884
 
.
2885
 
.SS "path.basename(p, ext)"
2886
 
Return the last portion of a path.  Similar to the Unix \fBbasename\fR command.  Example:
2887
 
.
2888
 
.IP "" 4
2889
 
.
2890
 
.nf
2891
 
path.basename('/foo/bar/baz/asdf/quux.html')
2892
 
// returns
2893
 
'quux.html'
2894
 
path.basename('/foo/bar/baz/asdf/quux.html', '.html')
2895
 
// returns
2896
 
'quux'
2897
 
.
2898
 
.fi
2899
 
.
2900
 
.IP "" 0
2901
 
.
2902
 
.SS "path.extname(p)"
2903
 
Return the extension of the path.  Everything after the last '.' in the last portion
2904
 
of the path.  If there is no '.' in the last portion of the path or the only '.' is
2905
 
the first character, then it returns an empty string.  Examples:
2906
 
.
2907
 
.IP "" 4
2908
 
.
2909
 
.nf
2910
 
path.extname('index.html')
2911
 
// returns
2912
 
'.html'
2913
 
path.extname('index')
2914
 
// returns
2915
 
''
2916
 
.
2917
 
.fi
2918
 
.
2919
 
.IP "" 0
2920
 
.
2921
 
.SS "path.exists(p, callback)"
2922
 
Test whether or not the given path exists.  Then, call the \fBcallback\fR argument with either true or false.  Example:
2923
 
.
2924
 
.IP "" 4
2925
 
.
2926
 
.nf
2927
 
path.exists('/etc/passwd', function (exists) {
2928
 
  sys.debug(exists ? "it's there" : "no passwd!");
 
3176
This module contains utilities for dealing with file paths\.  Use \fBrequire(\'path\')\fR to use it\.  It provides the following methods:
 
3177
.
 
3178
.SS "path\.join([path1], [path2], [\.\.\.])"
 
3179
Join all arguments together and resolve the resulting path\.
 
3180
.
 
3181
.P
 
3182
Example:
 
3183
.
 
3184
.IP "" 4
 
3185
.
 
3186
.nf
 
3187
node> require(\'path\')\.join(
 
3188
\|\.\.\.   \'/foo\', \'bar\', \'baz/asdf\', \'quux\', \'\.\.\')
 
3189
\'/foo/bar/baz/asdf\'
 
3190
.
 
3191
.fi
 
3192
.
 
3193
.IP "" 0
 
3194
.
 
3195
.SS "path\.normalizeArray(arr)"
 
3196
Normalize an array of path parts, taking care of \fB\'\.\.\'\fR and \fB\'\.\'\fR parts\.
 
3197
.
 
3198
.P
 
3199
Example:
 
3200
.
 
3201
.IP "" 4
 
3202
.
 
3203
.nf
 
3204
path\.normalizeArray([\'\', 
 
3205
  \'foo\', \'bar\', \'baz\', \'asdf\', \'quux\', \'\.\.\'])
 
3206
// returns
 
3207
[ \'\', \'foo\', \'bar\', \'baz\', \'asdf\' ]
 
3208
.
 
3209
.fi
 
3210
.
 
3211
.IP "" 0
 
3212
.
 
3213
.SS "path\.normalize(p)"
 
3214
Normalize a string path, taking care of \fB\'\.\.\'\fR and \fB\'\.\'\fR parts\.
 
3215
.
 
3216
.P
 
3217
Example:
 
3218
.
 
3219
.IP "" 4
 
3220
.
 
3221
.nf
 
3222
path\.normalize(\'/foo/bar/baz/asdf/quux/\.\.\')
 
3223
// returns
 
3224
\'/foo/bar/baz/asdf\'
 
3225
.
 
3226
.fi
 
3227
.
 
3228
.IP "" 0
 
3229
.
 
3230
.SS "path\.dirname(p)"
 
3231
Return the directory name of a path\.  Similar to the Unix \fBdirname\fR command\.
 
3232
.
 
3233
.P
 
3234
Example:
 
3235
.
 
3236
.IP "" 4
 
3237
.
 
3238
.nf
 
3239
path\.dirname(\'/foo/bar/baz/asdf/quux\')
 
3240
// returns
 
3241
\'/foo/bar/baz/asdf\'
 
3242
.
 
3243
.fi
 
3244
.
 
3245
.IP "" 0
 
3246
.
 
3247
.SS "path\.basename(p, [ext])"
 
3248
Return the last portion of a path\.  Similar to the Unix \fBbasename\fR command\.
 
3249
.
 
3250
.P
 
3251
Example:
 
3252
.
 
3253
.IP "" 4
 
3254
.
 
3255
.nf
 
3256
path\.basename(\'/foo/bar/baz/asdf/quux\.html\')
 
3257
// returns
 
3258
\'quux\.html\'
 
3259
path\.basename(\'/foo/bar/baz/asdf/quux\.html\', \'\.html\')
 
3260
// returns
 
3261
\'quux\'
 
3262
.
 
3263
.fi
 
3264
.
 
3265
.IP "" 0
 
3266
.
 
3267
.SS "path\.extname(p)"
 
3268
Return the extension of the path\.  Everything after the last \'\.\' in the last portion
 
3269
of the path\.  If there is no \'\.\' in the last portion of the path or the only \'\.\' is
 
3270
the first character, then it returns an empty string\.  Examples:
 
3271
.
 
3272
.IP "" 4
 
3273
.
 
3274
.nf
 
3275
path\.extname(\'index\.html\')
 
3276
// returns 
 
3277
\'\.html\'
 
3278
path\.extname(\'index\')
 
3279
// returns
 
3280
\'\'
 
3281
.
 
3282
.fi
 
3283
.
 
3284
.IP "" 0
 
3285
.
 
3286
.SS "path\.exists(p, [callback])"
 
3287
Test whether or not the given path exists\.  Then, call the \fBcallback\fR argument with either true or false\.  Example:
 
3288
.
 
3289
.IP "" 4
 
3290
.
 
3291
.nf
 
3292
path\.exists(\'/etc/passwd\', function (exists) {
 
3293
  sys\.debug(exists ? "it\'s there" : "no passwd!");
2929
3294
});
2930
3295
.
2931
3296
.fi
2933
3298
.IP "" 0
2934
3299
.
2935
3300
.SH "URL"
2936
 
This module has utilities for URL resolution and parsing.
2937
 
Call \fBrequire('url')\fR to use it.
 
3301
This module has utilities for URL resolution and parsing\.
 
3302
Call \fBrequire(\'url\')\fR to use it\.
2938
3303
.
2939
3304
.P
2940
3305
Parsed URL objects have some or all of the following fields, depending on
2941
 
whether or not they exist in the URL string. Any parts that are not in the URL
2942
 
string will not be in the parsed object. Examples are shown for the URL
 
3306
whether or not they exist in the URL string\. Any parts that are not in the URL
 
3307
string will not be in the parsed object\. Examples are shown for the URL
2943
3308
.
2944
3309
.P
2945
 
\fB'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'\fR
 
3310
\fB\'http://user:pass@host\.com:8080/p/a/t/h?query=string#hash\'\fR
2946
3311
.
2947
3312
.IP "\(bu" 4
2948
3313
\fBhref\fR
2949
3314
.
2950
3315
.IP
2951
 
The full URL that was originally parsed. Example:\fB'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'\fR
 
3316
The full URL that was originally parsed\. Example: \fB\'http://user:pass@host\.com:8080/p/a/t/h?query=string#hash\'\fR
2952
3317
.
2953
3318
.IP "\(bu" 4
2954
3319
\fBprotocol\fR
2955
3320
.
2956
3321
.IP
2957
 
The request protocol.  Example: \fB'http:'\fR
 
3322
The request protocol\.  Example: \fB\'http:\'\fR
2958
3323
.
2959
3324
.IP "\(bu" 4
2960
3325
\fBhost\fR
2961
3326
.
2962
3327
.IP
2963
 
The full host portion of the URL, including port and authentication information. Example:\fB'user:pass@host.com:8080'\fR
 
3328
The full host portion of the URL, including port and authentication information\. Example: \fB\'user:pass@host\.com:8080\'\fR
2964
3329
.
2965
3330
.IP "\(bu" 4
2966
3331
\fBauth\fR
2967
3332
.
2968
3333
.IP
2969
 
The authentication information portion of a URL.  Example: \fB'user:pass'\fR
 
3334
The authentication information portion of a URL\.  Example: \fB\'user:pass\'\fR
2970
3335
.
2971
3336
.IP "\(bu" 4
2972
3337
\fBhostname\fR
2973
3338
.
2974
3339
.IP
2975
 
Just the hostname portion of the host.  Example: \fB'host.com'\fR
 
3340
Just the hostname portion of the host\.  Example: \fB\'host\.com\'\fR
2976
3341
.
2977
3342
.IP "\(bu" 4
2978
3343
\fBport\fR
2979
3344
.
2980
3345
.IP
2981
 
The port number portion of the host.  Example: \fB'8080'\fR
 
3346
The port number portion of the host\.  Example: \fB\'8080\'\fR
2982
3347
.
2983
3348
.IP "\(bu" 4
2984
3349
\fBpathname\fR
2985
3350
.
2986
3351
.IP
2987
 
The path section of the URL, that comes after the host and before the query, including the initial slash if present.  Example: \fB'/p/a/t/h'\fR
 
3352
The path section of the URL, that comes after the host and before the query, including the initial slash if present\.  Example: \fB\'/p/a/t/h\'\fR
2988
3353
.
2989
3354
.IP "\(bu" 4
2990
3355
\fBsearch\fR
2991
3356
.
2992
3357
.IP
2993
 
The 'query string' portion of the URL, including the leading question mark. Example: \fB'?query=string'\fR
 
3358
The \'query string\' portion of the URL, including the leading question mark\. Example: \fB\'?query=string\'\fR
2994
3359
.
2995
3360
.IP "\(bu" 4
2996
3361
\fBquery\fR
2997
3362
.
2998
3363
.IP
2999
 
Either the 'params' portion of the query string, or a querystring\-parsed object. Example:\fB'query=string'\fR or \fB{'query':'string'}\fR
 
3364
Either the \'params\' portion of the query string, or a querystring\-parsed object\. Example: \fB\'query=string\'\fR or \fB{\'query\':\'string\'}\fR
3000
3365
.
3001
3366
.IP "\(bu" 4
3002
3367
\fBhash\fR
3003
3368
.
3004
3369
.IP
3005
 
The 'fragment' portion of the URL including the pound\-sign. Example: \fB'#hash'\fR
 
3370
The \'fragment\' portion of the URL including the pound\-sign\. Example: \fB\'#hash\'\fR
3006
3371
.
3007
3372
.IP "" 0
3008
3373
.
3009
3374
.P
3010
3375
The following methods are provided by the URL module:
3011
3376
.
3012
 
.SS "url.parse(urlStr, parseQueryString=false)"
3013
 
Take a URL string, and return an object.  Pass \fBtrue\fR as the second argument to also parse
3014
 
the query string using the \fBquerystring\fR module.
3015
 
.
3016
 
.SS "url.format(urlObj)"
3017
 
Take a parsed URL object, and return a formatted URL string.
3018
 
.
3019
 
.SS "url.resolve(from, to)"
3020
 
Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag.
 
3377
.SS "url\.parse(urlStr, parseQueryString=false)"
 
3378
Take a URL string, and return an object\.  Pass \fBtrue\fR as the second argument to also parse
 
3379
the query string using the \fBquerystring\fR module\.
 
3380
.
 
3381
.SS "url\.format(urlObj)"
 
3382
Take a parsed URL object, and return a formatted URL string\.
 
3383
.
 
3384
.SS "url\.resolve(from, to)"
 
3385
Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag\.
3021
3386
.
3022
3387
.SH "Query String"
3023
 
This module provides utilities for dealing with query strings.  It provides the following methods:
3024
 
.
3025
 
.SS "querystring.stringify(obj, sep='&', eq='=', munge=true)"
3026
 
Serialize an object to a query string.  Optionally override the default separator and assignment characters.
3027
 
Example:
3028
 
.
3029
 
.IP "" 4
3030
 
.
3031
 
.nf
3032
 
querystring.stringify({foo: 'bar'})
3033
 
// returns
3034
 
'foo=bar'
3035
 
querystring.stringify({foo: 'bar', baz: 'bob'}, ';', ':')
3036
 
// returns
3037
 
'foo:bar;baz:bob'
3038
 
.
3039
 
.fi
3040
 
.
3041
 
.IP "" 0
3042
 
.
3043
 
.P
3044
 
By default, this function will perform PHP/Rails\-style parameter mungeing for arrays and objects used as
3045
 
values within \fBobj\fR.
3046
 
Example:
3047
 
.
3048
 
.IP "" 4
3049
 
.
3050
 
.nf
3051
 
querystring.stringify({foo: 'bar', foo: 'baz', foo: 'boz'})
3052
 
// returns
3053
 
'foo[]=bar&foo[]=baz&foo[]=boz'
3054
 
querystring.stringify({foo: {bar: 'baz'}})
3055
 
// returns
3056
 
'foo[bar]=baz'
3057
 
.
3058
 
.fi
3059
 
.
3060
 
.IP "" 0
3061
 
.
3062
 
.P
3063
 
If you wish to disable the array mungeing (e.g. when generating parameters for a Java servlet), you
3064
 
can set the \fBmunge\fR argument to \fBfalse\fR.
3065
 
Example:
3066
 
.
3067
 
.IP "" 4
3068
 
.
3069
 
.nf
3070
 
querystring.stringify({foo: 'bar', foo: 'baz', foo: 'boz'}, '&', '=', false)
3071
 
// returns
3072
 
'foo=bar&foo=baz&foo=boz'
3073
 
.
3074
 
.fi
3075
 
.
3076
 
.IP "" 0
3077
 
.
3078
 
.P
3079
 
Note that when \fBmunge\fR is \fBfalse\fR, parameter names with object values will still be munged.
3080
 
.
3081
 
.SS "querystring.parse(str, sep='&', eq='=')"
3082
 
Deserialize a query string to an object.  Optionally override the default separator and assignment characters.
3083
 
.
3084
 
.IP "" 4
3085
 
.
3086
 
.nf
3087
 
querystring.parse('a=b&b=c')
3088
 
// returns
3089
 
{ 'a': 'b'
3090
 
, 'b': 'c'
 
3388
This module provides utilities for dealing with query strings\.  It provides the following methods:
 
3389
.
 
3390
.SS "querystring\.stringify(obj, sep=\'&amp;\', eq=\'=\', munge=true)"
 
3391
Serialize an object to a query string\.  Optionally override the default separator and assignment characters\.
 
3392
Example:
 
3393
.
 
3394
.IP "" 4
 
3395
.
 
3396
.nf
 
3397
querystring\.stringify({foo: \'bar\'})
 
3398
// returns
 
3399
\'foo=bar\'
 
3400
querystring\.stringify({foo: \'bar\', baz: \'bob\'}, \';\', \':\')
 
3401
// returns
 
3402
\'foo:bar;baz:bob\'
 
3403
.
 
3404
.fi
 
3405
.
 
3406
.IP "" 0
 
3407
.
 
3408
.P
 
3409
By default, this function will perform PHP/Rails\-style parameter munging for arrays and objects used as
 
3410
values within \fBobj\fR\|\.
 
3411
Example:
 
3412
.
 
3413
.IP "" 4
 
3414
.
 
3415
.nf
 
3416
querystring\.stringify({foo: [\'bar\', \'baz\', \'boz\']})
 
3417
// returns
 
3418
\'foo%5B%5D=bar&foo%5B%5D=baz&foo%5B%5D=boz\'
 
3419
querystring\.stringify({foo: {bar: \'baz\'}})
 
3420
// returns
 
3421
\'foo%5Bbar%5D=baz\'
 
3422
.
 
3423
.fi
 
3424
.
 
3425
.IP "" 0
 
3426
.
 
3427
.P
 
3428
If you wish to disable the array munging (e\.g\. when generating parameters for a Java servlet), you
 
3429
can set the \fBmunge\fR argument to \fBfalse\fR\|\.
 
3430
Example:
 
3431
.
 
3432
.IP "" 4
 
3433
.
 
3434
.nf
 
3435
querystring\.stringify({foo: [\'bar\', \'baz\', \'boz\']}, \'&\', \'=\', false)
 
3436
// returns
 
3437
\'foo=bar&foo=baz&foo=boz\'
 
3438
.
 
3439
.fi
 
3440
.
 
3441
.IP "" 0
 
3442
.
 
3443
.P
 
3444
Note that when \fBmunge\fR is \fBfalse\fR, parameter names with object values will still be munged\.
 
3445
.
 
3446
.SS "querystring\.parse(str, sep=\'&amp;\', eq=\'=\')"
 
3447
Deserialize a query string to an object\.  Optionally override the default separator and assignment characters\.
 
3448
.
 
3449
.IP "" 4
 
3450
.
 
3451
.nf
 
3452
querystring\.parse(\'a=b&b=c\')
 
3453
// returns
 
3454
{ \'a\': \'b\'
 
3455
, \'b\': \'c\'
3091
3456
}
3092
3457
.
3093
3458
.fi
3095
3460
.IP "" 0
3096
3461
.
3097
3462
.P
3098
 
This function can parse both munged and unmunged query strings (see \fBstringify\fR for details).
3099
 
.
3100
 
.SS "querystring.escape"
3101
 
The escape function used by \fBquerystring.stringify\fR, provided so that it could be overridden if necessary.
3102
 
.
3103
 
.SS "querystring.unescape"
3104
 
The unescape function used by \fBquerystring.parse\fR, provided so that it could be overridden if necessary.
 
3463
This function can parse both munged and unmunged query strings (see \fBstringify\fR for details)\.
 
3464
.
 
3465
.SS "querystring\.escape"
 
3466
The escape function used by \fBquerystring\.stringify\fR, provided so that it could be overridden if necessary\.
 
3467
.
 
3468
.SS "querystring\.unescape"
 
3469
The unescape function used by \fBquerystring\.parse\fR, provided so that it could be overridden if necessary\.
3105
3470
.
3106
3471
.SH "REPL"
3107
 
A Read\-Eval\-Print\-Loop is available both as a standalone program and easily
3108
 
includable in other programs.  REPL provides a way to interactively run
3109
 
JavaScript and see the results.  It can be used for debugging, testing, or
3110
 
just trying things out.
 
3472
A Read\-Eval\-Print\-Loop (REPL) is available both as a standalone program and easily
 
3473
includable in other programs\.  REPL provides a way to interactively run
 
3474
JavaScript and see the results\.  It can be used for debugging, testing, or
 
3475
just trying things out\.
3111
3476
.
3112
3477
.P
3113
 
The standalone REPL is called \fBnode\-repl\fR and is installed at \fB$PREFIX/bin/node\-repl\fR.
 
3478
By executing \fBnode\fR without any arguments from the command\-line you will be
 
3479
dropped into the REPL\. It has simplistic emacs line\-editing\.
3114
3480
.
3115
3481
.IP "" 4
3116
3482
.
3117
3483
.nf
3118
 
mjr:~$ /usr/local/bin/node\-repl
3119
 
Welcome to the Node.js REPL.
3120
 
Enter ECMAScript at the prompt.
3121
 
Tip 1: Use 'rlwrap node\-repl' for a better interface
3122
 
Tip 2: Type Control\-D to exit.
3123
 
Type '.help' for options.
 
3484
mjr:~$ node
 
3485
Type \'\.help\' for options\.
3124
3486
node> a = [ 1, 2, 3];
3125
3487
[ 1, 2, 3 ]
3126
 
node> a.forEach(function (v) {
3127
 
...   sys.puts(v);
3128
 
...   });
 
3488
node> a\.forEach(function (v) {
 
3489
\|\.\.\.   console\.log(v);
 
3490
\|\.\.\.   });
3129
3491
1
3130
3492
2
3131
3493
3
3134
3496
.
3135
3497
.IP "" 0
3136
3498
.
3137
 
.SS "repl.start(prompt, stream)"
3138
 
Starts a REPL with \fBprompt\fR as the prompt and \fBstream\fR for all I/O.  \fBprompt\fR
3139
 
is optional and defaults to \fBnode>\fR.  \fBstream\fR is optional and defaults to \fBprocess.openStdin()\fR.
3140
 
.
3141
 
.P
3142
 
Multiple REPLs may be started against the same running instance of node.  Each
3143
 
will share the same global object but will have unique I/O.
 
3499
.P
 
3500
For advanced line\-editors, start node with the environmental variable \fBNODE_NO_READLINE=1\fR\|\.
 
3501
This will start the REPL in canonical terminal settings which will allow you to use with \fBrlwrap\fR\|\.
 
3502
.
 
3503
.P
 
3504
For example, you could add this to your bashrc file:
 
3505
.
 
3506
.IP "" 4
 
3507
.
 
3508
.nf
 
3509
alias node="env NODE_NO_READLINE=1 rlwrap node"
 
3510
.
 
3511
.fi
 
3512
.
 
3513
.IP "" 0
 
3514
.
 
3515
.SS "repl\.start(prompt=\'node&gt; \', stream=process\.openStdin())"
 
3516
Starts a REPL with \fBprompt\fR as the prompt and \fBstream\fR for all I/O\.  \fBprompt\fR
 
3517
is optional and defaults to \fBnode> \fR\|\.  \fBstream\fR is optional and defaults to  \fBprocess\.openStdin()\fR\|\.
 
3518
.
 
3519
.P
 
3520
Multiple REPLs may be started against the same running instance of node\.  Each
 
3521
will share the same global object but will have unique I/O\.
3144
3522
.
3145
3523
.P
3146
3524
Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:
3148
3526
.IP "" 4
3149
3527
.
3150
3528
.nf
3151
 
var sys = require("sys"),
3152
 
    net = require("net"),
 
3529
var net = require("net"),
3153
3530
    repl = require("repl");
3154
3531
connections = 0;
3155
 
repl.start("node via stdin> ");
3156
 
net.createServer(function (socket) {
3157
 
  connections += 1;
3158
 
  repl.start("node via Unix socket> ", socket);
3159
 
}).listen("/tmp/node\-repl\-sock");
3160
 
net.createServer(function (socket) {
3161
 
  connections += 1;
3162
 
  repl.start("node via TCP socket> ", socket);
3163
 
}).listen(5001);
 
3532
repl\.start("node via stdin> ");
 
3533
net\.createServer(function (socket) {
 
3534
  connections += 1;
 
3535
  repl\.start("node via Unix socket> ", socket);
 
3536
})\.listen("/tmp/node\-repl\-sock");
 
3537
net\.createServer(function (socket) {
 
3538
  connections += 1;
 
3539
  repl\.start("node via TCP socket> ", socket);
 
3540
})\.listen(5001);
3164
3541
.
3165
3542
.fi
3166
3543
.
3167
3544
.IP "" 0
3168
3545
.
3169
3546
.P
3170
 
Running this program from the command line will start a REPL on stdin.  Other
3171
 
REPL clients may connect through the Unix socket or TCP socket. \fBtelnet\fR is useful
 
3547
Running this program from the command line will start a REPL on stdin\.  Other
 
3548
REPL clients may connect through the Unix socket or TCP socket\. \fBtelnet\fR is useful
3172
3549
for connecting to TCP sockets, and \fBsocat\fR can be used to connect to both Unix and
3173
 
TCP sockets.
3174
 
.
3175
 
.P
3176
 
By starting a REPL from a Unix socket\-based server instead of stdin, you can
3177
 
connect to a long\-running node process without restarting it.
3178
 
.
3179
 
.SS "readline support"
3180
 
Interactive command history for REPL is available from external programs like \fBrlwrap\fR
3181
 
or \fBsocat\fR.  These programs are available from many Unix package managers.
3182
 
.
3183
 
.P
3184
 
To start the standalone REPL with \fBrlwrap\fR:
3185
 
.
3186
 
.IP "" 4
3187
 
.
3188
 
.nf
3189
 
rlwrap node\-repl
3190
 
.
3191
 
.fi
3192
 
.
3193
 
.IP "" 0
3194
 
.
3195
 
.P
3196
 
It might be convenient to use this alias in your shell configuration:
3197
 
.
3198
 
.IP "" 4
3199
 
.
3200
 
.nf
3201
 
alias repl='rlwrap node\-repl'
3202
 
.
3203
 
.fi
3204
 
.
3205
 
.IP "" 0
3206
 
.
3207
 
.P
3208
 
Using \fBsocat\fR to connect to a Unix socket:
3209
 
.
3210
 
.IP "" 4
3211
 
.
3212
 
.nf
3213
 
socat READLINE UNIX\-CONNECT:/tmp/node\-repl\-sock
3214
 
.
3215
 
.fi
3216
 
.
3217
 
.IP "" 0
3218
 
.
3219
 
.P
3220
 
Using \fBsocat\fR to connect to a TCP socket on localhost:
3221
 
.
3222
 
.IP "" 4
3223
 
.
3224
 
.nf
3225
 
socat READLINE TCP\-CONNECT:localhost:5001
3226
 
.
3227
 
.fi
3228
 
.
3229
 
.IP "" 0
 
3550
TCP sockets\.
 
3551
.
 
3552
.P
 
3553
By starting a REPL from a Unix socket\-based server instead of stdin, you can 
 
3554
connect to a long\-running node process without restarting it\.
3230
3555
.
3231
3556
.SS "REPL Features"
3232
 
Inside the REPL, Control+D will exit.  Multi\-line expressions can be input.
 
3557
Inside the REPL, Control+D will exit\.  Multi\-line expressions can be input\.
3233
3558
.
3234
3559
.P
3235
 
The special variable \fB_\fR (underscore) contains the result of the last expression.
 
3560
The special variable \fB_\fR (underscore) contains the result of the last expression\.
3236
3561
.
3237
3562
.IP "" 4
3238
3563
.
3239
3564
.nf
3240
3565
node> [ "a", "b", "c" ]
3241
 
[ 'a', 'b', 'c' ]
3242
 
node> _.length
 
3566
[ \'a\', \'b\', \'c\' ]
 
3567
node> _\.length 
3243
3568
3
3244
3569
node> _ += 1
3245
3570
4
3249
3574
.IP "" 0
3250
3575
.
3251
3576
.P
3252
 
The REPL provides access to any variables in the global scope. You can expose a variable
3253
 
to the REPL explicitly by assigning it to the \fBscope\fR object associated with each \fBREPLServer\fR.  For example:
 
3577
The REPL provides access to any variables in the global scope\. You can expose a variable 
 
3578
to the REPL explicitly by assigning it to the \fBcontext\fR object associated with each \fBREPLServer\fR\|\.  For example:
3254
3579
.
3255
3580
.IP "" 4
3256
3581
.
3257
3582
.nf
3258
 
// repl_test.js
 
3583
// repl_test\.js
3259
3584
var repl = require("repl"),
3260
3585
    msg = "message";
3261
 
repl.start().scope.m = msg;
 
3586
repl\.start()\.context\.m = msg;
3262
3587
.
3263
3588
.fi
3264
3589
.
3265
3590
.IP "" 0
3266
3591
.
3267
3592
.P
3268
 
Things in the \fBscope\fR object appear as local within the REPL:
 
3593
Things in the \fBcontext\fR object appear as local within the REPL:
3269
3594
.
3270
3595
.IP "" 4
3271
3596
.
3272
3597
.nf
3273
 
mjr:~$ node repl_test.js
 
3598
mjr:~$ node repl_test\.js 
3274
3599
node> m
3275
 
'message'
 
3600
\'message\'
3276
3601
.
3277
3602
.fi
3278
3603
.
3282
3607
There are a few special REPL commands:
3283
3608
.
3284
3609
.IP "\(bu" 4
3285
 
\fB.break\fR \- While inputting a multi\-line expression, sometimes you get lost or just don't care
3286
 
about completing it.  \fB.break\fR will start over.
3287
 
.
3288
 
.IP "\(bu" 4
3289
 
\fB.clear\fR \- Resets the \fBscope\fR object to an empty object and clears any multi\-line expression.
3290
 
.
3291
 
.IP "\(bu" 4
3292
 
\fB.exit\fR \- Close the I/O stream, which will cause the REPL to exit.
3293
 
.
3294
 
.IP "\(bu" 4
3295
 
\fB.help\fR \- Show this list of special commands.
 
3610
\fB\|\.break\fR \- While inputting a multi\-line expression, sometimes you get lost or just don\'t care 
 
3611
about completing it\.  \fB\|\.break\fR will start over\.
 
3612
.
 
3613
.IP "\(bu" 4
 
3614
\fB\|\.clear\fR \- Resets the \fBcontext\fR object to an empty object and clears any multi\-line expression\.
 
3615
.
 
3616
.IP "\(bu" 4
 
3617
\fB\|\.exit\fR \- Close the I/O stream, which will cause the REPL to exit\.
 
3618
.
 
3619
.IP "\(bu" 4
 
3620
\fB\|\.help\fR \- Show this list of special commands\.
3296
3621
.
3297
3622
.IP "" 0
3298
3623
.
3299
3624
.SH "Modules"
3300
 
Node uses the CommonJS module system.
3301
 
.
3302
 
.P
3303
 
Node has a simple module loading system.  In Node, files and modules are in
3304
 
one\-to\-one correspondence.  As an example, \fBfoo.js\fR loads the module \fBcircle.js\fR in the same directory.
3305
 
.
3306
 
.P
3307
 
The contents of \fBfoo.js\fR:
 
3625
Node uses the CommonJS module system\.
 
3626
.
 
3627
.P
 
3628
Node has a simple module loading system\.  In Node, files and modules are in
 
3629
one\-to\-one correspondence\.  As an example, \fBfoo\.js\fR loads the module \fBcircle\.js\fR in the same directory\.
 
3630
.
 
3631
.P
 
3632
The contents of \fBfoo\.js\fR:
3308
3633
.
3309
3634
.IP "" 4
3310
3635
.
3311
3636
.nf
3312
 
var circle = require('./circle'),
3313
 
    sys = require('sys');
3314
 
sys.puts( 'The area of a circle of radius 4 is '
3315
 
  + circle.area(4));
 
3637
var circle = require(\'\./circle\');
 
3638
console\.log( \'The area of a circle of radius 4 is \'
 
3639
           + circle\.area(4));
3316
3640
.
3317
3641
.fi
3318
3642
.
3319
3643
.IP "" 0
3320
3644
.
3321
3645
.P
3322
 
The contents of \fBcircle.js\fR:
 
3646
The contents of \fBcircle\.js\fR:
3323
3647
.
3324
3648
.IP "" 4
3325
3649
.
3326
3650
.nf
3327
 
var PI = 3.14;
3328
 
exports.area = function (r) {
 
3651
var PI = 3\.14;
 
3652
exports\.area = function (r) {
3329
3653
  return PI * r * r;
3330
3654
};
3331
 
exports.circumference = function (r) {
 
3655
exports\.circumference = function (r) {
3332
3656
  return 2 * PI * r;
3333
3657
};
3334
3658
.
3337
3661
.IP "" 0
3338
3662
.
3339
3663
.P
3340
 
The module \fBcircle.js\fR has exported the functions \fBarea()\fR and \fBcircumference()\fR.  To export an object, add to the special \fBexports\fR
3341
 
object.  (Alternatively, one can use \fBthis\fR instead of \fBexports\fR.) Variables
3342
 
local to the module will be private. In this example the variable \fBPI\fR is
3343
 
private to \fBcircle.js\fR. The function \fBputs()\fR comes from the module \fB'sys'\fR,
3344
 
which is a built\-in module. Modules which are not prefixed by \fB'./'\fR are
3345
 
built\-in module\-\-more about this later.
3346
 
.
3347
 
.P
3348
 
A module prefixed with \fB'./'\fR is relative to the file calling \fBrequire()\fR.
3349
 
That is, \fBcircle.js\fR must be in the same directory as \fBfoo.js\fR for \fBrequire('./circle')\fR to find it.
3350
 
.
3351
 
.P
3352
 
Without the leading \fB'./'\fR, like \fBrequire('assert')\fR the module is searched
3353
 
for in the \fBrequire.paths\fR array. \fBrequire.paths\fR on my system looks like
3354
 
this:
3355
 
.
3356
 
.P
3357
 
\fB[ '/home/ryan/.node_libraries' ]\fR
3358
 
.
3359
 
.P
3360
 
That is, when \fBrequire('assert')\fR is called Node looks for:
3361
 
.
3362
 
.IP "\(bu" 4
3363
 
1: \fB/home/ryan/.node_libraries/assert.js\fR
3364
 
.
3365
 
.IP "\(bu" 4
3366
 
2: \fB/home/ryan/.node_libraries/assert.node\fR
3367
 
.
3368
 
.IP "\(bu" 4
3369
 
3: \fB/home/ryan/.node_libraries/assert/index.js\fR
3370
 
.
3371
 
.IP "\(bu" 4
3372
 
4: \fB/home/ryan/.node_libraries/assert/index.node\fR
 
3664
The module \fBcircle\.js\fR has exported the functions \fBarea()\fR and \fBcircumference()\fR\|\.  To export an object, add to the special \fBexports\fR
 
3665
object\.  (Alternatively, one can use \fBthis\fR instead of \fBexports\fR\|\.) Variables
 
3666
local to the module will be private\. In this example the variable \fBPI\fR is
 
3667
private to \fBcircle\.js\fR\|\. The function \fBputs()\fR comes from the module \fB\'sys\'\fR,
 
3668
which is a built\-in module\. Modules which are not prefixed by \fB\'\./\'\fR are
 
3669
built\-in module\-\-more about this later\.
 
3670
.
 
3671
.P
 
3672
A module prefixed with \fB\'\./\'\fR is relative to the file calling \fBrequire()\fR\|\.
 
3673
That is, \fBcircle\.js\fR must be in the same directory as \fBfoo\.js\fR for \fBrequire(\'\./circle\')\fR to find it\.
 
3674
.
 
3675
.P
 
3676
Without the leading \fB\'\./\'\fR, like \fBrequire(\'assert\')\fR the module is searched
 
3677
for in the \fBrequire\.paths\fR array\. \fBrequire\.paths\fR on my system looks like
 
3678
this: 
 
3679
.
 
3680
.P
 
3681
\fB[ \'/home/ryan/\.node_libraries\' ]\fR
 
3682
.
 
3683
.P
 
3684
That is, when \fBrequire(\'assert\')\fR is called Node looks for: 
 
3685
.
 
3686
.IP "\(bu" 4
 
3687
1: \fB/home/ryan/\.node_libraries/assert\.js\fR
 
3688
.
 
3689
.IP "\(bu" 4
 
3690
2: \fB/home/ryan/\.node_libraries/assert\.node\fR
 
3691
.
 
3692
.IP "\(bu" 4
 
3693
3: \fB/home/ryan/\.node_libraries/assert/index\.js\fR
 
3694
.
 
3695
.IP "\(bu" 4
 
3696
4: \fB/home/ryan/\.node_libraries/assert/index\.node\fR
3373
3697
.
3374
3698
.IP "" 0
3375
3699
.
3376
3700
.P
3377
 
interrupting once a file is found. Files ending in \fB'.node'\fR are binary Addon
3378
 
Modules; see 'Addons' below. \fB'index.js'\fR allows one to package a module as
3379
 
a directory.
 
3701
interrupting once a file is found\. Files ending in \fB\'\.node\'\fR are binary Addon
 
3702
Modules; see \'Addons\' below\. \fB\'index\.js\'\fR allows one to package a module as
 
3703
a directory\.
3380
3704
.
3381
3705
.P
3382
 
\fBrequire.paths\fR can be modified at runtime by simply unshifting new
 
3706
\fBrequire\.paths\fR can be modified at runtime by simply unshifting new
3383
3707
paths onto it, or at startup with the \fBNODE_PATH\fR environmental
3384
 
variable (which should be a list of paths, colon separated).
 
3708
variable (which should be a list of paths, colon separated)\.
3385
3709
.
3386
3710
.SH "Addons"
3387
 
Addons are dynamically linked shared objects. They can provide glue to C and
3388
 
C++ libraries. The API (at the moment) is rather complex, involving
 
3711
Addons are dynamically linked shared objects\. They can provide glue to C and
 
3712
C++ libraries\. The API (at the moment) is rather complex, involving
3389
3713
knowledge of several libraries:
3390
3714
.
3391
3715
.IP "\(bu" 4
3392
 
V8 JavaScript, a C++ library. Used for interfacing with JavaScript:
3393
 
creating objects, calling functions, etc.  Documented mostly in the\fBv8.h\fR header file (\fBdeps/v8/include/v8.h\fR in the Node source tree).
 
3716
V8 JavaScript, a C++ library\. Used for interfacing with JavaScript:
 
3717
creating objects, calling functions, etc\.  Documented mostly in the \fBv8\.h\fR header file (\fBdeps/v8/include/v8\.h\fR in the Node source tree)\.
3394
3718
.
3395
3719
.IP "\(bu" 4
3396
 
libev, C event loop library. Anytime one needs to wait for a file
 
3720
libev, C event loop library\. Anytime one needs to wait for a file
3397
3721
descriptor to become readable, wait for a timer, or wait for a signal to
3398
 
received one will need to interface with libev.  That is, if you perform
3399
 
any I/O, libev will need to be used.  Node uses the \fBEV_DEFAULT\fR event
3400
 
loop.  Documentation can be found http:/cvs.schmorp.de/libev/ev.html[here].
3401
 
.
3402
 
.IP "\(bu" 4
3403
 
libeio, C thread pool library. Used to execute blocking POSIX system
3404
 
calls asynchronously. Mostly wrappers already exist for such calls, in\fBsrc/file.cc\fR so you will probably not need to use it. If you do need it,
3405
 
look at the header file \fBdeps/libeio/eio.h\fR.
3406
 
.
3407
 
.IP "\(bu" 4
3408
 
Internal Node libraries. Most importantly is the \fBnode::ObjectWrap\fR
3409
 
class which you will likely want to derive from.
3410
 
.
3411
 
.IP "\(bu" 4
3412
 
Others. Look in \fBdeps/\fR for what else is available.
 
3722
received one will need to interface with libev\.  That is, if you perform
 
3723
any I/O, libev will need to be used\.  Node uses the \fBEV_DEFAULT\fR event
 
3724
loop\.  Documentation can be found http:/cvs\.schmorp\.de/libev/ev\.html[here]\.
 
3725
.
 
3726
.IP "\(bu" 4
 
3727
libeio, C thread pool library\. Used to execute blocking POSIX system
 
3728
calls asynchronously\. Mostly wrappers already exist for such calls, in \fBsrc/file\.cc\fR so you will probably not need to use it\. If you do need it,
 
3729
look at the header file \fBdeps/libeio/eio\.h\fR\|\.
 
3730
.
 
3731
.IP "\(bu" 4
 
3732
Internal Node libraries\. Most importantly is the \fBnode::ObjectWrap\fR
 
3733
class which you will likely want to derive from\.
 
3734
.
 
3735
.IP "\(bu" 4
 
3736
Others\. Look in \fBdeps/\fR for what else is available\.
3413
3737
.
3414
3738
.IP "" 0
3415
3739
.
3416
3740
.P
3417
 
Node statically compiles all its dependencies into the executable. When
3418
 
compiling your module, you don't need to worry about linking to any of these
3419
 
libraries.
 
3741
Node statically compiles all its dependencies into the executable\. When
 
3742
compiling your module, you don\'t need to worry about linking to any of these
 
3743
libraries\.
3420
3744
.
3421
3745
.P
3422
 
To get started let's make a small Addon which does the following except in
 
3746
To get started let\'s make a small Addon which does the following except in
3423
3747
C++:
3424
3748
.
3425
3749
.IP "" 4
3426
3750
.
3427
3751
.nf
3428
 
exports.hello = 'world';
 
3752
exports\.hello = \'world\';
3429
3753
.
3430
3754
.fi
3431
3755
.
3432
3756
.IP "" 0
3433
3757
.
3434
3758
.P
3435
 
To get started we create a file \fBhello.cc\fR:
 
3759
To get started we create a file \fBhello\.cc\fR:
3436
3760
.
3437
3761
.IP "" 4
3438
3762
.
3439
3763
.nf
3440
 
#include <v8.h>
 
3764
#include <v8\.h>
3441
3765
using namespace v8;
3442
 
extern 'C' void
3443
 
init (Handle<Object> target)
 
3766
extern "C" void
 
3767
init (Handle<Object> target) 
3444
3768
{
3445
3769
  HandleScope scope;
3446
3770
  target\->Set(String::New("hello"), String::New("World"));
3451
3775
.IP "" 0
3452
3776
.
3453
3777
.P
3454
 
This source code needs to be built into \fBhello.node\fR, the binary Addon. To
 
3778
This source code needs to be built into \fBhello\.node\fR, the binary Addon\. To
3455
3779
do this we create a file called \fBwscript\fR which is python code and looks
3456
3780
like this:
3457
3781
.
3458
3782
.IP "" 4
3459
3783
.
3460
3784
.nf
3461
 
srcdir = '.'
3462
 
blddir = 'build'
3463
 
VERSION = '0.0.1'
 
3785
srcdir = \'\.\'
 
3786
blddir = \'build\'
 
3787
VERSION = \'0\.0\.1\'
3464
3788
def set_options(opt):
3465
 
  opt.tool_options('compiler_cxx')
 
3789
  opt\.tool_options(\'compiler_cxx\')
3466
3790
def configure(conf):
3467
 
  conf.check_tool('compiler_cxx')
3468
 
  conf.check_tool('node_addon')
 
3791
  conf\.check_tool(\'compiler_cxx\')
 
3792
  conf\.check_tool(\'node_addon\')
3469
3793
def build(bld):
3470
 
  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
3471
 
  obj.target = 'hello'
3472
 
  obj.source = 'hello.cc'
 
3794
  obj = bld\.new_task_gen(\'cxx\', \'shlib\', \'node_addon\')
 
3795
  obj\.target = \'hello\'
 
3796
  obj\.source = \'hello\.cc\'
3473
3797
.
3474
3798
.fi
3475
3799
.
3476
3800
.IP "" 0
3477
3801
.
3478
3802
.P
3479
 
Running \fBnode\-waf configure build\fR will create a file \fBbuild/default/hello.node\fR which is our Addon.
 
3803
Running \fBnode\-waf configure build\fR will create a file \fBbuild/default/hello\.node\fR which is our Addon\.
3480
3804
.
3481
3805
.P
3482
 
\fBnode\-waf\fR is just http://code.google.com/p/waf/[WAF], the python\-based build system. \fBnode\-waf\fR is
3483
 
provided for the ease of users.
 
3806
\fBnode\-waf\fR is just http://code\.google\.com/p/waf/[WAF], the python\-based build system\. \fBnode\-waf\fR is
 
3807
provided for the ease of users\.
3484
3808
.
3485
3809
.P
3486
3810
All Node addons must export a function called \fBinit\fR with this signature:
3488
3812
.IP "" 4
3489
3813
.
3490
3814
.nf
3491
 
extern 'C' void init (Handle<Object> target)
 
3815
extern \'C\' void init (Handle<Object> target)
3492
3816
.
3493
3817
.fi
3494
3818
.
3495
3819
.IP "" 0
3496
3820
.
3497
3821
.P
3498
 
For the moment, that is all the documentation on addons. Please see\fIhttp://github.com/ry/node_postgres\fR for a real example.
 
3822
For the moment, that is all the documentation on addons\. Please see \fIhttp://github\.com/ry/node_postgres\fR for a real example\.