VM Guest Library Functions

The vSphere Guest SDK contains the header file
vmGuestLib.h
. This file declares the functions and data types that you use to call the VM Guest API. The following sections describe the VM Guest API functions:

Calling Context Functions

The VM Guest API provides a set of functions that initialize and manipulate the context where the Guest API operates. Before your application can use the accessor functions to retrieve information about a virtual machine, use the following functions to initialize the VM Guest API environment.
  1. Call the
    VMGuestLib_OpenHandle
    function to obtain a handle for accessing information about the virtual machine. The guest library handle is a parameter to every Guest API function.
  2. Call the
    VMGuestLib_UpdateInfo
    function to update the information available through the handle.
  3. Call the
    VMGuestLib_GetSessionId
    function to retrieve a session ID.

About Context Functions

The code block below shows a C language fragment that illustrates the function calls for initialization. (Code fragments in this section do not perform error handling. For information about error handling, see VM Guest API Error Codes.)
Initializing the VM Guest API Environment
VMGuestLibHandle glHandle; VMGuestLibError glError; VMSessionId sid = 0; glError = VMGuestLib_OpenHandle(&glHandle); glError = VMGuestLib_UpdateInfo(glHandle); glError = VMGuestLib_GetSessionId(glHandle, &sid);
You can use the session ID to detect changes that invalidate previously retrieved data. The code block below shows a fragment that illustrates how to use the session ID to detect stale data. The
ResetStats
function in the following fragment represents application code to handle the session change.
Detecting Stale Data
VMGuestLibHandle glHandle; VMGuestLibError glError; VMSessionId oldSid; VMSessionId newSid; /* [...code here would access data based on an existing, valid session ID (oldSid)...] */ /* Update the library, get the session ID, and compare it to the previous session ID */ glError = VMGuestLib_UpdateInfo(glHandle); glError = GuestLib_GetSessionId(glHandle, &newSid); if (oldSid != newSid) { ResetStats(); oldSid = newSid; }
Table 1 lists the context functions for creating and releasing handles, updating information, and obtaining session IDs.
Open, Close, and Update Functions
Function
Description
VMGuestLib_OpenHandle
Gets a handle for use with other VM Guest API functions. The guest library handle provides a context for accessing information about the virtual machine. Virtual machine statistics and state data are associated with a particular guest library handle, so using one handle does not affect the data associated with another handle.
VMGuestLib_CloseHandle
Releases a handle acquired with
VMGuestLib_OpenHandle
.
VMGuestLib_UpdateInfo
Updates information about the virtual machine. This information is associated with the
VMGuestLibHandle
.
VMGuestLib_UpdateInfo
requires similar CPU resources to a system call and therefore can affect performance. If you are concerned about performance, minimize the number of calls to
VMGuestLib_UpdateInfo
.
If your program uses multiple threads, each thread must use a different handle. Otherwise, you must implement a locking scheme around update calls. The VM Guest API does not implement internal locking around access with a handle.
VMGuestLib_GetSessionId
Retrieves the
VMSessionID
for the current session. Call this function after calling
VMGuestLib_UpdateInfo
. If
VMGuestLib_UpdateInfo
has never been called,
VMGuestLib_GetSessionId
returns
VMGUESTLIB_ERROR_NO_INFO
.

Accessor Functions (Virtual Machine)

Accessor functions retrieve information about a virtual machine. When you call an accessor function, you pass a guest library handle (type
VMGuestLibHandle
) to the function. If the function is successful, it returns the requested data as an output parameter. The function return value is an error code (type
VMGuestLibError
) that indicates success or failure. The code block below shows a C language fragment that illustrates calling
VMGuestLib_GetCpuLimitMHz
to retrieve the processor limit available to the virtual machine.
Using an Accessor Function
uint32 cpuLimitMHz = 0; glError = VMGuestLib_GetCpuLimitMHz(glHandle, &cpuLimitMHz);
When a call completes successfully, the function returns the value
VMGUESTLIB_ERROR_SUCCESS
. If the call is unsuccessful, the error code name contains an appropriate description. For details, see VM Guest API Error Codes.
Call
VMGuestLib_UpdateInfo
once to refresh all statistics before calling an accessor function or a series of accessor functions.
Accessor Functions for Virtual Machine Data
Function
Description
VMGuestLib_GetCpuLimitMHz
Retrieves the upper limit of processor use in MHz available to the virtual machine. For information about setting the CPU limit, see Limits and Reservations.
VMGuestLib_GetCpuReservationMHz
Retrieves the minimum processing power in MHz reserved for the virtual machine. For information about setting a CPU reservation, see Limits and Reservations.
VMGuestLib_GetCpuShares
Retrieves the number of CPU shares allocated to the virtual machine. For information about how an ESXi host uses CPU shares to manage virtual machine priority, see the
vSphere Resource Management Guide
.
VMGuestLib_GetCpuStolenMs
Retrieves the number of milliseconds that the virtual machine was in a ready state (able to transition to a run state), but was not scheduled to run.
VMGuestLib_GetCpuUsedMs
Retrieves the number of milliseconds during which the virtual machine has used the CPU. This value includes the time used by the guest operating system and the time used by virtualization code for tasks for this virtual machine. You can combine this value with the elapsed time (
VMGuestLib_GetElapsedMs
) to estimate the effective virtual machine CPU speed. This value is a subset of elapsedMs.
VMGuestLib_GetElapsedMs
Retrieves the number of milliseconds that have passed in the virtual machine since it last started running on the server. The count of elapsed time restarts each time the virtual machine is powered on, resumed, or migrated using VMotion. This value counts milliseconds, regardless of whether the virtual machine is using processing power during that time. You can combine this value with the CPU time used by the virtual machine (
VMGuestLib_GetCpuUsedMs
) to estimate the effective virtual machine CPU speed. cpuUsedMS is a subset of this value.
VMGuestLib_GetHostProcessorSpeed
Retrieves the speed of the ESXi host’s physical CPU in MHz.
VMGuestLib_GetMemActiveMB
Retrieves the amount of memory the virtual machine is actively using—its estimated working set size.
VMGuestLib_GetMemBalloonedMB
Retrieves the amount of memory that has been reclaimed from this virtual machine by the vSphere memory balloon driver, which is also called the “vmmemctl” driver.
VMGuestLib_GetMemLimitMB
Retrieves the upper limit of memory that is available to the virtual machine. For information about setting a memory limit, see Limits and Reservations.
VMGuestLib_GetMemMappedMB
Retrieves the amount of memory that is allocated to the virtual machine. Memory that is ballooned, swapped, or has never been accessed is excluded.
VMGuestLib_GetMemOverheadMB
Retrieves the amount of “overhead” memory associated with this virtual machine that is currently consumed on the host system. Overhead memory is additional memory that is reserved for data structures required by the virtualization layer.
VMGuestLib_GetMemReservationMB
Retrieves the minimum amount of memory that is reserved for the virtual machine. For information about setting a memory reservation, see Limits and Reservations.
VMGuestLib_GetMemSharedMB
Retrieves the amount of physical memory associated with this virtual machine that is copy-on-write (COW) shared on the host.
VMGuestLib_GetMemSharedSavedMB
Retrieves the estimated amount of physical memory on the host saved from copy-on-write (COW) shared guest physical memory.
VMGuestLib_GetMemShares
Retrieves the number of memory shares allocated to the virtual machine, as an unsigned 32-bit value. If the value cannot fit in 32-bits, this call returns an error. In that case, use
VMGuestLib_GetMemShares64
instead. For information about how ESXi hosts use memory shares to manage virtual machine priority, see the
vSphere Resource Management Guide
.
VMGuestLib_GetMemShares64
This call was added in vSphere 7.0 to get the 64-bit value of memory shares allocated to the virtual machine.
VMGuestLib_GetMemSwappedMB
Retrieves the amount of memory that has been reclaimed from this virtual machine by transparently swapping guest memory to disk.
VMGuestLib_GetMemTargetSizeMB
Retrieves the size of the target memory allocation for this virtual machine.
VMGuestLib_GetMemUsedMB
Retrieves the estimated amount of physical host memory currently consumed for this virtual machine's physical memory.
VMGuestLib_GetResourcePoolPath
Retrieves the path name of the resource pool affiliated with the virtual machine on the ESXi host where it is running.
VMGuestLib_GetResourcePoolPath uses an additional parameter to determine the size of the path name output string buffer.
VMGuestLibError VmGuestLib_GetResourcePoolPath( 
 VMGuestLibHandle handle,
 size_t *bufferSize,
 char *pathBuffer );
handle
is an input parameter specifying the guest library handle.
bufferSize
is an input/output parameter. It is a pointer to the size of the pathBuffer in bytes. If bufferSize is not large enough to accommodate the path (including a NULL terminator), the function returns VMGUESTLIB_ERROR_BUFFER_TOO_SMALL. In this case, the function uses the bufferSize parameter to return the number of bytes required for the string.
pathBuffer
is an output parameter. It is a pointer to a buffer that receives the resource pool path string. The path string is NULL-terminated.
For information about using resource pools, see the
vSphere Resource Management Guide
.
For more information about ESXi resource management, see the
vSphere Resource Management Guide
, available on the VMware Web site.

Limits and Reservations

You use the Guest API to retrieve information about limits and reservations for CPU and memory. To set limits and reservations, you can use the vSphere (Web) Client or the vSphere API. Setting limits and reservations on a virtual machine ensures that resources are available to that machine and to other virtual machines that draw resources from the same resource pool.
To use the vSphere Client to set limits or reservations:
  1. In the vSphere Client window, click the Resource Allocation tab.
  2. In either the CPU or Memory section, click Edit.
  3. In the Virtual Machine Properties Window, click the Resources tab.
  4. Select either the CPU or Memory setting.
  5. Use the slider controls to set limits or reservations.
For more information, see online help for the vSphere Client.
To use the vSphere API to set limits or reservations, call the ReconfigVM_Task method. In the method call, use the VirtualMachineConfigSpec data object to set the cpuAllocation or memoryAllocation property. These properties are of type ResourceAllocationInfo, which has limit and reservation properties. For more information, see the VMware vSphere API Reference Documentation.