Executing External Programs: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Overview: Comparison
2	2
3	3		Here are different ways available in RTL, FCL and LCL libraries on how to execute an external command/process/program.
4	4
5	5		\| Method \| Library \| Platforms \| Single Line \| Features \|
6	6		\|----\|----\|----\|----\|----\|
7	7		\| [[Executing External Programs\|ExecuteProcess]] \| RTL \| Cross-Platform \| Yes \| Very limited, synchronous. \|
8	8		\| [[Executing External Programs\|ShellExecute]] \| WinAPI \| MS Windows only \| Yes \| Many. Can start programs with elevation/admin permissions. \|
9	9		\| [[Executing External Programs\|fpsystem, fpexecve]] \| Unix \| Unix only \| \| \|
10	10		\| [[Executing External Programs\|TProcess]] \| FCL \| Cross-Platform \| No \| Full. \|
11	11		\| [[Executing External Programs\|RunCommand]] \| FCL \| Cross-Platform Requires FPC 2.6.2+ \| Yes \| Covers common TProcess usage. \|
12	12		\| [[Executing External Programs\|OpenDocument]] \| LCL \| Cross-Platform \| Yes \| Only open document. The document would open with the application associated with that type of the document. \|
13	13		\| [[Executing External Programs\|WinExec]] \| WinAPI \| MS Windows only \| Yes Legacy option found in old Delphi code. Replace with one of the above. \| \|
14	14
15	15		## (Process.)RunCommand
16	16
17	17		- [RunCommand](http://www.freepascal.org/docs-html/fcl/process/runcommand.html) reference
18	18		- [RunCommandInDir](http://www.freepascal.org/docs-html/fcl/process/runcommandindir.html) reference
19	19
20	20		In FPC 2.6.2, some helper functions for TProcess were added to unit process based on wrappers used in the [[Projects using Lazarus\|fpcup]] project. These functions are meant for basic and intermediate use and can capture output to a single string and fully support the large output case.
21	21
22	22		A simple example is:
23	23
24	24		``` pascal
25	25		program project1;
26	26
27	27		{$mode objfpc}{$H+}
28	28
29	29		uses
30	30		Process;
31	31
32	32		var
33	33		s : ansistring;
34	34
35	35		begin
36	36
37	37		if RunCommand('/bin/bash',['-c','echo $PATH'],s) then
38	38		writeln(s);
39	39
40	40		end.
41	41		```
42	42
43	43		But note that not all shell "built-in" commands (eg alias) work because aliases by default are not expanded in non-interactive shells and .bashrc is not read by non-interactive shells unless you set the BASH_ENV environment variable. So, this does not produce any output:
44	44
45	45		``` pascal
46	46		program project2;
47	47
48	48		{$mode objfpc}{$H+}
49	49
50	50		uses
51	51		Process;
52	52
53	53		var
54	54		s : ansistring;
55	55
56	56		begin
57	57
58	58		if RunCommand('/bin/bash',['-c','alias'],s) then
59	59		writeln(s);
60	60
61	61		end.
62	62		```
63	63
64	64		An overloaded variant of RunCommand returns the exitcode of the program. The RunCommandInDir runs the command in a different directory (sets p.CurrentDirectory):
65	65
66	66		``` pascal
67	67		function RunCommandIndir(const curdir:string;const exename:string;const commands:array of string;var outputstring:string; var exitstatus:integer): integer;
68	68		function RunCommandIndir(const curdir:string;const exename:string;const commands:array of string;var outputstring:string): boolean;
69	69		function RunCommand(const exename:string;const commands:array of string;var outputstring:string): boolean;
70	70		```
71	71
72	72		In FPC 3.2.0+ the Runcommand got additional variants that allow to override TProcessOptions and WindowOptions.
73	73
74	74		### RunCommand extensions
75	75
76	76		In FPC 3.2.0+ the RunCommand implementation was generalized and integrated back into TProcess to allow for quicker construction of own variants. As an example a RunCommand variant with a timeout:
77	77
78	78		``` pascal
79	79
80	80		program TestTProcessTimeout;
81	81
82	82		uses classes, sysutils, process, dateutils;
83	83
84	84		type
85	85		{ TProcessTimeout }
86	86		TProcessTimeout = class(TProcess)
87	87		protected
88	88		timeoutperiod: TTime;
89	89		timedout : boolean;
90	90		started : TDateTime;
91	91		procedure LocalnIdleSleep(Sender,Context : TObject;status:TRunCommandEventCode;const message:string);
92	92		public
93	93		class function RunCommandwithTimeout(const exename:TProcessString;const commands:array of TProcessString;const dir:string;out outputstring:string;out errorstring:string;out exitstate:integer; ProcessOptions : TProcessOptions = [];SWOptions:TShowWindowOptions=swoNone;timeout:integer=15):boolean;static;
94	94		end;
95	95
96	96		procedure TProcessTimeout.LocalnIdleSleep(Sender,Context : TObject;status:TRunCommandEventCode;const message:string);
97	97		begin
98	98		if status=RunCommandIdle then
99	99		begin
100	100		writeln(Executable+'('+ Parameters.CommaText+')' +' time: '+TimeToStr(now-started));
101	101		if (now-started)>timeoutperiod then
102	102		begin
103	103		writeln('process timed out ');
104	104		timedout:=true;
105	105		Terminate(255);
106	106		exit;
107	107		end;
108	108		sleep(RunCommandSleepTime);
109	109		end;
110	110		end;
111	111
112	112		class function TProcessTimeout.RunCommandwithTimeout(
113	113		const exename : TProcessString;
114	114		const commands : array of TProcessString;
115	115		const dir : string;
116	116		out outputstring : string;
117	117		out errorstring : string;
118	118		out exitstate : integer;
119	119		ProcessOptions : TProcessOptions = [];
120	120		SWOptions : TShowWindowOptions=swoNone;
121	121		timeout : integer=15
122	122		):boolean;
123	123		Var
124	124		p : TProcessTimeout;
125	125		i : integer;
126	126		begin
127	127		p:=TProcessTimeout.create(nil);
128	128		p.OnRunCommandEvent:=@p.LocalnIdleSleep;
129	129		p.CurrentDirectory:=dir;
130	130
131	131		//timeout in Minutes, Check every Seconds
132	132		p.timeoutperiod:=timeout/MinsPerDay;
133	133
134	134		(*
135	135		//if you want to do the Timeout in Seconds
136	136		p.timeoutperiod:=timeout/SecsPerDay;
137	137		*)
138	138
139	139		// check every Second if finished
140	140		p.runcommandsleeptime := 1000;
141	141
142	142		if ProcessOptions<>[] then
143	143		P.Options:=ProcessOptions - [poRunSuspended,poWaitOnExit];
144	144		p.options:=p.options+[poRunIdle]; // needed to run the RUNIDLE event. See User Changes 3.2.0
145	145
146	146		P.ShowWindow:=SwOptions;
147	147		p.Executable:=exename;
148	148		if high(commands)>=0 then
149	149		for i:=low(commands) to high(commands) do
150	150		p.Parameters.add(commands[i]);
151	151		p.timedout:=false;
152	152		p.started:=now;
153	153		try
154	154		// the core loop of runcommand() variants, originally based on the "large output" scenario in the wiki, but continously expanded over 5 years.
155	155		RunCommandwithTimeout:=p.RunCommandLoop(outputstring,errorstring,exitstate)=0;
156	156		if p.timedout then
157	157		RunCommandwithTimeout:=false;
158	158		finally
159	159		p.free;
160	160		end;
161	161		if exitstate<>0 then RunCommandwithTimeout:=false;
162	162		end;
163	163
164	164		// example use:
165	165
166	166		var
167	167		output,errors : string;
168	168		exitcode :integer;
169	169		begin
170	170		//Windows and Unix have other programs that can be used
171	171		{$if defined(WINDOWS)}
172	172		if TProcessTimeout.RunCommandwithTimeout('cmd',['/c','dir','C:.exe','/s'],'c:\',output,errors,exitcode,[],swoNone,1) then // dir c:.exe /s
173	173		{$else$}
174	174		if TProcessTimeout.RunCommandwithTimeout('find',['/','-name','".sh"'],'/',output,errors,exitcode,[],swoNone,1) then // find / -name ".sh"
175	175		{$endif}
176	176		begin
177	177		writeln('program finished');
178	178		writeln('--------------------output-------------------');
179	179		writeln(output);
180	180		writeln('--------------------errors-------------------');
181	181		writeln(errors);
182	182		if not(exitcode=0) then
183	183		begin
184	184		writeln('-program finished with errors (exitcode: '+exitcode.tostring+')-');
185	185		end;
186	186		readln();
187	187		end
188	188		else
189	189		begin
190	190		writeln('program not finished');
191	191		writeln('--------------------output-------------------');
192	192		writeln(output);
193	193		writeln('--------------------errors-------------------');
194	194		writeln(errors);
195	195		writeln('-------------------EXITCODE------------------');
196	196		writeln(exitcode);
197	197		readln();
198	198		end;
199	199		end.
200	200		```
201	201
202	202		## SysUtils.ExecuteProcess
203	203
204	204		(Cross-platform)\
205	205		Despite a number of limitations, the simplest way to launch a program (modal, no pipes or any form of control) is to simply use :
206	206
207	207		``` pascal
208	208		SysUtils.ExecuteProcess(UTF8ToSys('/full/path/to/binary'), '', []);
209	209		```
210	210
211	211		The calling process runs synchronously: it 'hangs' until the external program has finished - but this may be useful if you require the user to do something before continuing in your application. For a more versatile approach, see the section about the preferred cross-platform RunCommand or other TProcess functionality, or if you only wish to target Windows you may use ShellExecute.
212	212
213	213		- [ExecuteProcess reference](http://www.freepascal.org/docs-html/rtl/sysutils/executeprocess.html)
214	214
215	215		## MS Windows: CreateProcess, ShellExecute and WinExec
216	216
217	217		> Note: While FPC/Lazarus has support for CreateProcess, ShellExecute and/or WinExec, this support is only in Win32/64. If your program is cross-platform, consider using RunCommand or TProcess.
218	218
219	219		> Note: WinExec is a 16-bit call that has been deprecated for years in the Windows API. In recent versions of FPC it generates a warning.
220	220
221	221		ShellExecute is a standard MS Windows function (ShellApi.h) with good \[<http://msdn.microsoft.com/en-us/library/windows/desktop/bb762153(v=vs.85>).aspx documentation on MSDN\] (note their remarks about initialising COM if you find the function unreliable).
222	222
223	223		``` pascal
224	224		uses ..., ShellApi;
225	225
226	226		// Simple one-liner (ignoring error returns) :
227	227		if ShellExecute(0,nil, PChar('"C:\my dir\prog.exe"'),PChar('"C:\somepath\some_doc.ext"'),nil,1) =0 then;
228	228
229	229		// Execute a Batch File :
230	230		if ShellExecute(0,nil, PChar('cmd'),PChar('/c mybatch.bat'),nil,1) =0 then;
231	231
232	232		// Open a command window in a given folder :
233	233		if ShellExecute(0,nil, PChar('cmd'),PChar('/k cd \path'),nil,1) =0 then;
234	234
235	235		// Open a webpage URL in the default browser using 'start' command (via a brief hidden cmd window) :
236	236		if ShellExecute(0,nil, PChar('cmd'),PChar('/c start www.lazarus.freepascal.org/'),nil,0) =0 then;
237	237
238	238		// or a useful procedure:
239	239		procedure RunShellExecute(const prog,params:string);
240	240		begin
241	241		// ( Handle, nil/'open'/'edit'/'find'/'explore'/'print', // 'open' isn't always needed
242	242		// path+prog, params, working folder,
243	243		// 0=hide / 1=SW_SHOWNORMAL / 3=max / 7=min) // for SW_ constants : uses ... Windows ...
244	244		if ShellExecute(0,'open',PChar(prog),PChar(params),PChar(extractfilepath(prog)),1) >32 then; //success
245	245		// return values 0..32 are errors
246	246		end;
247	247		```
248	248
249	249		There is also ShellExecuteExW as a WideChar version, and ShellExecuteExA is AnsiChar.
250	250
251	251		The fMask option can also use SEE_MASK_DOENVSUBST or SEE_MASK_FLAG_NO_UI or SEE_MASK_NOCLOSEPROCESS, etc.
252	252
253	253		If in Delphi you used ShellExecute for documents like Word documents or URLs, have a look at the open* (OpenURL etc) functions in lclintf (see the Alternatives section lower down this page).
254	254
255	255		### Using ShellExecuteEx for elevation/administrator permissions
256	256
257	257		If you need to execute external program with administrator/elevated privileges, you can use the runas method with the alternative ShellExecuteEx function:
258	258
259	259		``` pascal
260	260		uses ShellApi, ...;
261	261
262	262		function RunAsAdmin(const Handle: Hwnd; const Path, Params: string): Boolean;
263	263		var
264	264		sei: TShellExecuteInfoA;
265	265		begin
266	266		FillChar(sei, SizeOf(sei), 0);
267	267		sei.cbSize := SizeOf(sei);
268	268		sei.Wnd := Handle;
269	269		sei.fMask := SEE_MASK_FLAG_DDEWAIT or SEE_MASK_FLAG_NO_UI;
270	270		sei.lpVerb := 'runas';
271	271		sei.lpFile := PAnsiChar(Path);
272	272		sei.lpParameters := PAnsiChar(Params);
273	273		sei.nShow := SW_SHOWNORMAL;
274	274		Result := ShellExecuteExA(@sei);
275	275		end;
276	276
277	277		procedure TFormMain.RunAddOrRemoveApplication;
278	278		begin
279	279		// Example that uses elevated rundll to open the Control Panel to Programs and features
280	280		RunAsAdmin(FormMain.Handle, 'rundll32.exe shell32.dll,Control_RunDLL appwiz.cpl', '');
281	281		end;
282	282		```
283	283
284	284		## Unix fpsystem, fpexecve and shell
285	285
286	286		These functions are platform dependent.
287	287
288	288		- [fpsystem reference](http://www.freepascal.org/docs-html/rtl/unix/fpsystem.html)
289	289		- [fpexecve reference](http://www.freepascal.org/docs-html/rtl/baseunix/fpexecve.html)
290	290
291	291		Linux.Shell/Unix.Shell was an 1.0.x equivalent to fpsystem with less narrowly defined error handling, and after a decade of deprecation it was finally removed. In nearly all cases it can be replaced by fpsystem that features more POSIX like errorhandling.
292	292
293	293		## TProcess
294	294
295	295		You can use TProcess to launch external programs. Some of the benefits of using TProcess are that it is:
296	296
297	297		- Platform Independent
298	298		- Capable of reading from stdout and writing to stdin.
299	299		- Possible to wait for a command to finish or let it run while your program moves on.
300	300
301	301		Important notes:
302	302
303	303		- TProcess is not a terminal/shell! You cannot directly execute scripts or redirect output using operators like "\\|", "\>", "\<", "&" etc. It is possible to obtain the same results with TProcess using pascal, some examples are below..
304	304		- Presumably on Linux/Unix: you must specify the full path to the executable. For example '/bin/cp' instead of 'cp'. If the program is in the standard PATH then you can use the function [[doc:lcl/fileutil/finddefaultexecutablepath.html\|FindDefaultExecutablePath]] from the [[doc:lcl/fileutil/index.html\|FileUtil]] unit of the LCL.
305	305		- On Windows, if the command is in the path, you don't need to specify the full path.
306	306		- [[doc:fcl/process/tprocess.html\|TProcess reference]]
307	307
308	308		### The Simplest Example
309	309
310	310		A lot of typical cases have been prepared in the [[Executing External Programs\|Runcommand]] functions. Before you start copy and paste the examples below, check them out first.
311	311
312	312		### A Simple Example
313	313
314	314		This example (that shouldn't be used in production, see Large Output or, better, [[Executing External Programs\|Runcommand]]) just shows you how to run an external program, nothing more:
315	315
316	316		``` pascal
317	317		// This is a demo program that shows
318	318		// how to launch an external program.
319	319		program launchprogram;
320	320
321	321		// Here we include files that have useful functions
322	322		// and procedures we will need.
323	323		uses
324	324		Classes, SysUtils, Process;
325	325
326	326		// This defines the var "AProcess" as a variable
327	327		// of the type "TProcess"
328	328		var
329	329		AProcess: TProcess;
330	330
331	331		// This is where our program starts to run
332	332		begin
333	333		// Now we will create the TProcess object, and
334	334		// assign it to the var AProcess.
335	335		AProcess := TProcess.Create(nil);
336	336
337	337		// Tell the new AProcess what the command to execute is.
338	338		// Let's use the Free Pascal compiler (i386 version that is)
339	339		AProcess.Executable:= 'ppc386';
340	340
341	341		// Pass -h together with ppc386 so actually 'ppc386 -h' is executed:
342	342		AProcess.Parameters.Add('-h');
343	343
344	344		// We will define an option for when the program
345	345		// is run. This option will make sure that our program
346	346		// does not continue until the program we will launch
347	347		// has stopped running. vvvvvvvvvvvvvv
348	348		AProcess.Options := AProcess.Options + [poWaitOnExit];
349	349
350	350		// Now let AProcess run the program
351	351		AProcess.Execute;
352	352
353	353		// This is not reached until ppc386 stops running.
354	354		AProcess.Free;
355	355		end.
356	356		```
357	357
358	358		That's it! You have just learned to run an external program from inside your own program.
359	359
360	360		### An improved example (but not correct yet)
361	361
362	362		That's nice, but how do I read the Output of a program that I have run?
363	363
364	364		Well, let's expand our example a little and do just that: This example is kept simple so you can learn from it. Please don't use this example in production code, but use the code in #Reading large output.
365	365
366	366		``` pascal
367	367		// This is a
368	368		// FLAWED
369	369		// demo program that shows
370	370		// how to launch an external program
371	371		// and read from its output.
372	372		program launchprogram;
373	373
374	374		// Here we include files that have useful functions
375	375		// and procedures we will need.
376	376		uses
377	377		Classes, SysUtils, Process;
378	378
379	379		// This is defining the var "AProcess" as a variable
380	380		// of the type "TProcess"
381	381		// Also now we are adding a TStringList to store the
382	382		// data read from the programs output.
383	383		var
384	384		AProcess: TProcess;
385	385		AStringList: TStringList;
386	386
387	387		// This is where our program starts to run
388	388		begin
389	389		// Now we will create the TProcess object, and
390	390		// assign it to the var AProcess.
391	391		AProcess := TProcess.Create(nil);
392	392
393	393		// Tell the new AProcess what the command to execute is.
394	394		AProcess.Executable := '/usr/bin/ppc386';
395	395		AProcess.Parameters.Add('-h');
396	396
397	397		// We will define an option for when the program
398	398		// is run. This option will make sure that our program
399	399		// does not continue until the program we will launch
400	400		// has stopped running. Also now we will tell it that
401	401		// we want to read the output of the file.
402	402		AProcess.Options := AProcess.Options + [poWaitOnExit, poUsePipes];
403	403
404	404		// Now that AProcess knows what the commandline is it can be run.
405	405		AProcess.Execute;
406	406
407	407		// After AProcess has finished, the rest of the program will be executed.
408	408
409	409		// Now read the output of the program we just ran into a TStringList.
410	410		AStringList := TStringList.Create;
411	411		AStringList.LoadFromStream(AProcess.Output);
412	412
413	413		// Save the output to a file and clean up the TStringList.
414	414		AStringList.SaveToFile('output.txt');
415	415		AStringList.Free;
416	416
417	417		// Now that the output from the process is processed, it can be freed.
418	418		AProcess.Free;
419	419		end.
420	420		```
421	421
422	422		### Reading large output
423	423
424	424		In the previous example we waited until the program exited. Then we read what the program has written to its output.
425	425
426	426		Suppose the program writes a lot of data to the output. Then the output pipe becomes full and the called progam waits until the pipe has been read from.
427	427
428	428		But the calling program doesn't read from it until the called program has ended. A deadlock occurs.
429	429
430	430		The following example therefore doesn't use poWaitOnExit, but reads from the output while the program is still running. The output is stored in a memory stream, that can be used later to read the output into a TStringList.
431	431
432	432		If you want to read output from an external process, and can't use RunCommand, this is the code you should as a base for production use. If you are using FPC 3.2.0+ a parametrisable form of this loop is available as the method RunCommandLoop in TProcess. An event OnRunCommandEvent can be hooked to further modify the behaviour.
433	433
434	434		``` pascal
435	435		program LargeOutputDemo;
436	436
437	437		{$mode objfpc}{$H+}
438	438
439	439		uses
440	440		Classes, SysUtils, Process; // Process is the unit that holds TProcess
441	441
442	442		const
443	443		BUF_SIZE = 2048; // Buffer size for reading the output in chunks
444	444
445	445		var
446	446		AProcess : TProcess;
447	447		OutputStream : TStream;
448	448		BytesRead : longint;
449	449		Buffer : array[1..BUF_SIZE] of byte;
450	450
451	451		begin
452	452		// Set up the process; as an example a recursive directory search is used
453	453		// because that will usually result in a lot of data.
454	454		AProcess := TProcess.Create(nil);
455	455
456	456		// The commands for Windows and *nix are different hence the $IFDEFs
457	457		{$IFDEF Windows}
458	458		// In Windows the dir command cannot be used directly because it's a build-in
459	459		// shell command. Therefore cmd.exe and the extra parameters are needed.
460	460		AProcess.Executable := 'c:\windows\system32\cmd.exe';
461	461		AProcess.Parameters.Add('/c');
462	462		AProcess.Parameters.Add('dir /s c:\windows');
463	463		{$ENDIF Windows}
464	464
465	465		{$IFDEF Unix}
466	466		AProcess.Executable := '/bin/ls';
467	467
468	468		{$IFDEF Darwin}
469	469		AProcess.Parameters.Add('-recursive');
470	470		AProcess.Parameters.Add('-all');
471	471		{$ENDIF Darwin}
472	472
473	473		{$IFDEF Linux}
474	474		AProcess.Parameters.Add('--recursive');
475	475		AProcess.Parameters.Add('--all');
476	476		{$ENDIF Linux}
477	477
478	478		{$IFDEF FreeBSD}
479	479		AProcess.Parameters.Add('-R');
480	480		AProcess.Parameters.Add('-a');
481	481		{$ENDIF FreeBSD}
482	482
483	483		AProcess.Parameters.Add('-l');
484	484		{$ENDIF Unix}
485	485
486	486		// Process option poUsePipes has to be used so the output can be captured.
487	487		// Process option poWaitOnExit can not be used because that would block
488	488		// this program, preventing it from reading the output data of the process.
489	489		AProcess.Options := [poUsePipes];
490	490
491	491		// Start the process (run the dir/ls command)
492	492		AProcess.Execute;
493	493
494	494		// Create a stream object to store the generated output in. This could
495	495		// also be a file stream to directly save the output to disk.
496	496		OutputStream := TMemoryStream.Create;
497	497
498	498		// All generated output from AProcess is read in a loop until no more data is available
499	499		repeat
500	500		// Get the new data from the process to a maximum of the buffer size that was allocated.
501	501		// Note that all read(...) calls will block except for the last one, which returns 0 (zero).
502	502		BytesRead := AProcess.Output.Read(Buffer, BUF_SIZE);
503	503
504	504		// Add the bytes that were read to the stream for later usage
505	505		OutputStream.Write(Buffer, BytesRead)
506	506
507	507		until BytesRead = 0; // Stop if no more data is available
508	508
509	509		// The process has finished so it can be cleaned up
510	510		AProcess.Free;
511	511
512	512		// Now that all data has been read it can be used; for example to save it to a file on disk
513	513		with TFileStream.Create('output.txt', fmCreate) do
514	514		begin
515	515		OutputStream.Position := 0; // Required to make sure all data is copied from the start
516	516		CopyFrom(OutputStream, OutputStream.Size);
517	517		Free
518	518		end;
519	519
520	520		// Or the data can be shown on screen
521	521		with TStringList.Create do
522	522		begin
523	523		OutputStream.Position := 0; // Required to make sure all data is copied from the start
524	524		LoadFromStream(OutputStream);
525	525		writeln(Text);
526	526		writeln('--- Number of lines = ', Count, '----');
527	527		Free
528	528		end;
529	529
530	530		// Clean up
531	531		OutputStream.Free;
532	532		end.
533	533		```
534	534
535	535		Note that the above could also be accomplished by using RunCommand:
536	536
537	537		``` pascal
538	538		var s: string;
539	539		...
540	540		RunCommand('c:\windows\system32\cmd.exe', ['/c', 'dir /s c:\windows'], s);
541	541		```
542	542
543	543		### Using input and output of a TProcess
544	544
545	545		See processdemo example in the [Lazarus-CCR SVN](https://sourceforge.net/p/lazarus-ccr/svn/HEAD/tree/examples/process).
546	546
547	547		### Hints on the use of TProcess
548	548
549	549		When creating a cross-platform program, the OS-specific executable name can be set using directives "{\$IFDEF}" and "{\$ENDIF}".
550	550
551	551		Example:
552	552
553	553		``` pascal
554	554		{...}
555	555		AProcess := TProcess.Create(nil)
556	556
557	557		{$IFDEF WIN32}
558	558		AProcess.Executable := 'calc.exe';
559	559		{$ENDIF}
560	560
561	561		{$IFDEF LINUX}
562	562		AProcess.Executable := FindDefaultExecutablePath('kcalc');
563	563		{$ENDIF}
564	564
565	565		AProcess.Execute;
566	566		{...}
567	567		```
568	568
569	569		### macOS show application bundle in foreground
570	570
571	571		You can start an application bundle via TProcess by starting the executable within the bundle. For example:
572	572
573	573		``` pascal
574	574		AProcess.Executable:='/Applications/iCal.app/Contents/MacOS/iCal';
575	575		```
576	576
577	577		This will start the Calendar, but the window will be behind the current application. To get the application in the foreground you can use the open utility with the -n parameter:
578	578
579	579		``` pascal
580	580		AProcess.Executable:='/usr/bin/open';
581	581		AProcess.Parameters.Add('-n');
582	582		AProcess.Parameters.Add('-a'); // optional: specifies the application to use; only searches the Application directories
583	583		AProcess.Parameters.Add('-W'); // optional: open waits until the applications it opens (or were already open) have exited
584	584		AProcess.Parameters.Add('Pages.app'); // including .app is optional
585	585		```
586	586
587	587		If your application needs parameters, you can pass open the --args parameter, after which all parameters are passed to the application:
588	588
589	589		``` pascal
590	590		AProcess.Parameters.Add('--args');
591	591		AProcess.Parameters.Add('argument1');
592	592		AProcess.Parameters.Add('argument2');
593	593		```
594	594
595	595		See also: [[macOS Open Sesame\|macOS open command]].
596	596
597	597		### Run detached program
598	598
599	599		Normally a program started by your application is a child process and is killed, when your application is killed. When you want to run a standalone program that keeps running, you can use the following:
600	600
601	601		``` pascal
602	602		var
603	603		Process: TProcess;
604	604		I: Integer;
605	605		begin
606	606		Process := TProcess.Create(nil);
607	607		try
608	608		Process.InheritHandles := False;
609	609		Process.Options := [];
610	610		Process.ShowWindow := swoShow;
611	611
612	612		// Copy default environment variables including DISPLAY variable for GUI application to work
613	613		for I := 1 to GetEnvironmentVariableCount do
614	614		Process.Environment.Add(GetEnvironmentString(I));
615	615
616	616		Process.Executable := '/usr/bin/gedit';
617	617		Process.Execute;
618	618		finally
619	619		Process.Free;
620	620		end;
621	621		end;
622	622		```
623	623
624	624		### Example of "talking" with aspell process
625	625
626	626		Inside [pasdoc](https://github.com/pasdoc/pasdoc/wiki) source code you can find two units that perform spell-checking by "talking" with running aspell process through pipes:
627	627
628	628		- [PasDoc_ProcessLineTalk.pas unit](https://github.com/pasdoc/pasdoc/blob/master/source/component/PasDoc_ProcessLineTalk.pas) implements TProcessLineTalk class, descendant of TProcess, that can be easily used to talk with any process on a line-by-line basis.
629	629
630	630		- [PasDoc_Aspell.pas units](https://github.com/pasdoc/pasdoc/blob/master/source/component/PasDoc_Aspell.pas) implements TAspellProcess class, that performs spell-checking by using underlying TProcessLineTalk instance to execute aspell and communicate with running aspell process.
631	631
632	632		Both units are rather independent from the rest of pasdoc sources, so they may serve as real-world examples of using TProcess to run and communicate through pipes with other program.
633	633
634	634		### Replacing shell operators like "\\| \< \>"
635	635
636	636		Sometimes you want to run a more complicated command that pipes its data to another command or to a file. Something like
637	637
638	638		``` pascal
639	639		ShellExecute('firstcommand.exe \| secondcommand.exe');
640	640		```
641	641
642	642		or
643	643
644	644		``` pascal
645	645		ShellExecute('dir > output.txt');
646	646		```
647	647
648	648		Executing this with TProcess will not work. i.e:
649	649
650	650		``` pascal
651	651		// this won't work
652	652		Process.CommandLine := 'firstcommand.exe \| secondcommand.exe';
653	653		Process.Execute;
654	654		```
655	655
656	656		#### Why using special operators to redirect output doesn't work
657	657
658	658		TProcess is just that, it's not a shell environment, only a process. It's not two processes, it's only one. It is possible to redirect output however just the way you wanted. See the [[Executing External Programs\|next section]].
659	659
660	660		### How to redirect output with TProcess
661	661
662	662		You can redirect the output of a command to another command by using a TProcess instance for each command.
663	663
664	664		Here's an example that explains how to redirect the output of one process to another. To redirect the output of a process to a file/stream see the example [[Executing External Programs\|Reading Large Output]]
665	665
666	666		Not only can you redirect the "normal" output (also known as stdout), but you can also redirect the error output (stderr), if you specify the poStderrToOutPut option, as seen in the options for the second process.
667	667
668	668		``` pascal
669	669		program Project1;
670	670
671	671		uses
672	672		Classes, sysutils, process;
673	673
674	674		var
675	675		FirstProcess,
676	676		SecondProcess: TProcess;
677	677		Buffer: array[0..127] of char;
678	678		ReadCount: Integer;
679	679		ReadSize: Integer;
680	680		begin
681	681		FirstProcess := TProcess.Create(nil);
682	682		SecondProcess := TProcess.Create(nil);
683	683
684	684		FirstProcess.Options := [poUsePipes];
685	685		FirstProcess.Executable := 'pwd';
686	686
687	687		SecondProcess.Options := [poUsePipes,poStderrToOutPut];
688	688		SecondProcess.Executable := 'grep';
689	689		SecondProcess.Parameters.Add(DirectorySeparator+ ' -');
690	690		// this would be the same as "pwd \| grep / -"
691	691
692	692		FirstProcess.Execute;
693	693		SecondProcess.Execute;
694	694
695	695		while FirstProcess.Running or (FirstProcess.Output.NumBytesAvailable > 0) do
696	696		begin
697	697		if FirstProcess.Output.NumBytesAvailable > 0 then
698	698		begin
699	699		// make sure that we don't read more data than we have allocated
700	700		// in the buffer
701	701		ReadSize := FirstProcess.Output.NumBytesAvailable;
702	702		if ReadSize > SizeOf(Buffer) then
703	703		ReadSize := SizeOf(Buffer);
704	704		// now read the output into the buffer
705	705		ReadCount := FirstProcess.Output.Read(Buffer[0], ReadSize);
706	706		// and write the buffer to the second process
707	707		SecondProcess.Input.Write(Buffer[0], ReadCount);
708	708
709	709		// if SecondProcess writes much data to it's Output then
710	710		// we should read that data here to prevent a deadlock
711	711		// see the previous example "Reading Large Output"
712	712		end;
713	713		end;
714	714		// Close the input on the SecondProcess
715	715		// so it finishes processing it's data
716	716		SecondProcess.CloseInput;
717	717
718	718		// and wait for it to complete
719	719		// be carefull what command you run because it may not exit when
720	720		// it's input is closed and the following line may loop forever
721	721		while SecondProcess.Running do
722	722		Sleep(1);
723	723		// that's it! the rest of the program is just so the example
724	724		// is a little 'useful'
725	725
726	726		// we will reuse Buffer to output the SecondProcess's
727	727		// output to this programs stdout
728	728		WriteLn('Grep output Start:');
729	729		ReadSize := SecondProcess.Output.NumBytesAvailable;
730	730		if ReadSize > SizeOf(Buffer) then
731	731		ReadSize := SizeOf(Buffer);
732	732		if ReadSize > 0 then
733	733		begin
734	734		ReadCount := SecondProcess.Output.Read(Buffer, ReadSize);
735	735		WriteLn(Copy(Buffer,0, ReadCount));
736	736		end
737	737		else
738	738		WriteLn('grep did not find what we searched for. ', SecondProcess.ExitStatus);
739	739		WriteLn('Grep output Finish:');
740	740
741	741		// free our process objects
742	742		FirstProcess.Free;
743	743		SecondProcess.Free;
744	744		end.
745	745		```
746	746
747	747		That's it. Now you can redirect output from one program to another.
748	748
749	749		#### Notes
750	750
751	751		This example may seem overdone since it's possible to run "complicated" commands using a shell with TProcess like:
752	752
753	753		``` pascal
754	754		Process.Commandline := 'sh -c "pwd \| grep / -"';
755	755		```
756	756
757	757		But our example is more crossplatform since it needs no modification to run on Windows or Linux etc. "sh" may or may not exist on your platform and is generally only available on *nix platforms. Also we have more flexibility in our example since you can read and write from/to the input, output and stderr of each process individually, which could be very advantageous for your project.
758	758
759	759		### Redirecting input and output and running under root
760	760
761	761		A common problem on Unixes (FreeBSD, macOS) and Linux is that you want to execute some program under the root account (or, more generally, another user account). An example would be running the ping command.
762	762
763	763		If you can use sudo for this, you could adapt the following example adapted from one posted by andyman on the forum ([1](http://lazarus.freepascal.org/index.php/topic,14479.0.html)). This sample runs `ls` on the `/root` directory, but can of course be adapted.
764	764
765	765		A better way to do this is to use the policykit package, which should be available on all recent Linuxes. [See the forum thread for details.](http://lazarus.freepascal.org/index.php/topic,14479.0.html)
766	766
767	767		Large parts of this code are similar to the earlier example, but it also shows how to redirect stdout and stderr of the process being called separately to stdout and stderr of our own code.
768	768
769	769		``` pascal
770	770		program rootls;
771	771
772	772		{ Demonstrates using TProcess, redirecting stdout/stderr to our stdout/stderr,
773	773		calling sudo on FreeBSD/Linux/macOS, and supplying input on stdin}
774	774		{$mode objfpc}{$H+}
775	775
776	776		uses
777	777		Classes,
778	778		Math, {for min}
779	779		Process;
780	780
781	781		procedure RunsLsRoot;
782	782		var
783	783		Proc: TProcess;
784	784		CharBuffer: array [0..511] of char;
785	785		ReadCount: integer;
786	786		ExitCode: integer;
787	787		SudoPassword: string;
788	788		begin
789	789		WriteLn('Please enter the sudo password:');
790	790		Readln(SudoPassword);
791	791		ExitCode := -1; //Start out with failure, let's see later if it works
792	792		Proc := TProcess.Create(nil); //Create a new process
793	793		try
794	794		Proc.Options := [poUsePipes, poStderrToOutPut]; //Use pipes to redirect program stdin,stdout,stderr
795	795		Proc.CommandLine := 'sudo -S ls /root'; //Run ls /root as root using sudo
796	796		// -S causes sudo to read the password from stdin.
797	797		Proc.Execute; //start it. sudo will now probably ask for a password
798	798
799	799		// write the password to stdin of the sudo program:
800	800		SudoPassword := SudoPassword + LineEnding;
801	801		Proc.Input.Write(SudoPassword[1], Length(SudoPassword));
802	802		SudoPassword := '%*'; //short string, hope this will scramble memory a bit; note: using PChars is more fool-proof
803	803		SudoPassword := ''; // and make the program a bit safer from snooping?!?
804	804
805	805		// main loop to read output from stdout and stderr of sudo
806	806		while Proc.Running or (Proc.Output.NumBytesAvailable > 0) or
807	807		(Proc.Stderr.NumBytesAvailable > 0) do
808	808		begin
809	809		// read stdout and write to our stdout
810	810		while Proc.Output.NumBytesAvailable > 0 do
811	811		begin
812	812		ReadCount := Min(512, Proc.Output.NumBytesAvailable); //Read up to buffer, not more
813	813		Proc.Output.Read(CharBuffer, ReadCount);
814	814		Write(StdOut, Copy(CharBuffer, 0, ReadCount));
815	815		end;
816	816		// read stderr and write to our stderr
817	817		while Proc.Stderr.NumBytesAvailable > 0 do
818	818		begin
819	819		ReadCount := Min(512, Proc.Stderr.NumBytesAvailable); //Read up to buffer, not more
820	820		Proc.Stderr.Read(CharBuffer, ReadCount);
821	821		Write(StdErr, Copy(CharBuffer, 0, ReadCount));
822	822		end;
823	823		end;
824	824		ExitCode := Proc.ExitStatus;
825	825		finally
826	826		Proc.Free;
827	827		Halt(ExitCode);
828	828		end;
829	829		end;
830	830
831	831		begin
832	832		RunsLsRoot;
833	833		end.
834	834		```
835	835
836	836		Other thoughts: It would no doubt be advisable to see if sudo actually prompts for a password. This can be checked consistently by setting the environment variable SUDO_PROMPT to something we watch for while reading the stdout of TProcess avoiding the problem of the prompt being different for different locales. Setting an environment variable causes the default values to be cleared(inherited from our process) so we have to copy the environment from our program if needed.
837	837
838	838		### Using fdisk with sudo on Linux
839	839
840	840		The following example shows how to run fdisk on a Linux machine using the sudo command to get root permissions. Note: this is an example only, and does not cater for large output.
841	841
842	842		``` pascal
843	843		program getpartitioninfo;
844	844		{Originally contributed by Lazarus forums wjackon153. Please contact him for questions, remarks etc.
845	845		Modified from Lazarus snippet to FPC program for ease of understanding/conciseness by BigChimp}
846	846
847	847		Uses
848	848		Classes, SysUtils, FileUtil, Process;
849	849
850	850		var
851	851		hprocess: TProcess;
852	852		sPass: String;
853	853		OutputLines: TStringList;
854	854
855	855		begin
856	856		sPass := 'yoursudopasswordhere'; // You need to change this to your own sudo password
857	857		OutputLines:=TStringList.Create; //... a try...finally block would be nice to make sure
858	858		// OutputLines is freed... Same for hProcess.
859	859
860	860		// The following example will open fdisk in the background and give us partition information
861	861		// Since fdisk requires elevated priviledges we need to
862	862		// pass our password as a parameter to sudo using the -S
863	863		// option, so it will will wait till our program sends our password to the sudo application
864	864		hProcess := TProcess.Create(nil);
865	865		// On Linux/Unix/FreeBSD/macOS, we need specify full path to our executable:
866	866		hProcess.Executable := '/bin/sh';
867	867		// Now we add all the parameters on the command line:
868	868		hprocess.Parameters.Add('-c');
869	869		// Here we pipe the password to the sudo command which then executes fdisk -l:
870	870		hprocess.Parameters.add('echo ' + sPass + ' \| sudo -S fdisk -l');
871	871		// Run asynchronously (wait for process to exit) and use pipes so we can read the output pipe
872	872		hProcess.Options := hProcess.Options + [poWaitOnExit, poUsePipes];
873	873		// Now run:
874	874		hProcess.Execute;
875	875
876	876		// hProcess should have now run the external executable (because we use poWaitOnExit).
877	877		// Now you can process the process output (standard output and standard error), eg:
878	878		OutputLines.Add('stdout:');
879	879		OutputLines.LoadFromStream(hprocess.Output);
880	880		OutputLines.Add('stderr:');
881	881		OutputLines.LoadFromStream(hProcess.Stderr);
882	882		// Show output on screen:
883	883		writeln(OutputLines.Text);
884	884
885	885		// Clean up to avoid memory leaks:
886	886		hProcess.Free;
887	887		OutputLines.Free;
888	888
889	889		//Below are some examples as you see we can pass illegal characters just as if done from terminal
890	890		//Even though you have read elsewhere that you can not I assure with this method you can :)
891	891
892	892		//hprocess.Parameters.Add('ping -c 1 www.google.com');
893	893		//hprocess.Parameters.Add('ifconfig wlan0 \| grep ' + QuotedStr('inet addr:') + ' \| cut -d: -f2');
894	894
895	895		//Using QuotedStr() is not a requirement though it makes for cleaner code;
896	896		//you can use double quote and have the same effect.
897	897
898	898		//hprocess.Parameters.Add('glxinfo \| grep direct');
899	899
900	900		// This method can also be used for installing applications from your repository:
901	901
902	902		//hprocess.Parameters.add('echo ' + sPass + ' \| sudo -S apt-get install -y pkg-name');
903	903
904	904		end.
905	905		```
906	906
907	907		### Parameters which contain spaces (Replacing Shell Quotes)
908	908
909	909		In the Linux shell it is possible to write quoted arguments like this:
910	910
911		-	~~`gdb --batch --eval-command="info symbol 0x0000DDDD" myprogram`~~
	911	+	```text
	912	+	gdb --batch --eval-command="info symbol 0x0000DDDD" myprogram
	913	+	```
912	914
913	915		And GDB will receive 3 arguments (in addition to the first argument which is the full path to the executable):
914	916
915	917		1. --batch
916	918		2. --eval-command=info symbol 0x0000DDDD
917	919		3. the full path to myprogram
918	920
919	921		The best solution to avoid complicated quoting is to to switch to TProcess.Parameters.Add instead of setting the Commandline for non trivial cases e.g.
920	922
921		-	~~` AProcess.Executable:='/usr/bin/gdb';`\~~
922		-	~~` AProcess.Parameters.Add('--batch');`\~~
923		-	~~` AProcess.Parameters.Add('--eval-command=info symbol 0x0000DDDD'); // note the absence of quoting here`\~~
924		-	~~` AProcess.Parameters.Add('/home/me/myprogram');`~~
	923	+	``` pascal
	924	+	AProcess.Executable:='/usr/bin/gdb';
	925	+	AProcess.Parameters.Add('--batch');
	926	+	AProcess.Parameters.Add('--eval-command=info symbol 0x0000DDDD'); // note the absence of quoting here
	927	+	AProcess.Parameters.Add('/home/me/myprogram');
	928	+	```
925	929
926	930		And also remember to only pass full paths.
927	931
928	932		TProcess.Commandline however does support some basic quoting for parameters with quoting. Quote the whole parameter containing spaces with double quotes. Like this:
929	933
930		-	~~`AProcess.CommandLine := '/usr/bin/gdb --batch "--eval-command=info symbol 0x0000DDDD" /home/me/myprogram';`~~
	934	+	``` pascal
	935	+	AProcess.CommandLine := '/usr/bin/gdb --batch "--eval-command=info symbol 0x0000DDDD" /home/me/myprogram';
	936	+	```
931	937
932	938		The .CommandLine property is [deprecated](http://bugs.freepascal.org/view.php?id=14446) and bugreports to support more complicated quoting cases won't accepted.
933	939
934	940		## LCLIntf Alternatives
935	941
936	942		Sometimes, you don't need to explicitly call an external program to get the functionality you need. Instead of opening an application and specifying the document to go with it, just ask the OS to open the document and let it use the default application associated with that file type. Below are some examples.
937	943
938	944		### Open document in default application
939	945
940	946		In some situations you need to open some document/file using default associated application rather than execute a particular program. This depends on running operating system. Lazarus provides a platform independent procedure OpenDocument which will handle it for you. Your application will continue running without waiting for the document process to close.
941	947
942	948		``` pascal
943	949		uses LCLIntf;
944	950		...
945	951		OpenDocument('manual.pdf');
946	952		...
947	953		```
948	954
949	955		- [[opendocument\|OpenDocument reference]]
950	956
951	957		### Open web page in default web browser
952	958
953	959		Just pass the URL required, the leading <http://> appears to be optional under certain circumstances. Also, passing a filename appears to give the same results as OpenDocument()
954	960
955	961		``` pascal
956	962		uses LCLIntf;
957	963		...
958	964		OpenURL('www.lazarus.freepascal.org/');
959	965		```
960	966
961	967		See also:
962	968
963	969		- [[OpenURL\|OpenURL reference]]
964	970
965	971		Or, you could use TProcess like this:
966	972
967	973		``` pascal
968	974		uses Process;
969	975
970	976		procedure OpenWebPage(URL: string);
971	977		// Apparently you need to pass your URL inside ", like "www.lazarus.freepascal.org"
972	978		var
973	979		Browser, Params: string;
974	980		begin
975	981		FindDefaultBrowser(Browser, Params);
976	982		with TProcess.Create(nil) do
977	983		try
978	984		Executable := Browser;
979	985		Params:=Format(Params, [URL]);
980	986		Params:=copy(Params,2,length(Params)-2); // remove "", the new version of TProcess.Parameters does that itself
981	987		Parameters.Add(Params);
982	988		Options := [poNoConsole];
983	989		Execute;
984	990		finally
985	991		Free;
986	992		end;
987	993		end;
988	994		```
989	995
990	996		## WinExec
991	997
992	998		The Windows 3.x precursor of CreateProcess, sometimes still encountered in ancient Delphi code. Replace with one of the above. It is still available in unit Windows, but marked deprecated
993	999
994	1000		## See also
995	1001
996	1002		- [TProcess documentation](http://lazarus-ccr.sourceforge.net/docs/fcl/process/tprocess.html)
997	1003		- [[opendocument\|OpenDocument]]
998	1004		- [[OpenURL]]
999	1005		- [[TProcessUTF8]]
1000	1006		- [[TXMLPropStorage]]
1001	1007		- [[Webbrowser]]
1002	1008
1003	1009		---
1004	1010		From the Free Pascal wiki, page "Executing External Programs", as it stood on 2023-09-19 after a change by Marcov, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history