From d0ec6e8f02a26a6ebf25479ac7ee16ca3ccb731f 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 | 132 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/doc/api/process.md b/doc/api/process.md index f4a31a85806e1c..c878cb2da778b1 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,6 +20,9 @@ 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' + 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 @@ -41,6 +47,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 @@ -50,6 +59,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 `.catch()`) later than after an event loop turn. This event @@ -91,6 +103,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 @@ -136,6 +151,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 @@ -289,11 +307,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'`. @@ -302,6 +326,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 @@ -326,6 +353,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. @@ -341,6 +371,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 @@ -380,12 +413,18 @@ 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.cwd() + Returns the current working directory of the process. @@ -394,6 +433,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. @@ -404,6 +446,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). @@ -462,6 +507,9 @@ console.log(process.env.TEST); ``` ## 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 @@ -489,6 +537,9 @@ and process.argv: ``` ## process.execPath + This is the absolute pathname of the executable that started the process. @@ -500,6 +551,9 @@ Example: ## process.exit([code]) + Ends the process with the specified `code`. If omitted, exit uses the 'success' code `0`. @@ -514,6 +568,9 @@ The shell that executed Node.js should see the exit code as 1. ## 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 @@ -524,6 +581,9 @@ setting of `process.exitCode`. ## process.getegid() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -539,6 +599,9 @@ if (process.getegid) { ## process.geteuid() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -553,6 +616,9 @@ if (process.geteuid) { ``` ## process.getgid() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -567,6 +633,9 @@ if (process.getgid) { ``` ## process.getgroups() + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -575,6 +644,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) @@ -589,6 +661,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 @@ -613,6 +688,9 @@ setTimeout(() => { ## process.initgroups(user, extra_group) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -634,6 +712,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 @@ -667,6 +748,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 @@ -676,6 +760,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. @@ -698,6 +785,9 @@ This will generate: ## process.nextTick(callback[, arg][, ...]) + * `callback` {Function} @@ -785,6 +875,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. @@ -793,6 +886,9 @@ console.log(`This process is pid ${process.pid}`); ``` ## process.platform + What platform you're running on: `'darwin'`, `'freebsd'`, `'linux'`, `'sunos'` or `'win32'` @@ -802,6 +898,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. @@ -835,6 +934,9 @@ In custom builds from non-release versions of the source tree, only the relied upon to exist. ## process.send(message[, sendHandle][, callback]) + * `message` {Object} * `sendHandle` {Handle object} @@ -850,6 +952,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) @@ -872,6 +977,9 @@ if (process.getegid && process.setegid) { ``` ## process.seteuid(id) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -894,6 +1002,9 @@ if (process.geteuid && process.seteuid) { ``` ## process.setgid(id) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -916,6 +1027,9 @@ if (process.getgid && process.setgid) { ``` ## process.setgroups(groups) + Note: this function is only available on POSIX platforms (i.e. not Windows, Android) @@ -926,6 +1040,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) @@ -1033,6 +1150,9 @@ false See [the tty docs][] for more information. ## process.title + Getter/setter to set what is displayed in `ps`. @@ -1047,6 +1167,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 @@ -1062,10 +1185,16 @@ console.log( ## process.uptime() + Number of seconds Node.js has been running. ## process.version + A compiled-in property that exposes `NODE_VERSION`. @@ -1074,6 +1203,9 @@ console.log(`Version: ${process.version}`); ``` ## process.versions + A property exposing version strings of Node.js and its dependencies.