Module libvirt-host from libvirt

Provides APIs for the management of hosts

Macros

#define VIR_NODEINFO_MAXCPUS
#define VIR_NODE_CPU_STATS_FIELD_LENGTH
#define VIR_NODE_CPU_STATS_IDLE
#define VIR_NODE_CPU_STATS_INTR
#define VIR_NODE_CPU_STATS_IOWAIT
#define VIR_NODE_CPU_STATS_KERNEL
#define VIR_NODE_CPU_STATS_USER
#define VIR_NODE_CPU_STATS_UTILIZATION
#define VIR_NODE_MEMORY_SHARED_FULL_SCANS
#define VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES
#define VIR_NODE_MEMORY_SHARED_PAGES_SHARED
#define VIR_NODE_MEMORY_SHARED_PAGES_SHARING
#define VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN
#define VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED
#define VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE
#define VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS
#define VIR_NODE_MEMORY_STATS_BUFFERS
#define VIR_NODE_MEMORY_STATS_CACHED
#define VIR_NODE_MEMORY_STATS_FIELD_LENGTH
#define VIR_NODE_MEMORY_STATS_FREE
#define VIR_NODE_MEMORY_STATS_TOTAL
#define VIR_SECURITY_DOI_BUFLEN
#define VIR_SECURITY_LABEL_BUFLEN
#define VIR_SECURITY_MODEL_BUFLEN
#define VIR_UUID_BUFLEN
#define VIR_UUID_STRING_BUFLEN

Types

typedef enum virCPUCompareResult
typedef struct _virConnect virConnect
typedef struct _virConnectAuth virConnectAuth
typedef virConnectAuth * virConnectAuthPtr
typedef enum virConnectBaselineCPUFlags
typedef enum virConnectCompareCPUFlags
typedef struct _virConnectCredential virConnectCredential
typedef virConnectCredential * virConnectCredentialPtr
typedef enum virConnectCredentialType
typedef enum virConnectFlags
typedef virConnect * virConnectPtr
typedef enum virNodeAllocPagesFlags
typedef struct _virNodeCPUStats virNodeCPUStats
typedef virNodeCPUStats * virNodeCPUStatsPtr
typedef enum virNodeGetCPUStatsAllCPUs
typedef enum virNodeGetMemoryStatsAllCells
typedef struct _virNodeInfo virNodeInfo
typedef virNodeInfo * virNodeInfoPtr
typedef struct _virNodeMemoryStats virNodeMemoryStats
typedef virNodeMemoryStats * virNodeMemoryStatsPtr
typedef enum virNodeSuspendTarget
typedef struct _virSecurityLabel virSecurityLabel
typedef virSecurityLabel * virSecurityLabelPtr
typedef struct _virSecurityModel virSecurityModel
typedef virSecurityModel * virSecurityModelPtr
typedef struct _virStream virStream
typedef virStream * virStreamPtr

Functions

typedef virConnectAuthCallbackPtr
int	virConnectAuthCallbackPtr	(virConnectCredentialPtr cred, 
					 unsigned int ncred, 
					 void * cbdata)

char *	virConnectBaselineCPU		(virConnectPtr conn, 
					 const char ** xmlCPUs, 
					 unsigned int ncpus, 
					 unsigned int flags)
int	virConnectClose			(virConnectPtr conn)
typedef virConnectCloseFunc
void	virConnectCloseFunc		(virConnectPtr conn, 
					 int reason, 
					 void * opaque)

int	virConnectCompareCPU		(virConnectPtr conn, 
					 const char * xmlDesc, 
					 unsigned int flags)
int	virConnectGetCPUModelNames	(virConnectPtr conn, 
					 const char * arch, 
					 char ** * models, 
					 unsigned int flags)
char *	virConnectGetCapabilities	(virConnectPtr conn)
char *	virConnectGetHostname		(virConnectPtr conn)
int	virConnectGetLibVersion		(virConnectPtr conn, 
					 unsigned long * libVer)
int	virConnectGetMaxVcpus		(virConnectPtr conn, 
					 const char * type)
char *	virConnectGetSysinfo		(virConnectPtr conn, 
					 unsigned int flags)
const char *	virConnectGetType	(virConnectPtr conn)
char *	virConnectGetURI		(virConnectPtr conn)
int	virConnectGetVersion		(virConnectPtr conn, 
					 unsigned long * hvVer)
int	virConnectIsAlive		(virConnectPtr conn)
int	virConnectIsEncrypted		(virConnectPtr conn)
int	virConnectIsSecure		(virConnectPtr conn)
virConnectPtr	virConnectOpen		(const char * name)
virConnectPtr	virConnectOpenAuth	(const char * name, 
					 virConnectAuthPtr auth, 
					 unsigned int flags)
virConnectPtr	virConnectOpenReadOnly	(const char * name)
int	virConnectRef			(virConnectPtr conn)
int	virConnectRegisterCloseCallback	(virConnectPtr conn, 
					 virConnectCloseFunc cb, 
					 void * opaque, 
					 virFreeCallback freecb)
int	virConnectSetKeepAlive		(virConnectPtr conn, 
					 int interval, 
					 unsigned int count)
int	virConnectUnregisterCloseCallback	(virConnectPtr conn, 
						 virConnectCloseFunc cb)
int	virGetVersion			(unsigned long * libVer, 
					 const char * type, 
					 unsigned long * typeVer)
int	virInitialize			(void)
int	virNodeAllocPages		(virConnectPtr conn, 
					 unsigned int npages, 
					 unsigned int * pageSizes, 
					 unsigned long long * pageCounts, 
					 int startCell, 
					 unsigned int cellCount, 
					 unsigned int flags)
int	virNodeGetCPUMap		(virConnectPtr conn, 
					 unsigned char ** cpumap, 
					 unsigned int * online, 
					 unsigned int flags)
int	virNodeGetCPUStats		(virConnectPtr conn, 
					 int cpuNum, 
					 virNodeCPUStatsPtr params, 
					 int * nparams, 
					 unsigned int flags)
int	virNodeGetCellsFreeMemory	(virConnectPtr conn, 
					 unsigned long long * freeMems, 
					 int startCell, 
					 int maxCells)
unsigned long long	virNodeGetFreeMemory	(virConnectPtr conn)
int	virNodeGetFreePages		(virConnectPtr conn, 
					 unsigned int npages, 
					 unsigned int * pages, 
					 int startCell, 
					 unsigned int cellCount, 
					 unsigned long long * counts, 
					 unsigned int flags)
int	virNodeGetInfo			(virConnectPtr conn, 
					 virNodeInfoPtr info)
int	virNodeGetMemoryParameters	(virConnectPtr conn, 
					 virTypedParameterPtr params, 
					 int * nparams, 
					 unsigned int flags)
int	virNodeGetMemoryStats		(virConnectPtr conn, 
					 int cellNum, 
					 virNodeMemoryStatsPtr params, 
					 int * nparams, 
					 unsigned int flags)
int	virNodeGetSecurityModel		(virConnectPtr conn, 
					 virSecurityModelPtr secmodel)
int	virNodeSetMemoryParameters	(virConnectPtr conn, 
					 virTypedParameterPtr params, 
					 int nparams, 
					 unsigned int flags)
int	virNodeSuspendForDuration	(virConnectPtr conn, 
					 unsigned int target, 
					 unsigned long long duration, 
					 unsigned int flags)

Description

`VIR_NODEINFO_MAXCPUS`¶

#define VIR_NODEINFO_MAXCPUS

This macro is to calculate the total number of CPUs supported but not necessary active in the host.

`VIR_NODE_CPU_STATS_FIELD_LENGTH`¶

#define VIR_NODE_CPU_STATS_FIELD_LENGTH

Macro providing the field length of virNodeCPUStats

`VIR_NODE_CPU_STATS_IDLE`¶

#define VIR_NODE_CPU_STATS_IDLE

The cumulative idle CPU time, since the node booting up (in nanoseconds).

`VIR_NODE_CPU_STATS_INTR`¶

#define VIR_NODE_CPU_STATS_INTR

The cumulative interrupt CPU time, since the node booting up (in nanoseconds).

`VIR_NODE_CPU_STATS_IOWAIT`¶

#define VIR_NODE_CPU_STATS_IOWAIT

The cumulative I/O wait CPU time, since the node booting up (in nanoseconds).

`VIR_NODE_CPU_STATS_KERNEL`¶

#define VIR_NODE_CPU_STATS_KERNEL

Macro for the cumulative CPU time which was spent by the kernel, since the node booting up (in nanoseconds).

`VIR_NODE_CPU_STATS_USER`¶

#define VIR_NODE_CPU_STATS_USER

The cumulative CPU time which was spent by user processes, since the node booting up (in nanoseconds).

`VIR_NODE_CPU_STATS_UTILIZATION`¶

#define VIR_NODE_CPU_STATS_UTILIZATION

The CPU utilization of a node. The usage value is in percent and 100% represents all CPUs of the node.

`VIR_NODE_MEMORY_SHARED_FULL_SCANS`¶

#define VIR_NODE_MEMORY_SHARED_FULL_SCANS

Macro for typed parameter that represents how many times all mergeable areas have been scanned.

`VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES`¶

#define VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES

Macro for typed parameter that represents whether pages from different NUMA nodes can be merged. The parameter has type int, when its value is 0, only pages which physically reside in the memory area of same NUMA node are merged; When its value is 1, pages from all nodes can be merged. Other values are reserved for future use.

`VIR_NODE_MEMORY_SHARED_PAGES_SHARED`¶

#define VIR_NODE_MEMORY_SHARED_PAGES_SHARED

Macro for typed parameter that represents how many the shared memory pages are being used.

`VIR_NODE_MEMORY_SHARED_PAGES_SHARING`¶

#define VIR_NODE_MEMORY_SHARED_PAGES_SHARING

Macro for typed parameter that represents how many sites are sharing the pages i.e. how much saved.

`VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN`¶

#define VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN

Macro for typed parameter that represents how many present pages to scan before the shared memory service goes to sleep.

`VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED`¶

#define VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED

Macro for typed parameter that represents how many pages unique but repeatedly checked for merging.

`VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE`¶

#define VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE

Macro for typed parameter that represents how many pages changing too fast to be placed in a tree.

`VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS`¶

#define VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS

Macro for typed parameter that represents how many milliseconds the shared memory service should sleep before next scan.

`VIR_NODE_MEMORY_STATS_BUFFERS`¶

#define VIR_NODE_MEMORY_STATS_BUFFERS

Macro for the buffer memory: On Linux, it is only returned in case of VIR_NODE_MEMORY_STATS_ALL_CELLS.

`VIR_NODE_MEMORY_STATS_CACHED`¶

#define VIR_NODE_MEMORY_STATS_CACHED

Macro for the cached memory: On Linux, it is only returned in case of VIR_NODE_MEMORY_STATS_ALL_CELLS.

`VIR_NODE_MEMORY_STATS_FIELD_LENGTH`¶

#define VIR_NODE_MEMORY_STATS_FIELD_LENGTH

Macro providing the field length of virNodeMemoryStats

`VIR_NODE_MEMORY_STATS_FREE`¶

#define VIR_NODE_MEMORY_STATS_FREE

Macro for the free memory of specified cell: On Linux, it includes buffer and cached memory, in case of VIR_NODE_MEMORY_STATS_ALL_CELLS.

`VIR_NODE_MEMORY_STATS_TOTAL`¶

#define VIR_NODE_MEMORY_STATS_TOTAL

Macro for the total memory of specified cell: it represents the maximum memory.

`VIR_SECURITY_DOI_BUFLEN`¶

#define VIR_SECURITY_DOI_BUFLEN

Macro providing the maximum length of the virSecurityModel doi string.

`VIR_SECURITY_LABEL_BUFLEN`¶

#define VIR_SECURITY_LABEL_BUFLEN

Macro providing the maximum length of the virSecurityLabel label string. Note that this value is based on that used by Labeled NFS.

`VIR_SECURITY_MODEL_BUFLEN`¶

#define VIR_SECURITY_MODEL_BUFLEN

Macro providing the maximum length of the virSecurityModel model string.

`VIR_UUID_BUFLEN`¶

#define VIR_UUID_BUFLEN

This macro provides the length of the buffer required for virDomainGetUUID()

`VIR_UUID_STRING_BUFLEN`¶

#define VIR_UUID_STRING_BUFLEN

This macro provides the length of the buffer required for virDomainGetUUIDString()

Types ¶

`virCPUCompareResult`¶

enum virCPUCompareResult {

VIR_CPU_COMPARE_ERROR	=	-1
VIR_CPU_COMPARE_INCOMPATIBLE	=	0
VIR_CPU_COMPARE_IDENTICAL	=	1
VIR_CPU_COMPARE_SUPERSET	=	2
VIR_CPU_COMPARE_LAST	=	3

`virConnect`¶

struct virConnect {

The content of this structure is not made public by the API

`virConnectAuth`¶

struct virConnectAuth {

int *	credtype	List of supported virConnectCredentialType values
unsigned int	ncredtype
virConnectAuthCallbackPtr	cb	Callback used to collect credentials
void *	cbdata

`virConnectBaselineCPUFlags`¶

enum virConnectBaselineCPUFlags {

VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES	=	1	show all features
VIR_CONNECT_BASELINE_CPU_MIGRATABLE	=	2	filter out non-migratable features

`virConnectCompareCPUFlags`¶

enum virConnectCompareCPUFlags {

VIR_CONNECT_COMPARE_CPU_FAIL_INCOMPATIBLE

treat incompatible CPUs as failure

`virConnectCredential`¶

struct virConnectCredential {

int	type	One of virConnectCredentialType constants
const char *	prompt	Prompt to show to user
const char *	challenge	Additional challenge to show
const char *	defresult	Optional default result
char *	result	Result to be filled with user response (or defresult)
unsigned int	resultlen	Length of the result

`virConnectCredentialType`¶

enum virConnectCredentialType {

VIR_CRED_USERNAME	=	1	Identity to act as
VIR_CRED_AUTHNAME	=	2	Identify to authorize as
VIR_CRED_LANGUAGE	=	3	RFC 1766 languages, comma separated
VIR_CRED_CNONCE	=	4	client supplies a nonce
VIR_CRED_PASSPHRASE	=	5	Passphrase secret
VIR_CRED_ECHOPROMPT	=	6	Challenge response
VIR_CRED_NOECHOPROMPT	=	7	Challenge response
VIR_CRED_REALM	=	8	Authentication realm
VIR_CRED_EXTERNAL	=	9	Externally managed credential
VIR_CRED_LAST	=	10	More may be added - expect the unexpected

`virConnectFlags`¶

enum virConnectFlags {

VIR_CONNECT_RO	=	1	A readonly connection
VIR_CONNECT_NO_ALIASES	=	2	Don't try to resolve URI aliases

`virNodeAllocPagesFlags`¶

enum virNodeAllocPagesFlags {

VIR_NODE_ALLOC_PAGES_ADD	=	0	Add @pageCounts to the pages pool. This can be used only to size up the pool.
VIR_NODE_ALLOC_PAGES_SET	=	1	Don't add @pageCounts, instead set passed number of pages. This can be used to free allocated pages.

`virNodeCPUStats`¶

struct virNodeCPUStats {

char field[VIR_NODE_CPU_STATS_FIELD_LENGTH]	field
unsigned long long	value

`virNodeGetCPUStatsAllCPUs`¶

enum virNodeGetCPUStatsAllCPUs {

VIR_NODE_CPU_STATS_ALL_CPUS

-1

`virNodeGetMemoryStatsAllCells`¶

enum virNodeGetMemoryStatsAllCells {

VIR_NODE_MEMORY_STATS_ALL_CELLS

-1

`virNodeInfo`¶

struct virNodeInfo {

char model[32]	model	string indicating the CPU model
unsigned long	memory	memory size in kilobytes
unsigned int	cpus	the number of active CPUs
unsigned int	mhz	expected CPU frequency, 0 if not known or on unusual architectures
unsigned int	nodes	the number of NUMA cell, 1 for unusual NUMA topologies or uniform memory access; check capabilities XML for the actual NUMA topology
unsigned int	sockets	number of CPU sockets per node if nodes > 1, 1 in case of unusual NUMA topology
unsigned int	cores	number of cores per socket, total number of processors in case of unusual NUMA topolog
unsigned int	threads	number of threads per core, 1 in case of unusual numa topology

`virNodeMemoryStats`¶

struct virNodeMemoryStats {

char field[VIR_NODE_MEMORY_STATS_FIELD_LENGTH]	field
unsigned long long	value

`virNodeSuspendTarget`¶

enum virNodeSuspendTarget {

VIR_NODE_SUSPEND_TARGET_MEM	=	0
VIR_NODE_SUSPEND_TARGET_DISK	=	1
VIR_NODE_SUSPEND_TARGET_HYBRID	=	2
VIR_NODE_SUSPEND_TARGET_LAST	=	3	This constant is subject to change

`virSecurityLabel`¶

struct virSecurityLabel {

char label[VIR_SECURITY_LABEL_BUFLEN]	label	security label string
int	enforcing	1 if security policy is being enforced for domain

`virSecurityModel`¶

struct virSecurityModel {

char model[VIR_SECURITY_MODEL_BUFLEN]	model	security model string
char doi[VIR_SECURITY_DOI_BUFLEN]	doi	domain of interpretation

`virStream`¶

struct virStream {

The content of this structure is not made public by the API

Functions ¶

`virConnectAuthCallbackPtr`¶

typedef int	(*virConnectAuthCallbackPtr)	(virConnectCredentialPtr cred,
					 unsigned int ncred,
					 void * cbdata)

When authentication requires one or more interactions, this callback is invoked. For each interaction supplied, data must be gathered from the user and filled in to the 'result' and 'resultlen' fields. If an interaction cannot be filled, fill in NULL and 0.

cred: list of virConnectCredential object to fetch from user
ncred: size of cred list
cbdata: opaque data passed to virConnectOpenAuth
Returns: 0 if all interactions were filled, or -1 upon error

`virConnectBaselineCPU`¶

char *	virConnectBaselineCPU		(virConnectPtr conn,
					 const char ** xmlCPUs,
					 unsigned int ncpus,
					 unsigned int flags)

Computes the most feature-rich CPU which is compatible with all given host CPUs.

If @flags includes VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES then libvirt will explicitly list all CPU features that are part of the host CPU, without this flag features that are part of the CPU model will not be listed.

If @flags includes VIR_CONNECT_BASELINE_CPU_MIGRATABLE, the resulting CPU will not include features that block migration.

conn: virConnect connection
xmlCPUs: array of XML descriptions of host CPUs
ncpus: number of CPUs in xmlCPUs
flags: bitwise-OR of virConnectBaselineCPUFlags
Returns: XML description of the computed CPU (caller frees) or NULL on error.

`virConnectClose`¶

int	virConnectClose			(virConnectPtr conn)

This function closes the connection to the Hypervisor. This should not be called if further interaction with the Hypervisor are needed especially if there is running domain which need further monitoring by the application.

Connections are reference counted; the count is explicitly increased by the initial open (virConnectOpen, virConnectOpenAuth, and the like) as well as virConnectRef; it is also temporarily increase

Module libvirt-host from libvirt

Table of Contents

Description