w_getpsent() — Get process data
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
z/OS® UNIX | both |
Format
#include <sys/ps.h>
int w_getpsent(int token, W_PSPROC *buffptr, size_t length);
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 1 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 | ps_starttime | Starting time |
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: 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_usertime reports 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_systime reports 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.
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