Lines Matching full:path
11 "desc": "<p><strong>Source Code:</strong> <a href=\"https://github.com/nodejs/node/blob/v18.20.1/lib/child_process.js\">lib/child_process.js</a></p>\n<p>The <code>node:child_process</code> module provides the ability to spawn subprocesses in\na manner that is similar, but not identical, to <a href=\"http://man7.org/linux/man-pages/man3/popen.3.html\"><code>popen(3)</code></a>. This capability\nis primarily provided by the <a href=\"#child_processspawncommand-args-options\"><code>child_process.spawn()</code></a> function:</p>\n<pre><code class=\"language-js\">const { spawn } = require('node:child_process');\nconst ls = spawn('ls', ['-lh', '/usr']);\n\nls.stdout.on('data', (data) => {\n console.log(`stdout: ${data}`);\n});\n\nls.stderr.on('data', (data) => {\n console.error(`stderr: ${data}`);\n});\n\nls.on('close', (code) => {\n console.log(`child process exited with code ${code}`);\n});\n</code></pre>\n<p>By default, pipes for <code>stdin</code>, <code>stdout</code>, and <code>stderr</code> are established between\nthe parent Node.js process and the spawned subprocess. These pipes have\nlimited (and platform-specific) capacity. If the subprocess writes to\nstdout in excess of that limit without the output being captured, the\nsubprocess blocks waiting for the pipe buffer to accept more data. This is\nidentical to the behavior of pipes in the shell. Use the <code>{ stdio: 'ignore' }</code>\noption if the output will not be consumed.</p>\n<p>The command lookup is performed using the <code>options.env.PATH</code> environment\nvariable if <code>env</code> is in the <code>options</code> object. Otherwise, <code>process.env.PATH</code> is\nused. If <code>options.env</code> is set without <code>PATH</code>, lookup on Unix is performed\non a default search path search of <code>/usr/bin:/bin</code> (see your operating system's\nmanual for execvpe/execvp), on Windows the current processes environment\nvariable <code>PATH</code> is used.</p>\n<p>On Windows, environment variables are case-insensitive. Node.js\nlexicographically sorts the <code>env</code> keys and uses the first one that\ncase-insensitively matches. Only first (in lexicographic order) entry will be\npassed to the subprocess. This might lead to issues on Windows when passing\nobjects to the <code>env</code> option that have multiple variants of the same key, such as\n<code>PATH</code> and <code>Path</code>.</p>\n<p>The <a href=\"#child_processspawncommand-args-options\"><code>child_process.spawn()</code></a> method spawns the child process asynchronously,\nwithout blocking the Node.js event loop. The <a href=\"#child_processspawnsynccommand-args-options\"><code>child_process.spawnSync()</code></a>\nfunction provides equivalent functionality in a synchronous manner that blocks\nthe event loop until the spawned process either exits or is terminated.</p>\n<p>For convenience, the <code>node:child_process</code> module provides a handful of\nsynchronous and asynchronous alternatives to <a href=\"#child_processspawncommand-args-options\"><code>child_process.spawn()</code></a> and\n<a href=\"#child_processspawnsynccommand-args-options\"><code>child_process.spawnSync()</code></a>. Each of these alternatives are implemented on\ntop of <a href=\"#child_processspawncommand-args-options\"><code>child_process.spawn()</code></a> or <a href=\"#child_processspawnsynccommand-args-options\"><code>child_process.spawnSync()</code></a>.</p>\n<ul>\n<li><a href=\"#child_processexeccommand-options-callback\"><code>child_process.exec()</code></a>: spawns a shell and runs a command within that\nshell, passing the <code>stdout</code> and <code>stderr</code> to a callback function when\ncomplete.</li>\n<li><a href=\"#child_processexecfilefile-args-options-callback\"><code>child_process.execFile()</code></a>: similar to <a href=\"#child_processexeccommand-options-callback\"><code>child_process.exec()</code></a> except\nthat it spawns the command directly without first spawning a shell by\ndefault.</li>\n<li><a href=\"#child_processforkmodulepath-args-options\"><code>child_process.fork()</code></a>: spawns a new Node.js process and invokes a\nspecified module with an IPC communication channel established that allows\nsending messages between parent and child.</li>\n<li><a href=\"#child_processexecsynccommand-options\"><code>child_process.execSync()</code></a>: a synchronous version of\n<a href=\"#child_processexeccommand-options-callback\"><code>child_process.exec()</code></a> that will block the Node.js event loop.</li>\n<li><a href=\"#child_processexecfilesyncfile-args-options\"><code>child_process.execFileSync()</code></a>: a synchronous version of\n<a href=\"#child_processexecfilefile-args-options-callback\"><code>child_process.execFile()</code></a> that will block the Node.js event loop.</li>\n</ul>\n<p>For certain use cases, such as automating shell scripts, the\n<a href=\"#synchronous-process-creation\">synchronous counterparts</a> may be more convenient. In many cases, however,\nthe synchronous methods can have significant impact on performance due to\nstalling the event loop while spawned processes complete.</p>",
174 "desc": "<p>Spawns a shell then executes the <code>command</code> within that shell, buffering any\ngenerated output. The <code>command</code> string passed to the exec function is processed\ndirectly by the shell and special characters (vary based on\n<a href=\"https://en.wikipedia.org/wiki/List_of_command-line_interpreters\">shell</a>)\nneed to be dealt with accordingly:</p>\n<pre><code class=\"language-js\">const { exec } = require('node:child_process');\n\nexec('\"/path/to/test file/test.sh\" arg1 arg2');\n// Double quotes are used so that the space in the path is not interpreted as\n// a delimiter of multiple arguments.\n\nexec('echo \"The \\\\$HOME variable is $HOME\"');\n// The $HOME variable is escaped in the first instance, but not in the second.\n</code></pre>\n<p><strong>Never pass unsanitized user input to this function. Any input containing shell\nmetacharacters may be used to trigger arbitrary command execution.</strong></p>\n<p>If a <code>callback</code> function is provided, it is called with the arguments\n<code>(error, stdout, stderr)</code>. On success, <code>error</code> will be <code>null</code>. On error,\n<code>error</code> will be an instance of <a href=\"errors.html#class-error\"><code>Error</code></a>. The <code>error.code</code> property will be\nthe exit code of the process. By convention, any exit code other than <code>0</code>\nindicates an error. <code>error.signal</code> will be the signal that terminated the\nprocess.</p>\n<p>The <code>stdout</code> and <code>stderr</code> arguments passed to the callback will contain the\nstdout and stderr output of the child process. By default, Node.js will decode\nthe output as UTF-8 and pass strings to the callback. The <code>encoding</code> option\ncan be used to specify the character encoding used to decode the stdout and\nstderr output. If <code>encoding</code> is <code>'buffer'</code>, or an unrecognized character\nencoding, <code>Buffer</code> objects will be passed to the callback instead.</p>\n<pre><code class=\"language-js\">const { exec } = require('node:child_process');\nexec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {\n if (error) {\n console.error(`exec error: ${error}`);\n return;\n }\n console.log(`stdout: ${stdout}`);\n console.error(`stderr: ${stderr}`);\n});\n</code></pre>\n<p>If <code>timeout</code> is greater than <code>0</code>, the parent will send the signal\nidentified by the <code>killSignal</code> property (the default is <code>'SIGTERM'</code>) if the\nchild runs longer than <code>timeout</code> milliseconds.</p>\n<p>Unlike the <a href=\"http://man7.org/linux/man-pages/man3/exec.3.html\"><code>exec(3)</code></a> POSIX system call, <code>child_process.exec()</code> does not replace\nthe existing process and uses a shell to execute the command.</p>\n<p>If this method is invoked as its <a href=\"util.html#utilpromisifyoriginal\"><code>util.promisify()</code></a>ed version, it returns\na <code>Promise</code> for an <code>Object</code> with <code>stdout</code> and <code>stderr</code> properties. The returned\n<code>ChildProcess</code> instance is attached to the <code>Promise</code> as a <code>child</code> property. In\ncase of an error (including any error resulting in an exit code other than 0), a\nrejected promise is returned, with the same <code>error</code> object given in the\ncallback, but with two additional properties <code>stdout</code> and <code>stderr</code>.</p>\n<pre><code class=\"language-js\">const util = require('node:util');\nconst exec = util.promisify(require('node:child_process').exec);\n\nasync function lsExample() {\n const { stdout, stderr } = await exec('ls');\n console.log('stdout:', stdout);\n console.error('stderr:', stderr);\n}\nlsExample();\n</code></pre>\n<p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding\n<code>AbortController</code> is similar to calling <code>.kill()</code> on the child process except\nthe error passed to the callback will be an <code>AbortError</code>:</p>\n<pre><code class=\"language-js\">const { exec } = require('node:child_process');\nconst controller = new AbortController();\nconst { signal } = controller;\nconst child = exec('grep ssh', { signal }, (error) => {\n console.error(error); // an AbortError\n});\ncontroller.abort();\n</code></pre>"
217 "textRaw": "`file` {string} The name or path of the executable file to run.",
220 "desc": "The name or path of the executable file to run."
530 "desc": "<p>The <code>child_process.fork()</code> method is a special case of\n<a href=\"#child_processspawncommand-args-options\"><code>child_process.spawn()</code></a> used specifically to spawn new Node.js processes.\nLike <a href=\"#child_processspawncommand-args-options\"><code>child_process.spawn()</code></a>, a <a href=\"#class-childprocess\"><code>ChildProcess</code></a> object is returned. The\nreturned <a href=\"#class-childprocess\"><code>ChildProcess</code></a> will have an additional communication channel\nbuilt-in that allows messages to be passed back and forth between the parent and\nchild. See <a href=\"#subprocesssendmessage-sendhandle-options-callback\"><code>subprocess.send()</code></a> for details.</p>\n<p>Keep in mind that spawned Node.js child processes are\nindependent of the parent with exception of the IPC communication channel\nthat is established between the two. Each process has its own memory, with\ntheir own V8 instances. Because of the additional resource allocations\nrequired, spawning a large number of child Node.js processes is not\nrecommended.</p>\n<p>By default, <code>child_process.fork()</code> will spawn new Node.js instances using the\n<a href=\"process.html#processexecpath\"><code>process.execPath</code></a> of the parent process. The <code>execPath</code> property in the\n<code>options</code> object allows for an alternative execution path to be used.</p>\n<p>Node.js processes launched with a custom <code>execPath</code> will communicate with the\nparent process using the file descriptor (fd) identified using the\nenvironment variable <code>NODE_CHANNEL_FD</code> on the child process.</p>\n<p>Unlike the <a href=\"http://man7.org/linux/man-pages/man2/fork.2.html\"><code>fork(2)</code></a> POSIX system call, <code>child_process.fork()</code> does not clone the\ncurrent process.</p>\n<p>The <code>shell</code> option available in <a href=\"#child_processspawncommand-args-options\"><code>child_process.spawn()</code></a> is not supported by\n<code>child_process.fork()</code> and will be ignored if set.</p>\n<p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding\n<code>AbortController</code> is similar to calling <code>.kill()</code> on the child process except\nthe error passed to the callback will be an <code>AbortError</code>:</p>\n<pre><code class=\"language-js\">if (process.argv[2] === 'child') {\n setTimeout(() => {\n console.log(`Hello from ${process.argv[2]}!`);\n }, 1_000);\n} else {\n const { fork } = require('node:child_process');\n const controller = new AbortController();\n const { signal } = controller;\n const child = fork(__filename, ['child'], { signal });\n child.on('error', (err) => {\n // This will be called with err being an AbortError if the controller aborts\n });\n controller.abort(); // Stops the child process\n}\n</code></pre>"
719 "desc": "<p>The <code>child_process.spawn()</code> method spawns a new process using the given\n<code>command</code>, with command-line arguments in <code>args</code>. If omitted, <code>args</code> defaults\nto an empty array.</p>\n<p><strong>If the <code>shell</code> option is enabled, do not pass unsanitized user input to this\nfunction. Any input containing shell metacharacters may be used to trigger\narbitrary command execution.</strong></p>\n<p>A third argument may be used to specify additional options, with these defaults:</p>\n<pre><code class=\"language-js\">const defaults = {\n cwd: undefined,\n env: process.env,\n};\n</code></pre>\n<p>Use <code>cwd</code> to specify the working directory from which the process is spawned.\nIf not given, the default is to inherit the current working directory. If given,\nbut the path does not exist, the child process emits an <code>ENOENT</code> error\nand exits immediately. <code>ENOENT</code> is also emitted when the command\ndoes not exist.</p>\n<p>Use <code>env</code> to specify environment variables that will be visible to the new\nprocess, the default is <a href=\"process.html#processenv\"><code>process.env</code></a>.</p>\n<p><code>undefined</code> values in <code>env</code> will be ignored.</p>\n<p>Example of running <code>ls -lh /usr</code>, capturing <code>stdout</code>, <code>stderr</code>, and the\nexit code:</p>\n<pre><code class=\"language-js\">const { spawn } = require('node:child_process');\nconst ls = spawn('ls', ['-lh', '/usr']);\n\nls.stdout.on('data', (data) => {\n console.log(`stdout: ${data}`);\n});\n\nls.stderr.on('data', (data) => {\n console.error(`stderr: ${data}`);\n});\n\nls.on('close', (code) => {\n console.log(`child process exited with code ${code}`);\n});\n</code></pre>\n<p>Example: A very elaborate way to run <code>ps ax | grep ssh</code></p>\n<pre><code class=\"language-js\">const { spawn } = require('node:child_process');\nconst ps = spawn('ps', ['ax']);\nconst grep = spawn('grep', ['ssh']);\n\nps.stdout.on('data', (data) => {\n grep.stdin.write(data);\n});\n\nps.stderr.on('data', (data) => {\n console.error(`ps stderr: ${data}`);\n});\n\nps.on('close', (code) => {\n if (code !== 0) {\n console.log(`ps process exited with code ${code}`);\n }\n grep.stdin.end();\n});\n\ngrep.stdout.on('data', (data) => {\n console.log(data.toString());\n});\n\ngrep.stderr.on('data', (data) => {\n console.error(`grep stderr: ${data}`);\n});\n\ngrep.on('close', (code) => {\n if (code !== 0) {\n console.log(`grep process exited with code ${code}`);\n }\n});\n</code></pre>\n<p>Example of checking for failed <code>spawn</code>:</p>\n<pre><code class=\"language-js\">const { spawn } = require('node:child_process');\nconst subprocess = spawn('bad_command');\n\nsubprocess.on('error', (err) => {\n console.error('Failed to start subprocess.');\n});\n</code></pre>\n<p>Certain platforms (macOS, Linux) will use the value of <code>argv[0]</code> for the process\ntitle while others (Windows, SunOS) will use <code>command</code>.</p>\n<p>Node.js overwrites <code>argv[0]</code> with <code>process.execPath</code> on startup, so\n<code>process.argv[0]</code> in a Node.js child process will not match the <code>argv0</code>\nparameter passed to <code>spawn</code> from the parent. Retrieve it with the\n<code>process.argv0</code> property instead.</p>\n<p>If the <code>signal</code> option is enabled, calling <code>.abort()</code> on the corresponding\n<code>AbortController</code> is similar to calling <code>.kill()</code> on the child process except\nthe error passed to the callback will be an <code>AbortError</code>:</p>\n<pre><code class=\"language-js\">const { spawn } = require('node:child_process');\nconst controller = new AbortController();\nconst { signal } = controller;\nconst grep = spawn('grep', ['ssh'], { signal });\ngrep.on('error', (err) => {\n // This will be called with err being an AbortError if the controller aborts\n});\ncontroller.abort(); // Stops the child process\n</code></pre>",
820 "textRaw": "`file` {string} The name or path of the executable file to run.",
823 "desc": "The name or path of the executable file to run."
1300 "desc": "<p>Although Microsoft specifies <code>%COMSPEC%</code> must contain the path to\n<code>'cmd.exe'</code> in the root environment, child processes are not always subject to\nthe same requirement. Thus, in <code>child_process</code> functions where a shell can be\nspawned, <code>'cmd.exe'</code> is used as a fallback if <code>process.env.ComSpec</code> is\nunavailable.</p>",