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');

---

Updated: 2022-10-25