mirrors/nodejs

Fork 0

mirror of https://github.com/nodejs/node.git synced 2024-11-29 23:16:30 +01:00

Timothy J Fontaine ffb718b5a3 doc: clarify process on exit safe usage

2013-12-31 14:48:20 -08:00

18 KiB

Raw Blame History

process

The process object is a global object and can be accessed from anywhere. It is an instance of EventEmitter.

Event: 'exit'

Emitted when the process is about to exit. There is no way to prevent the exiting of the event loop at this point, and once all exit listeners have finished running the process will exit. Therefore you must only perform synchronous operations in this handler. This is a good hook to perform checks on the module's state (like for unit tests). The callback takes one argument, the code the process is exiting with.

Example of listening for exit:

process.on('exit', function(code) {
  // do *NOT* do this
  setTimeout(function() {
    console.log('This will not run');
  }, 0);
  console.log('About to exit with code:', code);
});

Event: 'uncaughtException'

Emitted when an exception bubbles all the way back to the event loop. If a listener is added for this exception, the default action (which is to print a stack trace and exit) will not occur.

Example of listening for uncaughtException:

process.on('uncaughtException', function(err) {
  console.log('Caught exception: ' + err);
});

setTimeout(function() {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');

Note that uncaughtException is a very crude mechanism for exception handling and may be removed in the future.

Don't use it, use domains instead. If you do use it, restart your application after every unhandled exception!

Do not use it as the node.js equivalent of On Error Resume Next. An unhandled exception means your application - and by extension node.js itself - is in an undefined state. Blindly resuming means anything could happen.

Think of resuming as pulling the power cord when you are upgrading your system. Nine out of ten times nothing happens - but the 10th time, your system is bust.

You have been warned.

Signal Events

Emitted when the processes receives a signal. See sigaction(2) for a list of standard POSIX signal names such as SIGINT, SIGHUP, etc.

Example of listening for SIGINT:

// Start reading from stdin so we don't exit.
process.stdin.resume();

process.on('SIGINT', function() {
  console.log('Got SIGINT.  Press Control-D to exit.');
});

An easy way to send the SIGINT signal is with Control-C in most terminal programs.

Note:

SIGUSR1 is reserved by node.js to start the debugger. It's possible to install a listener but that won't stop the debugger from starting.
SIGTERM and SIGINT have default handlers on non-Windows platforms that resets the terminal mode before exiting with code 128 + signal number. If one of these signals has a listener installed, its default behaviour will be removed (node will no longer exit).
SIGPIPE is ignored by default, it can have a listener installed.
SIGHUP is generated on Windows when the console window is closed, and on other platforms under various similar conditions, see signal(7). It can have a listener installed, however node will be unconditionally terminated by Windows about 10 seconds later. On non-Windows platforms, the default behaviour of SIGHUP is to terminate node, but once a listener has been installed its default behaviour will be removed.
SIGTERM is not supported on Windows, it can be listened on.
SIGINT is supported on all platforms, and can usually be generated with CTRL+C (though this may be configurable). It is not generated when terminal raw mode is enabled.
SIGBREAK is delivered on Windows when CTRL+BREAK is pressed, on non-Windows platforms it can be listened on, but there is no way to send or generate it.
SIGWINCH is delivered when the console has been resized. On Windows, this will only happen on write to the console when the cursor is being moved, or when a readable tty is used in raw mode.
SIGKILL cannot have a listener installed, it will unconditionally terminate node on all platforms.
SIGSTOP cannot have a listener installed.

process.stdout

A Writable Stream to stdout.

Example: the definition of console.log

console.log = function(d) {
  process.stdout.write(d + '\n');
};

process.stderr and process.stdout are unlike other streams in Node in that writes to them are usually blocking. They are blocking in the case that they refer to regular files or TTY file descriptors. In the case they refer to pipes, they are non-blocking like other streams.

To check if Node is being run in a TTY context, read the isTTY property on process.stderr, process.stdout, or process.stdin:

$ node -p "Boolean(process.stdin.isTTY)"
true
$ echo "foo" | node -p "Boolean(process.stdin.isTTY)"
false

$ node -p "Boolean(process.stdout.isTTY)"
true
$ node -p "Boolean(process.stdout.isTTY)" | cat
false

See the tty docs for more information.

process.stderr

A writable stream to stderr.

process.stdin

A Readable Stream for stdin. The stdin stream is paused by default, so one must call process.stdin.resume() to read from it.

Example of opening standard input and listening for both events:

process.stdin.resume();
process.stdin.setEncoding('utf8');

process.stdin.on('data', function(chunk) {
  process.stdout.write('data: ' + chunk);
});

process.stdin.on('end', function() {
  process.stdout.write('end');
});

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.

// print process.argv
process.argv.forEach(function(val, index, array) {
  console.log(index + ': ' + val);
});

This will generate:

$ node process-2.js one two=three four
0: node
1: /Users/mjr/work/node/process-2.js
2: one
3: two=three
4: four

process.execPath

This is the absolute pathname of the executable that started the process.

Example:

/usr/local/bin/node

process.execArgv

This is the set of node-specific command line options from the executable that started the process. These options do not show up in process.argv, and do not include the node executable, the name of the script, or any options following the script name. These options are useful in order to spawn child processes with the same execution environment as the parent.

Example:

$ node --harmony script.js --version

results in process.execArgv:

['--harmony']

and process.argv:

['/usr/local/bin/node', 'script.js', '--version']

process.abort()

This causes node to emit an abort. This will cause node to exit and generate a core file.

process.chdir(directory)

Changes the current working directory of the process or throws an exception if that fails.

console.log('Starting directory: ' + process.cwd());
try {
  process.chdir('/tmp');
  console.log('New directory: ' + process.cwd());
}
catch (err) {
  console.log('chdir: ' + err);
}

process.cwd()

Returns the current working directory of the process.

console.log('Current directory: ' + process.cwd());

process.env

An object containing the user environment. See environ(7).

process.exit([code])

Ends the process with the specified code. If omitted, exit uses the 'success' code 0.

To exit with a 'failure' code:

process.exit(1);

The shell that executed node should see the exit code as 1.