InheritableHandles.md

Console Application Runner Classes Inheritable Handles

Applies to: ~>3.0

When we use TPJConsoleApp to redirect the input and/or output of a child process we create handles to the redirected resources (files or pipes) and pass those handles to the child process. This is done by setting TPJConsoleApp's StdIn, StdOut and StdErr properties.

The handles are created in the context of the application that is using TPJConsoleApp and are used in the context of the console application running as a child process. The child process is said to inherit the handles.

A child process can only inherit handles that have been made inheritable. This is done by means of the TSecurityAttributes structure. This structure is passed to the various Windows API calls used to open files and create pipes and return a handles to them. To ensure that the returned handle is inheritable the bInheritHandle member of the TSecurityAttributes record must be set to true.

The following code shows how to do this:

var
  Security: TSecurityAttributes;
begin
  Security.nLength := SizeOf(Security);
  Security.lpSecurityDescriptor := nil;
  Security.bInheritHandle := True;
  // ...
  // Pass Security to some API call to create handle
end;

You can see concrete examples of using such code in Appendix 1.

File and pipe handles aren't the only ones that can be inherited. There's much more information on inheritance on Microsoft Learn.