wait()--Wait for Child Process to End

Syntax

 #include <sys/types.h>
 #include <sys/wait.h>

 pid_t wait(int *stat_loc);

  Service Program Name: QP0ZSPWN

  Default Public Authority: *USE

  Threadsafe: Yes

The wait() function suspends processing until a child process has ended. The calling thread will suspend processing until status information is available for a child process that ended. A suspended wait() function call can be interrupted by the delivery of a signal whose action is either to run a signal-catching function or to terminate the process. When wait() is successful, status information about how the child process ended (for example, whether the process ended *stat_loc.

Parameters

stat_loc: (Input) Pointer to an area where status information about how the child process ended is to be placed.

*stat_loc argument is interpreted using macros defined in the <sys/wait.h> header file. The macros use an argument stat_val, which is the integer value *stat_loc. When wait() returns with a valid process ID (pid), the macros analyze the status referenced by the *stat_loc argument. The macros are as follows:

WIFEXITED(stat_val)

Evaluates to a nonzero value if the status was returned for a child process that ended normally.

WEXITSTATUS(stat_val)

If the value of the WIFEXITED(stat_val) is nonzero, evaluates to the low-order 8 bits of the status argument that the child process passed to exit(), or to the value the child process returned from main().

WIFSIGNALED(stat_val)

Evaluates to a nonzero value if the status was returned for a child process that ended because of the receipt of a terminating signal that was not caught by the process.

WTERMSIG(stat_val)

If the value of WIFSIGNALED(stat_val) is nonzero, evaluates to the number of the signal that caused the child process to end.

WIFStopPED(stat_val)

Evaluates to a nonzero value if the status was returned for a child process that is currently stopped.

WStopSIG(stat_val)

If the value of the WIFStopPED(stat_val) is nonzero, evaluates to the number of the signal that caused the child process to stop.

WIFEXCEPTION(stat_val)

Evaluates to a nonzero value if the status was returned for a child process that ended because of an error condition.

Note: The WIFEXCEPTION macro is unique to the IBM^® i implementation. See Usage Notes.

WEXCEPTNUMBER(stat_val)

If the value of the WIFEXCEPTION(stat_val) is nonzero, this macro evaluates to the last IBM i exception number related to the child process.

Note: The WEXCEPTNUMBER macro is unique to the IBM i implementation. See Usage Notes.

Authorities

None.

Return Value

value

wait() was successful. The value returned indicates the process ID of the child process whose status information *stat_loc.

-1

wait() was not successful. The errno value is set to indicate the error.

Error Conditions

If wait() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[ECHILD]

Calling process has no remaining child processes on which wait operation can be performed.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINTR]

Interrupted function call.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Usage Notes

The WIFEXCEPTION macro is unique to the IBM i implementation. This macro can be used to determine whether the child process has ended because of an exception. When WIFEXCEPTION returns a nonzero value, the value returned by the WEXCEPTNUMBER macro corresponds to the last IBM i exception number related to the child process.
When a child process ends because of an exception, the ILE C run-time library catches and handles the original exception. The value returned by WEXCEPTNUMBER indicates that the exception was CEE9901. This is a common exception ID. If you want to determine the original exception that ended the child process, look at the job log for the child process.
If the child process is ended by any of the following:
- ENDJOB OPTION(*IMMED)
- ENDJOB OPTION(*CNTRLD) and delay time was reached
- Debugging a child process (environment variable QIBM_CHILD_JOB_SNDINQMSG is used) and the resulting CPAA980 *INQUIRY message is replied to using C,
then the parent's wait() stat_loc value indicates that:
- WIFEXCEPTION(stat_val) evaluates to a nonzero value
- WEXCEPTNUMBER(stat_val) evaluates to zero.

Related Information

The <sys/types.h> file (see Header Files for UNIX^®-Type Functions)
The <sys/wait.h> file (see Header Files for UNIX-Type Functions)
spawn()--Spawn Process
spawnp()--Spawn Process with Path
waitpid()--Wait for Specific Child Process
Signal Concepts

Example

For an example of using this function, see Example: Using process-related APIs.

API introduced: V3R6

[ Back to top | UNIX-Type APIs | APIs by category ]