diff --git a/doc/api/process.md b/doc/api/process.md index b0e85746cf3548..95602d07649d71 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -2,97 +2,131 @@ -The `process` object is a global object and can be accessed from anywhere. -It is an instance of [`EventEmitter`][]. +The `process` object is a `global` that provides information about, and control +over, the current Node.js process. As a global, it is always available to +Node.js applications without using `require()`. -## Event: 'beforeExit' +## Process Events + +The `process` object is an instance of [`EventEmitter`][]. + +### Event: 'beforeExit' -This event is emitted when Node.js empties its event loop and has nothing else -to schedule. Normally, Node.js exits when there is no work scheduled, but a -listener for `'beforeExit'` can make asynchronous calls, and cause Node.js to +The `'beforeExit'` event is emitted when Node.js empties its event loop and has +no additional work to schedule. Normally, the Node.js process will exit when +there is no work scheduled, but a listener registered on the `'beforeExit'` +event can make asynchronous calls, and thereby cause the Node.js process to continue. -`'beforeExit'` is not emitted for conditions causing explicit termination, such -as [`process.exit()`][] or uncaught exceptions, and should not be used as an -alternative to the `'exit'` event unless the intention is to schedule more work. +The listener callback function is invoked with the value of +[`process.exitCode`][] passed as the only argument. + +The `'beforeExit'` event is *not* emitted for conditions causing explicit +termination, such as calling [`process.exit()`][] or uncaught exceptions. + +The `'beforeExit'` should *not* be used as an alternative to the `'exit'` event +unless the intention is to schedule additional work. -## Event: 'disconnect' +### Event: 'disconnect' -If process is spawned with an IPC channel, `'disconnect'` will be emitted when -IPC channel is closed. Read more in [child_process `'disconnect'` event][] doc. +If the Node.js process is spawned with an IPC channel (see the [Child Process][] +and [Cluster][] documentation), the `'disconnect'` event will be emitted when +the IPC channel is closed. -## Event: 'exit' +### 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. +The `'exit'` event is emitted when the Node.js process is about to exit as a +result of either: + +* The `process.exit()` method being called explicitly; +* The Node.js event loop no longer having any additional work to perform. + +There is no way to prevent the exiting of the event loop at this point, and once +all `'exit'` listeners have finished running the Node.js process will terminate. + +The listener callback function is invoked with the exit code specified either +by the [`process.exitCode`][] property, or the `exitCode` argument passed to the +[`process.exit()`] method, as the only argument. -This event is only emitted when Node.js exits explicitly by process.exit() or -implicitly by the event loop draining. +For example: + +```js +process.on('exit', (code) => { + console.log(`About to exit with code: ${code}`); +}); +``` -Example of listening for `'exit'`: +Listener functions **must** only perform **synchronous** operations. The Node.js +process will exit immediately after calling the `'exit'` event listeners +causing any additional work still queued in the event loop to be abandoned. +In the following example, for instance, the timeout will never occur: ```js process.on('exit', (code) => { - // do *NOT* do this setTimeout(() => { console.log('This will not run'); }, 0); - console.log('About to exit with code:', code); }); ``` -## Event: 'message' +### Event: 'message' +If the Node.js process is spawned with an IPC channel (see the [Child Process][] +and [Cluster][] documentation), the `'message'` event is emitted whenever a +message sent by a parent process using [`childprocess.send()`][] is received by +the child process. + +The listener callback is invoked with the following arguments: * `message` {Object} a parsed JSON object or primitive value * `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or undefined. -Messages sent by [`ChildProcess.send()`][] are obtained using the `'message'` -event on the child's process object. -## Event: 'rejectionHandled' +### Event: 'rejectionHandled' -Emitted whenever a Promise was rejected and an error handler was attached to it -(for example with [`promise.catch()`][]) later than after an event loop turn. This event -is emitted with the following arguments: +The `'rejectionHandled'` event is emitted whenever a `Promise` has been rejected +and an error handler was attached to it (using [`promise.catch()`][], for +example) later than one turn of the Node.js event loop. + +The listener callback is invoked with a reference to the rejected `Promise` as +the only argument. - - `p` the promise that was previously emitted in an `'unhandledRejection'` - event, but which has now gained a rejection handler. +The `Promise` object would have previously been emitted in an +`'unhandledRejection'` event, but during the course of processing gained a +rejection handler. -There is no notion of a top level for a promise chain at which rejections can -always be handled. Being inherently asynchronous in nature, a promise rejection -can be handled at a future point in time — possibly much later than the -event loop turn it takes for the `'unhandledRejection'` event to be emitted. +There is no notion of a top level for a `Promise` chain at which rejections can +always be handled. Being inherently asynchronous in nature, a `Promise` +rejection can be handled at a future point in time — possibly much later than +the event loop turn it takes for the `'unhandledRejection'` event to be emitted. Another way of stating this is that, unlike in synchronous code where there is -an ever-growing list of unhandled exceptions, with promises there is a -growing-and-shrinking list of unhandled rejections. In synchronous code, the -`'uncaughtException'` event tells you when the list of unhandled exceptions -grows. And in asynchronous code, the `'unhandledRejection'` event tells you -when the list of unhandled rejections grows, while the `'rejectionHandled'` -event tells you when the list of unhandled rejections shrinks. +an ever-growing list of unhandled exceptions, with Promises there can be a +growing-and-shrinking list of unhandled rejections. + +In synchronous code, the `'uncaughtException'` event is emitted when the list of +unhandled exceptions grows. -For example using the rejection detection hooks in order to keep a map of all -the rejected promise reasons at a given time: +In asynchronous code, the `'unhandledRejection'` event is emitted when the list +of unhandled rejections grows, and the `'rejectionHandled'` event is emitted +when the list of unhandled rejections shrinks. + +For example: ```js const unhandledRejections = new Map(); @@ -104,22 +138,25 @@ process.on('rejectionHandled', (p) => { }); ``` -This map will grow and shrink over time, reflecting rejections that start -unhandled and then become handled. You could record the errors in some error -log, either periodically (probably best for long-running programs, allowing -you to clear the map, which in the case of a very buggy program could grow -indefinitely) or upon process exit (more convenient for scripts). +In this example, the `unhandledRejections` `Map` will grow and shrink over time, +reflecting rejections that start unhandled and then become handled. It is +possible to record such errors in an error log, either periodically (which is +likely best for long-running application) or upon process exit (which is likely +most convenient for scripts). -## Event: 'uncaughtException' +### Event: 'uncaughtException' The `'uncaughtException'` event is emitted when an exception bubbles all the way back to the event loop. By default, Node.js handles such exceptions by -printing the stack trace to stderr and exiting. Adding a handler for the +printing the stack trace to `stderr` and exiting. Adding a handler for the `'uncaughtException'` event overrides this default behavior. +The listener function is called with the `Error` object passed as the only +argument. + For example: ```js @@ -136,7 +173,7 @@ nonexistentFunc(); console.log('This will not run.'); ``` -### Warning: Using `'uncaughtException'` correctly +#### Warning: Using `'uncaughtException'` correctly Note that `'uncaughtException'` is a crude mechanism for exception handling intended to be used only as a last resort. The event *should not* be used as @@ -158,43 +195,40 @@ of allocated resources (e.g. file descriptors, handles, etc) before shutting down the process. It is not safe to resume normal operation after `'uncaughtException'`. -## Event: 'unhandledRejection' +### Event: 'unhandledRejection' -Emitted whenever a `Promise` is rejected and no error handler is attached to -the promise within a turn of the event loop. When programming with promises -exceptions are encapsulated as rejected promises. Such promises can be caught -and handled using [`promise.catch()`][] and rejections are propagated through -a promise chain. This event is useful for detecting and keeping track of -promises that were rejected whose rejections were not handled yet. This event -is emitted with the following arguments: +The `'unhandledRejection`' event is emitted whenever a `Promise` is rejected and +no error handler is attached to the promise within a turn of the event loop. +When programming with Promises, exceptions are encapsulated as "rejected +promises". Rejections can be caught and handled using [`promise.catch()`][] and +are propagated through a `Promise` chain. The `'unhandledRejection'` event is +useful for detecting and keeping track of promises that were rejected whose +rejections have not yet been handled. - - `reason` the object with which the promise was rejected (usually an - [`Error`][] instance). - - `p` the promise that was rejected. +The listener function is called with the following arguments: -Here is an example that logs every unhandled rejection to the console +* `reason` {Error|any} The object with which the promise was rejected + (typically an [`Error`][] objet). +* `p` the `Promise` that was rejected. + +For example: ```js process.on('unhandledRejection', (reason, p) => { console.log("Unhandled Rejection at: Promise ", p, " reason: ", reason); // application specific logging, throwing an error, or other logic here }); -``` -For example, here is a rejection that will trigger the `'unhandledRejection'` -event: - -```js somePromise.then((res) => { return reportToUser(JSON.pasre(res)); // note the typo (`pasre`) }); // no `.catch` or `.then` ``` -Here is an example of a coding pattern that will also trigger -`'unhandledRejection'`: +The following will also trigger the `'unhandledRejection'` event to be +emitted: ```js function SomeResource() { @@ -206,18 +240,19 @@ var resource = new SomeResource(); // no .catch or .then on resource.loaded for at least a turn ``` -In cases like this, you may not want to track the rejection as a developer -error like you would for other `'unhandledRejection'` events. To address -this, you can either attach a dummy [`.catch(() => { })`][`promise.catch()`] handler to -`resource.loaded`, preventing the `'unhandledRejection'` event from being -emitted, or you can use the [`'rejectionHandled'`][] event. +In this example case, it is possible to track the rejection as a developer error +as would typically be the case for other `'unhandledRejection'` events. To +address such failures, a non-operational +[`.catch(() => { })`][`promise.catch()`] handler may be attached to +`resource.loaded`, which would prevent the `'unhandledRejection'` event from +being emitted. Alternatively, the [`'rejectionHandled'`][] event may be used. -## Event: 'warning' +### Event: 'warning' -Emitted whenever Node.js emits a process warning. +The `'warning'` event is emitted whenever Node.js emits a process warning. A process warning is similar to an error in that it describes exceptional conditions that are being brought to the user's attention. However, warnings @@ -225,14 +260,13 @@ are not part of the normal Node.js and JavaScript error handling flow. Node.js can emit warnings whenever it detects bad coding practices that could lead to sub-optimal application performance, bugs or security vulnerabilities. -The event handler for `'warning'` events is called with a single `warning` -argument whose value is an `Error` object. There are three key properties that -describe the warning: +The listener function is called with a single `warning` argument whose value is +an `Error` object. There are three key properties that describe the warning: -* `name` - The name of the warning (currently `Warning` by default). -* `message` - A system-provided description of the warning. -* `stack` - A stack trace to the location in the code where the warning was - issued. +* `name` {String} The name of the warning (currently `Warning` by default). +* `message` {String} A system-provided description of the warning. +* `stack` {String} A stack trace to the location in the code where the warning + was issued. ```js process.on('warning', (warning) => { @@ -273,7 +307,7 @@ $ node --no-warnings The `--trace-warnings` command-line option can be used to have the default console output for warnings include the full stack trace of the warning. -### Emitting custom warnings +#### Emitting custom warnings The [`process.emitWarning()`][process_emit_warning] method can be used to issue custom or application specific warnings. @@ -300,7 +334,7 @@ process.emitWarning(myWarning); // Prints: (node 12345) CustomWarning: Something happened! ``` -### Emitting custom deprecation warnings +#### Emitting custom deprecation warnings Custom deprecation warnings can be emitted by setting the `name` of a custom warning to `DeprecationWarning`. For instance: @@ -329,105 +363,64 @@ of the custom deprecation. The `*-deprecation` command line flags only affect warnings that use the name `DeprecationWarning`. -## Exit Codes - -Node.js will normally exit with a `0` status code when no more async -operations are pending. The following status codes are used in other -cases: - -* `1` **Uncaught Fatal Exception** - There was an uncaught exception, - and it was not handled by a domain or an [`'uncaughtException'`][] event - handler. -* `2` - Unused (reserved by Bash for builtin misuse) -* `3` **Internal JavaScript Parse Error** - The JavaScript source code - internal in Node.js's bootstrapping process caused a parse error. This - is extremely rare, and generally can only happen during development - of Node.js itself. -* `4` **Internal JavaScript Evaluation Failure** - The JavaScript - source code internal in Node.js's bootstrapping process failed to - return a function value when evaluated. This is extremely rare, and - generally can only happen during development of Node.js itself. -* `5` **Fatal Error** - There was a fatal unrecoverable error in V8. - Typically a message will be printed to stderr with the prefix `FATAL - ERROR`. -* `6` **Non-function Internal Exception Handler** - There was an - uncaught exception, but the internal fatal exception handler - function was somehow set to a non-function, and could not be called. -* `7` **Internal Exception Handler Run-Time Failure** - There was an - uncaught exception, and the internal fatal exception handler - function itself threw an error while attempting to handle it. This - can happen, for example, if a [`'uncaughtException'`][] or - `domain.on('error')` handler throws an error. -* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes - indicated an uncaught exception. -* `9` - **Invalid Argument** - Either an unknown option was specified, - or an option requiring a value was provided without a value. -* `10` **Internal JavaScript Run-Time Failure** - The JavaScript - source code internal in Node.js's bootstrapping process threw an error - when the bootstrapping function was called. This is extremely rare, - and generally can only happen during development of Node.js itself. -* `12` **Invalid Debug Argument** - The `--debug` and/or `--debug-brk` - options were set, but an invalid port number was chosen. -* `>128` **Signal Exits** - If Node.js receives a fatal signal such as - `SIGKILL` or `SIGHUP`, then its exit code will be `128` plus the - value of the signal code. This is a standard Unix practice, since - exit codes are defined to be 7-bit integers, and signal exits set - the high-order bit, and then contain the value of the signal code. - -## Signal Events +### 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. +Signal events will be emitted when the Node.js process receives a signal. Please +refer to sigaction(2) for a listing of standard POSIX signal names such as +`SIGINT`, `SIGHUP`, etc. + +The name of each event will be the uppercase common name for the signal (e.g. +`'SIGINT'` for `SIGINT` signals). -Example of listening for `SIGINT`: +For example: ```js -// Start reading from stdin so we don't exit. +// Begin reading from stdin so the process does not exit. process.stdin.resume(); process.on('SIGINT', () => { - console.log('Got SIGINT. Press Control-D to exit.'); + console.log('Received SIGINT. Press Control-D to exit.'); }); ``` -An easy way to send the `SIGINT` signal is with `Control-C` in most terminal -programs. +*Note*: An easy way to send the `SIGINT` signal is with `-C` in most +terminal programs. -Note: +It is important to take note of the following: -- `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 +* `SIGUSR1` is reserved by Node.js to start the debugger. It's possible to + install a listener but doing so will _not_ 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 behavior will be removed (Node.js 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 +* `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.js will be unconditionally terminated by Windows about 10 seconds later. On non-Windows platforms, the default behavior of `SIGHUP` is to terminate Node.js, but once a listener has been installed its default behavior will be removed. -- `SIGTERM` is not supported on Windows, it can be listened on. -- `SIGINT` from the terminal is supported on all platforms, and can usually be +* `SIGTERM` is not supported on Windows, it can be listened on. +* `SIGINT` from the terminal 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 +* `SIGBREAK` is delivered on Windows when `+` 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 +* `SIGKILL` cannot have a listener installed, it will unconditionally terminate Node.js on all platforms. -- `SIGSTOP` cannot have a listener installed. +* `SIGSTOP` cannot have a listener installed. -Note that Windows does not support sending Signals, but Node.js offers some -emulation with [`process.kill()`][], and [`ChildProcess.kill()`][]. Sending signal `0` -can be used to test for the existence of a process. Sending `SIGINT`, +*Note*: Windows does not support sending signals, but Node.js offers some +emulation with [`process.kill()`][], and [`ChildProcess.kill()`][]. Sending +signal `0` can be used to test for the existence of a process. Sending `SIGINT`, `SIGTERM`, and `SIGKILL` cause the unconditional termination of the target process. @@ -436,7 +429,7 @@ process. added: v0.7.0 --> -This causes Node.js to emit an abort. This will cause Node.js to exit and +The `process.abort()` method causes the Node.js process to exit immediately and generate a core file. ## process.arch @@ -444,10 +437,12 @@ generate a core file. added: v0.5.0 --> -What processor architecture you're running on: `'arm'`, `'ia32'`, or `'x64'`. +The `process.arch` property returns a String identifying the processor +architecture that the Node.js process is currently running on. For instance +`'arm'`, `'ia32'`, or `'x64'`. ```js -console.log('This processor architecture is ' + process.arch); +console.log(`This processor architecture is ${process.arch}`); ``` ## process.argv @@ -455,21 +450,29 @@ console.log('This processor architecture is ' + process.arch); added: v0.1.27 --> -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. +The `process.argv` property returns a array containing the command line +arguments passed when the Node.js process was launched. The first element will +be 'node', the second element will be the name of the JavaScript file. The +remaining elements will be any additional command line arguments. + +For example, assuming the following script for `process-args.js`: ```js // print process.argv -process.argv.forEach((val, index, array) => { +process.argv.forEach((val, index) => { console.log(`${index}: ${val}`); }); ``` -This will generate: +Launching the Node.js process as: ``` $ node process-2.js one two=three four +``` + +Would generate the output: + +```text 0: node 1: /Users/mjr/work/node/process-2.js 2: one @@ -482,7 +485,11 @@ $ node process-2.js one two=three four added: v0.1.17 --> -Changes the current working directory of the process or throws an exception if that fails. +* `directory` {String} + +The `process.chdir()` method changes the current working directory of the +Node.js process or throws an exception if doing so fails (for instance, if +the specified `directory` does not exist). ```js console.log(`Starting directory: ${process.cwd()}`); @@ -500,13 +507,14 @@ catch (err) { added: v0.7.7 --> -An Object containing the JavaScript representation of the configure options -that were used to compile the current Node.js executable. This is the same as -the `config.gypi` file that was produced when running the `./configure` script. +The `process.config` property returns an Object containing the JavaScript +representation of the configure options used to compile the current Node.js +executable. This is the same as the `config.gypi` file that was produced when +running the `./configure` script. An example of the possible output looks like: -``` +```js { target_defaults: { cflags: [], @@ -533,29 +541,36 @@ An example of the possible output looks like: } ``` -*Note: the `process.config` property is **not** read-only and there are existing -modules in the ecosystem that are known to extend, modify, or entirely replace -the value of `process.config`.* +*Note*: The `process.config` property is **not** read-only and there are +existing modules in the ecosystem that are known to extend, modify, or entirely +replace the value of `process.config`. ## process.connected -* {Boolean} Set to `false` after `process.disconnect()` is called +If the Node.js process is spawned with an IPC channel (see the [Child Process][] +and [Cluster][] documentation), the `process.connected` property will return +`true` so long as the IPC channel is connected and will return `false` after +`process.disconnect()` is called. -If `process.connected` is `false`, it is no longer possible to send messages. +Once `process.connected` is `false`, it is no longer possible to send messages +over the IPC channel using `process.send()`. ## process.cpuUsage([previousValue]) -Returns the user and system CPU time usage of the current process, in an object -with properties `user` and `system`, whose values are microsecond values -(millionth of a second). These values measure time spent in user and -system code respectively, and may end up being greater than actual elapsed time -if multiple CPU cores are performing work for this process. +* `previousValue` {Array} A previous return value from calling + `process.cpuUsage()` + +The `process.cpuUsage()` method returns the user and system CPU time usage of +the current process, in an object with properties `user` and `system`, whose +values are microsecond values (millionth of a second). These values measure time +spent in user and system code respectively, and may end up being greater than +actual elapsed time if multiple CPU cores are performing work for this process. The result of a previous call to `process.cpuUsage()` can be passed as the argument to the function, to get a diff reading. @@ -577,7 +592,8 @@ console.log(process.cpuUsage(startUsage)); added: v0.1.8 --> -Returns the current working directory of the process. +The `process.cwd()` method returns the current working directory of the Node.js +process. ```js console.log(`Current directory: ${process.cwd()}`); @@ -588,25 +604,30 @@ console.log(`Current directory: ${process.cwd()}`); added: v0.7.2 --> -Close the IPC channel to the parent process, allowing this child to exit -gracefully once there are no other connections keeping it alive. +If the Node.js process is spawned with an IPC channel (see the [Child Process][] +and [Cluster][] documentation), the `process.disconnect()` method will close the +IPC channel to the parent process, allowing the child process to exit gracefully +once there are no other connections keeping it alive. -Identical to the parent process's [`ChildProcess.disconnect()`][]. +The effect of calling `process.disconnect()` is that same as calling the parent +process's [`ChildProcess.disconnect()`][]. -If Node.js was not spawned with an IPC channel, `process.disconnect()` will be -undefined. +If the Node.js process was not spawned with an IPC channel, +`process.disconnect()` will be `undefined`. ## process.env -An object containing the user environment. See environ(7). +The `process.env` property returns an object containing the user environment. +See environ(7). An example of this object looks like: ```js -{ TERM: 'xterm-256color', +{ + TERM: 'xterm-256color', SHELL: '/usr/local/bin/bash', USER: 'maciej', PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin', @@ -615,17 +636,19 @@ An example of this object looks like: SHLVL: '1', HOME: '/Users/maciej', LOGNAME: 'maciej', - _: '/usr/local/bin/node' } + _: '/usr/local/bin/node' +} ``` -You can write to this object, but changes won't be reflected outside of your -process. That means that the following won't work: +It is possible to modify this object, but such modifications will not be +reflected outside the Node.js process. In other words, the following example +would not work: ``` $ node -e 'process.env.foo = "bar"' && echo $foo ``` -But this will: +While the following will: ```js process.env.foo = 'bar'; @@ -751,26 +774,26 @@ emitMyWarning(); added: v0.7.7 --> -This is the set of Node.js-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.js 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. +The `process.execArgv' property returns the set of Node.js-specific command-line +options passed when the Node.js process was launched. These options do not +appear in the array returned by the [`process.argv`][] property, and do not +include the Node.js 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: +For example: ``` $ node --harmony script.js --version ``` -results in process.execArgv: +Results in `process.execArgv`: ```js ['--harmony'] ``` -and process.argv: +And `process.argv`: ```js ['/usr/local/bin/node', 'script.js', '--version'] @@ -781,9 +804,10 @@ and process.argv: added: v0.1.100 --> -This is the absolute pathname of the executable that started the process. +The `process.execPath` property returns the absolute pathname of the executable +that started the Node.js process. -Example: +For example: ``` /usr/local/bin/node @@ -873,11 +897,8 @@ previous setting of `process.exitCode`. added: v2.0.0 --> -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -Gets the effective group identity of the process. (See getegid(2).) -This is the numerical group id, not the group name. +The `process.getegid()` method returns the numerical effective group identity +of the Node.js process. (See getegid(2).) ```js if (process.getegid) { @@ -885,17 +906,16 @@ if (process.getegid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android) ## process.geteuid() -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -Gets the effective user identity of the process. (See geteuid(2).) -This is the numerical userid, not the username. +The `process.geteuid()` method returns the numerical effective user identity of +the process. (See geteuid(2).) ```js if (process.geteuid) { @@ -903,16 +923,16 @@ if (process.geteuid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + ## process.getgid() -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -Gets the group identity of the process. (See getgid(2).) -This is the numerical group id, not the group name. +The `process.getgid()` method returns the numerical group identity of the +process. (See getgid(2).) ```js if (process.getgid) { @@ -920,27 +940,29 @@ if (process.getgid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + + ## process.getgroups() -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) +The `process.getgroups()` method returns an array with the supplementary group +IDs. POSIX leaves it unspecified if the effective group ID is included but +Node.js ensures it always is. -Returns an array with the supplementary group IDs. POSIX leaves it unspecified -if the effective group ID is included but Node.js ensures it always is. +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) ## process.getuid() -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -Gets the user identity of the process. (See getuid(2).) -This is the numerical userid, not the username. +The `process.getuid()` method returns the numeric user identity of the process. +(See getuid(2).) ```js if (process.getuid) { @@ -948,21 +970,24 @@ if (process.getuid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + ## process.hrtime([time]) -Returns the current high-resolution real time in a `[seconds, nanoseconds]` -tuple Array. `time` is an optional parameter that must be the result of a -previous `process.hrtime()` call (and therefore, a real time in a -`[seconds, nanoseconds]` tuple Array containing a previous time) to diff with -the current time. These times are relative to an arbitrary time in the past, -and not related to the time of day and therefore not subject to clock drift. -The primary use is for measuring performance between intervals. +The `process.hrtime()` method returns the current high-resolution real time in a +`[seconds, nanoseconds]` tuple Array. `time` is an optional parameter that must +be the result of a previous `process.hrtime()` call (and therefore, a real time +in a `[seconds, nanoseconds]` tuple Array containing a previous time) to diff +with the current time. These times are relative to an arbitrary time in the +past, and not related to the time of day and therefore not subject to clock +drift. The primary use is for measuring performance between intervals. -You may pass in the result of a previous call to `process.hrtime()` to get -a diff reading, useful for benchmarks and measuring intervals: +Passing in the result of a previous call to `process.hrtime()` is useful for +calculating an amount of time passed between calls: ```js var time = process.hrtime(); @@ -972,7 +997,7 @@ setTimeout(() => { var diff = process.hrtime(time); // [ 1, 552 ] - console.log('benchmark took %d nanoseconds', diff[0] * 1e9 + diff[1]); + console.log(`Benchmark took ${diff[0] * 1e9 + diff[1]} nanoseconds`); // benchmark took 1000000527 nanoseconds }, 1000); ``` @@ -986,16 +1011,15 @@ passing the result to process.hrtime() will result in undefined behavior. added: v0.9.4 --> -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -Reads /etc/group and initializes the group access list, using all groups of -which the user is a member. This is a privileged operation, meaning you need -to be root or have the `CAP_SETGID` capability. +* `user` {String|number} The user name or numeric identifier. +* `extra_group` {String|number} A group name or numeric identifier. -`user` is a user name or user ID. `extra_group` is a group name or group ID. +The `process.initgroups()` method reads the `/etc/group` file and initializes +the group access list, using all groups of which the user is a member. This is +a privileged operation that requires that the Node.js process either have `root` +access or the `CAP_SETGID` capability. -Some care needs to be taken when dropping privileges. Example: +Note that care must be taken when dropping privileges. Example: ```js console.log(process.getgroups()); // [ 0 ] @@ -1005,25 +1029,34 @@ process.setgid(1000); // drop root gid console.log(process.getgroups()); // [ 27, 30, 46, 1000 ] ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + ## 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 `'SIGHUP'`. If omitted, the signal will be `'SIGTERM'`. -See [Signal Events][] and kill(2) for more information. +* `pid` {number} A process ID +* `signal` {String|number} The signal to send, either as a string or number. + Defaults to `'SIGTERM'`. + +The `process.kill()` method sends the `signal` to the process identified by +`pid`. -Will throw an error if target does not exist, and as a special case, a signal -of `0` can be used to test for the existence of a process. Windows platforms -will throw an error if the `pid` is used to kill a process group. +Signal names are strings such as `'SIGINT'` or `'SIGHUP'`. See [Signal Events][] +and kill(2) for more information. -Note that even though the name of this function is `process.kill`, it is really +This method will throw an error if the target `pid` does not exist. As a special +case, a signal of `0` can be used to test for the existence of a process. +Windows platforms will throw an error if the `pid` is used to kill a process +group. + +*Note*:Even though 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: +For example: ```js process.on('SIGHUP', () => { @@ -1038,28 +1071,32 @@ setTimeout(() => { process.kill(process.pid, 'SIGHUP'); ``` -Note: When SIGUSR1 is received by Node.js it starts the debugger, see -[Signal Events][]. +*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start the +debugger, see [Signal Events][]. ## process.mainModule -Alternate way to retrieve [`require.main`][]. The difference is that if the main -module changes at runtime, [`require.main`][] might still refer to the original main -module in modules that were required before the change occurred. Generally it's +The `process.mainModule` property provides an alternative way of retrieving +[`require.main`][]. The difference is that if the main module changes at +runtime, [`require.main`][] may still refer to the original main module in +modules that were required before the change occurred. Generally it's safe to assume that the two refer to the same module. -As with [`require.main`][], it will be `undefined` if there was no entry script. +As with [`require.main`][], `process.mainModule` will be `undefined` if there +is no entry script. ## process.memoryUsage() -Returns an object describing the memory usage of the Node.js process -measured in bytes. +The `process.memoryUsage()` method returns an object describing the memory usage +of the Node.js process measured in bytes. + +For example, the code: ```js const util = require('util'); @@ -1067,26 +1104,30 @@ const util = require('util'); console.log(util.inspect(process.memoryUsage())); ``` -This will generate: +Will generate: ```js -{ rss: 4935680, +{ + rss: 4935680, heapTotal: 1826816, - heapUsed: 650472 } + heapUsed: 650472 +} ``` `heapTotal` and `heapUsed` refer to V8's memory usage. - ## process.nextTick(callback[, arg][, ...]) * `callback` {Function} +* `[, arg][, ...]` {any} Additional arguments to pass when invoking the + `callback` -Once the current event loop turn runs to completion, call the callback -function. +The `process.nextTick()` method adds the `callback` to the "next tick queue". +Once the current turn of the event loop turn runs to completion, all callbacks +currently in the next tick queue will be called. This is *not* a simple alias to [`setTimeout(fn, 0)`][], it's much more efficient. It runs before any additional I/O events (including @@ -1104,9 +1145,9 @@ console.log('scheduled'); // nextTick callback ``` -This is important in developing APIs where you want to give the user the -chance to assign event handlers after an object has been constructed, -but before any I/O has occurred. +This is important when developing APIs in order to give users the opportunity +to assign event handlers *after* an object has been constructed but before any +I/O has occurred: ```js function MyThing(options) { @@ -1138,7 +1179,7 @@ function maybeSync(arg, cb) { } ``` -This API is hazardous. If you do this: +This API is hazardous because in the following case: ```js maybeSync(true, () => { @@ -1147,9 +1188,9 @@ maybeSync(true, () => { bar(); ``` -then it's not clear whether `foo()` or `bar()` will be called first. +It is not clear whether `foo()` or `bar()` will be called first. -This approach is much better: +The following approach is much better: ```js function definitelyAsync(arg, cb) { @@ -1162,7 +1203,7 @@ function definitelyAsync(arg, cb) { } ``` -Note: the nextTick queue is completely drained on each pass of the +*Note*: the next tick queue is completely drained on each pass of the event loop **before** additional I/O is processed. As a result, recursively setting nextTick callbacks will block any I/O from happening, just like a `while(true);` loop. @@ -1172,7 +1213,7 @@ happening, just like a `while(true);` loop. added: v0.1.15 --> -The PID of the process. +The `process.pid` property returns the PID of the process. ```js console.log(`This process is pid ${process.pid}`); @@ -1183,7 +1224,8 @@ console.log(`This process is pid ${process.pid}`); added: v0.1.16 --> -What platform you're running on: +The `process.platform` property returns a string identifying the operating +system platform on which the Node.js process is running. For instance `'darwin'`, `'freebsd'`, `'linux'`, `'sunos'` or `'win32'` ```js @@ -1195,31 +1237,37 @@ console.log(`This platform is ${process.platform}`); added: v3.0.0 --> -An Object containing metadata related to the current release, including URLs -for the source tarball and headers-only tarball. +The `process.release` property returns an Object containing metadata related to +the current release, including URLs for the source tarball and headers-only +tarball. `process.release` contains the following properties: -* `name`: a string with a value that will always be `'node'` for Node.js. For +* `name` {String} A value that will always be `'node'` for Node.js. For legacy io.js releases, this will be `'io.js'`. -* `sourceUrl`: a complete URL pointing to a _.tar.gz_ file containing the - source of the current release. -* `headersUrl`: a complete URL pointing to a _.tar.gz_ file containing only - the header files for the current release. This file is significantly smaller - than the full source file and can be used for compiling add-ons against - Node.js. -* `libUrl`: a complete URL pointing to an _node.lib_ file matching the +* `sourceUrl` {String} an absolute URL pointing to a `_.tar.gz_` file containing + the source code of the current release. +* `headersUrl`{String} an absolute URL pointing to a `_.tar.gz_` file containing + only the source header files for the current release. This file is + significantly smaller than the full source file and can be used for compiling + Node.js native add-ons. +* `libUrl` {String} an absolute URL pointing to a `_node.lib_` file matching the architecture and version of the current release. This file is used for - compiling add-ons against Node.js. _This property is only present on Windows + compiling Node.js native add-ons. _This property is only present on Windows builds of Node.js and will be missing on all other platforms._ +* `lts` {String} a string label identifying the [LTS][] label for this release. + If the Node.js release is not an LTS release, this will be `undefined`. -e.g. +For example: ```js -{ name: 'node', - sourceUrl: 'https://nodejs.org/download/release/v4.0.0/node-v4.0.0.tar.gz', - headersUrl: 'https://nodejs.org/download/release/v4.0.0/node-v4.0.0-headers.tar.gz', - libUrl: 'https://nodejs.org/download/release/v4.0.0/win-x64/node.lib' } +{ + name: 'node', + lts: 'Argon', + sourceUrl: 'https://nodejs.org/download/release/v4.4.5/node-v4.4.5.tar.gz', + headersUrl: 'https://nodejs.org/download/release/v4.4.5/node-v4.4.5-headers.tar.gz', + libUrl: 'https://nodejs.org/download/release/v4.4.5/win-x64/node.lib' +} ``` In custom builds from non-release versions of the source tree, only the @@ -1237,25 +1285,27 @@ added: v0.5.9 * `callback` {Function} * Return: {Boolean} -When Node.js is spawned with an IPC channel attached, it can send messages to its -parent process using `process.send()`. Each will be received as a +If Node.js is spawned with an IPC channel, the `process.send()` method can be +used to send messages to the parent process. Messages will be received as a [`'message'`][] event on the parent's [`ChildProcess`][] object. -*Note: this function uses [`JSON.stringify()`][] internally to serialize the `message`.* +If Node.js was not spawned with an IPC channel, `process.send()` will be +`undefined`. -If Node.js was not spawned with an IPC channel, `process.send()` will be undefined. +*Note*: This function uses [`JSON.stringify()`][] internally to serialize the +`message`.* ## process.setegid(id) -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) +* `id` {String|number} A group name or ID -Sets the effective group identity of the process. (See setegid(2).) -This accepts either a numerical ID or a group name string. If a group name -is specified, this method blocks while resolving it to a numerical ID. +The `process.setegid()` method sets the effective group identity of the process. +(See setegid(2).) The `id` can be passed as either a numeric ID or a group +name string. If a group name is specified, this method blocks while resolving +the associated a numeric ID. ```js if (process.getegid && process.setegid) { @@ -1270,17 +1320,21 @@ if (process.getegid && process.setegid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + + ## process.seteuid(id) -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) +* `id` {String|number} A user name or ID -Sets the effective user identity of the process. (See seteuid(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. +The `process.seteuid()` method sets the effective user identity of the process. +(See seteuid(2).) The `id` can be passed as either a numeric ID or a username +string. If a username is specified, the method blocks while resolving the +associated numeric ID. ```js if (process.geteuid && process.seteuid) { @@ -1295,17 +1349,20 @@ if (process.geteuid && process.seteuid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + ## process.setgid(id) -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) +* `id` {String|number} The group name or ID -Sets the group identity of the process. (See setgid(2).) This accepts either -a numerical ID or a group name string. If a group name is specified, this method -blocks while resolving it to a numerical ID. +The `process.setgid()` method sets the group identity of the process. (See +setgid(2).) The `id` can be passed as either a numeric ID or a group name +string. If a group name is specified, this method blocks while resolving the +associated numeric ID. ```js if (process.getgid && process.setgid) { @@ -1320,30 +1377,34 @@ if (process.getgid && process.setgid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + ## process.setgroups(groups) -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) +* `groups` {Array} + +The `process.setgroups()` method sets the supplementary group IDs for the +Node.js proess. This is a privileged operation that requires the Node.js process +to have `root` or the `CAP_SETGID` capability. -Sets the supplementary group IDs. This is a privileged operation, meaning you -need to be root or have the `CAP_SETGID` capability. +The `groups` array can contain numeric group IDs, group names or both. -The list can contain group IDs, group names or both. +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) ## process.setuid(id) -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -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. +The `process.setuid(id) method sets the user identity of the process. (See +setuid(2).) The `id` can be passed as either a numeric ID or a username string. +If a username is specified, the method blocks while resolving the associated +numeric ID. ```js if (process.getuid && process.setuid) { @@ -1358,15 +1419,20 @@ if (process.getuid && process.setuid) { } ``` +*Note*: This function is only available on POSIX platforms (i.e. not Windows or +Android) + + ## process.stderr -A writable stream to stderr (on fd `2`). +The `process.stderr` property returns a [Writable][] stream equivalent to or +associated with `stderr` (fd `2`). `process.stderr` and `process.stdout` are unlike other streams in Node.js in -that they cannot be closed ([`end()`][] will throw), they never emit the [`'finish'`][] -event and that writes can block when output is redirected to a file (although -disks are fast and operating systems normally employ write-back caching so it -should be a very rare occurrence indeed.) +that they cannot be closed (calling [`end()`][] will throw an Error), they never +emit the [`'finish'`][] event, and writes can block when output is redirected to +a file (although disks are fast and operating systems normally employ write-back +caching so it should be a very rare occurrence indeed.) Additionally, `process.stderr` and `process.stdout` are blocking when outputting to TTYs (terminals) on OS X as a workaround for the OS's very small, 1kb @@ -1374,9 +1440,10 @@ buffer size. This is to prevent interleaving between `stdout` and `stderr`. ## process.stdin -A `Readable Stream` for stdin (on fd `0`). +The `process.stdin` property returns a [Readable][] stream equivalent to or +associated with `stdin` (fd `0`). -Example of opening standard input and listening for both events: +For example: ```js process.stdin.setEncoding('utf8'); @@ -1393,22 +1460,20 @@ process.stdin.on('end', () => { }); ``` -As a Stream, `process.stdin` can also be used in "old" mode that is compatible -with scripts written for node.js prior to v0.10. +As a [Readable][] stream, `process.stdin` can also be used in "old" mode that +is compatible with scripts written for Node.js prior to v0.10. For more information see [Stream compatibility][]. -In "old" Streams mode the stdin stream is paused by default, so one +*Note*: In "old" streams mode the `stdin` stream is paused by default, so one must call `process.stdin.resume()` to read from it. Note also that calling `process.stdin.resume()` itself would switch stream to "old" mode. -If you are starting a new project you should prefer a more recent "new" Streams -mode over "old" one. - ## process.stdout -A `Writable Stream` to `stdout` (on fd `1`). +The `process.stdout` propety returns a [Writable][] stream equivalent to or +associated with `stdout` (fd `1`). -For example, a `console.log` equivalent could look like this: +For example: ```js console.log = (msg) => { @@ -1417,18 +1482,24 @@ console.log = (msg) => { ``` `process.stderr` and `process.stdout` are unlike other streams in Node.js in -that they cannot be closed ([`end()`][] will throw), they never emit the [`'finish'`][] -event and that writes can block when output is redirected to a file (although -disks are fast and operating systems normally employ write-back caching so it -should be a very rare occurrence indeed.) - -Additionally, `process.stderr` and `process.stdout` are blocking when outputting -to TTYs (terminals) on OS X as a workaround for the OS's very small, 1kb -buffer size. This is to prevent interleaving between `stdout` and `stderr`. +that they cannot be closed (calling [`end()`][] will throw an Error), they never +emit the [`'finish'`][] event and that writes can block when output is +redirected to a file (although disks are fast and operating systems normally +employ write-back caching so it should be a very rare occurrence indeed.) To check if Node.js is being run in a TTY context, read the `isTTY` property on `process.stderr`, `process.stdout`, or `process.stdin`: +### TTY Terminals and `process.stdout` + +The `process.stderr` and `process.stdout` streams are blocking when outputting +to TTYs (terminals) on OS X as a workaround for the operating system's small, +1kb buffer size. This is to prevent interleaving between `stdout` and `stderr`. + +To check if Node.js is being run in a [TTY][] context, check the `isTTY` +property on `process.stderr`, `process.stdout`, or `process.stdin`. + +For instance: ``` $ node -p "Boolean(process.stdin.isTTY)" true @@ -1441,23 +1512,24 @@ $ node -p "Boolean(process.stdout.isTTY)" | cat false ``` -See [the tty docs][] for more information. +See the [TTY][] documentation for more information. ## process.title -Getter/setter to set what is displayed in `ps`. - -When used as a setter, the maximum length is platform-specific and probably -short. - -On Linux and OS X, it's limited to the size of the binary name plus the -length of the command line arguments because it overwrites the argv memory. - -v0.8 allowed for longer process title strings by also overwriting the environ -memory but that was potentially insecure/confusing in some (rather obscure) +The `process.title` property returns the current process title (i.e. returns +the current value of `ps`). Assigning a new value to `process.title` modifies +the current value of `ps`. + +*Note*: When a new value is assigned, different platforms will impose different +maximum length restrictions on the title. Usually such restrictions are quite +limited. For instance, on Linux and OS X, `process.title` is limited to the size +of the binary name plus the length of the command line arguments because setting +the `process.title` overwrites the `argv` memory of the process. Node.js v0.8 +allowed for longer process title strings by also overwriting the `environ` +memory but that was potentially insecure and confusing in some (rather obscure) cases. ## process.umask([mask]) @@ -1465,9 +1537,12 @@ cases. added: v0.1.19 --> -Sets or reads the process's file mode creation mask. Child processes inherit -the mask from the parent process. Returns the old mask if `mask` argument is -given, otherwise returns the current mask. +* `mask` {number} + +The `process.umask()` method sets or returns the Node.js process's file mode +creation mask. Child processes inherit the mask from the parent process. The old +mask is return if the `mask` argument is given, otherwise returns the current +mask. ```js const newmask = 0o022; @@ -1483,14 +1558,15 @@ console.log( added: v0.5.0 --> -Number of seconds Node.js has been running. +The `process.uptime()` method returns the number of seconds the current Node.js +process has been running. ## process.version -A compiled-in property that exposes `NODE_VERSION`. +The `process.version` property returns the Node.js version string. ```js console.log(`Version: ${process.version}`); @@ -1501,16 +1577,18 @@ console.log(`Version: ${process.version}`); added: v0.2.0 --> -A property exposing version strings of Node.js and its dependencies. +The `process.versions` property returns an object listing the version strings of +Node.js and its dependencies. ```js console.log(process.versions); ``` -Will print something like: +Will generate output similar to: ```js -{ http_parser: '2.3.0', +{ + http_parser: '2.3.0', node: '1.1.1', v8: '4.1.0.14', uv: '1.3.0', @@ -1518,9 +1596,56 @@ Will print something like: ares: '1.10.0-DEV', modules: '43', icu: '55.1', - openssl: '1.0.1k' } + openssl: '1.0.1k' +} ``` +## Exit Codes + +Node.js will normally exit with a `0` status code when no more async +operations are pending. The following status codes are used in other +cases: + +* `1` **Uncaught Fatal Exception** - There was an uncaught exception, + and it was not handled by a domain or an [`'uncaughtException'`][] event + handler. +* `2` - Unused (reserved by Bash for builtin misuse) +* `3` **Internal JavaScript Parse Error** - The JavaScript source code + internal in Node.js's bootstrapping process caused a parse error. This + is extremely rare, and generally can only happen during development + of Node.js itself. +* `4` **Internal JavaScript Evaluation Failure** - The JavaScript + source code internal in Node.js's bootstrapping process failed to + return a function value when evaluated. This is extremely rare, and + generally can only happen during development of Node.js itself. +* `5` **Fatal Error** - There was a fatal unrecoverable error in V8. + Typically a message will be printed to stderr with the prefix `FATAL + ERROR`. +* `6` **Non-function Internal Exception Handler** - There was an + uncaught exception, but the internal fatal exception handler + function was somehow set to a non-function, and could not be called. +* `7` **Internal Exception Handler Run-Time Failure** - There was an + uncaught exception, and the internal fatal exception handler + function itself threw an error while attempting to handle it. This + can happen, for example, if a [`'uncaughtException'`][] or + `domain.on('error')` handler throws an error. +* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes + indicated an uncaught exception. +* `9` - **Invalid Argument** - Either an unknown option was specified, + or an option requiring a value was provided without a value. +* `10` **Internal JavaScript Run-Time Failure** - The JavaScript + source code internal in Node.js's bootstrapping process threw an error + when the bootstrapping function was called. This is extremely rare, + and generally can only happen during development of Node.js itself. +* `12` **Invalid Debug Argument** - The `--debug` and/or `--debug-brk` + options were set, but an invalid port number was chosen. +* `>128` **Signal Exits** - If Node.js receives a fatal signal such as + `SIGKILL` or `SIGHUP`, then its exit code will be `128` plus the + value of the signal code. This is a standard Unix practice, since + exit codes are defined to be 7-bit integers, and signal exits set + the high-order bit, and then contain the value of the signal code. + + [`'finish'`]: stream.html#stream_event_finish [`'message'`]: child_process.html#child_process_event_message [`'rejectionHandled'`]: #process_event_rejectionhandled @@ -1546,4 +1671,8 @@ Will print something like: [process_warning]: #process_event_warning [Signal Events]: #process_signal_events [Stream compatibility]: stream.html#stream_compatibility_with_older_node_js_versions -[the tty docs]: tty.html#tty_tty +[TTY]: tty.html#tty_tty +[Writable]: stream.html +[Readable]: stream.html +[Child Process]: child_process.html +[Cluster]: cluster.html