11.  Process Creation and Control  

(unix-system string)

unix-system starts ``/bin/sh'' as a child process with string as input and waits until the shell terminates. All file descriptors except standard input, standard output, and standard error output are closed in the child process. unix-system returns the exit code of the shell as an integer or, if the shell was interrupted by a signal, the termination status as a list of one integer element. If the shell could not be executed, exit code 127 is returned.

(unix-open-input-pipe string)
(unix-open-output-pipe string)

The UNIX popen() function. Both procedures create a pipe between the caller and a shell executing the command string; they return a Scheme port containing the file pointer associated with the pipe. Closing the Scheme port, or running the garbage collector after the port has become unused, causes the pipe to be closed by a call to the pclose() function.

unix-open-input-pipe returns an input port that can be used to read from the standard output of the specified command; unix-open-output-pipe returns an output port that accepts input to be sent to the standard input of the command.

(unix-fork)

The UNIX fork() system call. unix-fork returns the process-ID of the newly created process as an integer in the parent process, and the integer 0 in the child process.

The child process, as its first action, invokes the onfork handlers that may have been registered by other Elk extensions that are currently active (one purpose of onfork handlers is to make new links to temporary files in the newly created child process).

(unix-exec filename arguments)
(unix-exec filename arguments environment)

(unix-exec-path filename arguments)
(unix-exec-path filename arguments environment)

These procedures are based on the UNIX execv() family of system calls and library functions. The first argument is the name of the file to be executed. arguments is a list of strings to be passed to the program as arguments. The environment argument, if present, is a list of environment variable definitions to be used as the new program's environment. Each element of the list is pair of strings; the car of an element is the name of an environment variable, the cdr is the variable's value (the unix-environ primitive can be used to obtain the current environment of the running program).

unix-exec-path searches the specified filename in a list of directories obtained from the calling program's PATH environment variable. The variant of unix-exec-path that accepts an environment argument is not available on the currently supported platforms (the reason is that there is no execvpe() variant of the execvp() function, although execve()/execle() variants of execv() and execl() usually exist in UNIX).

unix-exec and unix-exec-path remove the temporary files used by the dynamic loading module of the interpreter kernel and invoke the finalization functions that may have been registered by extensions. As a result, attempting to load an object file after a call to unix-exec or unix-exec-path has returned (i.e. failed) may not work correctly. The finalization functions are only invoked once.

(unix-wait)
(unix-wait options)

(unix-wait-process pid)
(unix-wait-process pid options)

unix-wait and unix-wait-process are based on the UNIX wait() family of system calls and library functions. Both procedures return a wait-record with the following fields:

+-----------+------------------+--------------------------------------------+
|  Field    |       Type       |                  Contents                  |
+-----------+------------------+--------------------------------------------+
|pid        | integer          | process-ID of the terminated child process |
+-----------+------------------+--------------------------------------------+
|status     | symbol           | reason for process termination             |
+-----------+------------------+--------------------------------------------+
|code       | integer          | exit code or termination status (signal)   |
+-----------+------------------+--------------------------------------------+
|core-dump? | boolean          | #t if a core-dump was produced             |
+-----------+------------------+--------------------------------------------+
|resources  | resources-record | resources of terminated process            |
+-----------+------------------+--------------------------------------------+

See unix-process-resources below for a description of the resources-record type.

The wait-record result holds the process-ID and termination status of one of the terminated (or stopped) children of the calling process. The value of the status is one of the symbols stopped (if the child process has been stopped), signaled (child process is terminated due to a signal), or exited (child process has invoked exit()). code holds the exit code (if status is exited), or a signal number (if status is either stopped or signaled). The resources field holds the user and system time consumed by the child process and its children in nanoseconds (additional resources may be supplied in future versions). The fields of the resources record are #f on platforms that do not support the wait3() or wait4() system call.

unix-wait-process allows to collect the termination status of an individual process or a group of processes specified by the integer pid argument. This procedure is only defined on platforms where the waitpid() or wait4() system call is available. In this case, the feature unix:wait-process is provided when the UNIX extension is loaded.

If no child process is available (or, in case of unix-wait-process, no process as specified by the pid argument), the pid field in the result is set to -1, and the status field is set to the symbol none.

The options argument, if present, is a list of one or more of the symbols nohang and untraced. Options are only supported if the feature unix:wait-options is provided.

(unix-process-resources)

This procedure is based on the UNIX times() library function. unix-process-resources returns the resource usage of the calling process and its terminated children as a pair of resources-records. Each resources-record has the following fields:

+------------+---------+----------------------------+
|   Field    |  Type   |          Contents          |
+------------+---------+----------------------------+
|user-time   | integer | user time in nanoseconds   |
+------------+---------+----------------------------+
|system-time | integer | system time in nanoseconds |
+------------+---------+----------------------------+

Addition fields may be supplied in future versions.

(unix-environ)

unix-environ returns the program's environment as a list of pairs. The car of each element is the name of an environment variable (a string), the cdr is the value of that variable (a string).

(unix-getenv string)

This procedure returns the value of the environment variable with the name string as a string, or #f if the specified variable is not defined.

(unix-working-directory)

unix-working-directory returns the calling program's current working directory as a string. The procedure is based on the getcwd() or getwd() function if any of these is available and invokes the ``pwd'' command otherwise.

(unix-getlogin)

unix-getlogin returns the login name as a string (obtained by the UNIX getlogin() library function).

(unix-getuids)
(unix-getgids)

unix-getuids (unix-getgids) returns the calling program's real and effective user-IDs (group-IDs) as a pair of integers.

(unix-getpids)

unix-getpids returns the process-ID of the calling process and the parent process-ID as a pair of integers.

(unix-getgroups)

unix-getgroups returns the current supplementary group-IDs of the process as a list of integers.

Example:

;;; Get list of names of supplementary group-IDs
(define (get-group-names)
  (map
    (lambda (gid)
      (group-name (unix-get-group gid)))
    (unix-getgroups)))

(unix-umask mask)

The UNIX umask() system call. mask is an integer. The procedure returns the previous value of the umask.

(unix-nice incr)

The UNIX nice() function. incr is an integer. unix-nice returns the new nice value (or zero on some platforms).

(unix-sleep seconds)

The UNIX sleep() function. seconds is a positive integer. The procedure returns the non-printing object.


Markup created by unroff 1.0,    September 24, 1996,    net@informatik.uni-bremen.de