diff --git a/doc/api/process.markdown b/doc/api/process.markdown index 5d152a4196e712..55226da71c724a 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -5,50 +5,15 @@ The `process` object is a global object and can be accessed from anywhere. It is an instance of [EventEmitter][]. -## Exit Codes +## Event: 'beforeExit' -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: +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 continue. -* `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 `process.on('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. +'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. ## Event: 'exit' @@ -72,7 +37,6 @@ Example of listening for `exit`: console.log('About to exit with code:', code); }); - ## Event: 'message' * `message` {Object} a parsed JSON object or primitive value @@ -82,17 +46,44 @@ Example of listening for `exit`: Messages sent by [ChildProcess.send()][] are obtained using the `'message'` event on the child's process object. +## Event: 'rejectionHandled' -## Event: 'beforeExit' +Emitted whenever a Promise was rejected and an error handler was attached to it +(for example with `.catch()`) later than after an event loop turn. This event +is emitted with the following arguments: -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 continue. + - `p` the promise that was previously emitted in an `'unhandledRejection'` + event, but which has now gained a rejection handler. -'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. +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 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. + +For example using the rejection detection hooks in order to keep a map of all +the rejected promise reasons at a given time: + + var unhandledRejections = new Map(); + process.on('unhandledRejection', function(reason, p) { + unhandledRejections.set(p, reason); + }); + process.on('rejectionHandled', function(p) { + unhandledRejections.delete(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). ## Event: 'uncaughtException' @@ -177,44 +168,50 @@ this, you can either attach a dummy `.catch(function() { })` handler to emitted, or you can use the `'rejectionHandled'` event. Below is an explanation of how to do that. -## Event: 'rejectionHandled' - -Emitted whenever a Promise was rejected and an error handler was attached to it -(for example with `.catch()`) later than after an event loop turn. This event -is emitted with the following arguments: - - - `p` the promise that was previously emitted in an `'unhandledRejection'` - event, but which has now 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 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. - -For example using the rejection detection hooks in order to keep a map of all -the rejected promise reasons at a given time: +## Exit Codes - var unhandledRejections = new Map(); - process.on('unhandledRejection', function(reason, p) { - unhandledRejections.set(p, reason); - }); - process.on('rejectionHandled', function(p) { - unhandledRejections.delete(p); - }); +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: -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). +* `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 `process.on('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 @@ -270,77 +267,16 @@ can be used to test for the existence of a process. Sending `SIGINT`, `SIGTERM`, and `SIGKILL` cause the unconditional termination of the target process. -## process.stdout - -A `Writable Stream` to `stdout` (on fd `1`). - -For example, a `console.log` equivalent could look like this: - - console.log = function(msg) { - process.stdout.write(msg + '\n'); - }; - -`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.) - -To check if Node.js 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](tty.html#tty_tty) for more information. - -## process.stderr - -A writable stream to stderr (on 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.) - -## process.stdin - -A `Readable Stream` for stdin (on fd `0`). - -Example of opening standard input and listening for both events: - - process.stdin.setEncoding('utf8'); - - process.stdin.on('readable', function() { - var chunk = process.stdin.read(); - if (chunk !== null) { - process.stdout.write('data: ' + chunk); - } - }); +## process.abort() - process.stdin.on('end', function() { - process.stdout.write('end'); - }); +This causes Node.js to emit an abort. This will cause Node.js to exit and +generate a core file. -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. -For more information see -[Stream compatibility](stream.html#stream_compatibility_with_older_node_js_versions). +## process.arch -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. +What processor architecture you're running on: `'arm'`, `'ia32'`, or `'x64'`. -If you are starting a new project you should prefer a more recent "new" Streams -mode over "old" one. + console.log('This processor architecture is ' + process.arch); ## process.argv @@ -362,64 +298,70 @@ This will generate: 3: two=three 4: four +## process.chdir(directory) -## process.execPath +Changes the current working directory of the process or throws an exception if that fails. -This is the absolute pathname of the executable that started the process. + console.log('Starting directory: ' + process.cwd()); + try { + process.chdir('/tmp'); + console.log('New directory: ' + process.cwd()); + } + catch (err) { + console.log('chdir: ' + err); + } -Example: +## process.config - /usr/local/bin/node - - -## process.execArgv - -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. - -Example: - - $ node --harmony script.js --version - -results in process.execArgv: - - ['--harmony'] - -and process.argv: - - ['/usr/local/bin/node', 'script.js', '--version'] +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. +An example of the possible output looks like: -## process.abort() + { target_defaults: + { cflags: [], + default_configuration: 'Release', + defines: [], + include_dirs: [], + libraries: [] }, + variables: + { host_arch: 'x64', + node_install_npm: 'true', + node_prefix: '', + node_shared_cares: 'false', + node_shared_http_parser: 'false', + node_shared_libuv: 'false', + node_shared_zlib: 'false', + node_use_dtrace: 'false', + node_use_openssl: 'true', + node_shared_openssl: 'false', + strict_aliasing: 'true', + target_arch: 'x64', + v8_use_snapshot: 'true' } } -This causes Node.js to emit an abort. This will cause Node.js to exit and -generate a core file. +### process.connected -## process.chdir(directory) +* {Boolean} Set to false after `process.disconnect()` is called -Changes the current working directory of the process or throws an exception if that fails. +If `process.connected` is false, it is no longer possible to send messages. - 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.cwd() +## process.disconnect() -Returns the current working directory of the process. +Close the IPC channel to the parent process, allowing this child to exit +gracefully once there are no other connections keeping it alive. - console.log('Current directory: ' + process.cwd()); +Identical to the parent process's +[ChildProcess.disconnect()](child_process.html#child_process_child_disconnect). +If Node.js was not spawned with an IPC channel, `process.disconnect()` will be +undefined. ## process.env @@ -448,6 +390,35 @@ But this will: process.env.foo = 'bar'; console.log(process.env.foo); +## process.execArgv + +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. + +Example: + + $ node --harmony script.js --version + +results in process.execArgv: + + ['--harmony'] + +and process.argv: + + ['/usr/local/bin/node', 'script.js', '--version'] + +## process.execPath + +This is the absolute pathname of the executable that started the process. + +Example: + + /usr/local/bin/node + ## process.exit([code]) @@ -471,19 +442,6 @@ Specifying a code to `process.exit(code)` will override any previous setting of `process.exitCode`. -## 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. - - if (process.getgid) { - console.log('Current gid: ' + process.getgid()); - } - - ## process.getegid() Note: this function is only available on POSIX platforms (i.e. not Windows, @@ -497,61 +455,6 @@ This is the numerical group id, not the group name. } -## process.setgid(id) - -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -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. - - if (process.getgid && process.setgid) { - console.log('Current gid: ' + process.getgid()); - try { - process.setgid(501); - console.log('New gid: ' + process.getgid()); - } - catch (err) { - console.log('Failed to set gid: ' + err); - } - } - - -## process.setegid(id) - -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) - -Sets the effective group identity of the process. (See setegid(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. - - if (process.getegid && process.setegid) { - console.log('Current gid: ' + process.getegid()); - try { - process.setegid(501); - console.log('New gid: ' + process.getegid()); - } - catch (err) { - console.log('Failed to set gid: ' + err); - } - } - - -## 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. - - if (process.getuid) { - console.log('Current uid: ' + process.getuid()); - } - - ## process.geteuid() Note: this function is only available on POSIX platforms (i.e. not Windows, @@ -564,67 +467,58 @@ This is the numerical userid, not the username. console.log('Current uid: ' + process.geteuid()); } - -## process.setuid(id) +## process.getgid() 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. +Gets the group identity of the process. (See getgid(2).) +This is the numerical group id, not the group name. - if (process.getuid && process.setuid) { - console.log('Current uid: ' + process.getuid()); - try { - process.setuid(501); - console.log('New uid: ' + process.getuid()); - } - catch (err) { - console.log('Failed to set uid: ' + err); - } + if (process.getgid) { + console.log('Current gid: ' + process.getgid()); } - -## process.seteuid(id) +## process.getgroups() Note: this function is only available on POSIX platforms (i.e. not Windows, Android) -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. - - if (process.geteuid && process.seteuid) { - console.log('Current uid: ' + process.geteuid()); - try { - process.seteuid(501); - console.log('New uid: ' + process.geteuid()); - } - catch (err) { - console.log('Failed to set uid: ' + err); - } - } - +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. -## process.getgroups() +## process.getuid() Note: this function is only available on POSIX platforms (i.e. not Windows, Android) -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. +Gets the user identity of the process. (See getuid(2).) +This is the numerical userid, not the username. + if (process.getuid) { + console.log('Current uid: ' + process.getuid()); + } -## process.setgroups(groups) +## process.hrtime() -Note: this function is only available on POSIX platforms (i.e. not Windows, -Android) +Returns the current high-resolution real time in a `[seconds, nanoseconds]` +tuple Array. It is relative to an arbitrary time in the past. It is not +related to the time of day and therefore not subject to clock drift. The +primary use is for measuring performance between intervals. -Sets the supplementary group IDs. This is a privileged operation, meaning you -need to be root or have the CAP_SETGID capability. +You may pass in the result of a previous call to `process.hrtime()` to get +a diff reading, useful for benchmarks and measuring intervals: -The list can contain group IDs, group names or both. + var time = process.hrtime(); + // [ 1800216, 25 ] + + setTimeout(function() { + var diff = process.hrtime(time); + // [ 1, 552 ] + + console.log('benchmark took %d nanoseconds', diff[0] * 1e9 + diff[1]); + // benchmark took 1000000527 nanoseconds + }, 1000); ## process.initgroups(user, extra_group) @@ -646,109 +540,19 @@ Some care needs to be taken when dropping privileges. Example: process.setgid(1000); // drop root gid console.log(process.getgroups()); // [ 27, 30, 46, 1000 ] +## process.kill(pid[, signal]) -## process.version +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](#process_signal_events) and kill(2) for more information. -A compiled-in property that exposes `NODE_VERSION`. +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. - console.log('Version: ' + process.version); - -## process.versions - -A property exposing version strings of Node.js and its dependencies. - - console.log(process.versions); - -Will print something like: - - { http_parser: '2.3.0', - node: '1.1.1', - v8: '4.1.0.14', - uv: '1.3.0', - zlib: '1.2.8', - ares: '1.10.0-DEV', - modules: '43', - icu: '55.1', - openssl: '1.0.1k' } - -## process.config - -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. - -An example of the possible output looks like: - - { target_defaults: - { cflags: [], - default_configuration: 'Release', - defines: [], - include_dirs: [], - libraries: [] }, - variables: - { host_arch: 'x64', - node_install_npm: 'true', - node_prefix: '', - node_shared_cares: 'false', - node_shared_http_parser: 'false', - node_shared_libuv: 'false', - node_shared_zlib: 'false', - node_use_dtrace: 'false', - node_use_openssl: 'true', - node_shared_openssl: 'false', - strict_aliasing: 'true', - target_arch: 'x64', - v8_use_snapshot: 'true' } } - -## process.release - -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 - legacy io.js releases, this will be `"io.js"`. -* `lts`: a string with a value indicating the _codename_ of the LTS (Long-term - Support) line the current release is part of. This property only exists for - LTS releases and is `undefined` for all other release types, including stable - releases. Current valid values are: - - `"Argon"` for the v4.x LTS line beginning with v4.2.0. -* `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 - 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 - builds of Node.js and will be missing on all other platforms._ - -e.g. - - { 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' } - -In custom builds from non-release versions of the source tree, only the -`name` property may be present. The additional properties should not be -relied upon to exist. - -## 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](#process_signal_events) and kill(2) for more information. - -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. - -Note that 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. +Note that 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: @@ -766,42 +570,16 @@ Example of sending a signal to yourself: Note: When SIGUSR1 is received by Node.js it starts the debugger, see [Signal Events](#process_signal_events). -## process.pid - -The PID of the process. - - console.log('This process is pid ' + process.pid); - - -## 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) -cases. - - -## process.arch - -What processor architecture you're running on: `'arm'`, `'ia32'`, or `'x64'`. - - console.log('This processor architecture is ' + process.arch); - - -## process.platform - -What platform you're running on: -`'darwin'`, `'freebsd'`, `'linux'`, `'sunos'` or `'win32'` +## process.mainModule - console.log('This platform is ' + process.platform); +Alternate way to retrieve +[`require.main`](modules.html#modules_accessing_the_main_module). +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 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. ## process.memoryUsage() @@ -897,45 +675,49 @@ 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. -## process.umask([mask]) - -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. - - var oldmask, newmask = 0022; +## process.pid - oldmask = process.umask(newmask); - console.log('Changed umask from: ' + oldmask.toString(8) + - ' to ' + newmask.toString(8)); +The PID of the process. + console.log('This process is pid ' + process.pid); -## process.uptime() +## process.platform -Number of seconds Node.js has been running. +What platform you're running on: +`'darwin'`, `'freebsd'`, `'linux'`, `'sunos'` or `'win32'` + console.log('This platform is ' + process.platform); -## process.hrtime() +## process.release -Returns the current high-resolution real time in a `[seconds, nanoseconds]` -tuple Array. It is relative to an arbitrary time in the past. It is not -related to the time of day and therefore not subject to clock drift. The -primary use is for measuring performance between intervals. +An Object containing metadata related to the current release, including URLs +for the source tarball and headers-only tarball. -You may pass in the result of a previous call to `process.hrtime()` to get -a diff reading, useful for benchmarks and measuring intervals: +`process.release` contains the following properties: - var time = process.hrtime(); - // [ 1800216, 25 ] +* `name`: a string with 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 + 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 + builds of Node.js and will be missing on all other platforms._ - setTimeout(function() { - var diff = process.hrtime(time); - // [ 1, 552 ] +e.g. - console.log('benchmark took %d nanoseconds', diff[0] * 1e9 + diff[1]); - // benchmark took 1000000527 nanoseconds - }, 1000); + { 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' } +In custom builds from non-release versions of the source tree, only the +`name` property may be present. The additional properties should not be +relied upon to exist. ## process.send(message[, sendHandle][, callback]) @@ -949,36 +731,223 @@ event on the parent's `ChildProcess` object. If Node.js was not spawned with an IPC channel, `process.send()` will be undefined. +## process.setegid(id) -## process.disconnect() +Note: this function is only available on POSIX platforms (i.e. not Windows, +Android) -Close the IPC channel to the parent process, allowing this child to exit -gracefully once there are no other connections keeping it alive. +Sets the effective group identity of the process. (See setegid(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. -Identical to the parent process's -[ChildProcess.disconnect()](child_process.html#child_process_child_disconnect). + if (process.getegid && process.setegid) { + console.log('Current gid: ' + process.getegid()); + try { + process.setegid(501); + console.log('New gid: ' + process.getegid()); + } + catch (err) { + console.log('Failed to set gid: ' + err); + } + } -If Node.js was not spawned with an IPC channel, `process.disconnect()` will be -undefined. +## process.seteuid(id) +Note: this function is only available on POSIX platforms (i.e. not Windows, +Android) -### process.connected +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. -* {Boolean} Set to false after `process.disconnect()` is called + if (process.geteuid && process.seteuid) { + console.log('Current uid: ' + process.geteuid()); + try { + process.seteuid(501); + console.log('New uid: ' + process.geteuid()); + } + catch (err) { + console.log('Failed to set uid: ' + err); + } + } -If `process.connected` is false, it is no longer possible to send messages. +## process.setgid(id) +Note: this function is only available on POSIX platforms (i.e. not Windows, +Android) -## process.mainModule +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. -Alternate way to retrieve -[`require.main`](modules.html#modules_accessing_the_main_module). -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 safe to assume that the two refer -to the same module. + if (process.getgid && process.setgid) { + console.log('Current gid: ' + process.getgid()); + try { + process.setgid(501); + console.log('New gid: ' + process.getgid()); + } + catch (err) { + console.log('Failed to set gid: ' + err); + } + } + +## process.setgroups(groups) + +Note: this function is only available on POSIX platforms (i.e. not Windows, +Android) + +Sets the supplementary group IDs. This is a privileged operation, meaning you +need to be root or have the CAP_SETGID capability. + +The list can contain group IDs, group names or both. + +## 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. + + if (process.getuid && process.setuid) { + console.log('Current uid: ' + process.getuid()); + try { + process.setuid(501); + console.log('New uid: ' + process.getuid()); + } + catch (err) { + console.log('Failed to set uid: ' + err); + } + } + +## process.stderr + +A writable stream to stderr (on 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.) + +## process.stdin + +A `Readable Stream` for stdin (on fd `0`). + +Example of opening standard input and listening for both events: + + process.stdin.setEncoding('utf8'); + + process.stdin.on('readable', function() { + var chunk = process.stdin.read(); + if (chunk !== null) { + process.stdout.write('data: ' + chunk); + } + }); + + process.stdin.on('end', function() { + process.stdout.write('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. +For more information see +[Stream compatibility](stream.html#stream_compatibility_with_older_node_js_versions). + +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`). + +For example, a `console.log` equivalent could look like this: + + console.log = function(msg) { + process.stdout.write(msg + '\n'); + }; + +`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.) + +To check if Node.js 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](tty.html#tty_tty) 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) +cases. + +## process.umask([mask]) + +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. + + var oldmask, newmask = 0022; + + oldmask = process.umask(newmask); + console.log('Changed umask from: ' + oldmask.toString(8) + + ' to ' + newmask.toString(8)); + + +## process.uptime() + +Number of seconds Node.js has been running. + +## process.version + +A compiled-in property that exposes `NODE_VERSION`. + + console.log('Version: ' + process.version); + +## process.versions + +A property exposing version strings of Node.js and its dependencies. + + console.log(process.versions); + +Will print something like: + + { http_parser: '2.3.0', + node: '1.1.1', + v8: '4.1.0.14', + uv: '1.3.0', + zlib: '1.2.8', + ares: '1.10.0-DEV', + modules: '43', + icu: '55.1', + openssl: '1.0.1k' } -As with `require.main`, it will be `undefined` if there was no entry script. [ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback [EventEmitter]: events.html#events_class_events_eventemitter