9.16 gauche.process - High Level Process Interface

Module: gauche.process

This module provides a higher-level API of Unix process control, implemented on top of low-level system calls such as sys-fork and sys-exec. This module also provides “process ports”, a convenient way to send/receive information to/from subprocesses.

9.16.1 Process object

Class: <process>

An object to keep the status of a child process. You can create the process object by run-process procedure described below. The process ports explained in the next section also use process objects.

The <process> class keeps track of the child processes spawned by high-level APIs such as run-process or open-input-process. The exit status of such children must be collected by process-wait or process-wait-any calls, which also do some bookkeeping. Using the low-level process calls such as sys-wait or sys-waitpid directly will cause inconsistent state.

Class: <process-abnormal-exit>

A condition type mainly used by the process port utility procedures. Inherits <error>. This type of condition is thrown when the high-level process port utilities detect the child proces exitted with non-zero status code.

Instance Variable of <process-abnormal-exit>: process

A process object.

Note: In Unix terms, exitting a process by calling exit(2) or returning from main() is a normal exit, regardless of the exit status. Some commands do use non-zero exit status to tell one of the normal results of execution (such as grep(1)). However, large number of commands uses non-zero exit status to indicate that they couldn't carry out the required operation, so we treat them as exceptional situations.

Function: run-process cmd/args &keyword input output error fork wait host sigmask

Runs a command with arguments given to cmd/args in a subprocess and returns a <process> object. The cmd/args argument must be a list, whose car specifies the command name and whose cdr is the command-line arguments.

If the command name contains a slash, it is taken as the pathname of the executable. Otherwise the named command is searched from the directories in the PATH environment variable.

Each element in cmd/args are converted to a string by x->string, for the convenience.

The following keyword arguments are recognized:

:input file

:output file

:error file

These arguments controls the subprocess' standard i/o. file may be either a string or a keyword :pipe. If it is a string, the process' standard input, output, or error goes to the named file. If it is :pipe, the process' corresponding standard i/o is connected to a pipe, and the other side of the pipe is available for the calling process.

:wait flag

If flag is true, run-process waits until the subprocess terminates. Othewise the subprocess runs asynchronously and run-process returns immediately, which is the default behavior. Note that if the subprocess is running asynchronously, it is the caller's responsibility to call process-wait at certain timing to collect its exit status.

:fork flag

If flag is true, run-process forks to run the subprocess, which is the default behavior. If flag is false, run-process directly calls sys-exec, so it never returns.

:host hostspec

This argument is used to execute command on the remote host. The full syntax of hostspec is protocol:user@hostname:port, where protocol:, user@, or :port part can be omitted. The protocol part specifies the protocol to commnucate with the remote host; currently only ssh is supported, and it is also the default when protocol is omitted. The user part specifies the login name of the remote host. The hostname specifies the remote host name, and the port part specifies the alternative port number which protocol connects to.

:sigmask mask

Mask must be either an instance of <sys-sigset>, a list of integers, or #f. If an instance of <sys-sigset> is given, the signal mask of executed process is set to it. A list of integers are treated as a list of signals to mask. It is important to set an appropriate mask if you call run-process from multithreaded application. See the description of sys-exec (Unix process management) for the details.

If the host keyword argument is specified, this argument merely sets the signal mask of the local process (ssh).

The following example runs ls -al synchronously.

(run-process '(ls -al) :wait #t)

Note that -i is read as an imaginary number, so be careful to pass -i as a command-line argument; you should use a string, or write |-i| to make it a symbol.

(run-process '(ls "-i") :wait #t)

Note: Old version of this procedure took arguments differently, like (run-process "ls" "-al" :wait #t), which was compatible to STk. This is still supported but deprecated.

Function: process? obj

≡ (is-a? obj <process>)

Method: process-pid (process <process>)

Returns the process ID of the subprocess process.

Method: process-command (process <process>)

Returns the command invoked in the subprocess process.

Method: process-input (process <process>)

Method: process-output (process <process>)

Method: process-error (process <process>)

If the process' standard input, output or error is connected to a pipe, returns another end of the pipe, i.e. process-input returns an output port that can feed data to process' stdin, process-output returns an input port that can read data from process' stdout, and process-error returns an input port that can read data from process' stderr. If the corresponding i/o is not connected to the pipe, the function returns #f.

(let* ((process (run-process '("date") :output :pipe)) (line (read-line (process-output process)))) (process-wait process) line) ⇒ "Fri Jun 22 22:22:22 HST 2001"

Function: process-alive? process

Returns true if process is alive. Note that Gauche can't know the subprocess' status until it is explicitly checked by process-wait.

Function: process-list

Returns a list of active processes. The process remains active until its exit status is explicitly collected by process-wait. Once the process's exit status is collected and its state changed to inactive, it is removed from the list process-list returns.

Function: process-wait process &optional nohang error-on-nonzero-status

Obtains the exit status of the subprocess process, and stores it to process's status slot. The status can be obtained by process-exit-status.

This suspends execution until process exits by default. However, if a true value is given to the optional argument nohang, it returns immediately if process hasn't exit.

If a true value is given to the optional argument error-on-nonzero-status, and the obtained status code is not zero, this procedure raises <process-abnormal-exit> error.

Returns #t if this call actually obtains the exit status, or #f otherwise.

Function: process-wait-any &optional nohang

Obtains the exit status of any of the subprocesses created by run-process. Returns a process object whose exit status is collected.

If a true value is given to the optional argument nohang, this procedure returns #f immediately even if no child process has exit. If nohang is omitted or #f, this procedure waits for any of children exits.

If there's no child processes, this procedure immediately returns #f.

Function: process-exit-status process

Returns exit status of process retrieved by process-wait. If this is called before process-wait is called on process, the result is undefined.

Function: process-send-signal process signal

Sends a signal signal to the subprocess process. signal must be an exact integer for signal number. See section Signal, for predefined variables of signals.

Function: process-kill process

Function: process-stop process

Function: process-continue process

Sends SIGKILL, SIGSTOP and SIGCONT to process, respectively.

9.16.2 Process ports

Function: open-input-process-port command &keyword input error encoding conversion-buffer-size

Runs command asynchronously in a subprocess. Returns two values, an input port which is connected to the stdout of the running subprocess, and a process object.

Command can be a string or a list.

If it is a string, it is passed to /bin/sh. You can use shell metacharacters in this form, such as environment variable interpolation, globbing, and redirections. If you create the command line by concatenating strings, it's your responsibility to ensure escaping special characters if you don't want the shell to interpret them. The shell-escape-string function described below might be a help.

If command is a list, each element is converted to a string by x->string and then passed directly to sys-exec (the car of the list is used as both the command path and the first element of argv, i.e. argv[0]). Use this form if you want to avoid the shell from interfering; i.e. you don't need to escape special characters.

The subprocess's stdin is redirected from /dev/null, and its stderr shares the calling process's stderr by default. You can change these by giving file pathnames to input and error keyword arguments, respectively.

You can also give the encoding keyword argument to specify character encoding of the process output. If it differs from the Gauche's internal encoding format, open-input-process-port inserts a character encoding conversion port. If encoding is given, the conversion-buffer-size keyword argument can control the conversion buffer size. See gauche.charconv - Character Code Conversion, for the details of character encoding conversions.

(receive (port process) (open-input-process-port "ls -l Makefile") (begin0 (read-line port) (process-wait process))) ⇒ "-rw-r--r-- 1 shiro users 1013 Jun 22 21:09 Makefile" (receive (port process) (open-input-process-port '(ls -l "Makefile")) (begin0 (read-line port) (process-wait process))) ⇒ "-rw-r--r-- 1 shiro users 1013 Jun 22 21:09 Makefile" (open-input-process-port "command 2>&1") ⇒ ;the port reads both stdout and stderr (open-input-process-port "command 2>&1 1>/dev/null") ⇒ ;the port reads stderr

The exit status of subprocess is not automatically collected. It is the caller's responsibility to issue process-wait, or the subprocess remains in a zombie state. If it bothers you, you can use one of the following functions.

Function: call-with-input-process command proc &keyword input error encoding conversion-buffer-size on-abnormal-exit

Runs command in a subprocess and pipes its stdout to an input port, then call proc with the port as an argument. When proc returns, it collects its exit status, then returns the result proc returned. The cleanup is done even if proc raises an error.

The keyword argument on-abnormal-exit specifies what happens when the child process exits with non-zero status code. It can be either :error (default), :ignore, or a procedure that takes one argument. If it is :error, a <process-abnormal-exit> error condition is thrown by non-zero exit status; the process slot of the condition holds the process object. If it is :ignore, nothing is done for non-zero exit status. If it is a procedure, it is called with a process object; when the procedure returns, call-with-input-process returns normally.

The semantics of command and other keyword arguments are the same as open-input-process-port above.

(call-with-input-process "ls -l *" (lambda (p) (read-line p)))

Function: with-input-from-process command thunk &keyword input error encoding conversion-buffer-size on-abnormal-exit

Runs command in a subprocess, and calls thunk with its current input port connected to the command's stdout. The command is terminated and its exit status is collected, after thunk returns or raises an error.

The semantics of command and keyword arguments are the same as call-with-input-process above.

(with-input-from-process "ls -l *" read-line)

Function: open-output-process-port command &keyword output error encoding conversion-buffer-size

Runs command in a subprocess asynchronously. Returns two values, an output port which is connected to the stdin of the subprocess. and the process object.

The semantics of command is the same as open-input-process-port. The semantics of encoding and conversion-buffer-size are also the same.

The subprocess's stdout is redirected to /dev/null by default, and its stderr shares the calling process's stderr. You can change these by giving file pathnames to output and error keyword arguments, respectively.

The exit status of the subprocess is not automatically collected. The caller should call process-wait on the subprocess at appropriate time.

Function: call-with-output-process command proc &keyword output error encoding conversion-buffer-size on-abnormal-exit

Runs command in a subprocess, and calls proc with an output port which is connected to the stdin of the command. The exit status of the command is collected after either proc returns or raises an error.

The semantics of keyword arguments are the same as open-output-process-port, except on-abnormal-exit, which is the same as described in call-with-input-process.

(call-with-output-process "/usr/sbin/sendmail" (lambda (out) (display mail-body out)))

Function: with-output-to-process command thunk &keyword output error encoding conversion-buffer-size on-abnormal-exit

Same as call-with-output-process, except that the output port which is connected to the stdin of the command is set to the current output port while executing thunk.

Function: call-with-process-io command proc &keyword error encoding conversion-buffer-size on-abnormal-exit

Runs command in a subprocess, and calls proc with two arguments; the first argument is an input port which is connected to the command's stdout, and the second is an output port connected to the command's stdin. The error output from the command is shared by the calling process's, unless an alternative pathname is given to the error keyword argument.

The exit status of the command is collected when proc returns or raises an error.

Function: process-output->string command &keyword error encoding conversion-buffer-size on-abnormal-exit

Function: process-output->string-list command &keyword error encoding conversion-buffer-size on-abnormal-exit

Runs command and collects its output (to stdout) and returns them. process-output->string concatenates all the output from command to one string, replacing any sequence of whitespace characters to single space. The action is similar to “command substitution” in shell scripts. process-output->string-list collects the output from command line-by-line and returns the list of them. Newline characters are stripped.

Internally, command is run by call-with-input-process, to which keyword arguments are passed.

(process-output->string '(uname -smp)) ⇒ "Linux i686 unknown" (process-output->string '(ls)) ⇒ "a.out foo.c foo.c~ foo.o" (process-output->string-list '(ls)) ⇒ ("a.out" "foo.c" "foo.c~" "foo.o")

Function: shell-escape-string arg

If arg contains characters that affects shell's command-line argument parsing, escape arg to avoid shell's interpretation. Otherwise, returns arg itself.

Use this procedure when you need to build a command-line string by yourself. (If you pass a command-line argument list, instead of a single command-line string, you don't need to escape them since we bypass the shell.)

On Windows native build, this procedure is compatible to the argument parsing convention of Windows standard C runtime.

This document was generated by Shiro Kawai on October, 7 2008 using texi2html 1.78.