Interface Process

This feature is not available in Worker threads.

since

v0.7.0

import { chdir, cwd } from 'process';

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

This feature is not available in Worker threads.

since

v0.1.17

The result of a previous call to process.cpuUsage() can be passed as the argument to the function, to get a diff reading.

import { cpuUsage } from 'process';

const startUsage = cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(cpuUsage(startUsage));
// { user: 514883, system: 11226 }

since

v6.1.0

import { cwd } from 'process';

console.log(`Current directory: ${cwd()}`);

since

v0.1.8

The effect of calling process.disconnect() is the same as calling ChildProcess.disconnect() from the parent process.

If the Node.js process was not spawned with an IPC channel,process.disconnect() will be undefined.

since

v0.7.2

import { emitWarning } from 'process';

// Emit a warning with a code and additional detail.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information'
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information

In this example, an Error object is generated internally byprocess.emitWarning() and passed through to the 'warning' handler.

import process from 'process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});

If warning is passed as an Error object, the options argument is ignored.

since

v8.0.0

To exit with a 'failure' code:

import { exit } from 'process';

exit(1);

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

Calling process.exit() will force the process to exit as quickly as possible even if there are still asynchronous operations pending that have not yet completed fully, including I/O operations to process.stdout andprocess.stderr.

In most situations, it is not actually necessary to call process.exit()explicitly. The Node.js process will exit on its own if there is no additional work pending in the event loop. The process.exitCode property can be set to tell the process which exit code to use when the process exits gracefully.

For instance, the following example illustrates a misuse of theprocess.exit() method that could lead to data printed to stdout being truncated and lost:

import { exit } from 'process';

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}

The reason this is problematic is because writes to process.stdout in Node.js are sometimes asynchronous and may occur over multiple ticks of the Node.js event loop. Calling process.exit(), however, forces the process to exit_before_ those additional writes to stdout can be performed.

Rather than calling process.exit() directly, the code should set theprocess.exitCode and allow the process to exit naturally by avoiding scheduling any additional work for the event loop:

import process from 'process';

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

If it is necessary to terminate the Node.js process due to an error condition, throwing an uncaught error and allowing the process to terminate accordingly is safer than calling process.exit().

In Worker threads, this function stops the current thread rather than the current process.

since

v0.1.13

import process from 'process';

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}

This function is only available on POSIX platforms (i.e. not Windows or Android).

since

v2.0.0

import process from 'process';

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}

This function is only available on POSIX platforms (i.e. not Windows or Android).

since

v2.0.0

import process from 'process';

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}

This function is only available on POSIX platforms (i.e. not Windows or Android).

since

v0.1.31

import process from 'process';

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}

This function is only available on POSIX platforms (i.e. not Windows or Android).

since

v0.9.4

import process from 'process';

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}

This function is only available on POSIX platforms (i.e. not Windows or Android).

since

v0.1.28

since

v9.3.0

Signal names are strings such as 'SIGINT' or 'SIGHUP'. See Signal Events and kill(2) for more information.

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.

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.

import process, { kill } from 'process';

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

kill(process.pid, 'SIGHUP');

When SIGUSR1 is received by a Node.js process, Node.js will start the debugger. See Signal Events.

since

v0.0.6

import { nextTick } from 'process';

console.log('start');
nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callback

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:

import { nextTick } from 'process';

function MyThing(options) {
  this.setupOptions(options);

  nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.

It is very important for APIs to be either 100% synchronous or 100% asynchronous. Consider this example:

// WARNING!  DO NOT USE!  BAD UNSAFE HAZARD!
function maybeSync(arg, cb) {
  if (arg) {
    cb();
    return;
  }

  fs.stat('file', cb);
}

This API is hazardous because in the following case:

const maybeTrue = Math.random() > 0.5;

maybeSync(maybeTrue, () => {
  foo();
});

bar();

It is not clear whether foo() or bar() will be called first.

The following approach is much better:

import { nextTick } from 'process';

function definitelyAsync(arg, cb) {
  if (arg) {
    nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}

since

v0.1.26

console.log(resourceUsage()); /* Will output: { userCPUTime: 82872, systemCPUTime: 4143, maxRSS: 33164, sharedMemorySize: 0, unsharedDataSize: 0, unsharedStackSize: 0, minorPageFault: 2469, majorPageFault: 0, swappedOut: 0, fsRead: 0, fsWrite: 8, ipcSent: 0, ipcReceived: 0, signalsCount: 0, voluntaryContextSwitches: 79, involuntaryContextSwitches: 1 }

```

since

v12.6.0

If Node.js was not spawned with an IPC channel, process.send will beundefined.

The message goes through serialization and parsing. The resulting message might not be the same as what is originally sent.

since

v0.5.9

If such a function is set, the 'uncaughtException' event will not be emitted. If --abort-on-uncaught-exception was passed from the command line or set through v8.setFlagsFromString(), the process will not abort. Actions configured to take place on exceptions such as report generations will be affected too

To unset the capture function,process.setUncaughtExceptionCaptureCallback(null) may be used. Calling this method with a non-null argument while another capture function is set will throw an error.

Using this function is mutually exclusive with using the deprecated domain built-in module.

since

v9.3.0

import process from 'process';

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}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

since

v2.0.0

import process from 'process';

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}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

since

v2.0.0

import process from 'process';

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}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

since

v0.1.31

The groups array can contain numeric group IDs, group names, or both.

import process from 'process';

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501]);
    console.log(process.getgroups()); // new groups
  } catch (err) {
    console.log(`Failed to set groups: ${err}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

since

v0.9.4

import process from 'process';

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}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

since

v0.1.28

since

v0.1.19

deprecated

Calling process.umask() with no argument causes the process-wide umask to be written twice. This introduces a race condition between threads, and is a potential * security vulnerability. There is no safe, cross-platform alternative API.

The return value includes fractions of a second. Use Math.floor() to get whole seconds.

since

v0.5.0