diff options
author | Antoine du Hamel <duhamelantoine1995@gmail.com> | 2022-04-20 11:23:41 +0300 |
---|---|---|
committer | Michaƫl Zasso <targos@protonmail.com> | 2022-04-28 07:56:14 +0300 |
commit | 3d65a3b13e61f136dc09027aa12473c2b3003725 (patch) | |
tree | 012259a22a22fec5325afd386bbae62e3293a09f /doc/api/child_process.md | |
parent | 46c880b99b4a74c3a7c99fdd824bf9ce22333987 (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.md | 90 |
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. |