6.19. kink/PROCESS¶

現在のプロセスとサブプロセスを操作する。

終了ステータスについて

POSIX互換のシステムでは、LSB側の8ビットだけが終了ステータスとして使える [1]。これにしたがうため、PROCESS.exitは [0, 255] の範囲の整数のみを受け入れる。

Windows APIでは、終了ステータスは32ビットの符号なし整数である [2]。これを扱えるように、Process.waitの結果の範囲は [0, 4294967295] と定義される。注意: Windows APIは終了ステータスを符号なしと規定しているが、cmd.exeとPowerShellはこれを符号付きとして扱っている。

[1] https://pubs.opengroup.org/onlinepubs/9799919799/functions/wait.html

[2] https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess

6.19.1. process型¶

processは、PROCESS.startで起動したサブプロセスである。

6.19.1.1. P.wait(...[$config={}])¶

waitは、サブプロセスの終了ステータスが利用可能になるまで、あるいはタイムアウトまで待つ。

コンフィグメソッド:

• C.timeout(Timeout_seconds)

• C.on_success($success): default = VAL.identity

• C.on_timeout($timeout): default = 例外を投げるサンク

Timeout_secondsは、任意のスケールの非負のnum値である。Timeout_secondsは、タイムアウトまでの秒数として使われる。サブプロセスの終了ステータスが利用可能になる前にタイムアウトした場合、waitは$timeoutを引数なしで末尾呼び出しする。

waitは、Timeout_secondsを妥当な値に調整する可能性がある。

C.timeoutが呼ばれない場合、waitがタイムアウトすることはない。

タイムアウト前に終了ステータスが利用可能になった場合、waitは、終了ステータスを [0, 4294967295] の範囲の整数のnum値の引数として、$successを末尾呼び出しする。

事前条件

Timeout_secondsは非負のnumでなければならない。

$successは [0, 4294967295] の範囲の整数のnumを取る関数でなければならない。

$timeoutはサンクでなければならない。

6.19.1.2. P.stdin¶

stdinは、サブプロセスの標準入力に接続したパイプのoutputを戻す。

事前条件

PROCESS.startが呼ばれた際に、C.stdin_from_pipeが指定されていなければならない。

6.19.1.3. P.stdout¶

stdoutは、サブプロセスの標準出力に接続したパイプのinputを戻す。

事前条件

PROCESS.startが呼ばれた際に、C.stdout_to_pipeが指定されていなければならない。

6.19.1.4. P.stderr¶

stderrは、サブプロセスの標準エラー出力に接続したパイプのinputを戻す。

事前条件

PROCESS.startが呼ばれた際に、C.stderr_to_pipeが指定されていなければならない。

6.19.2. PROCESS.start(Command_and_args ...[$config={}])¶

startは、Command_and_argsで指定されたコマンドを実行することで、サブプロセスを起動する。

startが成功裏にサブプロセスを起動したら、起動されたサブプロセスを表すprocess値を引数として$successを末尾呼び出しする。$successは、C.on_successで指定するか、デフォルトとしてVAL.identityが使われる。

startがサブプロセスの起動に失敗したら、exceptionを引数として$errorを末尾呼び出しする。$errorはC.on_errorで指定されるか、デフォルトとして {(:Exc) Exc.raise } が使われる。

事前条件

Command_and_argsはstr値のvecでなければならない。

Command_and_argsは空であってはならない。

$configはstart_configを取る関数でなければならない。

例: 標準入出力を現在のプロセスから継承する

:PROCESS.require_from('kink/')

:Ls <- PROCESS.start(['ls' '-1' '/']) # command: ls -1 /
stdout.print_line(Ls.wait) # => 0

例: 標準出力をパイプする

:PROCESS.require_from('kink/')
:CONTROL.require_from('kink/')
:INPUT_SCANNER.require_from('kink/io/')
:CHARSET.require_from('kink/')

:Lines <- CONTROL.with_finally{(:finally)
  :Ls = PROCESS.start(['ls' '-1' '/']){(:C)
    C.stdout_to_pipe
  }
  finally{ Ls.wait }
  :Stdout = Ls.stdout
  finally{ Stdout.close }
  :Scanner = INPUT_SCANNER.new(Stdout CHARSET.utf8)
  :loop <- {(:Lines)
    Scanner.scan_line{(:C)
      C.on_success{(:L) loop(Lines + [L]) }
      C.on_eof{ Lines }
    }
  }
  loop([])
}
stdout.print_line(Lines.repr) # => ["bin\n" "boot\n" "dev\n" "etc\n" "home\n" ,,,]

6.19.3. start_config型¶

start_configは、PROCESS.startのコンフィグ値である。

標準入出力

stdin_from_pipe, stdin_from_fileが呼ばれない場合、サブプロセスは現在のプロセスの標準入力を継承する。

stdout_to_pipe, stdout_to_overwrite, stdout_to_appendが呼ばれない場合、サブプロセスは現在のプロセスの標準出力を継承する。

stderr_to_pipe, stderr_to_overwrite, stderr_to_append, stderr_to_stdoutが呼ばれない場合、サブプロセスは現在のプロセスの標準エラー出力を継承する。

6.19.3.1. C.stdin_from_pipe¶

stdin_from_pipeは、サブプロセスの標準入力が、パイプのoutputに接続されることを指定する。

stdin_from_pipeを指定したら、サブプロセスに接続されたパイプのoutputを得るために、P.stdinを呼ぶ必要がある。

6.19.3.2. C.stdin_from_file(File_path)¶

stdin_from_fileは、File_pathで指定したファイルが、サブプロセスの標準出力のソースになることを指定する。

ファイルが開けなければ、PROCESS.startはエラーを起こす。

事前条件

File_pathはstrでなければならない。

6.19.3.3. C.stdout_to_pipe¶

stdout_to_pipeは、サブプロセスの標準出力が、パイプのinputに接続されることを指定する。

stdout_to_pipeを指定したら、サブプロセスに接続されたパイプのinputを得るために、P.stdoutを呼ぶ必要がある。

6.19.3.4. C.stdout_to_overwrite(File_path)¶

stdout_to_overwriteは、File_pathで指定したファイルが上書きモードで開かれ、サブプロセスの標準出力の宛先として使われることを指定する。

ファイルが開けなければ、PROCESS.startはエラーを起こす。

事前条件

File_pathはstrでなければならない。

6.19.3.5. C.stdout_to_append(File_path)¶

stdout_to_appendは、File_pathで指定したファイルが追加モードで開かれ、サブプロセスの標準出力の宛先として使われることを指定する。

ファイルが開けなければ、PROCESS.startはエラーを起こす。

事前条件

File_pathはstrでなければならない。

6.19.3.6. C.stderr_to_pipe¶

stderr_to_pipeは、サブプロセスの標準エラー出力が、パイプのinputに接続されることを指定する。

stderr_to_pipeを指定したら、サブプロセスに接続されたパイプのinputを得るために、P.stderrを呼ぶ必要がある。

6.19.3.7. C.stderr_to_overwrite(File_path)¶

stderr_to_overwriteは、File_pathで指定したファイルが上書きモードで開かれ、サブプロセスの標準エラー出力の宛先として使われることを指定する。

ファイルが開けなければ、PROCESS.startはエラーを起こす。

事前条件

File_pathはstrでなければならない。

6.19.3.8. C.stderr_to_append(File_path)¶

stderr_to_appendは、File_pathで指定したファイルが追加モードで開かれ、サブプロセスの標準エラー出力の宛先として使われることを指定する。

ファイルが開けなければ、PROCESS.startはエラーを起こす。

事前条件

File_pathはstrでなければならない。

6.19.3.9. C.stderr_to_stdout¶

stderr_to_stdoutは、サブプロセスの標準エラー出力が、標準出力にリダイレクトされることを指定する。

これは、Unixシェルで 2>&1 を指定するのと同じである。

6.19.3.10. C.dir(Dir_path)¶

dirは、サブプロセスの作業ディレクトリとしてDir_pathを指定する。

サブプロセスがDir_pathに移動できなければ、PROCESS.startはエラーを起こす。

事前条件

Dir_pathはstrでなければならない。

6.19.3.11. C.set_env(Env_name Env_val)¶

set_envは、サブプロセスがEnv_nameを名前とし、Env_valを値とする環境変数を持つことを指定する。

Env_nameの大文字小文字の区別はホストシステムに依存する。典型的には、Unixシステムでは大文字小文字が区別され、Windowsシステムでは区別されない。

事前条件

Env_nameはstrでなければならない。

Env_valはstrでなければならない。

6.19.3.12. C.unset_env(Env_name)¶

unset_envは、サブプロセスがEnv_nameの名前の環境変数を持たないことを指定する。

事前条件

Env_nameはstrでなければならない。

6.19.3.13. C.on_success($success)¶

on_successは、PROCESS.startの成功時継続として$successを使うことを指定する。

事前条件

$successはprocessを取る関数でなければならない。

6.19.3.14. C.on_error($error)¶

on_errorは、PROCESS.startのエラー時継続として$errorを使うことを指定する。

事前条件

$errorはexceptionを取る関数でなければならない。

6.19.4. PROCESS.pid¶

pidは、現在のプロセスのプロセスIDを整数のnum値で戻す。

例

:PROCESS.require_from('kink/')

stdout.print_line(PROCESS.pid.repr) # => 123

6.19.5. PROCESS.env(Env_name)¶

envは、Env_nameで指定された環境変数のstrを戻す。

事前条件

Env_nameはstrでなければならない。

現在のプロセスは指定された環境変数を持っていなければならない。

例

:PROCESS.require_from('kink/')

stdout.print_line(PROCESS.env('PATH').repr)
# => "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

6.19.6. PROCESS.have_env?(Env_name)¶

have_env?は、現在のプロセスがEnv_nameで指定された環境変数を持っているかどうかを戻す。

事前条件

Env_nameはstrでなければならない。

例

:PROCESS.require_from('kink/')

stdout.print_line(PROCESS.have_env?('PATH').repr) # => true
stdout.print_line(PROCESS.have_env?('NO_SUCH_ENV').repr)  # => false

6.19.7. PROCESS.exit(Exit_status)¶

exitは、現在のプロセスをExit_statusで終了する。

事前条件

Exit_statusは [0, 255] の範囲の整数のnumでなければならない。