View source with formatted comments or as raw
    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-2022, 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
   51            process_set_method/1        % +CreateMethod
   52          ]).   53:- autoload(library(apply),[maplist/3]).   54:- autoload(library(error),[must_be/2,existence_error/2]).   55:- autoload(library(option),[select_option/3]).   56
   57
   58:- use_foreign_library(foreign(process)).   59
   60:- predicate_options(process_create/3, 3,
   61                     [ stdin(any),
   62                       stdout(any),
   63                       stderr(any),
   64                       cwd(atom),
   65                       env(list(any)),
   66                       environment(list(any)),
   67                       priority(+integer),
   68                       process(-integer),
   69                       detached(+boolean),
   70                       window(+boolean)
   71                     ]).   72
   73/** <module> Create processes and redirect I/O
   74
   75The module library(process) implements interaction  with child processes
   76and unifies older interfaces such   as  shell/[1,2], open(pipe(command),
   77...) etc. This library is modelled after SICStus 4.
   78
   79The main interface is formed by process_create/3.   If the process id is
   80requested the process must be waited for using process_wait/2. Otherwise
   81the process resources are reclaimed automatically.
   82
   83In addition to the predicates, this module   defines  a file search path
   84(see user:file_search_path/2 and absolute_file_name/3) named =path= that
   85locates files on the system's  search   path  for  executables. E.g. the
   86following finds the executable for =ls=:
   87
   88    ==
   89    ?- absolute_file_name(path(ls), Path, [access(execute)]).
   90    ==
   91
   92*|Incompatibilities and current limitations|*
   93
   94    * Where SICStus distinguishes between an internal process id and
   95    the OS process id, this implementation does not make this
   96    distinction. This implies that is_process/1 is incomplete and
   97    unreliable.
   98
   99    * It is unclear what the detached(true) option is supposed to do. Disable
  100    signals in the child? Use setsid() to detach from the session?  The
  101    current implementation uses setsid() on Unix systems.
  102
  103    * An extra option env([Name=Value, ...]) is added to
  104    process_create/3.  As of version 4.1 SICStus added
  105    environment(List) which _modifies_ the environment.  A
  106    compatible option was added to SWI-Prolog 7.7.23.
  107
  108@tbd    Implement detached option in process_create/3
  109@compat SICStus 4
  110*/
  111
  112
  113%!  process_create(+Exe, +Args:list, +Options) is det.
  114%
  115%   Create a new process running the   file  Exe and using arguments
  116%   from the given list. Exe is a   file  specification as handed to
  117%   absolute_file_name/3. Typically one use the =path= file alias to
  118%   specify an executable file on the current   PATH. Args is a list
  119%   of arguments that  are  handed  to   the  new  process.  On Unix
  120%   systems, each element in the list becomes a separate argument in
  121%   the  new  process.  In  Windows,    the   arguments  are  simply
  122%   concatenated to form the commandline.   Each  argument itself is
  123%   either a primitive or  a  list   of  primitives.  A primitive is
  124%   either atomic or a term file(Spec). Using file(Spec), the system
  125%   inserts a filename using the OS   filename  conventions which is
  126%   properly quoted if needed.
  127%
  128%   Options:
  129%
  130%       * stdin(Spec)
  131%       * stdout(Spec)
  132%       * stderr(Spec)
  133%       Bind the standard streams of the new process. Spec is one of
  134%       the terms below. If pipe(Pipe) is used, the Prolog stream is
  135%       a stream in text-mode using the encoding of the default
  136%       locale.  The encoding can be changed using set_stream/2,
  137%       or by using the two-argument form of =pipe=, which accepts an
  138%       encoding(Encoding) option.
  139%       The options =stdout= and =stderr= may use the same stream,
  140%       in which case both output streams are connected to the same
  141%       Prolog stream.
  142%
  143%           * std
  144%           Just share with the Prolog I/O streams.  On Unix,
  145%           if the `user_input`, etc. are bound to a file handle
  146%           but not to 0,1,2 the process I/O is bound to the file
  147%           handles of these streams.
  148%           * null
  149%           Bind to a _null_ stream. Reading from such a stream
  150%           returns end-of-file, writing produces no output
  151%           * pipe(-Stream)
  152%           * pipe(-Stream, +StreamOptions)
  153%           Attach input and/or output to a Prolog stream.
  154%           The optional StreamOptions argument is a list of options
  155%           that affect the stream. Currently only the options
  156%           type(+Type) and encoding(+Encoding) are supported,
  157%           which have the same meaning as the stream properties
  158%           of the same name (see stream_property/2).
  159%           StreamOptions is provided mainly for SICStus compatibility -
  160%           the SWI-Prolog predicate set_stream/2 can be used
  161%           for the same purpose.
  162%           * stream(+Stream)
  163%           Attach input or output to an existing Prolog stream.
  164%           This stream must be associated with an OS file
  165%           handle (see stream_property/2, property `file_no`).
  166%           This option is __not__ provided by the SICStus
  167%           implementation.
  168%
  169%       * cwd(+Directory)
  170%       Run the new process in Directory.  Directory can be a
  171%       compound specification, which is converted using
  172%       absolute_file_name/3.  See also process_set_method/1.
  173%       * env(+List)
  174%       As environment(List), but _only_ the specified variables
  175%       are passed, i.e., no variables are _inherited_.
  176%       * environment(+List)
  177%       Specify _additional_ environment variables for the new process.
  178%       List is a list of `Name=Value` terms, where `Value` is expanded
  179%       the same way as the Args argument. If neither `env` nor
  180%       `environment` is passed the environment is inherited from the
  181%       Prolog process.  At most one env(List) or environment(List) term
  182%       may appear in the options. If multiple appear a
  183%       `permission_error` is raised for the second option.
  184%       * process(-PID)
  185%       Unify PID with the process id of the created process.
  186%       * detached(+Bool)
  187%       In Unix: If =true=, detach the process from the terminal
  188%       Currently mapped to setsid();
  189%       Also creates a new process group for the child
  190%       In Windows: If =true=, detach the process from the current
  191%       job via the CREATE_BREAKAWAY_FROM_JOB flag. In Vista and beyond,
  192%       processes launched from the shell directly have the 'compatibility
  193%       assistant' attached to them automatically unless they have a UAC
  194%       manifest embedded in them. This means that you will get a
  195%       permission denied error if you try and assign the newly-created
  196%       PID to a job you create yourself.
  197%       * window(+Bool)
  198%       If =true=, create a window for the process (Windows only)
  199%       * priority(+Priority)
  200%       In Unix: specifies the process priority for the newly
  201%       created process. Priority must be an integer between -20
  202%       and 19. Positive values are nicer to others, and negative
  203%       values are less so. The default is zero. Users are free to
  204%       lower their own priority. Only the super-user may _raise_ it
  205%       to less-than zero.
  206%
  207%   If the user specifies the process(-PID)   option, he *must* call
  208%   process_wait/2 to reclaim the process.  Without this option, the
  209%   system will wait for completion of   the  process after the last
  210%   pipe stream is closed.
  211%
  212%   If the process is not waited for, it must succeed with status 0.
  213%   If not, an process_error is raised.
  214%
  215%   *|Windows notes|*
  216%
  217%   On Windows this call is an interface to the CreateProcess() API.
  218%   The  commandline  consists  of  the  basename  of  Exe  and  the
  219%   arguments formed from Args. Arguments are  separated by a single
  220%   space. If all characters satisfy iswalnum()   it is unquoted. If
  221%   the argument contains a double-quote it   is quoted using single
  222%   quotes. If both single and double   quotes appear a domain_error
  223%   is raised, otherwise double-quote are used.
  224%
  225%   The CreateProcess() API has  many   options.  Currently only the
  226%   =CREATE_NO_WINDOW=   options   is   supported     through    the
  227%   window(+Bool) option. If omitted, the  default   is  to use this
  228%   option if the application has no   console.  Future versions are
  229%   likely to support  more  window   specific  options  and replace
  230%   win_exec/2.
  231%
  232%   *Examples*
  233%
  234%   First,  a  very  simple  example  that    behaves  the  same  as
  235%   =|shell('ls -l')|=, except for error handling:
  236%
  237%   ==
  238%   ?- process_create(path(ls), ['-l'], []).
  239%   ==
  240%
  241%   The following example uses grep to find  all matching lines in a
  242%   file.
  243%
  244%   ==
  245%   grep(File, Pattern, Lines) :-
  246%           setup_call_cleanup(
  247%               process_create(path(grep), [ Pattern, file(File) ],
  248%                              [ stdout(pipe(Out))
  249%                              ]),
  250%               read_lines(Out, Lines),
  251%               close(Out)).
  252%
  253%   read_lines(Out, Lines) :-
  254%           read_line_to_codes(Out, Line1),
  255%           read_lines(Line1, Out, Lines).
  256%
  257%   read_lines(end_of_file, _, []) :- !.
  258%   read_lines(Codes, Out, [Line|Lines]) :-
  259%           atom_codes(Line, Codes),
  260%           read_line_to_codes(Out, Line2),
  261%           read_lines(Line2, Out, Lines).
  262%   ==
  263%
  264%   @error  process_error(Exe, Status) where Status is one of
  265%           exit(Code) or killed(Signal).  Raised if the process
  266%           is waited for (i.e., Options does not include
  267%           process(-PID)), and does not exit with status 0.
  268%   @bug    On Windows, environment(List) is handled as env(List),
  269%           i.e., the environment is not inherited.
  270
  271process_create(Exe, Args, Options) :-
  272    exe_options(ExeOptions),
  273    absolute_file_name(Exe, PlProg, ExeOptions),
  274    must_be(list, Args),
  275    maplist(map_arg, Args, Av),
  276    prolog_to_os_filename(PlProg, Prog),
  277    Term =.. [Prog|Av],
  278    expand_cwd_option(Options, Options1),
  279    expand_env_option(env, Options1, Options2),
  280    expand_env_option(environment, Options2, Options3),
  281    process_create(Term, Options3).
  282
  283exe_options(Options) :-
  284    current_prolog_flag(windows, true),
  285    !,
  286    Options = [ extensions(['',exe,com]), access(read) ].
  287exe_options(Options) :-
  288    Options = [ access(execute) ].
  289
  290expand_cwd_option(Options0, Options) :-
  291    select_option(cwd(Spec), Options0, Options1),
  292    !,
  293    (   compound(Spec)
  294    ->  absolute_file_name(Spec, PlDir, [file_type(directory), access(read)]),
  295        prolog_to_os_filename(PlDir, Dir),
  296        Options = [cwd(Dir)|Options1]
  297    ;   exists_directory(Spec)
  298    ->  Options = Options0
  299    ;   existence_error(directory, Spec)
  300    ).
  301expand_cwd_option(Options, Options).
  302
  303expand_env_option(Name, Options0, Options) :-
  304    Term =.. [Name,Value0],
  305    select_option(Term, Options0, Options1),
  306    !,
  307    must_be(list, Value0),
  308    maplist(map_env, Value0, Value),
  309    NewOption =.. [Name,Value],
  310    Options = [NewOption|Options1].
  311expand_env_option(_, Options, Options).
  312
  313map_env(Name=Value0, Name=Value) :-
  314    map_arg(Value0, Value).
  315
  316%!  map_arg(+ArgIn, -Arg) is det.
  317%
  318%   Map an individual argument. Primitives  are either file(Spec) or
  319%   an atomic value (atom, string, number).  If ArgIn is a non-empty
  320%   list,  all  elements  are   converted    and   the  results  are
  321%   concatenated.
  322
  323map_arg([], []) :- !.
  324map_arg(List, Arg) :-
  325    is_list(List),
  326    !,
  327    maplist(map_arg_prim, List, Prims),
  328    atomic_list_concat(Prims, Arg).
  329map_arg(Prim, Arg) :-
  330    map_arg_prim(Prim, Arg).
  331
  332map_arg_prim(file(Spec), File) :-
  333    !,
  334    (   compound(Spec)
  335    ->  absolute_file_name(Spec, PlFile)
  336    ;   PlFile = Spec
  337    ),
  338    prolog_to_os_filename(PlFile, File).
  339map_arg_prim(Arg, Arg).
  340
  341
  342%!  process_id(-PID) is det.
  343%
  344%   True if PID is the process id of the running Prolog process.
  345%
  346%   @deprecated     Use current_prolog_flag(pid, PID)
  347
  348process_id(PID) :-
  349    current_prolog_flag(pid, PID).
  350
  351%!  process_id(+Process, -PID) is det.
  352%
  353%   PID is the process id of Process.  Given that they are united in
  354%   SWI-Prolog, this is a simple unify.
  355
  356process_id(PID, PID).
  357
  358%!  is_process(+PID) is semidet.
  359%
  360%   True if PID might  be  a   process.  Succeeds  for  any positive
  361%   integer.
  362
  363is_process(PID) :-
  364    integer(PID),
  365    PID > 0.
  366
  367%!  process_release(+PID)
  368%
  369%   Release process handle.  In this implementation this is the same
  370%   as process_wait(PID, _).
  371
  372process_release(PID) :-
  373    process_wait(PID, _).
  374
  375%!  process_wait(+PID, -Status) is det.
  376%!  process_wait(+PID, -Status, +Options) is det.
  377%
  378%   True if PID completed with  Status.   This  call normally blocks
  379%   until the process is finished.  Options:
  380%
  381%       * timeout(+Timeout)
  382%       Default: =infinite=.  If this option is a number, the
  383%       waits for a maximum of Timeout seconds and unifies Status
  384%       with =timeout= if the process does not terminate within
  385%       Timeout.  In this case PID is _not_ invalidated.  On Unix
  386%       systems only timeout 0 and =infinite= are supported.  A
  387%       0-value can be used to poll the status of the process.
  388%
  389%       * release(+Bool)
  390%       Do/do not release the process.  We do not support this flag
  391%       and a domain_error is raised if release(false) is provided.
  392%
  393%   @arg  Status is one of exit(Code) or killed(Signal), where
  394%         Code and Signal are integers.  If the `timeout` option
  395%         is used Status is unified with `timeout` after the wait
  396%         timed out.
  397
  398process_wait(PID, Status) :-
  399    process_wait(PID, Status, []).
  400
  401%!  process_kill(+PID) is det.
  402%!  process_kill(+PID, +Signal) is det.
  403%
  404%   Send signal to process PID.  Default   is  =term=.  Signal is an
  405%   integer, Unix signal name (e.g. =SIGSTOP=)   or  the more Prolog
  406%   friendly variation one gets after   removing  =SIG= and downcase
  407%   the result: =stop=. On Windows systems,   Signal  is ignored and
  408%   the process is terminated using   the TerminateProcess() API. On
  409%   Windows systems PID must  be   obtained  from  process_create/3,
  410%   while any PID is allowed on Unix systems.
  411%
  412%   @compat SICStus does not accept the prolog friendly version.  We
  413%           choose to do so for compatibility with on_signal/3.
  414
  415process_kill(PID) :-
  416    process_kill(PID, term).
  417
  418
  419%!  process_group_kill(+PID) is det.
  420%!  process_group_kill(+PID, +Signal) is det.
  421%
  422%   Send signal to the group containing process PID.  Default   is
  423%   =term=.   See process_wait/1  for  a  description  of  signal
  424%   handling. In Windows, the same restriction on PID applies: it
  425%   must have been created from process_create/3, and the the group
  426%   is terminated via the TerminateJobObject API.
  427
  428process_group_kill(PID) :-
  429    process_group_kill(PID, term).
  430
  431
  432%!  process_set_method(+Method) is det.
  433%
  434%   Determine how the process is created on  Unix systems. Method is one
  435%   of `spawn` (default), `fork` or `vfork`.   If  the method is `spawn`
  436%   but this cannot be used because it is either not supported by the OS
  437%   or the cwd(Dir) option is given `fork` is used.
  438%
  439%   The problem is to be understood   as  follows. The official portable
  440%   and safe method to create a process is using the fork() system call.
  441%   This call however copies the process   page tables and get seriously
  442%   slow  as  the  (Prolog)  process  is   multiple  giga  bytes  large.
  443%   Alternatively, we may use vfork() which   avoids copying the process
  444%   space. But, the safe usage as guaranteed   by  the POSIX standard of
  445%   vfork() is insufficient for our purposes.  On practical systems your
  446%   mileage may vary. Modern posix   systems also provide posix_spawn(),
  447%   which provides a safe and portable   alternative  for the fork() and
  448%   exec() sequence that may be implemented using   fork()  or may use a
  449%   fast  but  safe  alternative.  Unfortunately  posix_spawn()  doesn't
  450%   support the option to specify the   working  directory for the child
  451%   and we cannot use working_directory/2 as   the  working directory is
  452%   shared between threads.
  453%
  454%   Summarizing, the default is  safe  and  tries   to  be  as  fast  as
  455%   possible. On some scenarios and on some   OSes  it is possible to do
  456%   better. It is generally a good  idea   to  avoid  using the cwd(Dir)
  457%   option of process_create/3 as without we can use posix_spawn().
  458
  459
  460                 /*******************************
  461                 *            MESSAGES          *
  462                 *******************************/
  463
  464:- multifile
  465    prolog:error_message/3.  466
  467prolog:error_message(process_error(File, exit(Status))) -->
  468    [ 'Process "~w": exit status: ~w'-[File, Status] ].
  469prolog:error_message(process_error(File, killed(Signal))) -->
  470    [ 'Process "~w": killed by signal ~w'-[File, Signal] ].
  471prolog:error_message(existence_error(source_sink, path(Exe))) -->
  472    [ 'Could not find executable file "~p" in '-[Exe] ],
  473    path_var.
  474
  475path_var -->
  476    (   { current_prolog_flag(windows, true) }
  477    ->  [ '%PATH%'-[] ]
  478    ;   [ '$PATH'-[] ]
  479    )