Welcome to mirror list, hosted at ThFree Co, Russian Federation.

github.com/nodejs/node.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAntoine du Hamel <duhamelantoine1995@gmail.com>2022-04-20 11:23:41 +0300
committerMichaƫl Zasso <targos@protonmail.com>2022-04-28 07:56:14 +0300
commit3d65a3b13e61f136dc09027aa12473c2b3003725 (patch)
tree012259a22a22fec5325afd386bbae62e3293a09f /doc/api/child_process.md
parent46c880b99b4a74c3a7c99fdd824bf9ce22333987 (diff)
doc: add `node:` prefix for all core modules
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: https://github.com/nodejs/node/pull/42752 Fixes: https://github.com/nodejs/node/issues/38343 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Akhil Marsonya <akhil.marsonya27@gmail.com> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com> Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Diffstat (limited to 'doc/api/child_process.md')
-rw-r--r--doc/api/child_process.md90
1 files changed, 45 insertions, 45 deletions
diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index ad712eb8786..0f98613f729 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -6,12 +6,12 @@
<!-- source_link=lib/child_process.js -->
-The `child_process` module provides the ability to spawn subprocesses in
+The `node:child_process` module provides the ability to spawn subprocesses in
a manner that is similar, but not identical, to popen(3). This capability
is primarily provided by the [`child_process.spawn()`][] function:
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const ls = spawn('ls', ['-lh', '/usr']);
ls.stdout.on('data', (data) => {
@@ -54,8 +54,8 @@ without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
function provides equivalent functionality in a synchronous manner that blocks
the event loop until the spawned process either exits or is terminated.
-For convenience, the `child_process` module provides a handful of synchronous
-and asynchronous alternatives to [`child_process.spawn()`][] and
+For convenience, the `node:child_process` module provides a handful of
+synchronous and asynchronous alternatives to [`child_process.spawn()`][] and
[`child_process.spawnSync()`][]. Each of these alternatives are implemented on
top of [`child_process.spawn()`][] or [`child_process.spawnSync()`][].
@@ -110,7 +110,7 @@ spaces it needs to be quoted.
```js
// On Windows Only...
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const bat = spawn('cmd.exe', ['/c', 'my.bat']);
bat.stdout.on('data', (data) => {
@@ -128,7 +128,7 @@ bat.on('exit', (code) => {
```js
// OR...
-const { exec, spawn } = require('child_process');
+const { exec, spawn } = require('node:child_process');
exec('my.bat', (err, stdout, stderr) => {
if (err) {
console.error(err);
@@ -198,7 +198,7 @@ directly by the shell and special characters (vary based on
need to be dealt with accordingly:
```js
-const { exec } = require('child_process');
+const { exec } = require('node:child_process');
exec('"/path/to/test file/test.sh" arg1 arg2');
// Double quotes are used so that the space in the path is not interpreted as
@@ -226,7 +226,7 @@ stderr output. If `encoding` is `'buffer'`, or an unrecognized character
encoding, `Buffer` objects will be passed to the callback instead.
```js
-const { exec } = require('child_process');
+const { exec } = require('node:child_process');
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
if (error) {
console.error(`exec error: ${error}`);
@@ -252,8 +252,8 @@ rejected promise is returned, with the same `error` object given in the
callback, but with two additional properties `stdout` and `stderr`.
```js
-const util = require('util');
-const exec = util.promisify(require('child_process').exec);
+const util = require('node:util');
+const exec = util.promisify(require('node:child_process').exec);
async function lsExample() {
const { stdout, stderr } = await exec('ls');
@@ -268,7 +268,7 @@ If the `signal` option is enabled, calling `.abort()` on the corresponding
the error passed to the callback will be an `AbortError`:
```js
-const { exec } = require('child_process');
+const { exec } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
@@ -338,7 +338,7 @@ not spawned, behaviors such as I/O redirection and file globbing are not
supported.
```js
-const { execFile } = require('child_process');
+const { execFile } = require('node:child_process');
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
if (error) {
throw error;
@@ -362,8 +362,8 @@ rejected promise is returned, with the same `error` object given in the
callback, but with two additional properties `stdout` and `stderr`.
```js
-const util = require('util');
-const execFile = util.promisify(require('child_process').execFile);
+const util = require('node:util');
+const execFile = util.promisify(require('node:child_process').execFile);
async function getVersion() {
const { stdout } = await execFile('node', ['--version']);
console.log(stdout);
@@ -380,7 +380,7 @@ If the `signal` option is enabled, calling `.abort()` on the corresponding
the error passed to the callback will be an `AbortError`:
```js
-const { execFile } = require('child_process');
+const { execFile } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = execFile('node', ['--version'], { signal }, (error) => {
@@ -506,7 +506,7 @@ if (process.argv[2] === 'child') {
console.log(`Hello from ${process.argv[2]}!`);
}, 1_000);
} else {
- const { fork } = require('child_process');
+ const { fork } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = fork(__filename, ['child'], { signal });
@@ -625,7 +625,7 @@ Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const ls = spawn('ls', ['-lh', '/usr']);
ls.stdout.on('data', (data) => {
@@ -644,7 +644,7 @@ ls.on('close', (code) => {
Example: A very elaborate way to run `ps ax | grep ssh`
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);
@@ -681,7 +681,7 @@ grep.on('close', (code) => {
Example of checking for failed `spawn`:
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const subprocess = spawn('bad_command');
subprocess.on('error', (err) => {
@@ -702,7 +702,7 @@ If the `signal` option is enabled, calling `.abort()` on the corresponding
the error passed to the callback will be an `AbortError`:
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const grep = spawn('grep', ['ssh'], { signal });
@@ -745,7 +745,7 @@ Example of a long-running process, by detaching and also ignoring its parent
`stdio` file descriptors, in order to ignore the parent's termination:
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const subprocess = spawn(process.argv[0], ['child_program.js'], {
detached: true,
@@ -758,8 +758,8 @@ subprocess.unref();
Alternatively one can redirect the child process' output into files:
```js
-const fs = require('fs');
-const { spawn } = require('child_process');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
const out = fs.openSync('./out.log', 'a');
const err = fs.openSync('./out.log', 'a');
@@ -853,7 +853,7 @@ pipes between the parent and child. The value is one of the following:
default is `'ignore'`.
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
// Child will use parent's stdios.
spawn('prg', [], { stdio: 'inherit' });
@@ -1152,7 +1152,7 @@ streams. The `'close'` event will always emit after [`'exit'`][] was
already emitted, or [`'error'`][] if the child failed to spawn.
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const ls = spawn('ls', ['-lh', '/usr']);
ls.stdout.on('data', (data) => {
@@ -1348,7 +1348,7 @@ signal(7) for a list of available signals. This function returns `true` if
kill(2) succeeds, and `false` otherwise.
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const grep = spawn('grep', ['ssh']);
grep.on('close', (code, signal) => {
@@ -1382,7 +1382,7 @@ new process in a shell or with the use of the `shell` option of `ChildProcess`:
```js
'use strict';
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const subprocess = spawn(
'sh',
@@ -1427,7 +1427,7 @@ fails to spawn due to errors, then the value is `undefined` and `error` is
emitted.
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const grep = spawn('grep', ['ssh']);
console.log(`Spawned child pid: ${grep.pid}`);
@@ -1445,7 +1445,7 @@ restore the removed reference count for the child process, forcing the parent
to wait for the child to exit before exiting itself.
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const subprocess = spawn(process.argv[0], ['child_program.js'], {
detached: true,
@@ -1495,7 +1495,7 @@ message might not be the same as what is originally sent.
For example, in the parent script:
```js
-const cp = require('child_process');
+const cp = require('node:child_process');
const n = cp.fork(`${__dirname}/sub.js`);
n.on('message', (m) => {
@@ -1553,10 +1553,10 @@ The `sendHandle` argument can be used, for instance, to pass the handle of
a TCP server object to the child process as illustrated in the example below:
```js
-const subprocess = require('child_process').fork('subprocess.js');
+const subprocess = require('node:child_process').fork('subprocess.js');
// Open up the server object and send the handle.
-const server = require('net').createServer();
+const server = require('node:net').createServer();
server.on('connection', (socket) => {
socket.end('handled by parent');
});
@@ -1580,11 +1580,11 @@ process.on('message', (m, server) => {
Once the server is now shared between the parent and child, some connections
can be handled by the parent and some by the child.
-While the example above uses a server created using the `net` module, `dgram`
-module servers use exactly the same workflow with the exceptions of listening on
-a `'message'` event instead of `'connection'` and using `server.bind()` instead
-of `server.listen()`. This is, however, currently only supported on Unix
-platforms.
+While the example above uses a server created using the `node:net` module,
+`node:dgram` module servers use exactly the same workflow with the exceptions of
+listening on a `'message'` event instead of `'connection'` and using
+`server.bind()` instead of `server.listen()`. This is, however, currently only
+supported on Unix platforms.
#### Example: sending a socket object
@@ -1593,13 +1593,13 @@ socket to the child process. The example below spawns two children that each
handle connections with "normal" or "special" priority:
```js
-const { fork } = require('child_process');
+const { fork } = require('node:child_process');
const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);
// Open up the server and send sockets to child. Use pauseOnConnect to prevent
// the sockets from being read before they are sent to the child process.
-const server = require('net').createServer({ pauseOnConnect: true });
+const server = require('node:net').createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {
// If this is special priority...
@@ -1724,9 +1724,9 @@ pipe, so only the parent's `subprocess.stdio[1]` is a stream, all other values
in the array are `null`.
```js
-const assert = require('assert');
-const fs = require('fs');
-const child_process = require('child_process');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const child_process = require('node:child_process');
const subprocess = child_process.spawn('ls', {
stdio: [
@@ -1766,7 +1766,7 @@ then this will be `null`.
refer to the same value.
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const subprocess = spawn('ls');
@@ -1792,7 +1792,7 @@ independently of the child, unless there is an established IPC channel between
the child and the parent.
```js
-const { spawn } = require('child_process');
+const { spawn } = require('node:child_process');
const subprocess = spawn(process.argv[0], ['child_program.js'], {
detached: true,
@@ -1833,7 +1833,7 @@ added:
-->
Child processes support a serialization mechanism for IPC that is based on the
-[serialization API of the `v8` module][v8.serdes], based on the
+[serialization API of the `node:v8` module][v8.serdes], based on the
[HTML structured clone algorithm][]. This is generally more powerful and
supports more built-in JavaScript object types, such as `BigInt`, `Map`
and `Set`, `ArrayBuffer` and `TypedArray`, `Buffer`, `Error`, `RegExp` etc.