perfstat_cpu_total Subroutine
Purpose
Retrieves global processor usage statistics.
Library
Perfstat library (libperfstat.a)
Syntax
#include <libperfstat.h>perfstat_id_t *name;
perfstat_cpu_total_t *userbuff;
size_t sizeof_struct;
int desired_number;
Description
The perfstat_cpu_total subroutine returns global processor usage statistics in a perfstat_cpu_total_t structure.
To get statistics that are global to the whole system, the name parameter must be set to NULL, the userbuff parameter must be allocated, and the desired_number parameter must be set to 1.
The perfstat_cpu_total subroutine retrieves information from the ODM database. This information is automatically cached into a dictionary which is assumed to be frozen once loaded. The perfstat_reset subroutine must be called to flush the dictionary whenever the machine configuration has changed.
The SPLPAR environments virtualize physical processors. To help accurately measure the resource used in a virtualized environment, the POWER5 family of processors implements a register PURR (Processor Utilization Resource Register) for each core. The PURR is a 64-bit counter with the same units as the timebase register and tracks the real physical processor resource used on a per-thread or per-partition level. The PURR registers are not compatible with previous global counters (user, system, idle and wait fields) returned by the perfstat_cpu and the perfstat_cpu_total subroutines. All data consumers requiring processor use must be modified to support PURR-based computations as shown in the example for the perfstat_partition_total interface under Perfstat API programming.
This subroutine returns only global processor statistics inside a workload partition (WPAR).
Parameters
| Item | Description |
|---|---|
| name | Must set to NULL. |
| userbuff | Points to the memory area that is to be filled with the perfstat_cpu_total_t structure. |
| sizeof_struct | Specifies the size of the perfstat_cpu_total_t structure: sizeof(perfstat_cpu_total_t). |
| desired_number | Must set to 1. |
Return Values
Upon successful completion, the number of structures filled is returned. If unsuccessful, a value of -1 is returned and the errno global variable is set.
Error Codes
The perfstat_cpu_total subroutine is unsuccessful if one of the following is true:
| Item | Description |
|---|---|
| EINVAL | One of the parameters is not valid. |
| EFAULT | Insufficient memory. |
| ENOMEM | The string default length is too short. |
Files
The libperfstat.h file defines standard macros, data types, and subroutines.