From ec67abe4a7c074bb66700c4aede56ffd4aaf3363 Mon Sep 17 00:00:00 2001 From: Bryan English Date: Wed, 4 May 2016 21:57:59 -0700 Subject: [PATCH] doc: add `added:` information for process Most of the information is gleaned from changelogs. The rest is inferred from git history. Omitted cpuUsage() since it's not yet in a release. Also omitted the streams, events and signals, since I didn't really think it made sense for those. Ref: https://github.com/nodejs/node/issues/6578 PR-URL: https://github.com/nodejs/node/pull/6589 Reviewed-By: Anna Henningsen Reviewed-By: James M Snell Reviewed-By: Stephen Belanger Reviewed-By: Alexander Makarenko --- doc/api/process.md | 142 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/doc/api/process.md b/doc/api/process.md index b15d6db1b041be..80b1953d82a99d 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -6,6 +6,9 @@ The `process` object is a global object and can be accessed from anywhere. It 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 @@ -17,11 +20,17 @@ 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: '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. ## 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 @@ -46,6 +55,9 @@ process.on('exit', (code) => { ``` ## Event: 'message' + * `message` {Object} a parsed JSON object or primitive value * `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or @@ -55,6 +67,9 @@ Messages sent by [`ChildProcess.send()`][] are obtained using the `'message'` event on the child's process object. ## 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 @@ -96,6 +111,9 @@ 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' + 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 @@ -141,6 +159,9 @@ down the process. It is not safe to resume normal operation after `'uncaughtException'`. ## 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 @@ -192,6 +213,9 @@ this, you can either attach a dummy [`.catch(() => { })`][`promise.catch()`] han emitted, or you can use the [`'rejectionHandled'`][] event. ## Event: 'warning' + Emitted whenever Node.js emits a process warning. @@ -408,11 +432,17 @@ can be used to test for the existence of a process. Sending `SIGINT`, process. ## process.abort() + This causes Node.js to emit an abort. This will cause Node.js to exit and generate a core file. ## process.arch + What processor architecture you're running on: `'arm'`, `'ia32'`, or `'x64'`. @@ -421,6 +451,9 @@ console.log('This processor architecture is ' + process.arch); ``` ## process.argv + An array containing the command line arguments. The first element will be 'node', the second element will be the name of the JavaScript file. The @@ -445,6 +478,9 @@ $ node process-2.js one two=three four ``` ## process.chdir(directory) + Changes the current working directory of the process or throws an exception if that fails. @@ -460,6 +496,9 @@ catch (err) { ``` ## 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 @@ -499,12 +538,16 @@ 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 `process.connected` is `false`, it is no longer possible to send messages. ## 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 @@ -528,6 +571,9 @@ console.log(process.cpuUsage(startUsage)); ``` ## process.cwd() + Returns the current working directory of the process. @@ -536,6 +582,9 @@ console.log(`Current directory: ${process.cwd()}`); ``` ## process.disconnect() + Close the IPC channel to the parent process, allowing this child to exit gracefully once there are no other connections keeping it alive. @@ -546,6 +595,9 @@ If Node.js was not spawned with an IPC channel, `process.disconnect()` will be undefined. ## process.env + An object containing the user environment. See environ(7). @@ -604,6 +656,9 @@ console.log(process.env.TEST); ``` ## process.emitWarning(warning[, name][, ctor]) + * `warning` {String | Error} The warning to emit. * `name` {String} When `warning` is a String, `name` is the name to use @@ -690,6 +745,9 @@ emitMyWarning(); ``` ## 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 @@ -717,6 +775,9 @@ and process.argv: ``` ## process.execPath + This is the absolute pathname of the executable that started the process. @@ -728,6 +789,9 @@ Example: ## process.exit([code]) + * `code` {Integer} The exit code. Defaults to `0`. @@ -789,6 +853,9 @@ throwing an *uncaught* error and allowing the process to terminate accordingly is safer than calling `process.exit()`. ## process.exitCode + A number which will be the process exit code, when the process either exits gracefully, or is exited via [`process.exit()`][] without specifying @@ -799,6 +866,9 @@ previous setting of `process.exitCode`. ## process.getegid() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -814,6 +884,9 @@ if (process.getegid) { ## process.geteuid() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -828,6 +901,9 @@ if (process.geteuid) { ``` ## process.getgid() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -842,6 +918,9 @@ if (process.getgid) { ``` ## process.getgroups() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -850,6 +929,9 @@ 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.getuid() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -864,6 +946,9 @@ if (process.getuid) { ``` ## process.hrtime() + 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 @@ -888,6 +973,9 @@ setTimeout(() => { ## process.initgroups(user, extra_group) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -909,6 +997,9 @@ console.log(process.getgroups()); // [ 27, 30, 46, 1000 ] ``` ## 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 @@ -942,6 +1033,9 @@ Note: When SIGUSR1 is received by Node.js it starts 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 @@ -951,6 +1045,9 @@ 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() + Returns an object describing the memory usage of the Node.js process measured in bytes. @@ -973,6 +1070,9 @@ This will generate: ## process.nextTick(callback[, arg][, ...]) + * `callback` {Function} @@ -1059,6 +1159,9 @@ recursively setting nextTick callbacks will block any I/O from happening, just like a `while(true);` loop. ## process.pid + The PID of the process. @@ -1067,6 +1170,9 @@ console.log(`This process is pid ${process.pid}`); ``` ## process.platform + What platform you're running on: `'darwin'`, `'freebsd'`, `'linux'`, `'sunos'` or `'win32'` @@ -1076,6 +1182,9 @@ console.log(`This platform is ${process.platform}`); ``` ## process.release + An Object containing metadata related to the current release, including URLs for the source tarball and headers-only tarball. @@ -1109,6 +1218,9 @@ In custom builds from non-release versions of the source tree, only the relied upon to exist. ## process.send(message[, sendHandle[, options]][, callback]) + * `message` {Object} * `sendHandle` {Handle object} @@ -1125,6 +1237,9 @@ parent process using `process.send()`. Each will be received as a If Node.js was not spawned with an IPC channel, `process.send()` will be undefined. ## process.setegid(id) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -1147,6 +1262,9 @@ if (process.getegid && process.setegid) { ``` ## process.seteuid(id) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -1169,6 +1287,9 @@ if (process.geteuid && process.seteuid) { ``` ## process.setgid(id) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -1191,6 +1312,9 @@ if (process.getgid && process.setgid) { ``` ## process.setgroups(groups) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -1201,6 +1325,9 @@ 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) @@ -1300,6 +1427,9 @@ false See [the tty docs][] for more information. ## process.title + Getter/setter to set what is displayed in `ps`. @@ -1314,6 +1444,9 @@ 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 @@ -1329,10 +1462,16 @@ console.log( ## process.uptime() + Number of seconds Node.js has been running. ## process.version + A compiled-in property that exposes `NODE_VERSION`. @@ -1341,6 +1480,9 @@ console.log(`Version: ${process.version}`); ``` ## process.versions + A property exposing version strings of Node.js and its dependencies.