w_getpsent(), w_getpsent64() — Get process data
Standards
| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
| z/OS® UNIX | both |
Format
w_getpsent:#include <sys/ps.h>
int w_getpsent(int token, W_PSPROC *buffptr, size_t length);#define _LARGE_TIME_API
#include <sys/ps.h>
int w_getpsent64(int token, W_PSPROC64 *buffptr, size_t length);Compile requirement: Use of the w_getpsent64 function requires
the long long data type. For more information on how to make the long
long data type available, see z/OS XL C/C++ Language Reference.
General description
Provides information about the status of any process that the calling process has access to.
- token
- A relative number that identifies the relative position of a process in the system. Zero
represents the first process in the system. On the first call to
w_getpsent(), pass the token 0; the function then returns the token that identifies the next process to which the caller has access. Use that token on the next call. - buffptr
- The address of the buffer where the data is to be stored.
- length
- The length of the buffer.
The data returned is described in the
ps.h header file. See Table 2 for the format of the structure stored in the buffer.
| Variable Type | Variable Name | General Description |
|---|---|---|
| unsigned int | ps_state | Process state |
| pid_t | ps_pid | Process ID |
| pid_t | ps_ppid | Parent ID |
| pid_t | ps_sid | Session ID (leader) |
| pid_t | ps_pgpid | Process group ID |
| pid_t | ps_fgpid | Foreground process group ID |
| uid_t | ps_euid | Effective user ID |
| uid_t | ps_ruid | Real user ID |
| uid_t | ps_suid | Saved set user ID |
| gid_t | ps_egid | Effective group ID |
| gid_t | ps_rgid | Real group ID |
| gid_t | ps_sgid | Saved set group ID |
| long | ps_size | Total size |
| time_t 1 | ps_starttime | Starting time |
| time64_t 2 | ||
| clock_t | ps_usertime | User CPU time |
| clock_t | ps_systime | System CPU time |
| int | ps_conttylen | Length of ConTTY |
| char | *ps_conttyptr | Controlling terminal |
| int | ps_pathlen | Length of arg0 |
| char | *ps_pathptr | File name |
| int | ps_cmdlen | Length of command |
| char | *ps_cmdptr | Command and arguments |
|
Note:
|
||
Note: The
ps_cmdlen and ps_cmdptr elements of W_PSPROC identify
the length and location where w_getpsent() is to return the command and arguments
used to start the process. As of z/OS V1R11, the maximum
length in bytes, including the null terminator, that can be returned is defined by PS_CMDBLEN_LONG.
The actual maximum length of the command and arguments returned is PS_CMDBLEN_LONG minus the length
of the path. Prior to z/OS V1R11, the maximum length in
bytes, including the null terminator, that can be returned is defined by PS_CMDBLEN. The actual
maximum length of the command and arguments returned can be less than PS_CMDBLEN and depends on the
number of arguments. The system will truncate the command and arguments as needed to allow for the
null terminator. Both PS_CMDBLEN_LONG and PS_CMDBLEN are defined in
<sys/ps.h>.Usage notes
ps_usertimereports the user's CPU time consumed for the address space the process is running within. When only one process is running in the address space, this CPU time represents the accumulated user CPU time for that process. When more than one process is running in an address space, the information returned is actually the accumulated CPU time consumed by the address space. It is the sum of the CPU time used by all of the work running in that address space not including the system time.ps_systimereports the system's CPU time consumed for the address space the process is running within. When only one process is running in the address space, this time represents the accumulated system CPU time for that process. However, when more than one process is running in an address space, the information returned is actually the accumulated system CPU time consumed by all of the work running in the address space.
The w_getpsent64() function behaves exactly like
w_getpsent() except it uses struct w_psproc64 instead of struct
w_psproc to support time beyond 03:14:07 UTC on January 19, 2038.
Returned value
If successful, w_getpsent() returns the process token for the next process for
which the caller has access. For the last active process to which the user has access,
w_getpsent() returns 0, indicating there are no more processes to be accessed.
If unsuccessful,
w_getpsent() returns -1 and sets errno to one
of the following values: - Error Code
- Description
- EINVAL
- An incorrect process token or NULL buffer address was specified.
- E2BIG
- An insufficient buffer length was provided.
- ESRCH
- No process can be accessed by the active user.
Example
CELEBW33
/* CELEBW33
This example provides status information, using wgetpsent().
*/
#define _OPEN_SYS
#include <stdlib.h>
#include <stdio.h>
#include <sys/ps.h>
#include <sys/types.h>
#include <pwd.h>
#include <time.h>
#include <string.h>
int main(void) {
int token;
W_PSPROC buf;
struct passwd *pw;
token = 0;
memset(&buf, 0x00, sizeof(buf));
buf.ps_conttyptr = (char *) malloc(buf.ps_conttylen = PS_CONTTYBLEN);
buf.ps_pathptr = (char *) malloc(buf.ps_pathlen = PS_PATHBLEN);
buf.ps_cmdptr = (char *) malloc(buf.ps_cmdlen = PS_CMDBLEN_LONG);
if ((buf.ps_conttyptr == NULL) ||
(buf.ps_pathptr == NULL) ||
(buf.ps_cmdptr == NULL))
perror("buffer allocation error");
else do {
if ((token = w_getpsent(token, &buf, sizeof(buf))) == -1)
perror("w_getpsent() error");
else if (token > 0)
if ((pw = getpwuid(buf.ps_ruid)) == NULL)
perror("getpwuid() error");
else printf("token %d: pid %10d, user %8s, started %s", token,
(int) buf.ps_pid, pw->pw_name,
ctime(&buf.ps_starttime));
} while (token > 0);
return 0;
}
Output:
token 2: pid 131074, user MVSUSR1, started Fri Jun 16 08:09:17 2006
token 3: pid 65539, user MVSUSR1, started Fri Jun 16 08:09:41 2006
token 6: pid 589830, user MVSUSR1, started Fri Jun 16 10:29:17 2006
token 7: pid 851975, user MVSUSR1, started Fri Jun 16 10:30:04 2006