Unit implementing the TProcess component.

The Process unit contains the code for the component, a cross-platform component to start and control other programs, offering also access to standard input and output for these programs.

TProcess does not handle wildcard expansion, does not support complex pipelines as in Unix. If this behaviour is desired, the shell can be executed with the pipeline as the command it should execute.

For TComponent and TStream definitions. For pipe streams. For exception support. Options to be used when a process is started. When a new process is started using , these options control the way the process is started. Note that not all options are supported on all platforms. Start the process in suspended state. Wait for the process to terminate before returning. Use pipes to redirect standard input and output. Redirect standard error to the standard output stream. Do not allow access to the console window for the process (Win32 only) Start a new console window for the process (Win32 only) Use default error handling. Start the process in a new process group (Win32 only) Allow debugging of the process (Win32 only) Do not follow processes started by this process (Win32 only) Description of the main window of the new process. This type describes what the new process' main window should look like. Most of these have only effect on Windows. They are ignored on other systems. Allow system to position the window. The main window is hidden. The main window is maximized. The main window is minimized. Restore the previous position. Show the main window. When showing Show the main window on The main window is shown maximized The main window is shown minimized The main window is shown minimized but not activated The main window is shown but not activated The main window is shown but not activated The main window is shown normally Options determining how the application is started. These options are mainly for Win32, and determine what should be done with the application once it's started. Use the Show Window options specified in TShowWindowOption Use the window sizes as specified in TProcess Use the window sizes as specified in TProcess. Use the console character width as specified in TProcess. Use the console fill attribute as specified in TProcess. type determining the priority of the newly started process. This enumerated type determines the priority of the newly started process. It translates to default platform specific constants. If finer control is needed, then platform-dependent mechanism need to be used to set the priority. The process runs at higher than normal priority. The process only runs when the system is idle (i.e. has nothing else to do) The process runs at normal priority. The process runs at real-time priority. Set of TProcessOption. Set of TStartUpOption. Exception raised when an error occurs in a TProcess routine. TProcess Class to start and control other processes.

TProcess is a component that can be used to start and control other processes (programs/binaries). It contains a lot of options that control how the process is started. Many of these are Win32 specific, and have no effect on other platforms, so they should be used with care.

The simplest way to use this component is to create an instance, set the CommandLine property to the full pathname of the program that should be executed, and call Execute. To determine whether the process is still running (i.e. has not stopped executing), the Running property can be checked.

More advanced techniques can be used with the Options settings.

Create Execute Running CommandLine Options Create a new instance of the TProcess class. Create creates a new instance of the TProcess class. After calling the inherited constructor, it simply sets some default values. Owner of the instance. Destroy this instance of TProcess Destroy cleans up this instance of TProcess. Prior to calling the inherited destructor, it cleans up any streams that may have been created. If a process was started and is still executed, it is not stopped, but the standard input/output/stderr streams are no longer available, because they have been destroyed. None. Create Execute the program with the given options

Execute actually executes the program as specified in CommandLine, applying as much as of the specified options as supported on the current platform.

If the poWaitOnExit option is specified in Options, then the call will only return when the program has finished executing (or if an error occured). If this option is not given, the call returns immediatly, but the WaitOnExit call can be used to wait for it to close, or the Running call can be used to check whether it is still running.

The call can be used to terminate the program if it is still running, or the Suspend call can be used to temporarily stop the program's execution.

The ExitStatus function can be used to check the program's exit status, after it has stopped executing.

On error a exception is raised. Resume execution of a suspended process Resume should be used to let a suspended process resume it's execution. It should be called in particular when the poRunSuspended flag is set in Options. None. 0 on success, nonzero otherwise. Suspend a running process

Suspend suspends a running process. If the call is successful, the process is suspended: it stops running, but can be made to execute again using the Resume call.

Suspend is fundamentally different from which actually stops the process.

On error, a nonzero result is returned. 0 on success, nonzero otherwise. Terminate a running process

Terminate stops the execution of the running program. It effectively stops the program.

On Windows, the program will report an exit code of AExitCode, on other systems, this value is ignored.

On error, a nonzero value is returned. 0 on succes, nonzero for failure. Exit status to report (Windows only) Wait for the program to stop executing.

WaitOnExit waits for the running program to exit. It returns True if the wait was succesful, or False if there was some error waiting for the program to exit.

Note that the return value of this function has changed. The old return value was a DWord with a platform dependent error code. To make things consistent and cross-platform, a boolean return type was used.

On error, False is returned. No extended error information is available, as it is highly system dependent. True means the process was successfully waited on, False indicates some error occurred. Positions for the main program window. WindowRect can be used to specify the position of Handle of the process

Handle identifies the process. In Unix systems, this is the process ID. On windows, this is the process handle. It can be used to signal the process.

The handle is only valid after has been called. It is not reset after the process stopped.

Alias for Handle

ProcessHandle equals Handle and is provided for completeness only.

Main process thread handle

ThreadHandle is the main process thread handle. On Unix, this is the same as the process ID, on Windows, this may be a different handle than the process handle.

The handle is only valid after has been called. It is not reset after the process stopped.

ID of the process.

ProcessID is the ID of the process. It is the same as the handle of the process on Unix systems, but on Windows it is different from the process Handle.

The ID is only valid after has been called. It is not reset after the process stopped.

ID of the main process thread

ProcessID is the ID of the main process thread. It is the same as the handle of the main proces thread (or the process itself) on Unix systems, but on Windows it is different from the thread Handle.

The ID is only valid after has been called. It is not reset after the process stopped.

Stream connected to standard input of the process.

Input is a stream which is connected to the process' standard input file handle. Anything written to this stream can be read by the process.

The Input stream is only instantiated when the poUsePipes flag is used in Options.

Note that writing to the stream may cause the calling process to be suspended when the created process is not reading from it's input, or to cause errors when the process has terminated.

Stream connected to standard output of the process.

Output is a stream which is connected to the process' standard output file handle. Anything written to standard output by the created process can be read from this stream.

The Output stream is only instantiated when the poUsePipes flag is used in Options.

The Output stream also contains any data written to standard diagnostic output (stderr) when the poStdErrToOutPut flag is used in Options.

Note that reading from the stream may cause the calling process to be suspended when the created process is not writing anything to standard output, or to cause errors when the process has terminated.

Stream connected to standard diagnostic output of the process.

StdErr is a stream which is connected to the process' standard diagnostic output file handle (StdErr). Anything written to standard diagnostic output by the created process can be read from this stream.

The StdErr stream is only instantiated when the poUsePipes flag is used in Options.

The Output stream equals the Output when the poStdErrToOutPut flag is used in Options.

Exit status of the process.

ExitStatus contains the exit status as reported by the process when it stopped executing. The value of this property is only meaningful when the process is no longer running. If it is not running then the value is zero.

Should the created process inherit the open handles of the current process.

InheritHandles determines whether the created process inherits the open handles of the current process (value True) or not (False).

On Unix, setting this variable has no effect.

Start or stop the process. Active starts the process if it is set to True, or terminates the process if set to False. It's mostly intended for use in an IDE. Name of the application to start (deprecated)

ApplicationName is an alias for . It's mostly for use in the Windows CreateProcess call. If CommandLine is not set, then ApplicationName will be used instead.

ApplicationName is deprecated. New code should use Executable instead, and leave ApplicationName empty.

Command-line to execute (deprecated)

CommandLine is deprecated. To avoid problems with command-line options with spaces in them and the quoting problems that this entails, it has been superseded by the properties and , which should be used instead of CommandLine. New code should leave CommandLine empty.

CommandLine is the command-line to be executed: this is the name of the program to be executed, followed by any options it should be passed.

If the command to be executed or any of the arguments contains whitespace (space, tab character, linefeed character) it should be enclosed in single or double quotes.

If no absolute pathname is given for the command to be executed, it is searched for in the PATH environment variable. On Windows, the current directory always will be searched first. On other platforms, this is not so.

Note that either CommandLine or ApplicationName must be set prior to calling Execute.

Title of the console window

ConsoleTitle is used on Windows when executing a console application: it specifies the title caption of the console window. On other platforms, this property is currently ignored.

Changing this property after the process was started has no effect.

Working directory of the process.

CurrentDirectory specifies the working directory of the newly started process.

Changing this property after the process was started has no effect.

Desktop on which to start the process.

DeskTop is used on Windows to determine on which desktop the process' main window should be shown. Leaving this empty means the process is started on the same desktop as the currently running process.

Changing this property after the process was started has no effect.

On unix, this parameter is ignored.

Environment variables for the new process

Environment contains the environment for the new process; it's a list of Name=Value pairs, one per line.

If it is empty, the environment of the current process is passed on to the new process.

Options to be used when starting the process.

Options determine how the process is started. They should be set before the Execute call is made.

	Option	Meaning
`poRunSuspended`	Start the process in suspended state.
`poWaitOnExit`	Wait for the process to terminate before returning.
`poUsePipes`	Use pipes to redirect standard input and output.
`poStderrToOutPut`	Redirect standard error to the standard output stream.
`poNoConsole`	Do not allow access to the console window for the process (Win32 only)
`poNewConsole`	Start a new console window for the process (Win32 only)
`poDefaultErrorMode`	Use default error handling.
`poNewProcessGroup`	Start the process in a new process group (Win32 only)
`poDebugProcess`	Allow debugging of the process (Win32 only)
`poDebugOnlyThisProcess`	Do not follow processes started by this process (Win32 only)

Priority at which the process is running.

Priority determines the priority at which the process is running.

	Priority	Meaning
`ppHigh`	The process runs at higher than normal priority.
`ppIdle`	The process only runs when the system is idle (i.e. has nothing else to do)
`ppNormal`	The process runs at normal priority.
`ppRealTime`	The process runs at real-time priority.

Note that not all priorities can be set by any user. Usually, only users with administrative rights (the root user on Unix) can set a higher process priority.

On unix, the process priority is mapped on Nice values as follows:

	Priority	Nice value
`ppHigh`	20
`ppIdle`	20
`ppNormal`	0
`ppRealTime`	-20

Additional (Windows) startup options

StartUpOptions contains additional startup options, used mostly on Windows system. They determine which other window layout properties are taken into account when starting the new process.

	Priority	Meaning
`suoUseShowWindow`	Use the Show Window options specified in ShowWindow
`suoUseSize`	Use the specified window sizes
`suoUsePosition`	Use the specified window sizes.
`suoUseCountChars`	Use the specified console character width.
`suoUseFillAttribute`	Use the console fill attribute specified in FillAttribute.

Determines wheter the process is still running. Running can be read to determine whether the process is still running. Determines how the process main window is shown (Windows only)

ShowWindow determines how the process' main window is shown. It is useful only on Windows.

	Option	Meaning
`swoNone`	Allow system to position the window.
`swoHIDE`	The main window is hidden.
`swoMaximize`	The main window is maximized.
`swoMinimize`	The main window is minimized.
`swoRestore`	Restore the previous position.
`swoShow`	Show the main window.
`swoShowDefault`	When showing Show the main window on a default position
`swoShowMaximized`	The main window is shown maximized
`swoShowMinimized`	The main window is shown minimized
`swoshowMinNOActive`	The main window is shown minimized but not activated
`swoShowNA`	The main window is shown but not activated
`swoShowNoActivate`	The main window is shown but not activated
`swoShowNormal`	The main window is shown normally

Number of columns in console window (windows only) WindowColumns is the number of columns in the console window, used to run the command in. This property is only effective if suoUseCountChars is specified in StartupOptions Height of the process main window WindowHeight is the initial height (in pixels) of the process' main window. This property is only effective if suoUseSize is specified in StartupOptions X-coordinate of the initial window (Windows only) WindowLeft is the initial X coordinate (in pixels) of the process' main window, relative to the left border of the desktop. This property is only effective if suoUsePosition is specified in StartupOptions Number of rows in console window (Windows only) WindowRows is the number of rows in the console window, used to run the command in. This property is only effective if suoUseCountChars is specified in StartupOptions Y-coordinate of the initial window (Windows only) WindowTop is the initial Y coordinate (in pixels) of the process' main window, relative to the top border of the desktop. This property is only effective if suoUsePosition is specified in StartupOptions Height of the process main window (Windows only) WindowWidth is the initial width (in pixels) of the process' main window. This property is only effective if suoUseSize is specified in StartupOptions Color attributes of the characters in the console window (Windows only) FillAttribute is a WORD value which specifies the background and foreground colors of the console window. Close the input stream of the process CloseInput closes the input file descriptor of the process, that is, it closes the handle of the pipe to standard input of the process. Input StdErr Output CloseOutput CloseStdErr Close the output stream of the process CloseOutput closes the output file descriptor of the process, that is, it closes the handle of the pipe to standard output of the process. Output Input StdErr CloseInput CloseStdErr Close the error stream of the process CloseStdErr closes the standard error file descriptor of the process, that is, it closes the handle of the pipe to standard error output of the process. Output Input StdErr CloseInput CloseStdErr Event triggered after fork occurred on Linux OnForkEvent is triggered after the fpForkcall in the child process. It can be used to e.g. close file descriptors and make changes to other resources before the fpexecv call. This event is not used on windows. Output Input StdErr CloseInput CloseStdErr Prototype for TProcess.OnForkEvent event handler TProcessForkEvent is the prototype for . It is a simple procedure, as the idea is that only process-global things should be performed in this event handler. Executable name. Supersedes CommandLine and ApplicationName.

Executable is the name of the executable to start. It should not contain any command-line arguments. If no path is given, it will be searched in the PATH environment variable.

The extension must be given, none will be added by the component itself. It may be that the OS adds the extension, but this behaviour is not guaranteed.

Arguments should be passed in .

Executable supersedes the and properties, which have been deprecated. However, if either of CommandLine or ApplicationName is specified, they will be used instead of Executable.

CommandLine ApplicationName Parameters Command-line argumens. Supersedes CommandLine.

Parameters contains the command-line arguments that should be passed to the program specified in Executable.

Commandline arguments should be specified one per item in Parameters: each item in Parameters will be passed as a separate command-line item. It is therefor not necessery to quote whitespace in the items. As a consequence, it is not allowed to specify multiple command-line parameters in 1 item in the stringlist. If a command needs 2 options -t and -s, the following is not correct:


With Parameters do
  begin
  add('-t -s');
  end;

Instead, the code should read:


With Parameters do
  begin
  add('-t');
  Add('-s');
  end;

Note that Parameters is ignored if either of CommandLine or ApplicationName is specified. It can only be used with Executable. The idea of using Parameters is that they are passed unmodified to the operating system. On Windows, a single command-line string must be constructed, and each parameter is surrounded by double quote characters if it contains a space. The programmer must not quote parameters with spaces. Executable CommandLine ApplicationName XTerm program to use (unix only)

XTermProgram can be used to specify the console program to use when poConsole is specified in .

If none is specified, is used to detect the terminal program to use. the list specified in TryTerminals is tried. If none is found, then the DESKTOP_SESSION environment variable is examined:

kde: konsole is used if it is found.
gnome: gnome-terminal is used if it is found
windowmaker: aterm or xterm are used if found.

If after all this, no terminal is found, then a list of default programs is tested: 'x-terminal-emulator','xterm','aterm','wterm','rxvt'.

A list of terminal programs to use (unix only) TryTerminals is used under unix to test for available terminal programs in the function. If is empty, each item in this list will be searched in the path, and used as a terminal program if it was found. Default XTerm program to use XTermProgram is the terminal program that is used. If empty, it will be set the first time is called. Detect the terminal program.

DetectXTerm checks if is set. if so, it returns that. If XTermProgram is empty, the list specified in is tested for existence. If none is found, then the DESKTOP_SESSION environment variable is examined:

kde: konsole is used if it is found.
gnome: gnome-terminal is used if it is found
windowmaker: aterm or xterm are used if found.

If after all this, no terminal is found, then a list of default programs is tested: 'x-terminal-emulator','xterm','aterm','wterm','rxvt'.

If a terminal program is found, then it is saved in XTermProgram, so the next call to DetectXTerm will re-use the value. If the search must be performed again, it is sufficient to set XTermProgram to the empty string.

The terminal program to use, or empty if none was found. Buffer size to be used when using pipes PipeBufferSize indicates the buffer size used when creating pipes (when soUsePipes is specified in Options). This option is not respected on all platforms (currently only Windows uses this). Convert a command-line to a list of command options CommandToList splits the string S in command-line arguments that are returned, one per item, in the List stringlist. Command-line arguments are separated by whitespace (space, tab, CR and LF characters). If an argument needs to contain a space character, it can be surrounded in quote characters (single or double quotes). There is currently no way to specify a quote character inside a quoted argument. String to split up List of command-line arguments, one per item Run a command in a specific directory.

RunCommandInDir will execute binary exename with command-line options commands, setting curdir as the current working directory for the command. The output of the command is captured, and returned in the string OutputString. The function waits for the command to finish, and returns True if the command was started succesfully, False otherwise.

If a ExitStatus parameter is specified the exit status of the command is returned in this parameter.

The version using cmdline attempts to split the command line in a binary and separate command-line arguments. This version of the function is deprecated.

On error, False is returned. True if the command was started succesfully. Current working directory for the command. Executable to start. Command-line arguments for the executable. String to return the commands output. On exit, contains the exit status of the process Filename of binary to start plus command-line arguments separated by whitespace Execute a command in the current working directory RunCommand runs with an empty current working directory. True if the function executed succesfully Binary to start. Command-line arguments String containing the output of the process. Filename of ninary to start and command-line arguments, separated by whitespace.