Component-Specific interfaces

Edit online

Component-specific interfaces report metrics related to individual components on a system (such as a processor, disk, network interface, or paging space).

All of the following AIX® interfaces use the naming convention perfstat_subsystem, and use a common signature:

Item	Descriptor
perfstat_cpu	Retrieves individual processor usage metrics Note: This interface returns global values when called by an application running inside WPAR.
perfstat_disk	Retrieves individual disk usage metrics Note: This interface does not return any data when called by an application running inside WPAR
perfstat_diskpath	Retrieves individual disk path metrics Note: This interface does not return any data when called by an application running inside WPAR
perfstat_diskadapter	Retrieves individual disk adapter metrics Note: This interface does not return any data when called by an application running inside WPAR.
perfstat_netinterface	Retrieves individual network interfaces metrics Note: This interface returns WPAR-specific data when called by an application running inside WPAR.
perfstat_protocol	Retrieves individual network protocol-related metrics Note: This interface returns WPAR-specific data when called by an application running inside WPAR.
perfstat_netbuffer	Retrieves individual network buffer allocation metrics Note: This interface returns WPAR-specific data when called by an application running inside WPAR.
perfstat_pagingspace	Retrieves individual paging space metrics Note: This interface does not return any data when called by an application running inside WPAR.
perfstat_memory_page	Retrieves multiple page size usage metrics Note: This interface returns global values when it is called by an application running inside a WPAR.
perfstat_tape	Retrieves individual tape usage metrics Note: This interface does not return any data when it is called by an application running inside a WPAR.
perfstat_logicalvolume	Retrieves individual logical volume usage metrics Note: This interface does not return any data when called it is by an application running inside a WPAR.
perfstat_volumegroup	Retrieves individual volume group usage metrics Note: This interface does not return any data when it is called by an application running inside a WPAR.
perfstat_hfistat	Retrieves individual host fabric interface (HFI) statistics.
perfstat_hfistat_window	Retrieves individual window-based HFI statistics.
perfstat_cpu_util	Calculates CPU utilization
perfstat_process	Retrieves process utilization metrics
perfstat_process_util	Calculates process utilization metrics
perfstat_thread	Retrieves kernel thread utilization metrics
perfstat_thread_util	Calculates kernel thread utilization metrics

The common signature used by all the component interfaces except perfstat_memory_page and perfstat_hfistat_window is as follows:

int perfstat_subsystem(perfstat_id *name,
                       perfstat_subsystem_t * userbuff,
                       int sizeof_struct,
                       int desired_number);

The perfstat_memory_page uses the following signature:

int perfstat_memory_page(perfstat_psize_t *psize ,
			  perfstat_subsystem_t * userbuff,
			  int sizeof_struct,
			  int desired_number);

The perfstat_hfistat_window uses the following signature:

int perfstat_hfistat_window(perfstat_id_window_t *name,
			      perfstat_hfistat_window_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_t name**	Enter the name of the first component (for example hdisk2 for perfstat_disk()) to obtain the statistics. A structure containing a char * field is used instead of directly passing a char * argument to the function to avoid allocation errors and to prevent the user from giving a constant string as parameter. To start from the first component of a subsystem, set the char* field of the name parameter to "" (empty string). You can use macros such as FIRST_SUBSYSTEM (for example, FIRST_CPU) defined in the libperfstat.h file.
*perfstat_id_window_t name**	Enter the Host Fabric Interface name (for example, hfi0 or hfi1 or FIRST_HFI) in the "name->name" field, and the HFI window number in "name->windowid" field.
*perfstat_subsystem_t userbuff**	Specifies a pointer to a memory area with enough space for the returned structures.
int sizeof_struct	Set the parameter to sizeof(perfstat_subsystem_t).
int desired_number	Specifies the number of structures of type perfstat_subsystem_t to return in userbuff.

The return value is -1 in case of error. Otherwise, the number of structures copied is returned. The field name is either set to NULL or to the name of the next structure available.

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

To retrieve all structures of a given type, find the number of structures and allocate the required memory to hold the structures. You must then call the appropriate API to retrieve all structures in one call. Another method is to allocate a fixed set of structures and repeatedly call the API to get the next set of structures, each time passing the name returned by the previous call. Start the process with the name set to "" or FIRST_SUBSYSTEM, and repeat the process.

Minimizing the number of API calls, and the number of system calls, leads to more efficient code, so the two-call approach is preferred. Some of the examples shown in the following sections illustrate the API usage using the two-call approach. The two-call approach causes large amount of memory allocation, the multiple-call approach is sometimes used, and is illustrated in the following examples.

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