12. SubProcess
The subprocess object is a built-in object that provides process communication functions between external applications using pipes.
Functional overview:
- Provides the ability to respectively pipe standard input (stdin), standard output (stdout), and standard error output (stderr) of an external application and send and receive data in real time.
- Provides the function to send specific signals to external applications.
- Provides the function to retrieve the exit code of an external application.
Limitations:
- The number of command execution resources that can be used is 3.
subprocess Global Object
Methods()/Properties | Summary | Version | Note |
---|---|---|---|
subprocess.create() | Creates a command execution instance. |
subprocess.create(cmd[,options])
Creates a command execution instance.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
cmd | string | mandatory | Specify the command execution path. If command arguments are required, specify them separated by spaces after the command execution path. If a string containing a space character is to be treated as a single argument, enclose the target string range in single ' or double " quotes.The maximum number of command characters is 4095 and the maximum number of command argument including command execution path is 31 .Ex) date , uname -a , ls -l /tmp ,cat /tmp/memo.txt , tail -f /tmp/memo.txt ,/usr/bin/myApp "hello world" ,/home/user/start.sh "abc" 1 2 3 | Using redirects or pipes to execute multiple commands in combination is not supported. |
options | Object | optional | Options Refer to Options for details. | |
return | {Exec}, null | - | {Exec} : Generated {Exec} null : If instance creation fails due to lack of resources | If the parameter is abnormal, an exception occurs. |
Options
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
readBuffSize | number | optional | Read buffer size [Byte] Range: 1 - 2,147,483,647 The default value is 4096. | |
abortSigNo | number | optional | Signal number for forced termination Specify the signal number to be sent when forcibly aborting the command execution process by .abort() method call, etc. Note that the execution process must always be terminable by this signal number. Range: 1 (SIGHUP), 2 (SIGINT), 9 (SIGKILL), 15 (SIGTERM)The default value is 15 (SIGTERM). |
{Exec}
Methods()/Properties | Summary | Version | Note |
---|---|---|---|
.on() | Registers an event handler. | ||
.execute() | Starts command execution. | ||
.read() | Reads standard output (stdout) data received from the command execution process. | ||
.readError() | Reads standard error output (stderr) data received from the command execution process. | ||
.write() | Sends data to the standard input (stdin) of the command execution process. | ||
.sendSignal() | Sends the specified signal to the command execution process. | ||
.isBusy() | Gets the execution status of the command execution process. | ||
.getResult() | Gets the exit code of the command execution process. | ||
.abort() | Aborts the command execution process forcibly. | ||
.release() | Releases a command execution resource. |
Details
.on(event,callback)
Registers an event handler.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
event | string | mandatory | Event name Names that can be used are: stdout, stderr, exit | |
callback | function | mandatory | Executes callback processing when an event occurs. | |
return | undefined | - | - | If the parameter is abnormal, an exception occurs. |
event : ’stdout’
Executes callback processing when standard output (stdout) data is received from the command execution process and data is stored in the read buffer.
event : ’stderr’
Executes callback processing when standard error output (stderr) data is received from the command execution process and the data is stored in the read buffer.
event : ’exit’
Executes callback processing when the command execution process is exited.
Note that if the process exits with data in the standard output (stdout) and standard error output (stderr) read buffers, the callback process will not be executed immediately. It is necessary to read all data with the .read() and/or .readError() method.
.execute()
Starts command execution.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
return | boolean | - | true: Success false: Failure |
.read([isBin])
Reads standard output (stdout) data received from the command execution process.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
isBin | boolean | optional | Specify the readout data format. true: Readout in binary data format false: Readout in string format The default value is false. | |
return | ArrayBuffer, string | - | Readout data The return type is determined by isBin. If isBin is true, the type is ArrayBuffer; otherwise, the type is string. | The readout data will be less than or equal to the size specified by readBuffSize. If there is no readout data, the size will be 0. If the parameter is abnormal, an exception occurs. |
.readError([isBin])
Reads standard error output (stderr) data received from the command execution process.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
isBin | boolean | optional | Specify the readout data format. true: Readout in binary data format false: Readout in string format The default value is false. | |
return | ArrayBuffer, string | - | Readout data The return type is determined by isBin. If isBin is true, the type is ArrayBuffer; otherwise, the type is string. | The readout data will be less than or equal to the size specified by readBuffSize. If there is no readout data, the size will be 0. If the parameter is abnormal, an exception occurs. |
.write(data)
Sends data to the standard input (stdin) of the command execution process.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
data | string, ArrayBuffer | mandatory | Sent data | |
return | number | - | Sent data size If the sending fails, -1 is returned. | If the parameter is abnormal, an exception occurs. |
.sendSignal(sigNo)
Sends the specified signal to the command execution process.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
sigNo | number | mandatory | Signal number Range: 1 - 31 | |
return | boolean | - | true: Success false: Failure | If the parameter is abnormal, an exception occurs. |
.isBusy()
Gets the execution status of the command execution process.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
return | boolean | - | Execution state true: In process false: Terminated or stopped state |
.getResult()
Gets the exit code of the command execution process.
This method is used after the command execution process is exited.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
return | {ExecStatus} | - | {ExecStatus} : Exit code |
{ExecStatus}
The exit code and the exit signal number are basically exclusive, with either one having the invalid value -1
.
If the command has not been executed or is in progress, all property values are set to -1
.
Name | Type | Summary | Note |
---|---|---|---|
.exitCode | number | Exit code of the command execution process (0 - 255) The exit code is set when the command execution process exits normally. | |
.sigNo | number | Exit signal number of the command execution process If the command execution process is terminated by a signal, the signal number that caused the termination is set. | |
.wstatus | number | Exit Status Information (Reference data) This value is the original data in which the exit code and the exit signal information are stored. |
.abort()
Aborts the command execution process forcibly.
This method is valid only when the command is in progress.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
return | undefined | - | - |
.release()
Releases a command execution resource.
The command in execution will be forced to terminate.
Name | Type | M/O | Summary | Note |
---|---|---|---|---|
return | undefined | - | - |
Object Usage Examples
Sample 1
This is a sample of command execution.
Execute the uname -p
command to display CPU information.
var done = false;
var exec = subprocess.create('uname -p');
exec.on('stdout', function() {
var resp = exec.read();
print('response : ' + resp);
});
exec.on('exit', function() {
done = true;
});
exec.execute();
while(1) {
if(done) {
break;
}
}
exec.release();
exec = undefined;
print('done');
Sample 2
This is a sample of process communication between external applications using pipes.
The following shell script executes and establishes process communication.
Prints standard output and standard error output received from shell scripts. Then, sends "end"
to the shell script via standard input to terminate the shell script.
test.sh
#!/bin/bash
cnt=0
while :
do
read -t 1 key
if [ -n "$key" ]; then
echo "$key"
break
fi
if [ $((${cnt} % 2)) = 1 ]; then
echo "$cnt" 1>&2
else
echo "$cnt"
fi
cnt=`expr $cnt + 1`
done
neqto.js
var done = false;
var exec = subprocess.create('/tmp/test.sh');
if(!exec) {
throw 'subprocess is out of resource';
}
exec.on('stdout', function() {
var str = exec.read();
print('stdout : ' + str.replace(/\n/g, ''));
});
exec.on('stderr', function() {
var str = exec.readError();
print('stderr : ' + str.replace(/\n/g, ''));
});
exec.on('exit', function() {
done = true;
});
var tm = setTimeout(function() {
exec.write('end\n');
}, 10000);
exec.execute();
while(1) {
if(done) {
var res = exec.getResult();
print('.exitCode : ' + res.exitCode)
print('.sigNo : ' + res.sigNo)
break;
}
}
clearTimeout(tm);
exec.release();
exec = undefined;
print('script done');