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 -> true 275 ), 276 must_be(list, Args), 277 maplist(map_arg, Args, Av), 278 prolog_to_os_filename(PlProg, Prog), 279 Term =.. [Prog|Av], 280 expand_cwd_option(Options, Options1), 281 expand_env_option(env, Options1, Options2), 282 expand_env_option(environment, Options2, Options3), 283 process_create(Term, Options3). 284 285%! exe_options(-Options) is multi. 286% 287% Get options for absolute_file_name to find an executable file. On 288% Windows we first look for a readable file, but if this does not 289% exist we are happy with a existing file because the file may be a 290% [reparse point](https://docs.microsoft.com/en-us/windows/win32/fileio/reparse-points-and-file-operations) 291 292exe_options(Options) :- 293 current_prolog_flag(windows, true), 294 !, 295 ( Options = [ extensions(['',exe,com]), access(read), file_errors(fail) ] 296 ; Options = [ extensions(['',exe,com]), access(exist) ] 297 ). 298exe_options(Options) :- 299 Options = [ access(execute) ]. 300 301expand_cwd_option(Options0, Options) :- 302 select_option(cwd(Spec), Options0, Options1), 303 !, 304 ( compound(Spec) 305 -> absolute_file_name(Spec, PlDir, [file_type(directory), access(read)]), 306 prolog_to_os_filename(PlDir, Dir), 307 Options = [cwd(Dir)|Options1] 308 ; exists_directory(Spec) 309 -> Options = Options0 310 ; existence_error(directory, Spec) 311 ). 312expand_cwd_option(Options, Options). 313 314expand_env_option(Name, Options0, Options) :- 315 Term =.. [Name,Value0], 316 select_option(Term, Options0, Options1), 317 !, 318 must_be(list, Value0), 319 maplist(map_env, Value0, Value), 320 NewOption =.. [Name,Value], 321 Options = [NewOption|Options1]. 322expand_env_option(_, Options, Options). 323 324map_env(Name=Value0, Name=Value) :- 325 map_arg(Value0, Value). 326 327%! map_arg(+ArgIn, -Arg) is det. 328% 329% Map an individual argument. Primitives are either file(Spec) or 330% an atomic value (atom, string, number). If ArgIn is a non-empty 331% list, all elements are converted and the results are 332% concatenated. 333 334map_arg([], []) :- !. 335map_arg(List, Arg) :- 336 is_list(List), 337 !, 338 maplist(map_arg_prim, List, Prims), 339 atomic_list_concat(Prims, Arg). 340map_arg(Prim, Arg) :- 341 map_arg_prim(Prim, Arg). 342 343map_arg_prim(file(Spec), File) :- 344 !, 345 ( compound(Spec) 346 -> absolute_file_name(Spec, PlFile) 347 ; PlFile = Spec 348 ), 349 prolog_to_os_filename(PlFile, File). 350map_arg_prim(Arg, Arg). 351 352 353%! process_id(-PID) is det. 354% 355% True if PID is the process id of the running Prolog process. 356% 357% @deprecated Use current_prolog_flag(pid, PID) 358 359process_id(PID) :- 360 current_prolog_flag(pid, PID). 361 362%! process_id(+Process, -PID) is det. 363% 364% PID is the process id of Process. Given that they are united in 365% SWI-Prolog, this is a simple unify. 366 367process_id(PID, PID). 368 369%! is_process(+PID) is semidet. 370% 371% True if PID might be a process. Succeeds for any positive 372% integer. 373 374is_process(PID) :- 375 integer(PID), 376 PID > 0. 377 378%! process_release(+PID) 379% 380% Release process handle. In this implementation this is the same 381% as process_wait(PID, _). 382 383process_release(PID) :- 384 process_wait(PID, _). 385 386%! process_wait(+PID, -Status) is det. 387%! process_wait(+PID, -Status, +Options) is det. 388% 389% True if PID completed with Status. This call normally blocks 390% until the process is finished. Options: 391% 392% * timeout(+Timeout) 393% Default: =infinite=. If this option is a number, the 394% waits for a maximum of Timeout seconds and unifies Status 395% with =timeout= if the process does not terminate within 396% Timeout. In this case PID is _not_ invalidated. On Unix 397% systems only timeout 0 and =infinite= are supported. A 398% 0-value can be used to poll the status of the process. 399% 400% * release(+Bool) 401% Do/do not release the process. We do not support this flag 402% and a domain_error is raised if release(false) is provided. 403% 404% @arg Status is one of exit(Code) or killed(Signal), where 405% Code and Signal are integers. If the `timeout` option 406% is used Status is unified with `timeout` after the wait 407% timed out. 408 409process_wait(PID, Status) :- 410 process_wait(PID, Status, []). 411 412%! process_kill(+PID) is det. 413%! process_kill(+PID, +Signal) is det. 414% 415% Send signal to process PID. Default is =term=. Signal is an 416% integer, Unix signal name (e.g. =SIGSTOP=) or the more Prolog 417% friendly variation one gets after removing =SIG= and downcase 418% the result: =stop=. On Windows systems, Signal is ignored and 419% the process is terminated using the TerminateProcess() API. On 420% Windows systems PID must be obtained from process_create/3, 421% while any PID is allowed on Unix systems. 422% 423% @compat SICStus does not accept the prolog friendly version. We 424% choose to do so for compatibility with on_signal/3. 425 426process_kill(PID) :- 427 process_kill(PID, term). 428 429 430%! process_group_kill(+PID) is det. 431%! process_group_kill(+PID, +Signal) is det. 432% 433% Send signal to the group containing process PID. Default is 434% =term=. See process_wait/1 for a description of signal 435% handling. In Windows, the same restriction on PID applies: it 436% must have been created from process_create/3, and the the group 437% is terminated via the TerminateJobObject API. 438 439process_group_kill(PID) :- 440 process_group_kill(PID, term). 441 442 443%! process_set_method(+Method) is det. 444% 445% Determine how the process is created on Unix systems. Method is one 446% of `spawn` (default), `fork` or `vfork`. If the method is `spawn` 447% but this cannot be used because it is either not supported by the OS 448% or the cwd(Dir) option is given `fork` is used. 449% 450% The problem is to be understood as follows. The official portable 451% and safe method to create a process is using the fork() system call. 452% This call however copies the process page tables and get seriously 453% slow as the (Prolog) process is multiple giga bytes large. 454% Alternatively, we may use vfork() which avoids copying the process 455% space. But, the safe usage as guaranteed by the POSIX standard of 456% vfork() is insufficient for our purposes. On practical systems your 457% mileage may vary. Modern posix systems also provide posix_spawn(), 458% which provides a safe and portable alternative for the fork() and 459% exec() sequence that may be implemented using fork() or may use a 460% fast but safe alternative. Unfortunately posix_spawn() doesn't 461% support the option to specify the working directory for the child 462% and we cannot use working_directory/2 as the working directory is 463% shared between threads. 464% 465% Summarizing, the default is safe and tries to be as fast as 466% possible. On some scenarios and on some OSes it is possible to do 467% better. It is generally a good idea to avoid using the cwd(Dir) 468% option of process_create/3 as without we can use posix_spawn(). 469 470 471 /******************************* 472 * MESSAGES * 473 *******************************/ 474 475:- multifile 476 prolog:error_message/3. 477 478prologerror_message(process_error(File, exit(Status))) --> 479 [ 'Process "~w": exit status: ~w'-[File, Status] ]. 480prologerror_message(process_error(File, killed(Signal))) --> 481 [ 'Process "~w": killed by signal ~w'-[File, Signal] ]. 482prologerror_message(existence_error(source_sink, path(Exe))) --> 483 [ 'Could not find executable file "~p" in '-[Exe] ], 484 path_var. 485 486path_var --> 487 ( { current_prolog_flag(windows, true) } 488 -> [ '%PATH%'-[] ] 489 ; [ '$PATH'-[] ] 490 )