waitpid()--Wait for Specific Child Process
Syntax
#include <sys/types.h> #include <sys/wait.h> pid_t waitpid(pid_t pid, int *stat_loc, int options);
Service Program Name: QP0ZSPWN
Default Public Authority: *USE
Threadsafe: Yes
The waitpid() function allows the calling thread to obtain status information for one of its child processes. The calling thread suspends processing until status information is available for the specified child process, if the options argument is 0. A suspended waitpid() 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 waitpid() is successful, status information about how the child process ended (for example, whether the process ended normally) is stored in the location specified by stat_loc.
The waitpid() function behaves the same as wait() if the pid argument is (pid_t)-1 and the options argument is 0.
Parameters
- pid
- (Input) A process ID or a process group ID to identify the child process or
processes on which waitpid() should operate.
- stat_loc
- (Input) Pointer to an area where status information about how the child
process ended is to be placed.
- options
- (Input) An integer field containing flags that define how waitpid() should operate.
The pid argument specifies a set of child processes for which status is requested. The waitpid() function only returns the status of a child process from the following set:
- If pid is equal to (pid_t)-1, status is requested for any child
process. In this respect, waitpid() is then equivalent to
wait().
- If pid is greater than (pid_t)0, it specifies the process ID of a
single child process for which status is requested.
- If pid is (pid_t)0, status is requested for any child process
whose process group ID is equal to that of the calling thread.
- If pid is less than (pid_t)-1, status is requested for any child process whose process group ID is equal to the absolute value of pid.
The status referenced by the 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 pointed to by stat_loc. When waitpid() 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. |
The options argument can be set to either 0 or WNOHANG. WNOHANG indicates that the waitpid() function should not suspend processing of the calling thread if status is not immediately available for one of the child processes specified by pid. If WNOHANG is specified and no child process is immediately available, waitpid() returns 0.
Authorities
None.
Return Value
value | waitpid() was successful. The value returned indicates the process ID of the child process whose status information was recorded in the storage pointed to by stat_loc. |
0 | WNOHANG was specified on the options parameter, but no child process was immediately available. |
-1 | waitpid() was not successful. The errno value is set to indicate the error. |
Error Conditions
If waitpid() 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.
- [EINVAL]
The value specified for the argument is not correct.
A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.
An argument value is not valid, out of range, or NULL.
- [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.
- [EOPNOTSUPP]
Operation not supported.
The operation, though supported in general, is not supported for the requested object or the requested arguments.
- [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, or
- 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, and
- 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
- wait()--Wait for Child Process to End
- Signal Concepts
Example
For an example of using this function, see Example: Using process-related APIs.
API introduced: V3R6