wait (BPX1WAT, BPX4WAT) — Wait for a child process to end

Function

The wait callable service obtains 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 children that are created by the fork service, as well as processes that are attached by ptrace.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1WAT): 31-bit
AMODE (BPX4WAT): 64-bit
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1WAT,(Process_ID,
              Options,
              Status_field_address,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4WAT with the same parameters. The Status_field_address parameter is a doubleword.

Parameters

Process_ID
Supplied parameter
Type:
Integer
Length:
Fullword
The name of a fullword that contains a value that indicates the event that 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.
Options
Supplied parameter
Type:
Integer
Length:
Fullword
The name of a fullword that contains the wait options for this invocation of the wait service. The wait options that are specified affect the actions that are taken by the wait service, as described in this topic. These options can be specified separately or in combination. A zero value for the wait options implies that the wait service performs its default processing; that is, it waits for a child process to end. The following flags defined in the BPXYCONS macro are the allowable wait options (see BPXYCONS — Constants used by services).
Constant Description
WNOHANG The wait service does not suspend execution of the calling process if status is not immediately available for one of the child processes that is specified by Process_ID.
WUNTRACED The wait service also returns the status of any child processes that are 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.
WCONTINUED The wait service returns the status for any continued child process that is specified by Process_ID whose status has not yet been reported since it continued from a job control stop.
Status_field_address
Returned parameter
Type:
Address
Length:
Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of a fullword in which this service is to place the status value for the child process that ended or stopped. The status value can be analyzed with the status value map BPXYWAST. For a description of this mapping, see BPXYWAST — Map the wait status word. The status value is returned only if status is available for a child or debugged process, and the address specified in this field is not zero.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the wait service returns the process ID of the child that the status information applied to, if the request is successful, or -1 if it is not successful, or 0 if WNOHANG was specified and there is at least one process whose status information is not available.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the wait service stores the return code. The wait service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The wait service can return one of the following values in the Return_code parameter:
Return_code Explanation
ECHILD The caller has no appropriate child process; that is, no child process whose status has not already been obtained through earlier calls to wait meets the criteria for waiting.
EFAULT One of the parameters that was specified contained the address of a storage area that is not accessible to the caller. The following reason code unique to this service can accompany this return code: JRBadExitStatusAddr.
EINTR The calling process received a signal before the completion of an event that would cause the wait service to return. The service was interrupted by a signal. In this case, the value that is contained in Status_field_address is undefined.
EINVAL The value of the option is not valid.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the wait service stores the reason code. The wait service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

  1. The wait 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 wait is called, the routine immediately returns with that status information to the caller.

    If the WUNTRACED option is specified, the foregoing also applies for stopped children and stopped debugged processes.

  2. The wait service always returns status for stopped debugged processes, even if WUNTRACED is not specified.

    If status is available for one or more processes, the order in which the status is reported is unspecified.

  3. If the wait service is invoked simultaneously from multiple threads within the same process, the following behavior should be noted:
    • When multiple threads issue a fork call followed by a call to the wait service to wait for any child process to end, the status that is received by each thread may not be the status of the child that was created by that thread. If a thread wishes to receive the status of the child that it created, the thread should specify the returned child Process Id when it calls the wait service to wait for the child process to end.
    • If the wait service is called from multiple threads requesting status for the same process, the thread that receives the status is not specified when the process ends or stops. The thread that does not receive the status is returned to with a return value of -1 and a return code of ECHILD.
    Note: A debugged process is one that is being monitored for debugging purposes with the ptrace service.

Related services

Characteristics and restrictions

There are no restrictions on the use of the wait service.

Examples

For an example using this callable service, see BPX1WAT (wait) example.

Parent topic: Callable services descriptions