175 lines
8.4 KiB
Haxe
175 lines
8.4 KiB
Haxe
package node.child_process;
|
|
|
|
/**
|
|
Spawns a shell then executes the `command` within that shell, buffering any
|
|
generated output. The `command` string passed to the exec function is processed
|
|
directly by the shell and special characters (vary based on [shell](https://en.wikipedia.org/wiki/List_of_command-line_interpreters))
|
|
need to be dealt with accordingly:
|
|
|
|
```js
|
|
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
|
|
// a delimiter of multiple arguments.
|
|
|
|
exec('echo "The \\$HOME variable is $HOME"');
|
|
// The $HOME variable is escaped in the first instance, but not in the second.
|
|
```
|
|
|
|
**Never pass unsanitized user input to this function. Any input containing shell**
|
|
**metacharacters may be used to trigger arbitrary command execution.**
|
|
|
|
If a `callback` function is provided, it is called with the arguments`(error, stdout, stderr)`. On success, `error` will be `null`. On error,`error` will be an instance of `Error`. The
|
|
`error.code` property will be
|
|
the exit code of the process. By convention, any exit code other than `0`indicates an error. `error.signal` will be the signal that terminated the
|
|
process.
|
|
|
|
The `stdout` and `stderr` arguments passed to the callback will contain the
|
|
stdout and stderr output of the child process. By default, Node.js will decode
|
|
the output as UTF-8 and pass strings to the callback. The `encoding` option
|
|
can be used to specify the character encoding used to decode the stdout and
|
|
stderr output. If `encoding` is `'buffer'`, or an unrecognized character
|
|
encoding, `Buffer` objects will be passed to the callback instead.
|
|
|
|
```js
|
|
const { exec } = require('node:child_process');
|
|
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
|
|
if (error) {
|
|
console.error(`exec error: ${error}`);
|
|
return;
|
|
}
|
|
console.log(`stdout: ${stdout}`);
|
|
console.error(`stderr: ${stderr}`);
|
|
});
|
|
```
|
|
|
|
If `timeout` is greater than `0`, the parent will send the signal
|
|
identified by the `killSignal` property (the default is `'SIGTERM'`) if the
|
|
child runs longer than `timeout` milliseconds.
|
|
|
|
Unlike the [`exec(3)`](http://man7.org/linux/man-pages/man3/exec.3.html) POSIX system call, `child_process.exec()` does not replace
|
|
the existing process and uses a shell to execute the command.
|
|
|
|
If this method is invoked as its `util.promisify()` ed version, it returns
|
|
a `Promise` for an `Object` with `stdout` and `stderr` properties. The returned`ChildProcess` instance is attached to the `Promise` as a `child` property. In
|
|
case of an error (including any error resulting in an exit code other than 0), a
|
|
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('node:util');
|
|
const exec = util.promisify(require('node:child_process').exec);
|
|
|
|
async function lsExample() {
|
|
const { stdout, stderr } = await exec('ls');
|
|
console.log('stdout:', stdout);
|
|
console.error('stderr:', stderr);
|
|
}
|
|
lsExample();
|
|
```
|
|
|
|
If the `signal` option is enabled, calling `.abort()` on the corresponding`AbortController` is similar to calling `.kill()` on the child process except
|
|
the error passed to the callback will be an `AbortError`:
|
|
|
|
```js
|
|
const { exec } = require('node:child_process');
|
|
const controller = new AbortController();
|
|
const { signal } = controller;
|
|
const child = exec('grep ssh', { signal }, (error) => {
|
|
console.error(error); // an AbortError
|
|
});
|
|
controller.abort();
|
|
```
|
|
**/
|
|
@:jsRequire("child_process", "exec") @valueModuleOnly extern class Exec {
|
|
/**
|
|
Spawns a shell then executes the `command` within that shell, buffering any
|
|
generated output. The `command` string passed to the exec function is processed
|
|
directly by the shell and special characters (vary based on [shell](https://en.wikipedia.org/wiki/List_of_command-line_interpreters))
|
|
need to be dealt with accordingly:
|
|
|
|
```js
|
|
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
|
|
// a delimiter of multiple arguments.
|
|
|
|
exec('echo "The \\$HOME variable is $HOME"');
|
|
// The $HOME variable is escaped in the first instance, but not in the second.
|
|
```
|
|
|
|
**Never pass unsanitized user input to this function. Any input containing shell**
|
|
**metacharacters may be used to trigger arbitrary command execution.**
|
|
|
|
If a `callback` function is provided, it is called with the arguments`(error, stdout, stderr)`. On success, `error` will be `null`. On error,`error` will be an instance of `Error`. The
|
|
`error.code` property will be
|
|
the exit code of the process. By convention, any exit code other than `0`indicates an error. `error.signal` will be the signal that terminated the
|
|
process.
|
|
|
|
The `stdout` and `stderr` arguments passed to the callback will contain the
|
|
stdout and stderr output of the child process. By default, Node.js will decode
|
|
the output as UTF-8 and pass strings to the callback. The `encoding` option
|
|
can be used to specify the character encoding used to decode the stdout and
|
|
stderr output. If `encoding` is `'buffer'`, or an unrecognized character
|
|
encoding, `Buffer` objects will be passed to the callback instead.
|
|
|
|
```js
|
|
const { exec } = require('node:child_process');
|
|
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
|
|
if (error) {
|
|
console.error(`exec error: ${error}`);
|
|
return;
|
|
}
|
|
console.log(`stdout: ${stdout}`);
|
|
console.error(`stderr: ${stderr}`);
|
|
});
|
|
```
|
|
|
|
If `timeout` is greater than `0`, the parent will send the signal
|
|
identified by the `killSignal` property (the default is `'SIGTERM'`) if the
|
|
child runs longer than `timeout` milliseconds.
|
|
|
|
Unlike the [`exec(3)`](http://man7.org/linux/man-pages/man3/exec.3.html) POSIX system call, `child_process.exec()` does not replace
|
|
the existing process and uses a shell to execute the command.
|
|
|
|
If this method is invoked as its `util.promisify()` ed version, it returns
|
|
a `Promise` for an `Object` with `stdout` and `stderr` properties. The returned`ChildProcess` instance is attached to the `Promise` as a `child` property. In
|
|
case of an error (including any error resulting in an exit code other than 0), a
|
|
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('node:util');
|
|
const exec = util.promisify(require('node:child_process').exec);
|
|
|
|
async function lsExample() {
|
|
const { stdout, stderr } = await exec('ls');
|
|
console.log('stdout:', stdout);
|
|
console.error('stderr:', stderr);
|
|
}
|
|
lsExample();
|
|
```
|
|
|
|
If the `signal` option is enabled, calling `.abort()` on the corresponding`AbortController` is similar to calling `.kill()` on the child process except
|
|
the error passed to the callback will be an `AbortError`:
|
|
|
|
```js
|
|
const { exec } = require('node:child_process');
|
|
const controller = new AbortController();
|
|
const { signal } = controller;
|
|
const child = exec('grep ssh', { signal }, (error) => {
|
|
console.error(error); // an AbortError
|
|
});
|
|
controller.abort();
|
|
```
|
|
**/
|
|
@:overload(function(command:String, options:{ var encoding : Null<String>; } & ExecOptions, ?callback:(error:Null<ExecException>, stdout:node.buffer.Buffer, stderr:node.buffer.Buffer) -> Void):ChildProcess { })
|
|
@:overload(function(command:String, options:{ var encoding : global.nodejs.BufferEncoding; } & ExecOptions, ?callback:(error:Null<ExecException>, stdout:String, stderr:String) -> Void):ChildProcess { })
|
|
@:overload(function(command:String, options:{ var encoding : global.nodejs.BufferEncoding; } & ExecOptions, ?callback:(error:Null<ExecException>, stdout:ts.AnyOf2<String, node.buffer.Buffer>, stderr:ts.AnyOf2<String, node.buffer.Buffer>) -> Void):ChildProcess { })
|
|
@:overload(function(command:String, options:ExecOptions, ?callback:(error:Null<ExecException>, stdout:String, stderr:String) -> Void):ChildProcess { })
|
|
@:overload(function(command:String, options:Null<node.fs.ObjectEncodingOptions & ExecOptions>, ?callback:(error:Null<ExecException>, stdout:ts.AnyOf2<String, node.buffer.Buffer>, stderr:ts.AnyOf2<String, node.buffer.Buffer>) -> Void):ChildProcess { })
|
|
@:selfCall
|
|
static function call(command:String, ?callback:(error:Null<ExecException>, stdout:String, stderr:String) -> Void):ChildProcess;
|
|
} |