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