Description
Raised when a command cannot be spawned.
Append_Argument
procedure Append_Argument (Item : in out Command; Value : String)
Append one argv value after argv[0]. Empty arguments are retained.
Parameters
- Item
Command to update
- Value
Exact argument bytes
Raised exceptions
- Constraint_Error
Value contains NUL
Clear_Arguments
procedure Clear_Arguments (Item : in out Command)
Remove every argument while retaining the executable and launch policy.
Parameters
- Item
Command to update
Clear_Environment
procedure Clear_Environment (Item : in out Command)
Replace inherited environment behavior with an explicit empty environment. Add variables with Set_Environment_Variable.
Parameters
- Item
Command to update
Close
procedure Close (Child : in out Process)
End ownership. Close first closes stdin, hard-terminates a running group, reaps the root, closes output pipes, and joins the native reaper. Repeated calls are harmless.
Parameters
- Child
Process owner to release
Raised exceptions
- Process_Error
Process cleanup or observation fails
Close_Standard_Error
procedure Close_Standard_Error (Child : in out Process)
Close child stderr without consuming remaining bytes. Repeated calls are harmless.
Parameters
- Child
Process owner
Close_Standard_Input
procedure Close_Standard_Input (Child : in out Process)
Close child stdin. Repeated calls are harmless and the child observes end-of-file after buffered pipe data is consumed.
Parameters
- Child
Process owner
Close_Standard_Output
procedure Close_Standard_Output (Child : in out Process)
Close child stdout without consuming remaining bytes. Repeated calls are harmless.
Parameters
- Child
Process owner
Command
type Command is private;
Description of an executable and its launch environment. A command is a value and may be copied before Spawn. Arguments remain separate string values and are never interpreted by a shell.
Exit_Kind
type Exit_Kind is (Exited, Signaled);
Classification of a reaped root process.
Enumeration literals
- Exited
The process called exit or returned from its main routine
- Signaled
The process terminated because of a signal
Exit_Status
type Exit_Status is record
Kind : Exit_Kind := Exited;
Code : Natural range 0 .. 255 := 0;
Signal : Natural := 0;
Core_Dumped : Boolean := False;
end record;
Portable child termination result.
Record fields
- Kind
Exit or signal classification
- Code
Exit code when Kind is Exited; otherwise zero
- Signal
Signal number when Kind is Signaled; otherwise zero
- Core_Dumped
True when the host reports a core-producing signal
Has_Exited
function Has_Exited (Child : Process) return Boolean
Report whether the reaper has observed terminal process state. This is a nonblocking observation; the status remains available to Wait.
Parameters
- Child
Open process owner
Return value
True after exit or a terminal reaper failure is recorded
Raised exceptions
- Program_Error
Child is closed
Identifier
function Identifier (Child : Process) return Process_Id
Return the root's launch-time process identifier. After reaping, the host may reuse this value even before Child is closed. Do not use it for signaling or as a durable application identity.
Parameters
- Child
Open process owner
Return value
Root process identifier
Raised exceptions
- Program_Error
Child is closed
Inherit_Environment
procedure Inherit_Environment (Item : in out Command)
Restore complete environment inheritance from the parent process.
Parameters
- Item
Command to update
Inherit_Working_Directory
procedure Inherit_Working_Directory (Item : in out Command)
Restore inherited working-directory behavior.
Parameters
- Item
Command to update
Is_Open
function Is_Open (Child : Process) return Boolean
Report whether Child owns a spawned process that has not been closed. A reaped process remains owned until Close releases its pipes and reaper.
Parameters
- Child
Process owner to inspect
Return value
True between successful Spawn and Close
Kill
procedure Kill (Child : in out Process)
Send the hard termination signal to the owned process group without waiting. Reaping remains the owner's responsibility through Wait or Close.
Parameters
- Child
Open process owner
Raised exceptions
- Process_Error
kill(2) fails for a live group
- Program_Error
Child is closed
Pipe_Error
Pipe_Error : exception;
Raised when a standard-stream operation fails.
Process
type Process is new Ada.Finalization.Limited_Controlled with private;
Limited owner of one root process, its process group, its three parent pipe ends, and its reaper. Finalization closes stdin, hard-terminates an unjoined group, waits for root reaping, and closes stdout and stderr. At most one operation may be active on each standard stream. Operations on distinct streams may run concurrently. Serialize every explicit stream close and owner finalization against all active operations. Declare owners at a structured scope; finalization can wait indefinitely for a kernel task stuck in an uninterruptible state.
Process_Error
Process_Error : exception;
Raised when process observation or signaling fails.
Process_Id
subtype Process_Id is Interfaces.C.int range 1 .. Interfaces.C.int'Last;
Operating-system process identifier used for launch-time diagnostics. After the root is reaped, the host may reuse its value even while the corresponding Process owner remains open.
Read_Standard_Error
procedure Read_Standard_Error
(Child : in out Process;
Item : out Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Timeout : Duration := Flyology.IO.Infinite;
Token : access Flyology.Cancellation.Token := null)
Read one available stderr chunk with the same semantics as Read_Standard_Output.
Parameters
- Child
Process owner
- Item
Destination bytes
- Last
Last byte read, or Item'First - 1
- Timeout
Deadline interval in seconds; negative means unlimited
- Token
Optional cancellation source that must outlive the call
Raised exceptions
- Timeout_Error
The deadline expires
- Operation_Cancelled
Token is requested
- Pipe_Error
Read or descriptor state fails
Read_Standard_Output
procedure Read_Standard_Output
(Child : in out Process;
Item : out Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Timeout : Duration := Flyology.IO.Infinite;
Token : access Flyology.Cancellation.Token := null)
Read one available stdout chunk. Last precedes Item'First on EOF or for an empty Item. One monotonic deadline covers readiness retries.
Parameters
- Child
Process owner
- Item
Destination bytes
- Last
Last byte read, or Item'First - 1
- Timeout
Deadline interval in seconds; negative means unlimited
- Token
Optional cancellation source that must outlive the call
Raised exceptions
- Timeout_Error
The deadline expires
- Operation_Cancelled
Token is requested
- Pipe_Error
Read or descriptor state fails
Send_Signal
procedure Send_Signal (Child : in out Process; Signal : Signal_Kind)
Send one signal to the root process's original process group. A group already gone is treated as success. This operation does not wait.
Parameters
- Child
Open process owner
- Signal
Signal to send
Raised exceptions
- Process_Error
kill(2) fails for a live group
- Program_Error
Child is closed
Set_Environment_Variable
procedure Set_Environment_Variable (Item : in out Command; Name, Value : String)
Add or replace one variable in the explicit child environment. Calling this operation changes inherited mode to an explicit environment containing only variables set on Item.
Parameters
- Item
Command to update
- Name
Nonempty variable name without '=' or NUL
- Value
Variable value without NUL
Raised exceptions
- Constraint_Error
Name or Value is invalid
Set_Path_Search
procedure Set_Path_Search (Item : in out Command; Enabled : Boolean := True)
Select whether Spawn searches the caller's PATH for Executable. PATH lookup uses the parent environment even when an explicit child environment is configured.
Parameters
- Item
Command to update
- Enabled
True to use posix_spawnp; False to use posix_spawn
Set_Working_Directory
procedure Set_Working_Directory (Item : in out Command; Directory : String)
Set the child working directory. Darwin and glibc Linux implement this through posix_spawn file actions; an unavailable host extension causes Spawn_Error rather than a fork fallback.
Parameters
- Item
Command to update
- Directory
Directory entered before exec
Raised exceptions
- Constraint_Error
Directory is empty or contains NUL
Signal_Kind
type Signal_Kind is (Interrupt, Graceful_Termination, Hard_Kill);
Signals exposed by the portable process-group API.
Enumeration literals
- Interrupt
Interrupt request, normally SIGINT
- Graceful_Termination
Graceful request, normally SIGTERM
- Hard_Kill
Uncatchable hard termination, normally SIGKILL
Spawn
procedure Spawn (Item : Command; Child : in out Process)
Spawn Command and transfer the parent ends of stdin, stdout, and stderr into Child. All Flyology-created descriptors are close-on-exec. Other descriptors opened by the application follow their own FD_CLOEXEC policy. Spawn synchronously resets the child's signal mask to empty and every catchable signal disposition to its default before exec. It has no deadline or cancellation parameter. A failed call leaves Child empty and retains no process or descriptor ownership.
Parameters
- Item
Typed executable, argv, environment, and directory policy
- Child
Empty owner that receives the process and pipes
Raised exceptions
- Spawn_Error
Pipe setup, process attributes, exec, or reaper allocation fails
- Program_Error
Child already owns a process
- Storage_Error
Launch-description allocation fails
Spawn_Error
Spawn_Error : exception;
Raised when a command cannot be spawned.
Standard_Error_Is_Open
function Standard_Error_Is_Open (Child : Process) return Boolean
Report whether the readable parent end of child stderr remains open.
Parameters
- Child
Process owner to inspect
Return value
True when stderr can still be read
Standard_Input_Is_Open
function Standard_Input_Is_Open (Child : Process) return Boolean
Report whether the writable parent end of child stdin remains open.
Parameters
- Child
Process owner to inspect
Return value
True when stdin can still be written
Standard_Output_Is_Open
function Standard_Output_Is_Open (Child : Process) return Boolean
Report whether the readable parent end of child stdout remains open.
Parameters
- Child
Process owner to inspect
Return value
True when stdout can still be read
Stop
procedure Stop (Child : in out Process; Grace : Duration; Status : out Exit_Status)
Request graceful group termination and wait up to Grace seconds for the root. A nonpositive Grace permits only an immediate observation attempt. If the root is still running after that interval, hard-terminate the group. If the root exits sooner, the reaper immediately hard-terminates remaining members of its original group. The root is always reaped before return. Pipes stay open for explicit draining or Close.
Parameters
- Child
Open process owner
- Grace
Monotonic graceful-stop interval in seconds
- Status
Root process termination result
Raised exceptions
- Process_Error
Signaling or process observation fails
- Program_Error
Child is closed
Successful
function Successful (Status : Exit_Status) return Boolean
Report whether Status is an ordinary zero exit.
Parameters
- Status
Reaped child result
Return value
True only for Exited with code zero
To_Command
function To_Command (Executable : String) return Command
Construct a command with no arguments, inherited environment, inherited working directory, and no PATH search.
Parameters
- Executable
Executable path or name
Return value
New command description
Raised exceptions
- Constraint_Error
Executable is empty or contains NUL
Wait
procedure Wait
(Child : in out Process;
Status : out Exit_Status;
Timeout : Duration := Flyology.IO.Infinite;
Token : access Flyology.Cancellation.Token := null)
Wait for and reap the root process. Remaining members of its original process group are hard-terminated before the status becomes ready. The result is stable and subsequent Wait calls return it immediately.
Parameters
- Child
Process owner
- Status
Root process termination result
- Timeout
Deadline interval in seconds; negative means unlimited
- Token
Optional cancellation source that must outlive the call
Raised exceptions
- Timeout_Error
The deadline expires
- Operation_Cancelled
Token is requested
- Process_Error
Process observation fails
- Program_Error
Child is closed
Write_Standard_Input
procedure Write_Standard_Input
(Child : in out Process;
Item : Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Timeout : Duration := Flyology.IO.Infinite;
Token : access Flyology.Cancellation.Token := null)
Write one available stdin chunk. Last precedes Item'First only for an empty Item. A closed child read end raises Pipe_Error without delivering SIGPIPE to the calling native or event-loop pthread.
Parameters
- Child
Process owner
- Item
Source bytes
- Last
Last byte written, or Item'First - 1
- Timeout
Deadline interval in seconds; negative means unlimited
- Token
Optional cancellation source that must outlive the call
Raised exceptions
- Timeout_Error
The deadline expires
- Operation_Cancelled
Token is requested
- Pipe_Error
Write or descriptor state fails