wait-extension (BPX1WTE, BPX4WTE) — Obtain status information for children

Function

The wait-extension callable service allows the calling process to obtain status information for its child processes.

Requirements

Operation	Environment
Authorization:	Supervisor or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1WTE):	31-bit
AMODE (BPX4WTE):	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 BPX1WTE(Function_code,
             Idtype,
             Id,
             Stat_loc_ptr,
             Options,
             Info_area_ptr,
             Return_value,
             Return_code,
             Reason_code)

AMODE 64 callers use BPX4WTE with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.

Parameters

Function_code

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains a value that indicates the function to perform. If the value is #wait3, the wait3() function is performed. If the value is #waitid, the waitid() function is performed. The constants #wait3 and #waitid are defined in macro BPXYCONS.

Idtype

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains a value that indicates what type of children to wait for. This parameter is valid only when Function_code is #waitid. It can be one of the following values:

Table 1. Idtypes
Idtype	Description
P_PID	waitid() waits for the child with a process ID that is equal to the value that is specified in the 'id' parameter.
P_PGID	waitid() waits for the child with a process group ID that is equal to the value that is specified in the 'id' parameter.
P_ALL	waitid() waits for any children. The 'id' parameter is ignored.

The P_ constants are defined in the BPXYCONS macro.

Id

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains a value that contains the process id or process group id of the children to wait for. This value is valid only when the function_code is #waitid. Together with Idtype, Id is used to determine which children are to be waited for.

Stat_loc_ptr

Supplied parameter

Type:: Pointer
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 whose status is available.

This parameter is valid only when the function_code is #wait3.

If the wait-extension service returns because the status of a child process is available, and if Stat_loc_Ptr is not a null pointer, information is stored in the location that is pointed to by Stat_loc_ptr. If this field is null, no information is returned. This area is mapped by BPXYWAST.

Options

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the wait options for this invocation of the wait-extension service.

If the function_code is #wait3, the possible values are as the same as the 'options' parameter for the wait (BPX1WAT, BPX4WAT) service.

If the function_code is #waitid, this parameter is used to specify which state changes to wait for. It is formed by ORing together one or more of the following flags:

Table 2. Options
Option	Description
WEXITED	Wait for child processes that have exited.
WSTOPPED	Return status for any child that has stopped upon receipt of a signal.
WCONTINUED	Return status for any child that has stopped and has been continued.
WNOHANG	Return immediately if there are no children to wait for.
WNOWAIT	Keep the process whose status is returned in the info_area_ptr parameter in a waitable state. This does not affect the state of the process; the process may be waited for again after this call completes.

These constants are defined in BPXYCONS.

Info_area_ptr

Supplied parameter

Type:: Pointer
Length:: Fullword (doubleword)

If Function_code is #wait3, Info_area_ptr is the name of a fullword (doubleword) that contains the address of an rusage structure. If this field is null, no information is returned. The rusage structure is defined in macro BPXYRLIM.

If Function_code is #waitid, Info_area_ptr is the name of a fullword (doubleword) that contains the address of a siginfo_t structure. If the function returns because a child process was found that satisfied the conditions that were indicated by the arguments Idtype and Options, the structure that is pointed to by info_area_ptr is filled in by the system with the status of the process. If this field is null, no information is returned. The siginfo_t structure type is defined in macro BPXYSINF.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the BPXWTE service returns -1 if it is not successful.

If it is successful and the Function_code is #waitid, the wait-extension service returns a value of zero.

If it is successful and the Function_code is #wait3, the wait-extension service returns the process id of the child status is being reported for. If WNOHANG was specified and status is not available for any children specified by the Id, the wait-extension service returns a value of zero.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the wait-extension service stores the return code. The wait-extension service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The wait-extension service can return one of the following values in the Return_code parameter:

Return_code	Explanation
ECHILD	The calling process has no existing unwaited-for child processes.
EFAULT	The address of a returned parameter is incorrect. The following reason codes can accompany the return code: JrBadExitStatusAddr, JrBadSiginfoAddr, or JrBadRusageAddr.
EINTR	The function was interrupted because the calling process received a signal.
EINVAL	An incorrect Option, Idtype, or Function_code was specified. The following reason codes can accompany the return code: JrBadOptions, JrBadIdType, or JrBadEntryCode.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the wait-extension service stores the reason code. The wait-extension 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

When the siginfo_t structure is returned, the following applies:
- si_signo is always set to SIGCHLD.
- si_errno is always set to 0.
- si_code is set to CLD_EXITED, CLD_KILLED, CLD_DUMPED, CLD_TRAPPED, CLD_STOPPED, or CLD_CONTINUED. The CLD_ constants are defined in macro BPXYSIGH.
- si_pid is set to the process ID of the child status is being returned for.
- si_uid is set to the user ID of the child status is being returned for.
- si_addr is set to the faulting instruction if the child process terminated because of a SIGILL, SIGFPE, or SIGSEGV signal; otherwise, si_addr is set to 0.
- si_status is set to the child's exit status. The exit status is mapped by macro BPXYWAST.
- si_band is always set to 0.
If the Options field is 0, the wait-extension service waits for processes that have exited.

Characteristics and restrictions

None.

Examples

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