waitpid()--Wait for Specific Child Process

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

 pid_t waitpid(pid_t pid, int *stat_loc, int options);   

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:

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

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

1. 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.
   
   
2. 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.
   
   
3. 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.

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