lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Improve documentation.

v0.7.4-release
Matt Ranney 15 years ago
committed by Ryan Dahl
parent
40ea061c30
commit
7c77a56b4a
1 changed files with 234 additions and 100 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 330
      doc/api.markdown

330
doc/api.markdown
View File

@ -8,6 +8,7 @@ World":
var sys = require("sys"),
http = require("http");
http.createServer(function (request, response) {
response.writeHead(200, {
"Content-Type": "text/plain"
@ -15,6 +16,7 @@ World":
response.write("Hello World\n");
response.close();
}).listen(8000);
sys.puts("Server running at http://127.0.0.1:8000/");
To run the server, put the code into a file called `example.js` and execute
@ -25,6 +27,7 @@ it with the node program
All of the examples in the documentation can be run similarly.
## ENCODINGS
Node supports 3 string encodings. UTF-8 (`"utf8"`), ASCII (`"ascii"`), and
@ -55,15 +58,14 @@ object" section.
## PROCESS OBJECT
The `process` object is an instance of `EventEmitter` and has the following events:
- **`"exit"`** - `callback(code)`:
Made when the process exits. A listener on this event should not try to
perform I/O since the process will forcibly exit in less than a
microsecond. However, it is a good hook to perform constant time checks of
the module's state (like for unit tests).
The `process` object is a global object and can be accessed from anywhere.
It is an instance of `EventEmitter` and has the following events:
The parameter `code` is the integer exit code passed to `process.exit()`.
- **`"exit"`** - `callback()`:
Made when the process is about to exit.
This is a good hook to perform constant time checks of the module's state (like for unit tests).
The main event loop will no longer be run after the "exit" callback finishes, so timers may not
be scheduled.
- **`"uncaughtException"`** - `callback(exception)`:
Emitted when an exception bubbles all the way back to the event loop. If a
@ -74,6 +76,18 @@ The `process` object is an instance of `EventEmitter` and has the following even
Emitted when the processes receives a signal. See sigaction(2) for a list
of standard POSIX signal names such as SIGINT, SIGUSR1, etc.
Example of listening for `exit`:
var sys = require('sys');
process.addListener("exit", function () {
process.nextTick(function () {
sys.puts("This will not run");
});
sys.puts("About to exit.");
});
Example of listening for `uncaughtException`:
@ -101,7 +115,19 @@ Especially for server programs that are designed to stay running forever, `uncau
can be a useful safety mechanism.
### process.argv
Example of listening for `SIGINT`:
var sys = require("sys"),
stdin = process.openStdin();
process.addListener("SIGINT", function () {
sys.puts("Got SIGINT. Press Control-D to exit.");
});
An easy way to send the `SIGINT` signal is with `Control-C` in most terminal programs.
### process.argv, process.ARGV
An array containing the command line arguments. The first element will be 'node', the second element
will be the name of the JavaScript file. The next elements will be any additional command line arguments.
@ -122,96 +148,103 @@ This will generate:
3: two=three
4: four
### process.env
Note that `process.argv` and `process.ARGV` are equivalent.
An object containing the user environment. See environ(7).
// print process.env
var sys = require("sys");
### process.chdir(directory)
Object.getOwnPropertyNames(process.env).forEach(function (val, index, array) {
sys.puts(index + ": " + val + "=" + process.env[val]);
});
Changes the current working directory of the process or throws an exception if that fails.
var sys = require('sys');
### process.pid
sys.puts("Starting directory: " + process.cwd());
try {
process.chdir("/tmp");
sys.puts("New directory: " + process.cwd());
}
catch (err) {
sys.puts("chdir: " + err);
}
The PID of the process.
require("sys").puts("This process is pid " + process.pid);
### process.compile(code, filename)
Similar to `eval` except that you can specify a `filename` for better
error reporting and the `code` cannot see the local scope. The value of `filename`
will be used as a filename if a stack trace is generated by the compiled code.
### process.platform
Example of using `process.compile` and `eval` to run the same code:
What platform you're running on. `"linux2"`, `"darwin"`, etc.
var sys = require("sys"),
localVar = 123,
compiled, evaled;
require("sys").puts("This platform is " + process.platform);
compiled = process.compile("localVar = 1;", "myfile.js");
sys.puts("localVar: " + localVar + ", compiled: " + compiled);
evaled = eval("localVar = 1;");
sys.puts("localVar: " + localVar + ", evaled: " + evaled);
// localVar: 123, compiled: 1
// localVar: 1, evaled: 1
### process.memoryUsage()
`process.compile` does not have access to the local scope, so `localVar` is unchanged.
`eval` does have access to the local scope, so `localVar` is changed.
Returns an object describing the memory usage of the Node process.
See also: `process.evalcx`
var sys = require("sys");
sys.puts(sys.inspect(process.memoryUsage()));
### process.cwd()
This will generate:
Returns the current working directory of the process.
{ rss: 4935680
, vsize: 41893888
, heapTotal: 1826816
, heapUsed: 650472
}
require('sys').puts("Current directory: " + process.cwd());
`heapTotal` and `heapUsed` refer to V8's memory usage.
### process.nextTick(callback)
### process.env, process.ENV
On the next loop around the event loop call this callback.
This is *not* a simple alias to `setTimeout(fn, 0)`, it's much more
efficient.
An object containing the user environment. See environ(7).
// print process.env
var sys = require("sys");
process.nextTick(function () {
sys.puts("nextTick callback");
Object.getOwnPropertyNames(process.env).forEach(function (val, index, array) {
sys.puts(index + ": " + val + "=" + process.env[val]);
});
Note that `process.env` and `process.ENV` are equivalent.
### process.exit(code=0)
Ends the process with the specified code. By default it exits with the
success code 0.
To exit with
### process.evalcx(code, sandbox, filename)
process.exit(1);
Similar to `eval` and `process.compile`. `process.evalcx` compiles `code` to run in `sandbox`
as if it were loaded from `filename`. The object `sandbox` will be used as the global object for
`code`. `sandbox` and `filename` are optional.
The shell that executed node should see the exit code as 1.
var sys = require("sys"),
sandbox = {
animal: "cat",
count: 2
};
process.evalcx('count += 1; name = "kitty"', sandbox, "myfile.js");
sys.puts(sys.inspect(sandbox));
### process.cwd()
Note that running untrusted code is a tricky business requiring great care. To prevent accidental
global variable leakage, `process.evalcx` is quite useful, but to safely run untrusted code, many more steps
must be taken.
Returns the current working directory of the process.
require('sys').puts("Current directory: " + process.cwd());
### process.exit(code)
### process.getuid(), process.setuid(id)
Ends the process with the specified `code`. If omitted, exit uses the
"success" code `0`.
Gets/sets the user identity of the process. (See setuid(2).) This is the numerical userid, not the username.
To exit with a "failure" code:
var sys = require('sys');
process.exit(1);
sys.puts("Current uid: " + process.getuid());
try {
process.setuid(501);
sys.puts("New uid: " + process.getuid());
}
catch (err) {
sys.puts("Failed to set uid: " + err);
}
The shell that executed node should see the exit code as 1.
### process.getgid(), process.setgid(id)
@ -230,22 +263,102 @@ Gets/sets the group identity of the process. (See setgid(2).) This is the numer
}
### process.chdir(directory)
### process.getuid(), process.setuid(id)
Changes the current working directory of the process or throws an exception if that fails.
Gets/sets the user identity of the process. (See setuid(2).) This is the numerical userid, not the username.
var sys = require('sys');
sys.puts("Starting directory: " + process.cwd());
sys.puts("Current uid: " + process.getuid());
try {
process.chdir("/tmp");
sys.puts("New directory: " + process.cwd());
process.setuid(501);
sys.puts("New uid: " + process.getuid());
}
catch (err) {
sys.puts("chdir: " + err);
sys.puts("Failed to set uid: " + err);
}
### process.installPrefix
A compiled-in property that exposes `NODE_PREFIX`.
require("sys").puts("Install prefix: " + process.installPrefix);
### process.kill(pid, signal)
Send a signal to a process. `pid` is the process id and `signal` is the
string describing the signal to send. Signal names are strings like
"SIGINT" or "SIGUSR1". If omitted, the signal will be "SIGINT".
See kill(2) for more information.
Note that just because the name of this function is `process.kill`, it is
really just a signal sender, like the `kill` system call. The signal sent
may do something other than kill the target process.
Example of sending a signal to yourself:
var sys = require("sys");
process.addListener("SIGHUP", function () {
sys.puts("Got SIGHUP signal.");
});
setTimeout(function () {
sys.puts("Exiting.");
process.exit(0);
}, 100);
process.kill(process.pid, "SIGHUP");
### process.pid
The PID of the process.
require("sys").puts("This process is pid " + process.pid);
### process.platform
What platform you're running on. `"linux2"`, `"darwin"`, etc.
require("sys").puts("This platform is " + process.platform);
### process.memoryUsage()
Returns an object describing the memory usage of the Node process.
var sys = require("sys");
sys.puts(sys.inspect(process.memoryUsage()));
This will generate:
{ rss: 4935680
, vsize: 41893888
, heapTotal: 1826816
, heapUsed: 650472
}
`heapTotal` and `heapUsed` refer to V8's memory usage.
### process.nextTick(callback)
On the next loop around the event loop call this callback.
This is *not* a simple alias to `setTimeout(fn, 0)`, it's much more
efficient.
var sys = require("sys");
process.nextTick(function () {
sys.puts("nextTick callback");
});
### process.umask(mask)
Sets or read the process's file mode creation mask. Child processes inherit
@ -260,42 +373,45 @@ given, otherwise returns the current mask.
sys.puts("Changed umask from: " + oldmask + " to " + newmask);
### process.kill(pid, signal="SIGTERM")
Send a signal to a process. `pid` is the process id and `signal` is the
signal to send; for example, "SIGINT" or "SIGUSR1". See kill(2) for more
information.
### process.compile(source, scriptOrigin)
Similar to `eval()` except that you can specify a `scriptOrigin` for better
error reporting and the `code` cannot see the local scope.
## SYSTEM MODULE
These functions are in the module `"sys"`. Use `require("sys")` to access
them.
### puts(string)
Outputs `string` and a trailing new-line to `stdout`.
require("sys").puts("String with a newline");
### print(string)
Like `puts()` but without the trailing new-line.
require("sys").print("String with no newline");
### debug(string)
A synchronous output function. Will block the process and
output `string` immediately to `stdout`.
output `string` immediately to `stderr`.
require("sys").debug("message on stderr");
### log(string)
Output with timestamp.
Output with timestamp on `stdout`.
require("sys").log("Timestmaped message.");
### inspect(object, showHidden, depth)
Return a string representation of `object`. (For debugging.)
Return a string representation of `object`, which is useful for debugging.
If `showHidden` is `true`, then the object's non-enumerable properties will be
shown too.
@ -306,6 +422,14 @@ formatting the object. This is useful for inspecting large complicated objects.
The default is to only recurse twice. To make it recurse indefinitely, pass
in `null` for `depth`.
Example of inspecting all properties of the `sys` object:
var sys = require("sys");
sys.puts(sys.inspect(sys, true, null));
## EVENTS
Many objects in Node emit events: a TCP server emits an event each time
@ -318,6 +442,7 @@ Events are represented by a camel-cased string. Here are some examples:
Functions can be then be attached to objects, to be executed when an event
is emitted. These functions are called _listeners_.
### events.EventEmitter
`require("events")` to access the events module.
@ -325,8 +450,9 @@ is emitted. These functions are called _listeners_.
All EventEmitters emit the event `"newListener"` when new listeners are
added.
- **`"newListener"`** - `callback(event, listener)`:
This event is made any time someone adds a new listener.
- **`"newListener"`** - `callback(event, listener)`:
This event is made any time someone adds a new listener.
### emitter.addListener(event, listener)
@ -336,55 +462,63 @@ Adds a listener to the end of the listeners array for the specified event.
sys.puts("someone connected!");
});
### emitter.removeListener(event, listener)
Remove a listener from the listener array for the specified event.
**Caution**: changes array indices in the listener array behind the listener.
### emitter.removeAllListeners(event)
Removes all listeners from the listener array for the specified event.
### emitter.listeners(event)
Returns an array of listeners for the specified event. This array can be
manipulated, e.g. to remove listeners.
### emitter.emit(event, arg1, arg2, ...)
Execute each of the listeners in order with the supplied arguments.
## STANDARD I/O
Standard I/O is handled through a special object `process.stdio`. `stdout` and
`stdin` are fully non-blocking (even when piping to files). `stderr` is
synchronous.
Writing data to standard output is typically done with the output functions in the `sys` module.
- **`"data"`** - `callback(data)`:
Made when stdin has received a chunk of data. Depending on the encoding that
stdin was opened with, `data` will be a string. This event will only be
emited after `process.stdio.open()` has been called.
The underlying `net.Stream` object associated with `stdout` and `stdin` is available via `process.stdout`
and `process.stdin`. To read from standard input, it must first be opened. See below.
- **`"close"`** - `callback()`:
Made when stdin has been closed.
### process.stdio.open(encoding="utf8")
### process.openStdin()
Open stdin. The program will not exit until `process.stdio.close()` has been
Open stdin. The program will not exit until `process.stdin.close()` has been
called or the `"close"` event has been emitted.
### process.stdio.write(data)
- **`"data"`** - `callback(data)`:
Emitted when stdin has received a chunk of data.
- **`"close"`** - `callback()`:
Emitted when stdin has been closed.
Write data to stdout.
Example of opening standard input and listening for both events:
### process.stdio.writeError(data)
var sys = require("sys"),
stdin = process.openStdin();
Write data to stderr. Synchronous.
stdin.addListener("data", function (chunk) {
sys.print("data: " + chunk);
});
### process.stdio.close()
stdin.addListener("end", function () {
sys.puts("end");
});
Close stdin.
## MODULES

Write Preview
Loading…
Cancel
Save