#

## Module libvir from libvir

API Menu

- Main Menu
- API Menu
- ChangeLog

API Indexes

- Alphabetic
- Constructors
- Functions/Types
- Modules
- Symbols

Related links

- Mail archive
- Xen project

Provides the interfaces of the libvir library to handle Xen domains from a process running in domain 0

## Table of Contents

    #define LIBVIR_VERSION_NUMBER

    Structure virConnect
    struct _virConnect
    The content of this structure is not made public by the API.

    Typedef virConnect * virConnectPtr

    Structure virDomain
    struct _virDomain
    The content of this structure is not made public by the API.

    Enum virDomainFlags

    Structure virDomainInfo
    struct _virDomainInfo

    Typedef virDomainInfo * virDomainInfoPtr

    Typedef virDomain * virDomainPtr

    Enum virDomainState

    int	virConnectClose			(virConnectPtr conn)

    const char *	virConnectGetType	(virConnectPtr conn)

    int	virConnectGetVersion		(virConnectPtr conn,
    					 unsigned long * hvVer)

    int	virConnectListDomains		(virConnectPtr conn,
    					 int * ids,
    					 int maxids)

    int	virConnectNumOfDomains		(virConnectPtr conn)

    virConnectPtr	virConnectOpen		(const char * name)

    virConnectPtr	virConnectOpenReadOnly	(const char * name)

    virDomainPtr	virDomainCreateLinux	(virConnectPtr conn,
    					 const char * kernel_path,
    					 const char * initrd_path,
    					 const char * cmdline,
    					 unsigned long memory,
    					 unsigned int flags)

    int	virDomainDestroy		(virDomainPtr domain)

    unsigned int	virDomainGetID		(virDomainPtr domain)

    int	virDomainGetInfo		(virDomainPtr domain,
    					 virDomainInfoPtr info)

    unsigned long	virDomainGetMaxMemory	(virDomainPtr domain)

    const char *	virDomainGetName	(virDomainPtr domain)

    virDomainPtr	virDomainLookupByID	(virConnectPtr conn,
    					 int id)

    virDomainPtr	virDomainLookupByName	(virConnectPtr conn,
    					 const char * name)

    int	virDomainResume			(virDomainPtr domain)

    int	virDomainSetMaxMemory		(virDomainPtr domain,
    					 unsigned long memory)

    int	virDomainSuspend		(virDomainPtr domain)

    int	virGetVersion			(unsigned long * libVer,
    					 const char * type,
    					 unsigned long * typeVer)

## Description

### Macro: LIBVIR_VERSION_NUMBER

    #define LIBVIR_VERSION_NUMBER

Macro providing the version of the library as version * 1,000,000 + minor * 1000 + micro

### Structure virConnect

    Structure virConnect
    struct _virConnect {
    The content of this structure is not made public by the API.
    }

a virConnectPtr is pointer to a virConnect private structure, this is the type used to reference a connection to the Xen Hypervisor in the API.

### Structure virDomain

    Structure virDomain
    struct _virDomain {
    The content of this structure is not made public by the API.
    }

### Enum virDomainFlags

    Enum virDomainFlags {
        VIR_DOMAIN_NONE = 0
    }

### Structure virDomainInfo

    Structure virDomainInfo
    struct _virDomainInfo {
        unsigned char	state	: the running state, one of virDomainFlag
        unsigned long	maxMem	: the maximum memory in KBytes allowed
        unsigned long	memory	: the memory in KBytes used by the domain
        unsigned short	nrVirtCpu	: * Informations below are only available
        unsigned long long	cpuTime	: * TODO: * - check what can be extracted
    }

a virDomainInfoPtr is a pointer to a virDomainInfo structure. a virDomainPtr is pointer to a virDomain private structure, this is the type used to reference a Xen domain in the API.

### Enum virDomainState

    Enum virDomainState {
        VIR_DOMAIN_NOSTATE = 0 : no state
        VIR_DOMAIN_RUNNING = 1 : the domain is running
        VIR_DOMAIN_BLOCKED = 2 : the domain is blocked on resource
        VIR_DOMAIN_PAUSED = 3 : the domain is paused by user
        VIR_DOMAIN_SHUTDOWN = 4 : the domain is being shut down
        VIR_DOMAIN_SHUTOFF = 5 : the domain is shut off
    }

### Function: 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.

`conn`: | pointer to the hypervisor connection
`Returns`: | 0 in case of success or -1 in case of error.

### Function: virConnectGetType

    const char *	virConnectGetType	(virConnectPtr conn)

Get the name of the Hypervisor software used.

`conn`: | pointer to the hypervisor connection
`Returns`: | NULL in case of error, a static zero terminated string otherwise.

### Function: virConnectGetVersion

    int	virConnectGetVersion		(virConnectPtr conn,
    					 unsigned long * hvVer)

Get the version level of the Hypervisor running. This may work only with hypervisor call, i.e. with priviledged access to the hypervisor, not with a Read-Only connection.

`conn`: | pointer to the hypervisor connection
`hvVer`: | return value for the version of the running hypervisor (OUT)
`Returns`: | -1 in case of error, 0 otherwise. if the version can't be extracted by lack of capacities returns 0 and @hvVer is 0, otherwise @hvVer value is major * 1,000,000 + minor * 1,000 + release

### Function: virConnectListDomains

    int	virConnectListDomains		(virConnectPtr conn,
    					 int * ids,
    					 int maxids)

Collect the list of active domains, and store their ID in @maxids

`conn`: | pointer to the hypervisor connection
`ids`: | array to collect the list of IDs of active domains
`maxids`: | size of @ids
`Returns`: | the number of domain found or -1 in case of error

### Function: virConnectNumOfDomains

    int	virConnectNumOfDomains		(virConnectPtr conn)

`conn`: | pointer to the hypervisor connection
`Returns`: | the number of domain found or -1 in case of error

### Function: virConnectOpen

    virConnectPtr	virConnectOpen		(const char * name)

This function should be called first to get a connection to the Hypervisor and xen store

`name`: | optional argument currently unused, pass NULL
`Returns`: | a pointer to the hypervisor connection or NULL in case of error

### Function: virConnectOpenReadOnly

    virConnectPtr	virConnectOpenReadOnly	(const char * name)

This function should be called first to get a read-only connection to the xen store. The set of APIs usable are then restricted.

`name`: | optional argument currently unused, pass NULL
`Returns`: | a pointer to the hypervisor connection or NULL in case of error

### Function: virDomainCreateLinux

    virDomainPtr	virDomainCreateLinux	(virConnectPtr conn,
    					 const char * kernel_path,
    					 const char * initrd_path,
    					 const char * cmdline,
    					 unsigned long memory,
    					 unsigned int flags)

Launch a new Linux guest domain

`conn`: | pointer to the hypervisor connection
`kernel_path`: | the file path to the kernel image
`initrd_path`: | an optional file path to an initrd
`cmdline`: | optional command line parameters for the kernel
`memory`: | the memory size in kilobytes
`flags`: | an optional set of virDomainFlags
`Returns`: | a new domain object or NULL in case of failure

### Function: virDomainDestroy

    int	virDomainDestroy		(virDomainPtr domain)

Destroy the domain object. The running instance is shutdown if not down already and all resources used by it are given back to the hypervisor.

`domain`: | a domain object
`Returns`: | 0 in case of success and -1 in case of failure.

### Function: virDomainGetID

    unsigned int	virDomainGetID		(virDomainPtr domain)

Get the hypervisor ID number for the domain

`domain`: | a domain object
`Returns`: | the domain ID number or (unsigned int) -1 in case of error

### Function: virDomainGetInfo

    int	virDomainGetInfo		(virDomainPtr domain,
    					 virDomainInfoPtr info)

Extract information about a domain. Note that if the connection used to get the domain is limited only a partial set of the informations can be extracted.

`domain`: | a domain object or NULL
`info`: | pointer to a virDomainInfo structure allocated by the user
`Returns`: | 0 in case of success and -1 in case of failure.

### Function: virDomainGetMaxMemory

    unsigned long	virDomainGetMaxMemory	(virDomainPtr domain)

Retrieve the maximum amount of physical memory allocated to a domain. If domain is NULL, then this get the amount of memory reserved to Domain0 i.e. the domain where the application runs.

`domain`: | a domain object or NULL
`Returns`: | the memory size in kilobytes or 0 in case of error.

### Function: virDomainGetName

    const char *	virDomainGetName	(virDomainPtr domain)

Get the public name for that domain

`domain`: | a domain object
`Returns`: | a pointer to the name or NULL, the string need not be deallocated its lifetime will be the same as the domain object.

### Function: virDomainLookupByID

    virDomainPtr	virDomainLookupByID	(virConnectPtr conn,
    					 int id)

Try to find a domain based on the hypervisor ID number

`conn`: | pointer to the hypervisor connection
`id`: | the domain ID number
`Returns`: | a new domain object or NULL in case of failure

### Function: virDomainLookupByName

    virDomainPtr	virDomainLookupByName	(virConnectPtr conn,
    					 const char * name)

Try to lookup a domain on the given hypervisor

`conn`: | pointer to the hypervisor connection
`name`: | name for the domain
`Returns`: | a new domain object or NULL in case of failure

### Function: virDomainResume

    int	virDomainResume			(virDomainPtr domain)

Resume an suspended domain, the process is restarted from the state where it was frozen by calling virSuspendDomain().

`domain`: | a domain object
`Returns`: | 0 in case of success and -1 in case of failure.

### Function: virDomainSetMaxMemory

    int	virDomainSetMaxMemory		(virDomainPtr domain,
    					 unsigned long memory)

Dynamically change the maximum amount of physical memory allocated to a domain. If domain is NULL, then this change the amount of memory reserved to Domain0 i.e. the domain where the application runs.

`domain`: | a domain object or NULL
`memory`: | the memory size in kilobytes
`Returns`: | 0 in case of success and -1 in case of failure.

### Function: virDomainSuspend

    int	virDomainSuspend		(virDomainPtr domain)

Suspends an active domain, the process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated. Use virDomainResume() to reactivate the domain.

`domain`: | a domain object
`Returns`: | 0 in case of success and -1 in case of failure.

### Function: virGetVersion

    int	virGetVersion			(unsigned long * libVer,
    					 const char * type,
    					 unsigned long * typeVer)

Provides two information back, @libVer is the version of the library while @typeVer will be the version of the hypervisor type @type against which the library was compiled. If @type is NULL, "Xen" is assumed, if @type is unknown or not availble, an error code will be returned and @typeVer will be 0.

`libVer`: | return value for the library version (OUT)
`type`: | hypervisor type
`typeVer`: | return value for the version of the hypervisor (OUT)
`Returns`: | -1 in case of failure, 0 otherwise, and values for @libVer and @typeVer have the format major * 1,000,000 + minor * 1,000 + release.

Daniel Veillard