Technical Reference: Base Operating System and Extensions, Volume 1

getprocs Subroutine

Purpose

Gets process table entries.

Library

Standard C library (libc.a)

Syntax

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

Description

The getprocs subroutine returns information about processes, including process table information defined by the procsinfo structure, and information about the per-process file descriptors defined by the fdsinfo structure.

The getprocs subroutine retrieves up to Count process table entries, starting with the process table entry corresponding to the process identifier indicated by IndexPointer, and places them in the array of procsinfo structures indicated by the ProcessBuffer parameter. File descriptor information corresponding to the retrieved processes are stored in the array of fdsinfo structures indicated by the FileBuffer parameter.

On return, the process identifier referenced by IndexPointer is updated to indicate the next process table entry to be retrieved. The getprocs subroutine returns the number of process table entries retrieved.

The getprocs subroutine is normally called repeatedly in a loop, starting with a process identifier of zero, and looping until the return value is less than Count, indicating that there are no more entries to retrieve.

When used in 32-bit mode, limits larger than can be represented in 32 bits are truncated to RLIM_INFINITY. Large rusage and other values are truncated to INT_MAX. Alternatively, the struct procsinfo64 and sizeof (struct procsinfo64) can be used by 32-bit getprocs to return full 64-bit process information. Note that the procsinfo structure not only increases certain procsinfo fields from 32 to 64 bits, but that it contains additional information not present in procsinfo. The struct procsinfo64 contains the same data as struct procsinfo when compiled in a 64-bit program.

In AIX 5.1 and later, 64-bit applications are required to use getprocs64() and procentry64. Note that struct procentry64 contains the same information as struct procsinfo64, with the addition of support for the 64-bit time_t and dev_t, and the 256-bit sigset_t. The procentry64 structure also contains a new version of struct ucred (struct ucred_ext) and a new, expanded struct rusage (struct trusage64) as described in <sys/cred.h> and <sys/resource.h> respectively. Application developers are also encouraged to use getprocs64() in 32-bit applications to obtain 64-bit process information as this interface provides the new, larger types. The getprocs() interface will still be supported for 32-bit applications using struct procsinfo or struct procsinfo64 but will not be available to 64-bit applications.

Parameters

ProcessBuffer

Specifies the starting address of an array of procsinfo, procsinfo64, or procentry64 structures to be filled in with process table entries. If a value of NULL is passed for this parameter, the getprocs subroutine scans the process table and sets return values as normal, but no process entries are retrieved.

Note

The ProcessBuffer parameter of getprocs subroutine contains two struct rusage fields named pi_ru and pi_cru. Each of these fields contains two struct timeval fields named ru_utime and ru_stime. The tv_usec field in both of the struct timeval contain nanoseconds instead of microseconds. These values cone from the struct user fields named U_ru and U_cru.

ProcessSize

Specifies the size of a single procsinfo, procsinfo64, or procentry64 structure.

FileBuffer

Specifies the starting address of an array of fdsinfo, or fdsinfo64 structures to be filled in with per-process file descriptor information. If a value of NULL is passed for this parameter, the getprocs subroutine scans the process table and sets return values as normal, but no file descriptor entries are retrieved.

FileSize

Specifies the size of a single fdsinfo, or fdsinfo64 structure.

IndexPointer

Specifies the address of a process identifier which indicates the required process table entry. A process identifier of zero selects the first entry in the table. The process identifier is updated to indicate the next entry to be retrieved.

Note

The IndexPointer does not have to correspond to an existing process, and may in fact correspond to a different process than the one you expect. There is no guarantee that the process slot pointed to by IndexPointer will contain the same process between successive calls to getprocs() or getprocs64().

Count

Specifies the number of process table entries requested.

Return Values

If successful, the getprocs subroutine returns the number of process table entries retrieved; if this is less than the number requested, the end of the process table has been reached. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

The getprocs subroutine does not succeed if the following are true:

Related Information

The getpid (getpid, getpgrp, or getppid Subroutine), getpgrp (getpid, getpgrp, or getppid Subroutine), or getppid (getpid, getpgrp, or getppid Subroutine) subroutines, the getthrds (getthrds Subroutine) subroutine

The ps command.