Function

waitpid invokes the wait callable service to obtain the status of a child process that has ended or stopped. You can use the wait service to obtain the status of a process that is being debugged with the ptrace facilities. The term child refers to a child process created by a fork as well as a process attached by ptrace.

Parameters

pid

A numeric value indicating the event the caller is waiting upon:

• A value greater than zero is assumed to be a process ID. The caller waits for the child or debugged process with that specific process ID to end or to stop.
• A value of zero specifies that the caller is waiting for any children or debugged processes with a process group ID equal to the caller's to end or to stop.
• A value of -1 specifies that the caller is waiting for any of its children or debugged processes to end or to stop.
• If the value is negative and less than -1, its absolute value is assumed to be a process group ID. The caller waits for any children or debugged processes with that process group ID to end or to stop.

stem

The name of a stem variable used to return the information. Upon return, stem.0 contains the number of variables returned. To access the information in the stem variables, you can use numeric values (see REXX predefined variables), or the predefined variables beginning with W_ (see their description in wait).

options

A numeric value or its equivalent predefined variable beginning with W_ that indicates the wait options for this invocation of the wait service. These options can be specified separately or together. (For the numeric values, see REXX predefined variables.)

Variable	Description
0	Wait for the child process to end (default processing)
W_NOHANG	The wait service does not suspend execution of the calling process if status is not immediately available for one of the child processes specified by Process_ID.
W_UNTRACED	The wait service also returns the status of any child processes specified by Process_ID that are stopped, and whose status has not yet been reported since they stopped. If this option is not specified, the wait service returns only the status of processes that end.

Usage notes

1. Use waitpid when you want to wait for a specified child process. The pid argument specifies a set of child processes for which status is requested; waitpid returns the status of a child process from this set.
2. The waitpid service suspends execution of the calling thread until one of the requested child or debugged processes ends or until it obtains information about the process that ended. If a child or debugged process has already ended but its status has not been reported when waitpid is called, the routine immediately returns with that status information to the caller.
3. If the WUNTRACED option is specified, the foregoing also applies for stopped children or stopped debugged processes. A debugged process is one that is being monitored for debugging purposes with the ptrace service.
4. The wait service always returns status for stopped debugged processes, even if WUNTRACED is not specified.
5. If status is available for one or more processes, the order in which the status is reported is unspecified.