vmgetinfo Subroutine

Edit online

Purpose

Retrieves Virtual Memory Manager (VMM) information.

Library

Standard C Library (libc.a)

Syntax

#include <sys/vminfo.h>

int vmgetinfo(void *out, int command, int arg)

Description

The vmgetinfo subroutine returns the current value of certain VMM parameters.

Parameters

arg

Additional parameter which depends on the command parameter.

command

Specifies which information is returned. The command parameter has the following valid values:

VMINFO: Returns the content of the vminfo structure (described in the sys/vminfo.h file). The out parameter points to a vminfo structure and the arg parameter is the size of the vminfo structure. The smaller value of the arg parameter and sizeof (struct vminfo) is copied.
VMINFO64: Returns the contents of the vminfo64 structure (described in the sys/vminfo.h file). The out parameter points to a vminfo64 structure and the arg parameter is the size of the vminfo64 structure. The smaller value of the arg parameter and sizeof (struct vminfo64) is copied.
VMINFO_ABRIDGED: Returns the content of the vminfo structure (described in the sys/vminfo.h file). The VMINFO_ABRIDGED command updates only the non-time consuming statistics, therefore you must use the VMINFO_ABRIDGED command rather than the VMINFO command in performance-critical applications. The out parameter points to a vminfo structure and the arg parameter is the size of the vminfo structure. The smaller value between the arg and sizeof (struct vminfo) parameters is copied.
VM_PAGE_INFO: Returns the size, in bytes, of the page backing the address specified in the addr field of the vm_page_info structure (described in sys/vminfo.h). The out parameter points to a vm_page_info structure with the addr field set to the desired address of which to query the page size. The arg parameter is the size of the vm_page_info structure.
VM_NEW_HEAP_PSIZE: Sets a new preferred page size for future sbreak allocations for the calling process's private data heap. This page size setting is advisory. The out parameter is a pointer to a psize_t structure that contains the preferred page size, in bytes, to use to back any future sbreak allocations by the calling process. Presently, only 16M (0x1000000) and 4K (0x1000) are supported. The arg parameter is that of the sizeof(psize_t).

VM_SRAD_MEMINFO

Reports memory statistics about an Scheduler Resource Allocation Domain (SRAD). The arg parameter must contain the SRAD ID to be queried. The out parameter must be the pointer to the vm_srad_meminfo structure whose first field, vmsrad_in_size, must contain the size of the structure.

The output of this command is stored in the following fields of the vm_srad_meminfo structure:

vmsrad_out_size: The number of bytes returned in the buffer.
vmsrad_total_pg: The total number of bytes of pageable memory contained in the SRAD. This value excludes the memory that is permanently reserved for low-level memory management.
Note: This field was formerly known as vmsrad_total.
vmsrad_free_pg: The amount of free pageable memory displayed in bytes in the SRAD.
Note: This field was formerly known as vmsrad_free.
vmsrad_total_nonpg: The total number of bytes of non-pageable memory contained in the SRAD.
vmsrad_free_nonpg: The amount of free non-pageable memory displayed in bytes in the SRAD.
vmsrad_file: The number of bytes occupied by files.
vmsrad_aff_priv_pct: This is the maximum percentage of private memory that is allocated from the specified SRAD by the default page placement algorithm based on the tunable enhanced_affinity_private, the SRAD's computational usage, and the SRAD's memory-to-CPU capacity ratio.
vmsrad_aff_avail_pct: The percentage of available computational memory that is remaining in the vmpool parameter based on the tunable enhanced_affinity_vmpool_limit parameter and the average system computational percentage.

The total number of computational memory bytes available in SRAD is the value in the vmsrad_total parameter, minus the sum of the values in the vmsrad_free and vmsrad_file parameters.

VM_STAGGER_DATA

Staggers the calling process's current sbreak value by a cumulative per-MCM stagger value. This stagger value must be set through the vmo option data_stagger_interval. The value of the out parameter is NULL and that of the arg parameter is 0.

IPC_LIMITS

Returns the content of the ipc_limits struct (described in the sys/vminfo.h file). The out parameter points to an ipc_limits structure and arg is the size of this structure. The smaller value of the arg and sizeof (struct ipc_limits) parameters is copied. The ipc_limits struct contains the inter-process communication (IPC) limits for the system.

VMINFO_GETPSIZES

Reports a system's supported page sizes. When the value of arg is set to 0, the out parameter is ignored, and the number of supported page sizes is returned. When the value of arg is greater than 0, the arg parameter value indicates the number of page sizes to report, and the out parameter must be a pointer to an array with the number of psize_t structures specified by the arg parameter. The array of the psize_t structure is updated with the system's supported page sizes in sorted order starting with the smallest supported page size. The number of array entries updated with page sizes is returned.

VMINFO_PSIZE

Reports detailed VMM statistics for a specified page size. The out parameter points to a vminfo_psize structure with the psize field set to a page size, in bytes, for which to return statistics. Set the value of the arg parameter to the size of the vminfo_psize structure.

VM_PROC_PF_INFO or VM_THREAD_PF_INFO

Returns the time taken for processing page faults caused by a process or thread. The total number of page faults is also returned. The arg parameter must contain the size of the vm_pf_info structure and the out parameter must contain a pointer to the vm_pf_info structure. The first three fields of the vm_pf_info structure (version, flags, and id) are input fields that are populated by the calling process. The output of this command is stored by vmgetinfo in the output fields of the vm_pf_info structure. The vm_pf_info structure is defined in sys/vminfo.h as follows:

struct vm_pf_info
{
       /* INPUT */
       uint32_t version;
       uint32_t flags; /* currently unused */
       id64_t id; /* pid or tid */
       /* OUTPUT */
       struct timestruc64_t text_major_pf_time;
       struct timestruc64_t data_major_pf_time;
       struct timestruc64_t kernel_major_pf_time;
       struct timestruc64_t text_minor_pf_time;
       struct timestruc64_t data_minor_pf_time;
       struct timestruc64_t kernel_minor_pf_time;
       uint64_t minor_pf_count;
       uint64_t major_pf_count;
}

The fields of the vm_pf_info structure follows:

version: Must be set to the VM_PF_INFO_VER value (defined in the sys/vminfo.h header file).
flags: Unused. Must be set to 0.
id: Must contain a valid thread or a process identifier(depending on the command), or a value of -1. If the value is -1, the information about the calling thread or the process is requested.

out

Specifies the address where VMM information is returned.

Return Values

For all commands other than VMINFO_GETPSIZES, 0 is returned if the vmgetinfo subroutine is successful. When VMINFO_GETPSIZES is specified as the command, a number of page sizes is returned if the vmgetinfo subroutine is successful.

If the vmgetinfo subroutine is unsuccessful, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

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

EFAULT: The copy operation to the buffer was not successful.
EFAULT: Attempt at reading the page size pointed to by the out parameter was not successful.
EINVAL: When VM_PAGE_INFO is the command, the addr field of the vm_page_info structure is an invalid address.
EINVAL: When VM_NEW_HEAP_PSIZE is the command, the arg parameter is not set to the size of psize_t.
EINVAL: When VM_STAGGER_DATA is the command, the out parameter is not set to NULL, or the arg parameter is not set to 0.
EINVAL: When VMINFO_PSIZE is the command, the psize field of the vminfo_psize structure is an unsupported page size, the arg parameter is less than the size of a psize_t, or the out parameter is NULL.
EINVAL: When VMINFO_GETPSIZES is the command, the arg parameter is less than 0, or the out parameter is NULL when the arg parameter is non-zero.
ENOMEM: When VM_STAGGER_DATA is the command, the calling process's data could not be staggered because of resource limitations on the process's data size. (Use ulimit data to increase the allowed data for this process. See the ulimit Subroutine.)
ENOMEM: When VM_NEW_HEAP_PSIZE is the command, the break value of the process could not be adjusted because of resource limitations. (See the ulimit Subroutine.)
ENOSYS: The command parameter is not valid (or not yet implemented).
ENOSYS: Not implemented in current version of AIX® (or on 32-bit kernel).
ENOTSUP: When VM_NEW_HEAP_PSIZE is the command, the calling process is not 64-bit.
ENOTSUP: When VM_STAGGER_DATA is the command, the calling process is not 64-bit.
EPERM: When VM_NEW_HEAP_PSIZE is the command, the user does not have permission to use the requested page size.
ESRCH: When VM_PROC_PF_INFO or VM_THREAD_PF_INFO is the command, the thread or process identifier does not match any active thread or process.
EPERM: When you use the VM_PROC_PF_INFO or VM_THREAD_PF_INFO command, the user does not have sufficient role based access control (RBAC) privileges to retrieve information about the target process or thread.
EINVAL: When you use the VM_PROC_PF_INFO or VM_THREAD_PF_INFO , the version that is specified in the vm_pf_info structure does not match the VM_PF_INFO_VER value as seen by the vmgetinfo subroutine or, the flags field is not set to 0.

Examples

The following example demonstrates how an application could determine a system's supported page sizes with the vmgetinfo() subroutine:

int num_psizes;
psize_t *psizes;

/* Determine the number of supported page sizes */
num_psizes = vmgetinfo(NULL, VMINFO_GETPSIZES, 0);

if ((psizes = malloc(num_psizes*sizeof(psize_t))) == NULL)
	return(1);

/* Get the page sizes */
if (vmgetinfo(psizes, VMINFO_GETPSIZES, num_psizes)!= num_psizes)
{
	perror("vmgetinfo() unexpectedly failed");
	return(2);
}
		

/* psize[0] = smallest page size
 * psize[1] = next smallest page size...
 * psize[num_psizes-1] = largest supported page size
 */