Implements a version of the FCL TProcess component that allows UTF-8-encoded arguments.

utf8process.pp implements the TProcessUTF8 component which provides a TProcess descendant that allows UTF-8-encoded values in its properties. The TProcessUTF8 component is added to the System tab in the Lazarus IDE Component Palette.

Exception message raised when a process has no executable or command-line. Present for the Microsoft Windows platform.

Exception message raised when a process cannot be created for the executable or command-line. Present for the Microsoft Windows platform.

Implements a version of the FCL TProcess that allows UTF-8-encoded arguments.

TProcessUTF8 is a TProcess descendant which implements a version of TProcess that accepts and processes UTF-8-encoded arguments. It includes a ParseCmdLine method used to separate a command line into the Executable name and Parameters used in the class instance.

The TProcessUTF8 interface includes additional methods for the Microsoft Windows platform. An overridden Execute method is provided, and protected methods to assign IDs and Handles for the process and its thread. These methods handle Windows-specific nuances required for the CreateProcessW API. This includes security and thread attributes, pipe creation, and any quoting required for file names or parameters with space characters.

TProcessUTF8 is used in the implementation of the Lazarus IDE and related tools like the Debugger, HTML Help viewer, external tools, and the FP Doc Editor. Use TAsyncProcess for a process which receives asynchronous notifications during process execution.

TProcess TAsyncProcess
Updates the process handle for the class instance.

Raises an Exception if the ProcessHandle property cannot be set to the value specified in aProcessHandle.

TProcess.ProcessHandle
Process handle assigned to the ancestor class.
Sets ThreadHandle to the specified value.
Thread handle assigned to the ancestor class.
Sets ProcessID to the specified value.
Process ID assigned to the ancestor class.
Starts execution of the process.

Execute is an overridden method in TProcessUTF8, and is defined only for the Microsoft Windows platforms. Execute handles the nuances of configuring and executing a call to CreateProcessW in the Windows API.

The values in ApplicationName, CommandLine, and Executable are checked to ensure that they contain non-empty values. An EProcess exception is raised if any of these properties contain an empty string ('').

UTF8Decode is called to convert the property values to Unicode strings, and ultimately the WideStr values passed to CreateProcessW. Additional quoting may be applied to the values when the path to the file or arguments contain a Space character. UTF8Decode is also called for the value in the CurrentDirectory property. StringsToWChars is called to convert values in Environment.

Execute initializes the creation flags, process attributes, thread attributes, and start-up information required for the CreateProcessW API call. Values in the Options property determine whether CreatePipes is called for the handles in the start-up information.

Execute raises an EProcess exception if the CreateProcessW API call returns False. Otherwise, the values in ProcessID, ProcessHandle, and ThreadHandle are assigned for the current class instance.

When Options contains the value poUsePipes, the process will redirect information on the standard input, output, and error handles allocated in start-up information. Use the THandleStream instances used in the Input, Output, and StdErr properties to access values for the API call.

Executes sets the value in Running to True, and frees memory allocated to the pointer for the Environment in the process.

At run-time, Execute calls WaitOnExit to detect completion of the process and to set values in the ExitStatus and ExitCode properties. This occurs when poWaitOnExit is included in the Options for the process, and poRunSuspended is not included in the Options. WaitOnExit is never called at design-time to prevent hanging the IDE.

Please note: The overridden Execute method in TProcessUTF8 does not call the inherited method.

TProcess.Executable TProcess.Parameters TProcess.CommandLine TProcess.Environment TProcess.Execute TProcess.Options TProcess.Input TProcess.Output
Separates values in the CommandLine argument into the Executable and Parameters properties.

ParseCmdLine is used to separate the values in the CmdLine argument into the values used for the Executable and Parameters properties.

ReadBackSlash indicates if the BackSlash character (\) is used to quote a character value in the command line. The default value for the argument is False.

ParseCmdLine creates an internal TStringList instance used to store values returned from the SplitCmdLineParams routine in lazfileutils.pas. The first value in the string list (when present) is stored in the Executable property. The remaining values are stored in the Parameters property.

ParseCmdLine is provided as a convenience method. An equivalent operation can be performed using the values in Executable and Parameters properties.

SplitCmdLineParams TProcess.Executable TProcess.Parameters
Command line examined and parsed in the method.
When True, the BackSlash character is used to quote character values.
Executes a command found in the current PATH environment.

RunCmdFromPath is used to execute a command which can be found in the current PATH environment. For example, the following locates and executes the /bin/ls command with the specified arguments:

RunCmdFromPath('ls', '-l /home');

An exception will be raised if the program file cannot be located, or cannot be executed.

RunCmdFromPath creates an instance of TProcessUTF8 to execute the process. The value in ProgramFilename is surrounded by Quotation Mark (") characters if it contains a Space (' ') in the path or file name. RunCmdFromPath calls the Execute method to perform the process using the specified arguments.

EFOpenError
  Raised with the message in lrsProgramFileNotFound
EFOpenError
  Raised with the message in lrsCanNotExecute

TProcess.Execute TProcess.CommandLine TProcess.Executable TProcess.Parameters TProcess.Environment
Name of the program to execute.
Command line parameters for the process.
Gets the full path for the specified executable file.

FindFilenameOfCmd is a String function used to get the full path for the executable file specified in the ProgramFilename argument. FindFilenameOfCmd calls the FilenameIsAbsolute routine to determine if a relative path in ProgramFilename needs to be resolved. FindDefaultExecutablePath is called to search the PATH environment when path information is not used in ProgramFilename.

The return value contains the absolute path and file name. If the file does not exist on the local file system, the return value is an empty string ('').

FilenameIsAbsolute CleanAndExpandFilename FindDefaultExecutablePath
Absolute path to the requested program file, or an empty string.
Program file examined in the method.
Gets the number of threads available on the system.

GetSystemThreadCount is an Integer function used to get the number of threads on the system. The implementation for GetSystemThreadCount is platform- and/or OS-specific. For the Windows environment, the total number of processors available (including logical hyperthreaded processors) are returned using the GetProcessAffinityMask API. When GetProcessAffinityMask is unavailable, the total number of processors from GetSystemInfo is used. For UNIX-like environments, either the sysconf or the fpsysctl function is used. For other environments, the return value is always 1.

The number of threads on the system.
Registers components for use in the Lazarus IDE.

Register is a procedure used to make components in the unit available for use in the Lazarus IDE. Register calls RegisterComponents to make the TProcessUTF8 available on the System tab.