12. SubProcess

subprocessオブジェクトは、パイプを使用した外部アプリケーション間プロセス通信機能を提供する組み込みオブジェクトです。

機能概要:

• 外部アプリケーションの標準入力(stdin)、標準出力(stdout)、標準エラー出力(stderr)をそれぞれパイプ接続し、リアルタイムでデータを送受信する機能を提供します。
• 外部アプリケーションに特定シグナルを送信する機能を提供します。
• 外部アプリケーションの終了コードを取得する機能を提供します。

制限事項:

• 使用可能なコマンド実行リソースは3本です。

---

subprocess Global Object

Methods()/Properties	Summary	Version	Note
subprocess.create()	コマンド実行インスタンスを生成します。

---

subprocess.create(cmd[,options])

コマンド実行インスタンスを生成します。

Name	Type	M/O	Summary	Note
cmd	string	mandatory	コマンド実行パスを指定します。 コマンド引数が必要な場合はコマンド実行パスの後に空白文字区切りで指定します。空白文字を含む文字列を1つの引数として扱う場合は、対象となる文字列範囲をシングルクォート'またはダブルクォート"で囲んでください。 尚、コマンド文字数は最大4095文字、コマンド実行パスを含めたコマンド引数は最大31までとなります。 例: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	リダイレクト、パイプを使用した複数コマンドの組み合わせによる実行はサポートしていません。
options	Object	optional	オプション 詳細はOptionsを参照してください。
return	{Exec}, null	-	{Exec} : 生成された{Exec} null : リソース不足でインスタンスの生成が失敗した場合	パラメータ異常の場合は例外となります。

Options

Name	Type	M/O	Summary	Note
readBuffSize	number	optional	読み出しバッファサイズ[Byte] 設定範囲: 1～2,147,483,647 デフォルト値は4096となります。
abortSigNo	number	optional	強制終了シグナル番号 .abort()メソッドコール等により、強制的にコマンド実行プロセスを中止させる際に送信するシグナル番号を指定します。実行プロセスはこのシグナル番号で必ず終了可能である必要があります。 設定範囲: 1(SIGHUP), 2(SIGINT), 9(SIGKILL), 15(SIGTERM) デフォルト値は15(SIGTERM)となります。

---

{Exec}

Methods()/Properties	Summary	Version	Note
.on()	イベントハンドラを登録します。
.execute()	コマンド実行を開始します。
.read()	コマンド実行プロセスから受信した標準出力(stdout)データを読み出します。
.readError()	コマンド実行プロセスから受信した標準エラー出力(stderr)データを読み出します。
.write()	コマンド実行プロセスの標準入力(stdin)にデータを送信します。
.sendSignal()	コマンド実行プロセスに指定されたシグナルを送信します。
.isBusy()	コマンド実行プロセスの実行状態を取得します。
.getResult()	コマンド実行プロセスの終了コードを取得します。
.abort()	コマンド実行プロセスを強制的に中止します。
.release()	コマンド実行リソースを解放します。

---

Details

.on(event,callback)

イベントハンドラを登録します。

Name	Type	M/O	Summary	Note
event	string	mandatory	イベント名 使用できるイベント名は、stdout, stderr, exitとなります。
callback	function	mandatory	イベント発生時にコールバック処理を実行します。
return	undefined	-	-	パラメータ異常の場合は例外となります。

event : ’stdout’

コマンド実行プロセスから標準出力(stdout)データを受信し、読み出しバッファにデータが格納された際にコールバック処理を実行します。

event : ’stderr’

コマンド実行プロセスから標準エラー出力(stderr)データを受信し、読み出しバッファにデータが格納された際にコールバック処理を実行します。

event : ’exit’

コマンド実行プロセスが終了した際にコールバック処理を実行します。

尚、標準出力(stdout)および標準エラー出力(stderr)の読み出しバッファにデータが存在する状態でプロセスが終了した場合、コールバック処理はすぐに実行されません。必ず.read()または.readError()メソッドで全てのデータを読み出す必要があります。

.execute()

コマンド実行を開始します。

Name	Type	M/O	Summary	Note
return	boolean	-	true: 成功 false: 失敗

.read([isBin])

コマンド実行プロセスから受信した標準出力(stdout)データを読み出します。

Name	Type	M/O	Summary	Note
isBin	boolean	optional	読み出しデータの形式を指定します。 true: バイナリデータ形式で読み出し false: 文字列形式で読み出し デフォルト値はfalseとなります。
return	ArrayBuffer, string	-	読み出しデータ 戻り値の型はisBinで決定されます。 trueを指定した場合はArrayBuffer型、falseを指定した場合は、string型となります。	読み出しデータはreadBuffSizeで指定したサイズ以下となります。読み出しデータがない場合はサイズが0となります。 パラメータ異常の場合は例外となります。

.readError([isBin])

コマンド実行プロセスから受信した標準エラー出力(stderr)データを読み出します。

Name	Type	M/O	Summary	Note
isBin	boolean	optional	読み出しデータの形式を指定します。 true: バイナリデータ形式で読み出し false: 文字列形式で読み出し デフォルト値はfalseとなります。
return	ArrayBuffer, string	-	読み出しデータ 戻り値の型はisBinで決定されます。 trueを指定した場合はArrayBuffer型、falseを指定した場合は、string型となります。	読み出しデータはreadBuffSizeで指定したサイズ以下となります。読み出しデータがない場合はサイズが0となります。 パラメータ異常の場合は例外となります。

.write(data)

コマンド実行プロセスの標準入力(stdin)にデータを送信します。

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	送信データ
return	number	-	送信されたデータサイズ 送信が失敗した場合は-1を返却します。	パラメータ異常の場合は例外となります。

.sendSignal(sigNo)

コマンド実行プロセスに指定されたシグナルを送信します。

Name	Type	M/O	Summary	Note
sigNo	number	mandatory	シグナル番号 設定範囲: 1～31
return	boolean	-	true: 成功 false: 失敗	パラメータ異常の場合は例外となります。

.isBusy()

コマンド実行プロセスの実行状態を取得します。

Name	Type	M/O	Summary	Note
return	boolean	-	実行状態 true: 実行中 false: 終了または停止状態

.getResult()

コマンド実行プロセスの終了コードを取得します。
このメソッドはコマンド実行プロセスが終了した後に使用します。

Name	Type	M/O	Summary	Note
return	{ExecStatus}	-	{ExecStatus} : 終了コード

{ExecStatus}

終了コードおよび終了シグナル番号は基本排他的であり、どちらか一方が無効値-1となります。
尚、コマンド未実行またはコマンド実行中の場合は、全てのプロパティ値が-1となります。

Name	Type	Summary	Note
.exitCode	number	コマンド実行プロセスの終了コード (0～255) コマンド実行プロセスが正常終了した場合に終了コードが設定されます。
.sigNo	number	コマンド実行プロセスの終了シグナル番号 コマンド実行プロセスがシグナルにより終了した場合に終了の要因となったシグナル番号が設定されます。
.wstatus	number	終了ステータス情報 (参考データ) 終了コードおよび終了シグナル情報が格納されているオリジナルデータとなります。

.abort()

コマンド実行プロセスを強制的に中止します。
コマンド実行中の場合のみ有効となります。

Name	Type	M/O	Summary	Note
return	undefined	-	-

.release()

コマンド実行リソースを解放します。
実行中のコマンドは強制終了となります。

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

オブジェクトの使用例

Sample 1

コマンド実行のサンプルです。
uname -pコマンドを実行し、CPU情報を表示します。

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

パイプを使用した外部アプリケーション間プロセス通信のサンプルです。
下記、シェルスクリプトを起動し、プロセス通信を確立します。
シェルスクリプトから受信した標準出力および標準エラー出力をPrint出力します。
次にシェルスクリプトへ標準入力を介して"end"を送信し、シェルスクリプトを終了させます。

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-09-06