9. Subprocess Functions

These functions in process.sl facilitate the creation of subprocesses and pipelines.

9.1 new_process

Synopsis

Create a subprocess object

Usage

Struct_Type new_process (String_Type argv[]; qualifiers)

Description

This function executes the program specified by the argv parameter in a subprocess. If argv is an array, the first element (argv[0]) of the array gives the name of the program to be executed, and the remaining elements serve as arguments passed to the program. The program returns a structure that may be used to interact with the process. Upon error, an exception will be thrown.

The calling program may interact with the subprocess by reading from or writing to the file descriptor fields of the structure returned by the new_process function. The specific file descriptors are dictated via the read, write, and dupN qualifiers, as described in detail below.

The function returns a structure containing zero or more fields of the form fdN where N is an integer derived from the qualifiers, e.g., fd0 and fd1 correspond to the child's stdin and stdout, respectively. The structure also contains fields of the form fpN whose values are stdio File_Type objects obtained using fdopen with the corresponding fdN value.

Other important fields include pid whose value is the process-id of the newly created process.

The status of the process may be checked or collected using the wait method. It is very important to call this method to avoid the creation of zombie processes.

Qualifiers

The following qualifiers are supported:

   read=fds

fds is a list of integer file descriptors that are open for read access in the subprocess, and may be written to by the calling process using the fdN or fpN fields of the structure.

   write=fds

fds is a list of integer file descriptors that are open for write access in the subprocess, and may be read to by the calling process using the fdN or fpN fields of the structure.

   stdin=filename
   stdout=filename
   stderr=filename

These qualifiers allow the stdin, stdout, and stderr file descriptors in the subprocess to be redirected to a file. Note: The filenames are interpreted relative to the value of the dir qualifier.

   fdN=string

This qualifier will cause the integer file descriptor N to be open in the subprocess and redirected to the filename represented by the string, which is interpreted relative to the value of the dir qualifier. The access mode is dictated by the first few characters of the string as described in more detail below.

   stdin=File_Type|FD_Type
   stdout=File_Type|FD_Type
   stderr=File_Type|FD_Type
   fdN=FD_Type|FD_Type

If the stdin, stdout, stderr, or fdN qualifiers have File_Type or FD_Type values, then corresponding file descriptors in the subprocess will be dup'd to FD_Type or FP_Type file descriptor. This form of the qualifier may be used to setup pipelines.

   dupN=int

The file descriptor corresponding to the integer N in the subprocess is created by duping the descriptor given by the integer value of the qualifier. For example, dup2=1 would cause stderr (fd=2) in the subprocess to be redirected to stdout (fd=1).

   dir=string

Change to the specified directory in the child process. This will happen after the child process is started, but before any files have been opened. Hence, files attached to stdin, stdout, etc will be opened relative to this directory.

   pre_exec_hook=&func

This qualifier will cause the function corresponding to func to be called prior to closing unused file descriptors and invoking the executable. The function will be passed a list of integer valued file descriptors that will be kept open. Additional integers may be added to the list by the function. If the qualifier pre_exec_hook_optarg exists, it will also be passed as an addtional argument.

   pre_exec_hook_optarg=VALUE

If this qualifier exists, its value will be passed as the second argument to the pre_exec_hook callback function.

Note that the read and write qualifiers specify the nature of the file descriptors from the child process's view. That is, those opened in the child process using the read qualifier, may be written to by the parent. Similarly, those opened using the write qualifier may be read by the parent.

Methods

    Struct_Type .wait ( [ options ] )

The .wait method may be used to collect the exist status of the process. When called without arguments, it will cause the parent process to wait for the subprocess to exit and return its exit status in the form of a waitpid structure. The optional options argument corresponds to the options argument of the waitpid function. The most common is the WNOHANG option, which will cause the .wait method to return immediately if the process has not exited.

If an error occurs, the function will return NULL and set errno accordingly. Otherwise it will return a waitpid structure. See the documentation for waitpid for more information.

Example

In the following examples, pgm represents the program to be invoked in the subprocess. For simplicity, no addition arguments are shown

Create subprocess that inherits stdin, stdout, stderr from the caller:

   obj = new_process (pgm);

Create a subprocess that inherits stdin, stdout, and writes stderr to a file:

   obj = new_process (pgm; stderr="/tmp/file");   % form 1
   obj = new_process (pgm; fd2=">/tmp/file");     % form 2

Mimic popen(pgm, "r"):

   obj = new_process (pgm; write=1);   % Read from obj.fp1

Mimic popen(pgm, "w"):

   obj = new_process (pgm; read=0);  % Write to obj.fp0

Mimic popen("pgm 2>&1", "r"):

   obj = new_process (pgm; write=1, dup2=1);  % Read from fp1

Send stdout to a file, read from the subprocess's stderr:

   obj = new_process (pgm; stdout="/tmp/file", write=2);
   % Read from obj.fp2

Create a process with handles to its stdin, stdout, stderr

   obj = new_process (pgm; write={1,2}, read=0);
   % Use obj.fp0 for stdin, obj.fp1 for stdout, and obj.fp2 for stderr

Create a process with a write handle to the process's fd=27 and a read handle to the process's stdout.

   obj = new_process (pgm; read=27, write=1);
   % write to fp27, read from fp1

Create a pipeline: pgm1 | pgm2 > /tmp/log :

  obj1 = new_process (pgm1; write=1);
  obj2 = new_process (pgm2; stdin=obj1.fp1, stdout="/tmp/log");

Create a pipeline with fd=27 from pgm1 redirected to stdin of pgm2:

  obj1 = new_process (pgm1; write=27);
  obj2 = new_process (pgm2; stdin=obj1.fp27);

Create a pipeline with fd=27 from pgm1 redirected to fd=9 of pgm2:

  obj1 = new_process (pgm1; write=27);
  obj2 = new_process (pgm2; fp9=obj1.fp27);

Mimic: pgm 2>&1 1>/dev/null

  obj = new_process (pgm; fp2=1, stdout="/dev/null");

Mimic: pgm >/dev/null 2>&1

  obj = new_process (pgm; stdout="/dev/null", dup2=1);

Append the output of pgm to /tmp/file.log:

   obj = new_process (pgm; stdout=">>/tmp/file.log");

Notes

Care must be exercised when reading or writing to multiple file descriptors of a subprocess to avoid deadlock. In such cases, the select module should be used, or the file descriptors could be put in non-blocking mode via the fcntl module.

It is important to call the .wait method prevent the process from becoming a zombie and clogging the process table.

See Also

popen, system