Qp0wChkPgrp()--Check Status for Process Group

Syntax

 #include <qp0wpid.h>

 int Qp0wChkPgrp(QP0W_PID_Entries_T *mbrinfo);

  Service Program Name: QP0WPID

  Default Public Authority: *USE

  Threadsafe: Yes

The Qp0wChkPgrp() function returns the status and process table entry information for the processes that are members of the process group identified by pid in the structure QP0W_PID_Entry_T.

Parameters

*mbrinfo: (I/O) A pointer to the QP0W_PID_Entry_T structure. This structure contains the process table entry information for the processes that are members of the process group 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 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 Qp0wChkPgrp() 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 Qp0wChkPgrp().
pid_t pid;	(Input) The process group ID of the group of processes for which the process information is to be returned.
QP0W_PID_Data_T entry[1];	(Output) The process table information for the process group members. There is one `QP0W_PID_Data_T` structure entry for each process group member, limited by the value of `entries_prov`.

The structure QP0W_PID_Data_T is defined in the <qp0wpid.h> 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 was 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 is stopped by a signal.

unsigned int exit_status;

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

Authorities

The process calling Qp0wChkPgrp() must have the appropriate authority to the processes 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 Qp0wChkPgrp() 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 Qp0wChkPgrp()).
The real or effective user ID of the process matches the real or effective user ID of the process calling Qp0wChkPgrp().

Return Value

Qp0wChkPgrp() was successful.

value

Qp0wChkPgrp() 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 Qp0wChkPgrp() function provides an i5/OS-specific way to obtain the process table information for the members of a process group.

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

Top | UNIX-Type APIs | APIs by category