TSdlProcess

A system process.

Definition

Unit: Neslib.Sdl3.Additional

type TSdlProcess = record ... end;

Properties

Name	Description
Input	The TSdlIOStream associated with process standard input.
Output	The TSdlIOStream associated with process standard output.
Properties	The properties associated with a process.

Constructors

Name	Description
Create(TSdlProperties)	Create a new process with the specified properties.
Create(String, TArray<String>, Boolean)	Create a new process.

Operators

Name	Description
Equal(TSdlProcess, TSdlProcess)	Used to compare against another TSdlProcess.
Equal(TSdlProcess, Pointer)	Used to compare against nil.
Implicit	Used to set the value to nil.
NotEqual(TSdlProcess, TSdlProcess)	Used to compare against another TSdlProcess.
NotEqual(TSdlProcess, Pointer)	Used to compare against nil.

Methods

Name	Description
Free	Destroy the previously created process object.
Kill	Stop the process.
Read(Integer)	Read all the output from a process.
Read	Read all the output from a process.
Wait(Boolean, Integer)	Wait for the process to finish.
Wait(Boolean)	Wait for the process to finish.

Property Descriptions

Input

The TSdlIOStream associated with process standard input.

The process must have been created with APipeStdIO set to True, or with TSdlProperty.ProcessCreateStdIn set to TSdlProcessStdIO.App.

Writing to this stream can return less data than expected if the process hasn't read its input. It may be blocked waiting for its output to be read, if so you may need to use Output and read the output in parallel with writing input.

property Input: TSdlIOStream read GetInput

Type: TSdlIOStream

Exceptions

ESdlError: Raised on failure.

See Also

• Output

Remarks

It is safe to use this property from any thread.

---

Output

The TSdlIOStream associated with process standard output.

The process must have been created with APipeStdIO set to True, or with TSdlProperty.ProcessCreateStdOut set to TSdlProcessStdIO.App.

Reading from this stream can return 0 with TSdlIOStream.Status returning TSdlIOStatus.NotReady if no output is available yet.

property Output: TSdlIOStream read GetOutput

Type: TSdlIOStream

Exceptions

ESdlError: Raised on failure.

See Also

• Input

Remarks

It is safe to use this property from any thread.

---

Properties

The properties associated with a process.

The following read-only properties are provided by SDL:

• TSdlProperty.ProcessPid: the process ID of the process.
• TSdlProperty.ProcessStdIn: a TSdlIOStream that can be used to write input to the process, if it was created with TSdlProperty.ProcessCreateStdIn set to TSdlProcessIO.App.
• TSdlProperty.ProcessStdOut: a non-blocking TSdlIOStream that can be used to read output from the process, if it was created with TSdlProperty.ProcessCreateStdOut set to TSdlProcessIO.App.
• TSdlProperty.ProcessStdErr: a non-blocking TSdlIOStream that can be used to read error output from the process, if it was created with TSdlProperty.ProcessCreateStdErr set to TSdlProcessIO.App.
• TSdlProperty.ProcessBackground: True if the process is running in the background.

property Properties: TSdlProperties read GetProperties

Type: TSdlProperties

Exceptions

ESdlError: Raised on failure.

Remarks

It is safe to use this property from any thread.

---

Constructor Descriptions

Create

Create a new process with the specified properties.

These are the supported properties:

• TSdlProperty.ProcessCreateArgs: an array of strings (PUTF8Char) containing the program to run, any arguments, and a nil pointer. This is a required property.
• TSdlProperty.ProcessCreateEnvironment: a TSdlEnvironment pointer. If this property is set, it will be the entire environment for the process, otherwise the current environment is used.
• TSdlProperty.ProcessCreateStdIn: a TSdlProcessIO value describing where standard input for the process comes from, defaults to TSdlProcessStdIO.Null.
• TSdlProperty.ProcessCreateStdInStream: a TSdlIOStream pointer used for standard input when TSdlProperty.ProcessCreateStdIn is set to TSdlProcessStdIO.Redirect.
• TSdlProperty.ProcessCreateStdOut: a TSdlProcessIO value describing where standard output for the process goes to, defaults to TSdlProcessStdIO.Inherited.
• TSdlProperty.ProcessCreateStdOutStream: a TSdlIOStream pointer used for standard output when TSdlProperty.ProcessCreateStdOut is set TSdlProcessStdIO.Redirect.
• TSdlProperty.ProcessCreateStdErr: a TSdlProcessIO value describing where standard error for the process goes to, defaults to TSdlProcessStdIO.Inherited.
• TSdlProperty.ProcessCreateStdErrStream: a TSdlIOStream pointer used for standard error when TSdlProperty.ProcessCreateStdErr is set to TSdlProcessStdIO.Redirect.
• TSdlProperty.ProcessCreateStdErrToStdOut: True if the error output of the process should be redirected into the standard output of the process. This property has no effect if TSdlProperty.ProcessCreateStdErr is set.
• TSdlProperty.ProcessCreateBackground: True if the process should run in the background. In this case the default input and output is TSdlProcessStdIO.Null and the exitcode of the process is not available, and will always be 0.

On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and SIGCHLD should not be ignored or handled because those would prevent SDL from properly tracking the lifetime of the underlying process. You should use Wait instead.

constructor Create(const AProps: TSdlProperties); overload

Parameters

AProps: TSdlProperties : The properties to use.

Exceptions

ESdlError: Raised on failure.

See Also

• Properties
• Read
• Input
• Output
• Kill
• Wait
• Free

Remarks

It is safe to call this constructor from any thread.

---

Create

Create a new process.

The path to the executable is supplied in AExePath. AArgs are additional arguments passed on the command line of the new process.

Setting APipeStdIO to True is equivalent to setting TSdlProperty.ProcessCreateStdIn and TSdlProperty.ProcessCreateStdOut to TSdlProcessStrIO.App, and will allow the use of Read or Input and Output.

See the other constructor for more details.

constructor Create(const AExePath: String; const AArgs: TArray<String>; const APipeStdIO: Boolean); overload

Parameters

AExePath: String : Path to the executable.

AArgs: TArray<String> : Arguments for the new process.

APipeStdIO: Boolean : True to create pipes to the process's standard input and from the process's standard output, False for the process to have no input and inherit the application's standard output.

Exceptions

ESdlError: Raised on failure.

See Also

• Properties
• Read
• Input
• Output
• Kill
• Wait
• Free

Remarks

It is safe to call this constructor from any thread.

---

Operator Descriptions

Equal(TSdlProcess, TSdlProcess)

Used to compare against another TSdlProcess.

class operator Equal(const ALeft, ARight: TSdlProcess): Boolean; inline; static

Parameters

ALeft: TSdlProcess

ARight: TSdlProcess

Returns

Boolean

---

Equal(TSdlProcess, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlProcess; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlProcess

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlProcess; inline; static

Parameters

AValue: Pointer

Returns

TSdlProcess

---

NotEqual(TSdlProcess, TSdlProcess)

Used to compare against another TSdlProcess.

class operator NotEqual(const ALeft, ARight: TSdlProcess): Boolean; inline; static

Parameters

ALeft: TSdlProcess

ARight: TSdlProcess

Returns

Boolean

---

NotEqual(TSdlProcess, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlProcess; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlProcess

ARight: Pointer

Returns

Boolean

---

Method Descriptions

Free

Destroy the previously created process object.

Note that this does not stop the process, just destroys the SDL object used to track it. If you want to stop the process you should use Kill.

procedure Free; inline

See Also

• Kill

Remarks

This method is not thread safe.

---

Kill(Boolean)

Stop the process.

procedure Kill(const AForce: Boolean = False); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AForce: Boolean = False : (Optional) True to terminate the process immediately, False (Default) to try to stop the process gracefully. In general you should try to stop the process gracefully first as terminating a process may leave it with half-written data or in some other unstable state.

See Also

• Wait
• Free

Remarks

This method is not thread safe.

---

Read(Integer)

Read all the output from a process.

If a process was created with I/O enabled, you can use this function to read the output. This function blocks until the process is complete, capturing all output, and providing the process exit code.

function Read(out AExitCode: Integer): TBytes; overload; inline

Parameters

AExitCode: Integer : Is set to the process exit code if the process has exited.

Returns

TBytes: The data.

Remarks

This method is not thread safe.

---

Read

Read all the output from a process.

If a process was created with I/O enabled, you can use this function to read the output. This function blocks until the process is complete, capturing all output, and providing the process exit code.

function Read: TBytes; overload; inline

Returns

TBytes: The data.

Remarks

This method is not thread safe.

---

Wait(Boolean, Integer)

Wait for the process to finish.

This can be called multiple times to get the status of a process.

The exit code will be the exit code of the process if it terminates normally, a negative signal if it terminated due to a signal, or -255 otherwise. It will not be changed if the process is still running.

If you create a process with standard output piped to the application (APipeStdIO being True) then you should read all of the process output before calling Wait. If you don't do this the process might be blocked indefinitely waiting for output to be read and Wait will never return True.

function Wait(const ABlock: Boolean; out AExitCode: Integer): Boolean; overload; inline

Parameters

ABlock: Boolean : If True, block until the process finishes; otherwise, report on the process' status.

AExitCode: Integer : Is set to the process exit code if the process has exited.

Returns

Boolean: True if the process exited, False otherwise.

See Also

• Kill
• Free

Remarks

This method is not thread safe.

---

Wait(Boolean)

Wait for the process to finish.

This can be called multiple times to get the status of a process.

If you create a process with standard output piped to the application (APipeStdIO being True) then you should read all of the process output before calling Wait. If you don't do this the process might be blocked indefinitely waiting for output to be read and Wait will never return True.

function Wait(const ABlock: Boolean): Boolean; overload; inline

Parameters

ABlock: Boolean : If True, block until the process finishes; otherwise, report on the process' status.

Returns

Boolean: True if the process exited, False otherwise.

See Also

• Kill
• Free

Remarks

This method is not thread safe.

---