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% is waited for (i.e., Options does not include 238% process(-PID)), and does not exit with status 0. 239 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). 269 270 271%! map_arg(+ArgIn, -Arg) is det. 272% 273% Map an individual argument. Primitives are either file(Spec) or 274% an atomic value (atom, string, number). If ArgIn is a non-empty 275% list, all elements are converted and the results are 276% concatenated. 277 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). 295 296 297%! process_id(-PID) is det. 298% 299% True if PID is the process id of the running Prolog process. 300% 301% @deprecated Use current_prolog_flag(pid, PID) 302 303process_id(PID) :- 304 current_prolog_flag(pid, PID). 305 306%! process_id(+Process, -PID) is det. 307% 308% PID is the process id of Process. Given that they are united in 309% SWI-Prolog, this is a simple unify. 310 311process_id(PID, PID). 312 313%! is_process(+PID) is semidet. 314% 315% True if PID might be a process. Succeeds for any positive 316% integer. 317 318is_process(PID) :- 319 integer(PID), 320 PID > 0. 321 322%! process_release(+PID) 323% 324% Release process handle. In this implementation this is the same 325% as process_wait(PID, _). 326 327process_release(PID) :- 328 process_wait(PID, _). 329 330%! process_wait(+PID, -Status) is det. 331%! process_wait(+PID, -Status, +Options) is det. 332% 333% True if PID completed with Status. This call normally blocks 334% until the process is finished. Options: 335% 336% * timeout(+Timeout) 337% Default: =infinite=. If this option is a number, the 338% waits for a maximum of Timeout seconds and unifies Status 339% with =timeout= if the process does not terminate within 340% Timeout. In this case PID is _not_ invalidated. On Unix 341% systems only timeout 0 and =infinite= are supported. A 342% 0-value can be used to poll the status of the process. 343% 344% * release(+Bool) 345% Do/do not release the process. We do not support this flag 346% and a domain_error is raised if release(false) is provided. 347% 348% @param Status is one of exit(Code) or killed(Signal), where 349% Code and Signal are integers. 350 351process_wait(PID, Status) :- 352 process_wait(PID, Status, []). 353 354%! process_kill(+PID) is det. 355%! process_kill(+PID, +Signal) is det. 356% 357% Send signal to process PID. Default is =term=. Signal is an 358% integer, Unix signal name (e.g. =SIGSTOP=) or the more Prolog 359% friendly variation one gets after removing =SIG= and downcase 360% the result: =stop=. On Windows systems, Signal is ignored and 361% the process is terminated using the TerminateProcess() API. On 362% Windows systems PID must be obtained from process_create/3, 363% while any PID is allowed on Unix systems. 364% 365% @compat SICStus does not accept the prolog friendly version. We 366% choose to do so for compatibility with on_signal/3. 367 368process_kill(PID) :- 369 process_kill(PID, term). 370 371 372%! process_group_kill(+PID) is det. 373%! process_group_kill(+PID, +Signal) is det. 374% 375% Send signal to the group containing process PID. Default is 376% =term=. See process_wait/1 for a description of signal 377% handling. In Windows, the same restriction on PID applies: it 378% must have been created from process_create/3, and the the group 379% is terminated via the TerminateJobObject API. 380 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 392prologerror_message(process_error(File, exit(Status))) --> 393 [ 'Process "~w": exit status: ~w'-[File, Status] ]. 394prologerror_message(process_error(File, killed(Signal))) --> 395 [ 'Process "~w": killed by signal ~w'-[File, Signal] ]