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

?- 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. Args is a list of arguments that are handed to the new process. On Unix systems, each element in the list becomes a seperate 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. 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

null

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

pipe(-Stream)

Attach input and/or output to a Prolog stream.

cwd(+Directory)

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

env(+List)

Specify the environment for the new process. List is a list of Name=Value terms. Note that the current implementation does not pass any environment variables. If unspecified, the environment is inherited from the Prolog process.

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.

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.

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.

  240process_create(Exe, Args, Options) :-
  241    exe_options(ExeOptions),
  242    absolute_file_name(Exe, PlProg, ExeOptions),
  243    must_be(list, Args),
  244    maplist(map_arg, Args, Av),
  245    prolog_to_os_filename(PlProg, Prog),
  246    Term =.. [Prog|Av],
  247    expand_cwd_option(Options, Options1),
  248    process_create(Term, Options1).
  249
  250exe_options(Options) :-
  251    current_prolog_flag(windows, true),
  252    !,
  253    Options = [ extensions(['',exe,com]), access(read) ].
  254exe_options(Options) :-
  255    Options = [ access(execute) ].
  256
  257expand_cwd_option(Options0, Options) :-
  258    select_option(cwd(Spec), Options0, Options1),
  259    !,
  260    (   compound(Spec)
  261    ->  absolute_file_name(Spec, PlDir, [file_type(directory), access(read)]),
  262        prolog_to_os_filename(PlDir, Dir),
  263        Options = [cwd(Dir)|Options1]
  264    ;   exists_directory(Spec)
  265    ->  Options = Options0
  266    ;   existence_error(directory, Spec)
  267    ).
  268expand_cwd_option(Options, Options).

 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.

  278map_arg([], []) :- !.
  279map_arg(List, Arg) :-
  280    is_list(List),
  281    !,
  282    maplist(map_arg_prim, List, Prims),
  283    atomic_list_concat(Prims, Arg).
  284map_arg(Prim, Arg) :-
  285    map_arg_prim(Prim, Arg).
  286
  287map_arg_prim(file(Spec), File) :-
  288    !,
  289    (   compound(Spec)
  290    ->  absolute_file_name(Spec, PlFile)
  291    ;   PlFile = Spec
  292    ),
  293    prolog_to_os_filename(PlFile, File).
  294map_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)

  303process_id(PID) :-
  304    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.

  311process_id(PID, PID).

 is_process(+PID) is semidet

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

  318is_process(PID) :-
  319    integer(PID),
  320    PID > 0.

 process_release(+PID)

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

  327process_release(PID) :-
  328    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.

  351process_wait(PID, Status) :-
  352    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.

  368process_kill(PID) :-
  369    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.

  381process_group_kill(PID) :-
  382    process_group_kill(PID, term).
  383
  384
  385                 /*******************************
  386                 *            MESSAGES          *
  387                 *******************************/
  388
  389:- multifile
  390    prolog:error_message/3.  391
  392prolog:error_message(process_error(File, exit(Status))) -->
  393    [ 'Process "~w": exit status: ~w'-[File, Status] ].
  394prolog:error_message(process_error(File, killed(Signal))) -->
  395    [ 'Process "~w": killed by signal ~w'-[File, Signal] ]