getprocs Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

getprocs Subroutine

Purpose

Gets process table entries.

Library

Standard C library (libc.a)

Syntax

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

int 
getprocs (ProcessBuffer, ProcessSize, FileBuffer, FileSize, IndexPointer, Count)
struct procsinfo *ProcessBuffer;
or struct procsinfo64 *ProcessBuffer;
int ProcessSize;
struct fdsinfo *FileBuffer;
int FileSize;
pid_t *IndexPointer;
int Count;

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.

Note: The process table may change while the getprocs subroutine is accessing it. Returned entries will always be consistent, but since processes can be created or destroyed while the getprocs subroutine is running, there is no guarantee that retrieved entries will still exist, or that all existing processes have been retrieved.

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 ina 64-bit program.

When used in 64-bit mode, the struct procsinfo contains 64-bit rusage and rlimit structures.

Parameters

ProcessBuffer

Specifies the starting address of an array of procsinfo or procsinfo64 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 or procsinfo64 structure.
FileBuffer	Specifies the starting address of an array of fdsinfo 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 structure.
IndexPointer	Specifies the address of a process identifier which indicates the required process table entry (this does not have to correspond to an existing process). 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.
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:

EINVAL	The ProcessSize or FileSize parameters are invalid, or the IndexPointer parameter does not point to a valid process identifier, or the Count parameter is not greater than zero.
EFAULT	The copy operation to one of the buffers was not successful.

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The getpid, getpgrp, or getppid subroutines, the getthrds subroutine

The ps command.