vmgetinfo Subroutine

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 thevm_srad_meminfo structure:

vmsrad_out_size: The number of bytes returned in the buffer.
vmsrad_total: The total number of bytes of memory contained in the SRAD. This excludes the memory that is permanently reserved for low-level memory management.
vmsrad_free: The amount of free memory in the SRAD displayed in bytes.
vmsrad_file: The number of bytes occupied by files.
vmsrad_aff_priv_pct: This is the maximum percentage of private memory that will be 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 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.

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.

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
 */