10.16 Process Utilities—library(process)

This package contains utilities for process creation.

A process is represented by a process reference, a ground compound term. Both SICStus and the operating system maintain a state for each such process reference and they must therefore be released, either explicitly with process_release/1 or implicitly by process_wait/[2,3]. Process references are created with process_create/[2,3] if explicitly requested with the process/1 option. Process references are required in order to obtain the exit status of a process. Many of the predicates can accept a numeric operating system process id (“PID”) but since process ids are subject to re-use by the OS this is less reliable and does not work if the process has already exited. Run ls on a home directory in a subshell under UNIX:

     | ?- absolute_file_name('$SHELL', Shell),
          absolute_file_name('~/', Dir),
          process_create(Shell, ['-c', [ ls, ' ', file(Dir) ]]).

Run notepad.exe on a file C:/foo.txt under Windows:

     | ?- absolute_file_name('$SYSTEMROOT/notepad.exe', Prog),
          process_create(Prog, [file('C:/foo.txt')]).

Exported predicates:

process_create(+File, +Args)

process_create(+File, +Args, :Options)

Start a new process running the program identified by File and the arguments specified in Args. The standard streams of the new process can be redirected to prolog streams. The exit status of the process can be obtained with process_wait/[2,3].

File, is expanded as if by absolute_file_name/2 (with argument access(execute)) and is used to locate the file to execute.

The predefined file search path path/1 (see ref-fdi) is especially useful here since it makes it easy to look up the names of an executable in the directories mentioned by the PATH environment variable. To run the Windows command shell cmd you would simply specify path('cmd.exe'), to start the UNIX Bash shell you would specify path(bash).

Args is a list of argument specifications. Each argument specification is either a simple argument specification, see below, or a non-empty list of simple argument specifications. The expanded value of each element of Args is concatenated to produce a single argument to the new process. A simple argument specification can be one of:

an atom

The atom name is used as the expanded value. Some operating systems only support 7-bit ASCII characters here. Even when some larger subset of Unicode is used it may not work correctly with all programs.

file(File)

File, an atom, is treated as a file name and subject to an operating system specific transformation to ensure file name syntax and character set is appropriate for the new process. This is especially important under Windows where it ensures that the full Windows Unicode character set can be used. Please note: The File part of file(File) is not subject to syntactic rewriting, the argument specification file/1 only adjusts for differences in file name syntax and character encoding between SICStus and the operating system. You must explicitly call absolute_file_name/[2,3] if you want to expand file search paths etc.

Options is a list of options:

stdin(Spec)

stdout(Spec)

stderr(Spec)

Each Spec specifies how the corresponding standard stream of the new process should be created. Spec can be one of:

std

The new process shares the (OS level) standard stream with the Prolog process. This is the default. Note that, especially under Windows, the Prolog process may not have any OS level standard streams, or the OS streams may not be connected to a console or terminal. In such a case you need to use pipe/1 spec, see below, and explicitly read (write) data from (to) the process.

null

The stream is redirected to a null stream, i.e. a stream that discards written data and that is always at end of file when read.

pipe(Stream)

A new Prolog (text) stream is created and connected to the corresponding stream of the new process. It is currently not possible to request binary streams or to specify a character set different from the OS default. This stream must be closed using close/[1,2], it is not closed automatically when the new process exits.

process(Proc)

Proc will be bound to a process reference that can be used in calls to process_wait/[2,3] etc.. This process reference must be released, either explicitly with process_release/1 or implicitly by process_wait/[2,3].

detached(Bool)

Bool is either true or false. Specifies whether the new process should be “detached”, i.e. whether it should be notified of terminal events such as ^C interrupts. By default a new process is created detached if none of the standard streams are specified, explicitly or implicitly, as std.

cwd(CWD)

CWD is expanded as if by absolute_file_name/2 and is used as the working directory for the new process.

By default, the working directory is the same as the Prolog working directory.

window(Bool)

Bool is either true or false (the default). Specifies whether the process should open in its own window.

Specifying window(true) may give unexpected results if the standard stream options stdin/1, stdout/1 and stderr/1 are specified with anything but their default value std.

Currently only implemented on Windows.

environment(Env)

Env is a list of VAR=VALUE for extra environment variables to pass to the sub-process in addition to the default process environment. VAR and VALUE should be atoms. See System Properties and Environment Variables, for more information.

process_wait(+Process, -ExitStatus)

process_wait(+Process, -ExitStatus, +Options)

Wait for a process to exit and obtain the exit status.

Process is either a process reference obtained from process_create/3 or an OS process identifier. Specifying a process identifier is not reliable. The process identifier may have been re-used by the operating system. Under Windows, it is not possible to obtain the exit status using a process identifier if the process has already exited.

ExitStatus is one of:

exit(ExitCode)

The process has exited with exit code ExitCode. By convention processes use exit code zero to signify success and a (positive) non-zero value to specify failure.

killed(SignalNumber)

UNIX only, the process was killed by signal SignalNumber (a positive integer).

timeout

The timeout/1 option was specified and the process did not exit within the specified interval. In this case the process reference is not released, even if the release/1 option is specified.

Options is a list of options:

timeout(Seconds)

Specify a maximum time, in seconds, to wait for the process to terminate. Seconds should be an integer or floating point number or the atom infinite (the default) to specify infinite wait. If the specified timeout interval passes before the process exits, process_wait/3 exits with ExitStatus set to timeout and the process reference is not released.

Currently the UNIX implementation supports only timeout values 0 (zero) and infinite.

release(Bool)

Bool is either true (the default) or false. Specifies whether the process reference should be released when process_wait/3 exits successfully.

process_id(-PID)

Obtain the process identifier of the current (i.e. Prolog) process.

process_id(+Process, -PID)

Obtain the process identifier of the process reference Process.

is_process(+Thing)

Returns true if Thing is a process reference that has not been released.

process_release(+Process)

Release a process reference Process that has previously been obtained from process_create/3. This ensures that Prolog and the operating system can reclaim any resources associated with the process reference.

Usually you would not call this. Either do not request the process reference when calling process_create/3 or let process_wait/[2,3] reclaim the process reference when the process terminates.

process_kill(+Process)

process_kill(+Process, +SignalSpec)

Send a signal to the process designated by Process. The signal can either be a non-negative integer or a signal name as an (all uppercase) atom.

The following signal names are accepted under UNIX if the platform defines them: SIGABRT, SIGALRM, SIGBUS, SIGCHLD, SIGCONT, SIGFPE, SIGHUP, SIGILL, SIGINT, SIGKILL (the default), SIGPIPE, SIGPOLL, SIGPROF, SIGQUIT, SIGSEGV, SIGSTOP, SIGSYS, SIGTERM, SIGTRAP, SIGTSTP, SIGTTIN, SIGTTOU, SIGURG, SIGUSR1, SIGUSR2, SIGVTALRM, SIGXCPU and SIGXFSZ. However, many of these do not make sense to send as signals.

Under Windows, which does not have the signal concept, the signal name SIGKILL (the default) is treated specially and terminates the process with TerminateProcess(Process, -1). Please note: Using process_kill/[2,3] on Windows is not recommended. Also, on Windows, the call may throw an error if the process has already exited.