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 ]). 66 67/** <module> Create processes and redirect I/O 68 69The module library(process) implements interaction with child processes 70and unifies older interfaces such as shell/[1,2], open(pipe(command), 71...) etc. This library is modelled after SICStus 4. 72 73The main interface is formed by process_create/3. If the process id is 74requested the process must be waited for using process_wait/2. Otherwise 75the process resources are reclaimed automatically. 76 77In addition to the predicates, this module defines a file search path 78(see user:file_search_path/2 and absolute_file_name/3) named =path= that 79locates files on the system's search path for executables. E.g. the 80following finds the executable for =ls=: 81 82 == 83 ?- absolute_file_name(path(ls), Path, [access(execute)]). 84 == 85 86*|Incompatibilities and current limitations|* 87 88 * Where SICStus distinguishes between an internal process id and 89 the OS process id, this implementation does not make this 90 distinction. This implies that is_process/1 is incomplete and 91 unreliable. 92 93 * SICStus only supports ISO 8859-1 (latin-1). This implementation 94 supports arbitrary OS multibyte interaction using the default 95 locale. 96 97 * It is unclear what the detached(true) option is supposed to do. Disable 98 signals in the child? Use setsid() to detach from the session? The 99 current implementation uses setsid() on Unix systems. 100 101 * An extra option env([Name=Value, ...]) is added to 102 process_create/3. 103 104@tbd Implement detached option in process_create/3 105@compat SICStus 4 106*/ 107 108 109%! process_create(+Exe, +Args:list, +Options) is det. 110% 111% Create a new process running the file Exe and using arguments 112% from the given list. Exe is a file specification as handed to 113% absolute_file_name/3. Typically one use the =path= file alias to 114% specify an executable file on the current PATH. Args is a list 115% of arguments that are handed to the new process. On Unix 116% systems, each element in the list becomes a seperate argument in 117% the new process. In Windows, the arguments are simply 118% concatenated to form the commandline. Each argument itself is 119% either a primitive or a list of primitives. A primitive is 120% either atomic or a term file(Spec). Using file(Spec), the system 121% inserts a filename using the OS filename conventions which is 122% properly quoted if needed. 123% 124% Options: 125% 126% * stdin(Spec) 127% * stdout(Spec) 128% * stderr(Spec) 129% Bind the standard streams of the new process. Spec is one of 130% the terms below. If pipe(Pipe) is used, the Prolog stream is 131% a stream in text-mode using the encoding of the default 132% locale. The encoding can be changed using set_stream/2. 133% The options =stdout= and =stderr= may use the same stream, 134% in which case both output streams are connected to the same 135% Prolog stream. 136% 137% * std 138% Just share with the Prolog I/O streams 139% * null 140% Bind to a _null_ stream. Reading from such a stream 141% returns end-of-file, writing produces no output 142% * pipe(-Stream) 143% Attach input and/or output to a Prolog stream. 144% 145% * cwd(+Directory) 146% Run the new process in Directory. Directory can be a 147% compound specification, which is converted using 148% absolute_file_name/3. 149% * env(+List) 150% Specify the environment for the new process. List is 151% a list of Name=Value terms. Note that the current 152% implementation does not pass any environment variables. 153% If unspecified, the environment is inherited from the 154% Prolog process. 155% * process(-PID) 156% Unify PID with the process id of the created process. 157% * detached(+Bool) 158% In Unix: If =true=, detach the process from the terminal 159% Currently mapped to setsid(); 160% Also creates a new process group for the child 161% In Windows: If =true=, detach the process from the current 162% job via the CREATE_BREAKAWAY_FROM_JOB flag. In Vista and beyond, 163% processes launched from the shell directly have the 'compatibility 164% assistant' attached to them automatically unless they have a UAC 165% manifest embedded in them. This means that you will get a 166% permission denied error if you try and assign the newly-created 167% PID to a job you create yourself. 168% * window(+Bool) 169% If =true=, create a window for the process (Windows only) 170% * priority(+Priority) 171% In Unix: specifies the process priority for the newly 172% created process. Priority must be an integer between -20 173% and 19. Positive values are nicer to others, and negative 174% values are less so. The default is zero. Users are free to 175% lower their own priority. Only the super-user may _raise_ it 176% to less-than zero. 177% 178% If the user specifies the process(-PID) option, he *must* call 179% process_wait/2 to reclaim the process. Without this option, the 180% system will wait for completion of the process after the last 181% pipe stream is closed. 182% 183% If the process is not waited for, it must succeed with status 0. 184% If not, an process_error is raised. 185% 186% *|Windows notes|* 187% 188% On Windows this call is an interface to the CreateProcess() API. 189% The commandline consists of the basename of Exe and the 190% arguments formed from Args. Arguments are separated by a single 191% space. If all characters satisfy iswalnum() it is unquoted. If 192% the argument contains a double-quote it is quoted using single 193% quotes. If both single and double quotes appear a domain_error 194% is raised, otherwise double-quote are used. 195% 196% The CreateProcess() API has many options. Currently only the 197% =CREATE_NO_WINDOW= options is supported through the 198% window(+Bool) option. If omitted, the default is to use this 199% option if the application has no console. Future versions are 200% likely to support more window specific options and replace 201% win_exec/2. 202% 203% *Examples* 204% 205% First, a very simple example that behaves the same as 206% =|shell('ls -l')|=, except for error handling: 207% 208% == 209% ?- process_create(path(ls), ['-l'], []). 210% == 211% 212% The following example uses grep to find all matching lines in a 213% file. 214% 215% == 216% grep(File, Pattern, Lines) :- 217% setup_call_cleanup( 218% process_create(path(grep), [ Pattern, file(File) ], 219% [ stdout(pipe(Out)) 220% ]), 221% read_lines(Out, Lines), 222% close(Out)). 223% 224% read_lines(Out, Lines) :- 225% read_line_to_codes(Out, Line1), 226% read_lines(Line1, Out, Lines). 227% 228% read_lines(end_of_file, _, []) :- !. 229% read_lines(Codes, Out, [Line|Lines]) :- 230% atom_codes(Line, Codes), 231% read_line_to_codes(Out, Line2), 232% read_lines(Line2, Out, Lines). 233% == 234% 235% @error process_error(Exe, Status) where Status is one of 236% exit(Code) or killed(Signal). Raised if the process 237% does not exit with status 0. 238 239process_create(Exe, Args, Options) :- 240 exe_options(ExeOptions), 241 absolute_file_name(Exe, PlProg, ExeOptions), 242 must_be(list, Args), 243 maplist(map_arg, Args, Av), 244 prolog_to_os_filename(PlProg, Prog), 245 Term =.. [Prog|Av], 246 expand_cwd_option(Options, Options1), 247 process_create(Term, Options1). 248 249exe_options(Options) :- 250 current_prolog_flag(windows, true), 251 !, 252 Options = [ extensions(['',exe,com]), access(read) ]. 253exe_options(Options) :- 254 Options = [ access(execute) ]. 255 256expand_cwd_option(Options0, Options) :- 257 select_option(cwd(Spec), Options0, Options1), 258 !, 259 ( compound(Spec) 260 -> absolute_file_name(Spec, PlDir, [file_type(directory), access(read)]), 261 prolog_to_os_filename(PlDir, Dir), 262 Options = [cwd(Dir)|Options1] 263 ; exists_directory(Spec) 264 -> Options = Options0 265 ; existence_error(directory, Spec) 266 ). 267expand_cwd_option(Options, Options). 268 269 270%! map_arg(+ArgIn, -Arg) is det. 271% 272% Map an individual argument. Primitives are either file(Spec) or 273% an atomic value (atom, string, number). If ArgIn is a non-empty 274% list, all elements are converted and the results are 275% concatenated. 276 277map_arg([], []) :- !. 278map_arg(List, Arg) :- 279 is_list(List), 280 !, 281 maplist(map_arg_prim, List, Prims), 282 atomic_list_concat(Prims, Arg). 283map_arg(Prim, Arg) :- 284 map_arg_prim(Prim, Arg). 285 286map_arg_prim(file(Spec), File) :- 287 !, 288 ( compound(Spec) 289 -> absolute_file_name(Spec, PlFile) 290 ; PlFile = Spec 291 ), 292 prolog_to_os_filename(PlFile, File). 293map_arg_prim(Arg, Arg). 294 295 296%! process_id(-PID) is det. 297% 298% True if PID is the process id of the running Prolog process. 299% 300% @deprecated Use current_prolog_flag(pid, PID) 301 302process_id(PID) :- 303 current_prolog_flag(pid, PID). 304 305%! process_id(+Process, -PID) is det. 306% 307% PID is the process id of Process. Given that they are united in 308% SWI-Prolog, this is a simple unify. 309 310process_id(PID, PID). 311 312%! is_process(+PID) is semidet. 313% 314% True if PID might be a process. Succeeds for any positive 315% integer. 316 317is_process(PID) :- 318 integer(PID), 319 PID > 0. 320 321%! process_release(+PID) 322% 323% Release process handle. In this implementation this is the same 324% as process_wait(PID, _). 325 326process_release(PID) :- 327 process_wait(PID, _). 328 329%! process_wait(+PID, -Status) is det. 330%! process_wait(+PID, -Status, +Options) is det. 331% 332% True if PID completed with Status. This call normally blocks 333% until the process is finished. Options: 334% 335% * timeout(+Timeout) 336% Default: =infinite=. If this option is a number, the 337% waits for a maximum of Timeout seconds and unifies Status 338% with =timeout= if the process does not terminate within 339% Timeout. In this case PID is _not_ invalidated. On Unix 340% systems only timeout 0 and =infinite= are supported. A 341% 0-value can be used to poll the status of the process. 342% 343% * release(+Bool) 344% Do/do not release the process. We do not support this flag 345% and a domain_error is raised if release(false) is provided. 346% 347% @param Status is one of exit(Code) or killed(Signal), where 348% Code and Signal are integers. 349 350process_wait(PID, Status) :- 351 process_wait(PID, Status, []). 352 353%! process_kill(+PID) is det. 354%! process_kill(+PID, +Signal) is det. 355% 356% Send signal to process PID. Default is =term=. Signal is an 357% integer, Unix signal name (e.g. =SIGSTOP=) or the more Prolog 358% friendly variation one gets after removing =SIG= and downcase 359% the result: =stop=. On Windows systems, Signal is ignored and 360% the process is terminated using the TerminateProcess() API. On 361% Windows systems PID must be obtained from process_create/3, 362% while any PID is allowed on Unix systems. 363% 364% @compat SICStus does not accept the prolog friendly version. We 365% choose to do so for compatibility with on_signal/3. 366 367process_kill(PID) :- 368 process_kill(PID, term). 369 370 371%! process_group_kill(+PID) is det. 372%! process_group_kill(+PID, +Signal) is det. 373% 374% Send signal to the group containing process PID. Default is 375% =term=. See process_wait/1 for a description of signal 376% handling. In Windows, the same restriction on PID applies: it 377% must have been created from process_create/3, and the the group 378% is terminated via the TerminateJobObject API. 379 380process_group_kill(PID) :- 381 process_group_kill(PID, term). 382 383 384 /******************************* 385 * MESSAGES * 386 *******************************/ 387 388:- multifile 389 prolog:error_message/3. 390 391prologerror_message(process_error(File, exit(Status))) --> 392 [ 'Process "~w": exit status: ~w'-[File, Status] ]. 393prologerror_message(process_error(File, killed(Signal))) --> 394 [ 'Process "~w": killed by signal ~w'-[File, Signal] ].