Qp0wChkChld()--Check Status for Child Processes

Syntax

 #include <qp0wpid.h>

 int Qp0wChkChld(QP0W_PID_Entries_T *chldinfo);

  Service Program Name: QP0WPID

  Default Public Authority: *USE

  Threadsafe: Yes

The Qp0wChkChld() function returns the status and process table entry information for the child processes of the specified process ID.

Parameters

*chldinfo: (I/O) A pointer to the QP0W_PID_Entry_T structure. This structure contains the process table entry information for the children processes identified by pid.

The structure QP0W_PID_Entry_T is defined in the <qp0wpid.h> header file as follows:

typedef struct QP0W_PID_Entries_T {
    int          entries_prov;
    int          entries_could;
    int          entries_return;
    pid_t        pid;
    QP0W_PID_Data_T  entry[1];
} QP0W_PID_Entries_T;

The members of the QP0W_PID_Entry_T structure are as follows:

int entries_prov;

(Input) The number of entries of type QP0W_PID_Data_T for which that the caller has allocated storage to contain the status and process table entry information.

int entries_could;

(Output) The number of entries of type QP0W_PID_Data_T that could be returned. If the entries_could value exceeds the entries_prov value, the Qp0wChkChld() function should be called again with sufficient storage to contain the number of entries returned in entries_could (entries_prov must be greater than or equal to entries_could).

int entries_return;

(Output) The number of entries of type QP0W_PID_Data_T that were returned. If the entries_return value is less than the entries_prov value, the content of the excess number of entries provided is unchanged by Qp0wChkChld().

pid_t pid;

(Input) The process ID of the process for which information about its child processes is to be returned.

QP0W_PID_Data_T entry[1];

(Output) The process table information for child processes. There is one QP0W_PID_Data_T structure entry for each child process, limited by the value of entries_prov.

The structure QP0W_PID_Data_T is defined in the <qp0wpid.h> header file as follows:

typedef struct QP0W_PID_Data_T {
    pid_t         pid;
    pid_t         ppid;
    pid_t         pgrp;
    int           status;
    unsigned int  exit_status;
} QP0W_PID_Data_T;

The members of the QP0W_PID_Data_T structure are as follows:

pid_t pid;

The process ID of the process.

pid_t ppid;

The process ID of the parent process. If ppid has a value of binary 1, there is no parent process associated with the process.

pid_t pgrp;

The process group ID of the process.

int status;

A collection of flag bits that describe the current state of the process. The following flag bits can be set in status:

QP0W_PID_TERMINATED

The process has ended.

QP0W_PID_StopPED

The process has been stopped by a signal.

QP0W_PID_CHILDWAIT

The process is waiting for a child process to be ended or stopped by a signal.

QP0W_PID_SIGNALStop

The process has requested that the SIGCHLD signal be generated for the process when one of its child processes has been stopped by a signal.

unsigned int exit_status;

Exit status of the process. This member only has meaning if the status has been set to QP0W_PID_TERMINATED. See the wait() function for a description of the exit status for a process.

Authorities

The process calling Qp0wChkChld() must have the appropriate authority to the process being examined. A process is allowed to examine the process table information for a process if at least one of the following conditions is true:

The process is calling Qp0wChkChld() for its own process.
The process has *JOBCTL special authority defined in the process user profile or in a current adopted user profile.
The process is the parent of the process (the process being examined has a parent process ID equal to the process ID of the process calling Qp0wChkChld()).
The real or effective user ID of the process matches the real or effective user ID of the process calling Qp0wChkChld().

Return Value

Qp0wChkChld() was successful.

value

Qp0wChkChld() was not successful. The value returned indicates one of the following errors. Under some conditions, value could indicate an error other than those listed here.

[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.

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

[ESRCH]

No item could be found that matches the specified value.

Usage Notes

The Qp0wChkChld() function provides an IBM^® i-specific way to obtain the process table information for the child processes of the specified process.

Related Information

The <qp0wpid.h> file (see Header Files for UNIX^®-Type Functions)
The <signal.h> file (see Header Files for UNIX-Type Functions)
getpgrp()--Get Process Group ID
getpid()--Get Process ID
getppid()--Get Process ID of Parent Process
Qp0wGetPgrp()--Get Process Group ID
Qp0wGetPid()--Get Process ID
Qp0wGetPPid()--Get Process ID of Parent Process
wait()--Wait for Child Process to End

API introduced: V3R6

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