1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        jan@swi-prolog.org
    5    WWW:           https://www.swi-prolog.org
    6    Copyright (c)  2008-2026, University of Amsterdam
    7                              VU University Amsterdam
    8                              CWI, Amsterdam
    9                              SWI-Prolog Solutions b.v.
   10    All rights reserved.
   11
   12    Redistribution and use in source and binary forms, with or without
   13    modification, are permitted provided that the following conditions
   14    are met:
   15
   16    1. Redistributions of source code must retain the above copyright
   17       notice, this list of conditions and the following disclaimer.
   18
   19    2. Redistributions in binary form must reproduce the above copyright
   20       notice, this list of conditions and the following disclaimer in
   21       the documentation and/or other materials provided with the
   22       distribution.
   23
   24    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   25    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   26    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   27    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   28    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   29    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   30    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   31    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   32    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   33    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   34    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   35    POSSIBILITY OF SUCH DAMAGE.
   36*/
   37
   38:- module(process,
   39          [ process_create/3,           % +Exe, +Args, +Options
   40            process_wait/2,             % +PID, -Status
   41            process_wait/3,             % +PID, -Status, +Options
   42            process_id/1,               % -PID
   43            process_id/2,               % +Process, -PID
   44            is_process/1,               % +PID
   45            process_release/1,          % +PID
   46            process_kill/1,             % +PID
   47            process_group_kill/1,       % +PID
   48            process_group_kill/2,       % +PID, +Signal
   49            process_kill/2,             % +PID, +Signal
   50            process_which/2,            % +Exe, -AbsoluteFile
   51
   52            process_set_method/1        % +CreateMethod
   53          ]).   54:- multifile prolog:prolog_tool/4.   55:- dynamic   prolog:prolog_tool/4.   56
   57:- autoload(library(apply),[maplist/3]).   58:- autoload(library(error),[must_be/2,existence_error/2]).   59:- autoload(library(option),[select_option/3]).   60
   61:- use_foreign_library(foreign(process)).   62
   63:- predicate_options(process_create/3, 3,
   64                     [ stdin(any),
   65                       stdout(any),
   66                       stderr(any),
   67                       cwd(atom),
   68                       env(list(any)),
   69                       environment(list(any)),
   70                       priority(+integer),
   71                       process(-integer),
   72                       detached(+boolean),
   73                       window(+boolean)
   74                     ]).

?- absolute_file_name(path(ls), Path, [access(execute)]).

 process_create(+Exe, +Args:list, +Options) is det

Create a new process running the file Exe and using arguments from the given list. Exe is a file specification as handed to absolute_file_name/3. Typically one use the path file alias to specify an executable file on the current PATH. The path prolog is reserved. If Exe is prolog(Tool), a Prolog utility is invoked that belongs to the distribution of the calling Prolog process. Tool is one of self, swipl, swipl-win or swipl-ld. See prolog:prolog_tool/4 for details.

Args is a list of arguments that are handed to the new process. On Unix systems, each element in the list becomes a separate argument in the new process. In Windows, the arguments are simply concatenated to form the commandline. Each argument itself is either a primitive or a list of primitives. A primitive is either atomic or a term file(Spec). Using file(Spec), the system inserts a filename using the OS filename conventions which is properly quoted if needed.

Options:

stdin(Spec)

stdout(Spec)

stderr(Spec)

Bind the standard streams of the new process. Spec is one of the terms below. If pipe(Pipe) is used, the Prolog stream is a stream in text-mode using the encoding of the default locale. The encoding can be changed using set_stream/2, or by using the two-argument form of pipe, which accepts an encoding(Encoding) option. The options stdout and stderr may use the same stream, in which case both output streams are connected to the same Prolog stream.

std

Just share with the Prolog I/O streams. On Unix, if the user_input, etc. are bound to a file handle but not to 0,1,2 the process I/O is bound to the file handles of these streams.

null

Bind to a null stream. Reading from such a stream returns end-of-file, writing produces no output

pipe(-Stream)

pipe(-Stream, +StreamOptions)

Attach input and/or output to a Prolog stream. The optional StreamOptions argument is a list of options that affect the stream. Currently only the options type(+Type) and encoding(+Encoding) are supported, which have the same meaning as the stream properties of the same name (see stream_property/2). StreamOptions is provided mainly for SICStus compatibility - the SWI-Prolog predicate set_stream/2 can be used for the same purpose.

stream(+Stream)

Attach input or output to an existing Prolog stream. This stream must be associated with an OS file handle (see stream_property/2, property file_no). This option is not provided by the SICStus implementation.

cwd(+Directory)

Run the new process in Directory. Directory can be a compound specification, which is converted using absolute_file_name/3. See also process_set_method/1.

env(+List)

As environment(List), but only the specified variables are passed, i.e., no variables are inherited.

environment(+List)

Specify additional environment variables for the new process. List is a list of Name=Value terms, where Value is expanded the same way as the Args argument. If neither env nor environment is passed the environment is inherited from the Prolog process. At most one env(List) or environment(List) term may appear in the options. If multiple appear a permission_error is raised for the second option.

process(-PID)

Unify PID with the process id of the created process.

detached(+Bool)

In Unix: If true, detach the process from the terminal Currently mapped to setsid(); Also creates a new process group for the child In Windows: If true, detach the process from the current job via the CREATE_BREAKAWAY_FROM_JOB flag. In Vista and beyond, processes launched from the shell directly have the 'compatibility assistant' attached to them automatically unless they have a UAC manifest embedded in them. This means that you will get a permission denied error if you try and assign the newly-created PID to a job you create yourself.

If neither process(PID) nor any pipe is used the process is moreover not waited for: process_create/3 returns as soon as the process is started and its exit status is not available. On POSIX systems this is realised using a second fork(), such that the process is inherited by init rather than by us.

window(+Bool)

If true, create a window for the process (Windows only)

priority(+Priority)

In Unix: specifies the process priority for the newly created process. Priority must be an integer between -20 and 19. Positive values are nicer to others, and negative values are less so. The default is zero. Users are free to lower their own priority. Only the super-user may raise it to less-than zero.

If the user specifies the process(-PID) option, he must call process_wait/2 to reclaim the process. Without this option, the system will wait for completion of the process after the last pipe stream is closed, unless detached(true) is used.

If the process is not waited for, it must succeed with status 0. If not, an process_error is raised.

Windows notes

On Windows this call is an interface to the CreateProcess() API. The commandline consists of the basename of Exe and the arguments formed from Args. Arguments are separated by a single space. If all characters satisfy iswalnum() it is unquoted. If the argument contains a double-quote it is quoted using single quotes. If both single and double quotes appear a domain_error is raised, otherwise double-quote are used.

The CreateProcess() API has many options. Currently only the CREATE_NO_WINDOW options is supported through the window(+Bool) option. If omitted, the default is to use this option if the application has no console. Future versions are likely to support more window specific options and replace win_exec/2.

Examples

First, a very simple example that behaves the same as shell('ls -l'), except for error handling:

?- process_create(path(ls), ['-l'], []).

The following example uses grep to find all matching lines in a file.

grep(File, Pattern, Lines) :-
        setup_call_cleanup(
            process_create(path(grep), [ Pattern, file(File) ],
                           [ stdout(pipe(Out))
                           ]),
            read_lines(Out, Lines),
            close(Out)).

read_lines(Out, Lines) :-
        read_line_to_codes(Out, Line1),
        read_lines(Line1, Out, Lines).

read_lines(end_of_file, _, []) :- !.
read_lines(Codes, Out, [Line|Lines]) :-
        atom_codes(Line, Codes),
        read_line_to_codes(Out, Line2),
        read_lines(Line2, Out, Lines).

Errors

- process_error(Exe, Status) where Status is one of exit(Code) or killed(Signal). Raised if the process is waited for (i.e., Options does not include process(-PID)), and does not exit with status 0.

bug

- On Windows, environment(List) is handled as env(List), i.e., the environment is not inherited.

  277process_create(prolog(Prolog), Args, Options) =>
  278    prolog_executable(Prolog, Exe, Args, Args1),
  279    process_create(Exe, Args1, Options).
  280process_create(Exe, Args, Options) =>
  281    (   exe_options(ExeOptions),
  282        absolute_file_name(Exe, PlProg, ExeOptions)
  283    ->  true
  284    ),
  285    must_be(list, Args),
  286    maplist(map_arg, Args, Av),
  287    prolog_to_os_filename(PlProg, Prog),
  288    Term =.. [Prog|Av],
  289    expand_cwd_option(Options, Options1),
  290    expand_env_option(env, Options1, Options2),
  291    expand_env_option(environment, Options2, Options3),
  292    process_create(Term, Options3).

 prolog_executable(+Tool, -Exe, +ArgvIn, -Argv) is det

 prolog:prolog_tool(+Tool, -Exe, +ArgvIn, -Argv) is semidet

Find the executable and commandline arguments for running Tool. This provides a hook for process_create/3 called as process_create(prolog(Tool), ...). Tool is currently one of:

[115, 101, 108, 102]

Run Prolog itself.

[115, 119, 105, 112, 108]

Run the commandline version, also when called from the swipl-win app.

[115, 119, 105, 112, 108, 45, 119, 105, 110]

Run the swipl-win app, also when called from the commandline version.

[115, 119, 105, 112, 108, 45, 108, 100]

Run the C/C++ compiler frontend to embed Prolog or build foreign extensions.

prolog:prolog_tool/4 is defined as multifile and dynamic and can be used for special cases. This hook is notably intended to provide a portable way of calling Prolog when Prolog is embedded.

For example, when using rswipl, we can run Prolog using

R -s -e 'rswipl::swipl()' --args <Prolog Argv>

We can make process_create(prolog(swipl), ...) work using

:- multifile prolog:prolog_tool/4.
prolog:prolog_tool(swipl, path('R'), Argv,
                   [ '-s', '-e', 'rswipl::swipl()', '--args'
                   | Argv
                   ]).

  333prolog_executable(Prolog, Exe, Args0, Args),
  334    prolog:prolog_tool(Prolog, Exe, Args0, Args) =>
  335    true.
  336prolog_executable(self, Exe, Args0, Args) =>
  337    current_prolog_flag(executable, Exe),
  338    add_home_option(Args0, Args).
  339prolog_executable(Tool, Exe, Args0, Args),
  340    swipl_tool(Tool) =>
  341    current_prolog_flag(executable, Me),
  342    neighbour_exe(Tool, Me, Exe),
  343    add_home_option(Args0, Args).
  344
  345swipl_tool(swipl).
  346swipl_tool('swipl-win').
  347swipl_tool('swipl-ld').
  348
  349neighbour_exe(Target, Me, Exe) :-
  350    file_directory_name(Me, Dir),
  351    file_name_extension(_, Ext, Me),
  352    atomic_list_concat([Dir, Target], '/', Base),
  353    file_name_extension(Base, Ext, Exe).
  354
  355add_home_option(Args0, [HomeOption|Args0]) :-
  356    current_prolog_flag(home, Home),
  357    format(atom(HomeOption), '--home=~w', [Home]).

 process_which(+Exe, -Path) is semidet

True when Path is an absolute file name for the specification Exe. This deals with the search path as well as extensions used by the OS.

  365process_which(Exe, Path) :-
  366    exe_options(ExeOptions),
  367    absolute_file_name(Exe, Path, [file_errors(fail)|ExeOptions]),
  368    !.

 exe_options(-Options) is multi

Get options for absolute_file_name to find an executable file. On Windows we first look for a readable file, but if this does not exist we are happy with a existing file because the file may be a reparse point

  377exe_options(Options) :-
  378    current_prolog_flag(windows, true),
  379    !,
  380    (   Options = [ extensions(['',exe,com]), access(read), file_errors(fail) ]
  381    ;   Options = [ extensions(['',exe,com]), access(exist) ]
  382    ).
  383exe_options(Options) :-
  384    Options = [ access(execute) ].
  385
  386expand_cwd_option(Options0, Options) :-
  387    select_option(cwd(Spec), Options0, Options1),
  388    !,
  389    (   compound(Spec)
  390    ->  absolute_file_name(Spec, PlDir, [file_type(directory), access(read)]),
  391        prolog_to_os_filename(PlDir, Dir),
  392        Options = [cwd(Dir)|Options1]
  393    ;   exists_directory(Spec)
  394    ->  Options = Options0
  395    ;   existence_error(directory, Spec)
  396    ).
  397expand_cwd_option(Options, Options).
  398
  399expand_env_option(Name, Options0, Options) :-
  400    Term =.. [Name,Value0],
  401    select_option(Term, Options0, Options1),
  402    !,
  403    must_be(list, Value0),
  404    maplist(map_env, Value0, Value),
  405    NewOption =.. [Name,Value],
  406    Options = [NewOption|Options1].
  407expand_env_option(_, Options, Options).
  408
  409map_env(Name=Value0, Name=Value) :-
  410    map_arg(Value0, Value).

 map_arg(+ArgIn, -Arg) is det

Map an individual argument. Primitives are either file(Spec) or an atomic value (atom, string, number). If ArgIn is a non-empty list, all elements are converted and the results are concatenated.

  419map_arg([], []) :- !.
  420map_arg(List, Arg) :-
  421    is_list(List),
  422    !,
  423    maplist(map_arg_prim, List, Prims),
  424    atomic_list_concat(Prims, Arg).
  425map_arg(Prim, Arg) :-
  426    map_arg_prim(Prim, Arg).
  427
  428map_arg_prim(file(Spec), File) :-
  429    !,
  430    (   compound(Spec)
  431    ->  absolute_file_name(Spec, PlFile)
  432    ;   PlFile = Spec
  433    ),
  434    prolog_to_os_filename(PlFile, File).
  435map_arg_prim(Arg, Arg).

 process_id(-PID) is det

True if PID is the process id of the running Prolog process.

deprecated

- Use current_prolog_flag(pid, PID)

  444process_id(PID) :-
  445    current_prolog_flag(pid, PID).

 process_id(+Process, -PID) is det

PID is the process id of Process. Given that they are united in SWI-Prolog, this is a simple unify.

  452process_id(PID, PID).

 is_process(+PID) is semidet

True if PID might be a process. Succeeds for any positive integer.

  459is_process(PID) :-
  460    integer(PID),
  461    PID > 0.

 process_release(+PID)

Release process handle. In this implementation this is the same as process_wait(PID, _).

  468process_release(PID) :-
  469    process_wait(PID, _).

 process_wait(+PID, -Status) is det

 process_wait(+PID, -Status, +Options) is det

True if PID completed with Status. This call normally blocks until the process is finished. Options:

timeout(+Timeout)

Default: infinite. If this option is a number, the waits for a maximum of Timeout seconds and unifies Status with timeout if the process does not terminate within Timeout. In this case PID is not invalidated. On Unix systems only timeout 0 and infinite are supported. A 0-value can be used to poll the status of the process.

release(+Bool)

Do/do not release the process. We do not support this flag and a domain_error is raised if release(false) is provided.

Arguments:

Status

- is one of exit(Code) or killed(Signal), where Code and Signal are integers. If the timeout option is used Status is unified with timeout after the wait timed out.

  494process_wait(PID, Status) :-
  495    process_wait(PID, Status, []).

 process_kill(+PID) is det

 process_kill(+PID, +Signal) is det

Send signal to process PID. Default is term. Signal is an integer, Unix signal name (e.g. SIGSTOP) or the more Prolog friendly variation one gets after removing SIG and downcase the result: stop. On Windows systems, Signal is ignored and the process is terminated using the TerminateProcess() API. On Windows systems PID must be obtained from process_create/3, while any PID is allowed on Unix systems.

Compatibility

- SICStus does not accept the prolog friendly version. We choose to do so for compatibility with on_signal/3.

  511process_kill(PID) :-
  512    process_kill(PID, term).

 process_group_kill(+PID) is det

 process_group_kill(+PID, +Signal) is det

Send signal to the group containing process PID. Default is term. See process_wait/1 for a description of signal handling. In Windows, the same restriction on PID applies: it must have been created from process_create/3, and the the group is terminated via the TerminateJobObject API.

  524process_group_kill(PID) :-
  525    process_group_kill(PID, term).

 process_set_method(+Method) is det

Determine how the process is created on Unix systems. Method is one of spawn (default), fork or vfork. If the method is spawn but this cannot be used because it is either not supported by the OS or the cwd(Dir) option is given fork is used.

The problem is to be understood as follows. The official portable and safe method to create a process is using the fork() system call. This call however copies the process page tables and get seriously slow as the (Prolog) process is multiple giga bytes large. Alternatively, we may use vfork() which avoids copying the process space. But, the safe usage as guaranteed by the POSIX standard of vfork() is insufficient for our purposes. On practical systems your mileage may vary. Modern posix systems also provide posix_spawn(), which provides a safe and portable alternative for the fork() and exec() sequence that may be implemented using fork() or may use a fast but safe alternative. Unfortunately posix_spawn() doesn't support the option to specify the working directory for the child and we cannot use working_directory/2 as the working directory is shared between threads.

Summarizing, the default is safe and tries to be as fast as possible. On some scenarios and on some OSes it is possible to do better. It is generally a good idea to avoid using the cwd(Dir) option of process_create/3 as without we can use posix_spawn().

  556                 /*******************************
  557                 *            MESSAGES          *
  558                 *******************************/
  559
  560:- multifile
  561    prolog:error_message/3.  562
  563prolog:error_message(process_error(File, exit(Status))) -->
  564    [ 'Process "~w": exit status: ~w'-[File, Status] ].
  565prolog:error_message(process_error(File, killed(Signal))) -->
  566    [ 'Process "~w": killed by signal ~w'-[File, Signal] ].
  567prolog:error_message(existence_error(source_sink, path(Exe))) -->
  568    [ 'Could not find executable file "~p" in '-[Exe] ],
  569    path_var.
  570
  571path_var -->
  572    (   { current_prolog_flag(windows, true) }
  573    ->  [ '%PATH%'-[] ]
  574    ;   [ '$PATH'-[] ]
  575    )