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