WPAR Interfaces

Edit online
The following are two types of WPAR interfaces:
  • The metrics related to a set of components for a WPAR (such as processors, or memory).
  • The specific metrics related to individual components on a WPAR (such as a processor, network interface, or memory page).
All of the following WPAR interfaces use the naming convention perfstat_subsystem_total_wpar, and use a common signature:
Item Descriptor
perfstat_cpu_total_wpar Retrieves WPAR processor summary usage metrics
perfstat_memory_total_wpar Retrieves WPAR memory summary usage metrics
perfstat_wpar_total Retrieves WPAR information metrics
perfstat_memory_page_wpar Retrieves WPAR memory page usage metrics
The signature used by the subsystem_total interfaces, except for perfstat_memory_page_wpar, is as follows: 
int perfstat_subsystem_total_wpar(perfstat_id_wpar_t *name,
                             perfstat_subsystem_total_t *userbuff,
                             int sizeof_struct,
                             int desired_number);
The signature used by the perfstat_memory_page_wpar interface is as follows: 
int perfstat_memory_page_wpar(perfstat_id_wpar_t *name,
			      perfstat_psize_t *psize,			
                             perfstat_subsystem_total_t *userbuff,
                             int sizeof_struct,
                             int desired_number);
The usage of the parameters for all of the interfaces is as follows:
Item Descriptor
perfstat_id_wpar_t *name The WPAR ID or WPAR name for which the metrics must be retrieved.
Note: When called inside of a WPAR environment, the name must be NULL.
perfstat_subsystem_total_t *userbuff A memory area with enough space for the returned structure.
int sizeof_struct The size of the perfstat_memory_total_wpar_t structure.
int desired_number The number of different page size statistics to be collected.

The number of structures copied and returned without errors use the return value of 1. If there are errors, the return value is -1.

An exception to this scheme is perfstat_wpar_total. For this function, when name=NULL, userbuff=NULL and desired_number=0, the total number of perfstat_wpar_total_t structures available is returned.

To retrieve all perfstat_wpar_total_t structures, select one of the following methods:
  • Determine the number of structures and allocate the required memory to hold all structure at one time. You can then call the appropriate API to retrieve all structures using one call.
  • Allocate a fixed set of structures and repeatedly call the API to get the next number of structures, each time passing the name returned by the previous call. Start the process by using one of the following queries:
    • wparname set to ""
    • FIRST_WPARNAME
    • wpar_id set to -1
    • FIRST_WPARID
    Repeat the process until the wparname is returned equal to “ or the wpar_id is returned equal to -1.

The perfstat_id_wpar_total interface returns a set of structures of type perfstat_id_wpar_total_t, which is defined in the libperfstat.h file. Selected fields from the perfstat_id_wpar_total_t structure include:

Item Descriptor
spec Select WPAR ID, WPAR Name, or the RSET Handle from the union
wpar_id Specifies the WPAR ID
wparname Specifies the WPAR Name
rset Specifies the RSET Handle of the rset associated with the WPAR
name Reserved for future use, must be NULL

The following sections provide examples of the type of data returned and code using each of the interfaces.