# Module virterror from libvirt

Provides the interfaces of the libvirt library to handle errors raised while using the library.

## Table of Contents

### Types

    typedef struct _virError virError
    typedef enum virErrorDomain
    typedef enum virErrorLevel
    typedef enum virErrorNumber
    typedef virError * virErrorPtr

### Functions

    int	virConnCopyLastError		(virConnectPtr conn,
    					 virErrorPtr to)
    virErrorPtr	virConnGetLastError	(virConnectPtr conn)
    void	virConnResetLastError		(virConnectPtr conn)
    void	virConnSetErrorFunc		(virConnectPtr conn,
    					 void * userData,
    					 virErrorFunc handler)
    int	virCopyLastError		(virErrorPtr to)
    void	virDefaultErrorFunc		(virErrorPtr err)
    typedef virErrorFunc
    void	virErrorFunc			(void * userData,
    					 virErrorPtr error)

    void	virFreeError			(virErrorPtr err)
    virErrorPtr	virGetLastError		(void)
    void	virResetError			(virErrorPtr err)
    void	virResetLastError		(void)
    virErrorPtr	virSaveLastError	(void)
    void	virSetErrorFunc			(void * userData,
    					 virErrorFunc handler)

## Description

### Types

### `virError`

    struct virError{

int | code | : The error code, a virErrorNumber
int | domain | : What part of the library raised this error
char * | message | : human-readable informative error message
virErrorLevel | level | : how consequent is the error
virConnectPtr | conn | : connection if available, deprecated see note above
virDomainPtr | dom | : domain if available, deprecated see note above
char * | str1 | : extra string information
char * | str2 | : extra string information
char * | str3 | : extra string information
int | int1 | : extra number information
int | int2 | : extra number information
virNetworkPtr | net | : network if available, deprecated see note above

    }

### `virErrorDomain`

    enum virErrorDomain {

VIR_FROM_NONE | = | 0
VIR_FROM_XEN | = | 1 | : Error at Xen hypervisor layer
VIR_FROM_XEND | = | 2 | : Error at connection with xend daemon
VIR_FROM_XENSTORE | = | 3 | : Error at connection with xen store
VIR_FROM_SEXPR | = | 4 | : Error in the S-Expression code
VIR_FROM_XML | = | 5 | : Error in the XML code
VIR_FROM_DOM | = | 6 | : Error when operating on a domain
VIR_FROM_RPC | = | 7 | : Error in the XML-RPC code
VIR_FROM_PROXY | = | 8 | : Error in the proxy code
VIR_FROM_CONF | = | 9 | : Error in the configuration file handling
VIR_FROM_QEMU | = | 10 | : Error at the QEMU daemon
VIR_FROM_NET | = | 11 | : Error when operating on a network
VIR_FROM_TEST | = | 12 | : Error from test driver
VIR_FROM_REMOTE | = | 13 | : Error from remote driver
VIR_FROM_OPENVZ | = | 14 | : Error from OpenVZ driver
VIR_FROM_XENXM | = | 15 | : Error at Xen XM layer
VIR_FROM_STATS_LINUX | = | 16 | : Error in the Linux Stats code
VIR_FROM_LXC | = | 17 | : Error from Linux Container driver
VIR_FROM_STORAGE | = | 18 | : Error from storage driver
VIR_FROM_NETWORK | = | 19 | : Error from network config
VIR_FROM_DOMAIN | = | 20 | : Error from domain config
VIR_FROM_UML | = | 21 | : Error at the UML driver
VIR_FROM_NODEDEV | = | 22 | : Error from node device monitor
VIR_FROM_XEN_INOTIFY | = | 23 | : Error from xen inotify layer
VIR_FROM_SECURITY | = | 24 | : Error from security framework
VIR_FROM_VBOX | = | 25 | : Error from VirtualBox driver
VIR_FROM_INTERFACE | = | 26 | : Error when operating on an interface

    }

### `virErrorLevel`

    enum virErrorLevel {

VIR_ERR_NONE | = | 0
VIR_ERR_WARNING | = | 1 | : A simple warning
VIR_ERR_ERROR | = | 2 | : An error

    }

### `virErrorNumber`

    enum virErrorNumber {

VIR_ERR_OK | = | 0
VIR_ERR_INTERNAL_ERROR | = | 1 | : internal error
VIR_ERR_NO_MEMORY | = | 2 | : memory allocation failure
VIR_ERR_NO_SUPPORT | = | 3 | : no support for this function
VIR_ERR_UNKNOWN_HOST | = | 4 | : could not resolve hostname
VIR_ERR_NO_CONNECT | = | 5 | : can't connect to hypervisor
VIR_ERR_INVALID_CONN | = | 6 | : invalid connection object
VIR_ERR_INVALID_DOMAIN | = | 7 | : invalid domain object
VIR_ERR_INVALID_ARG | = | 8 | : invalid function argument
VIR_ERR_OPERATION_FAILED | = | 9 | : a command to hypervisor failed
VIR_ERR_GET_FAILED | = | 10 | : a HTTP GET command to failed
VIR_ERR_POST_FAILED | = | 11 | : a HTTP POST command to failed
VIR_ERR_HTTP_ERROR | = | 12 | : unexpected HTTP error code
VIR_ERR_SEXPR_SERIAL | = | 13 | : failure to serialize an S-Expr
VIR_ERR_NO_XEN | = | 14 | : could not open Xen hypervisor control
VIR_ERR_XEN_CALL | = | 15 | : failure doing an hypervisor call
VIR_ERR_OS_TYPE | = | 16 | : unknown OS type
VIR_ERR_NO_KERNEL | = | 17 | : missing kernel information
VIR_ERR_NO_ROOT | = | 18 | : missing root device information
VIR_ERR_NO_SOURCE | = | 19 | : missing source device information
VIR_ERR_NO_TARGET | = | 20 | : missing target device information
VIR_ERR_NO_NAME | = | 21 | : missing domain name information
VIR_ERR_NO_OS | = | 22 | : missing domain OS information
VIR_ERR_NO_DEVICE | = | 23 | : missing domain devices information
VIR_ERR_NO_XENSTORE | = | 24 | : could not open Xen Store control
VIR_ERR_DRIVER_FULL | = | 25 | : too many drivers registered
VIR_ERR_CALL_FAILED | = | 26 | : not supported by the drivers (DEPRECATED)
VIR_ERR_XML_ERROR | = | 27 | : an XML description is not well formed or broken
VIR_ERR_DOM_EXIST | = | 28 | : the domain already exist
VIR_ERR_OPERATION_DENIED | = | 29 | : operation forbidden on read-only connections
VIR_ERR_OPEN_FAILED | = | 30 | : failed to open a conf file
VIR_ERR_READ_FAILED | = | 31 | : failed to read a conf file
VIR_ERR_PARSE_FAILED | = | 32 | : failed to parse a conf file
VIR_ERR_CONF_SYNTAX | = | 33 | : failed to parse the syntax of a conf file
VIR_ERR_WRITE_FAILED | = | 34 | : failed to write a conf file
VIR_ERR_XML_DETAIL | = | 35 | : detail of an XML error
VIR_ERR_INVALID_NETWORK | = | 36 | : invalid network object
VIR_ERR_NETWORK_EXIST | = | 37 | : the network already exist
VIR_ERR_SYSTEM_ERROR | = | 38 | : general system call failure
VIR_ERR_RPC | = | 39 | : some sort of RPC error
VIR_ERR_GNUTLS_ERROR | = | 40 | : error from a GNUTLS call
VIR_WAR_NO_NETWORK | = | 41 | : failed to start network
VIR_ERR_NO_DOMAIN | = | 42 | : domain not found or unexpectedly disappeared
VIR_ERR_NO_NETWORK | = | 43 | : network not found
VIR_ERR_INVALID_MAC | = | 44 | : invalid MAC address
VIR_ERR_AUTH_FAILED | = | 45 | : authentication failed
VIR_ERR_INVALID_STORAGE_POOL | = | 46 | : invalid storage pool object
VIR_ERR_INVALID_STORAGE_VOL | = | 47 | : invalid storage vol object
VIR_WAR_NO_STORAGE | = | 48 | : failed to start storage
VIR_ERR_NO_STORAGE_POOL | = | 49 | : storage pool not found
VIR_ERR_NO_STORAGE_VOL | = | 50 | : storage pool not found
VIR_WAR_NO_NODE | = | 51 | : failed to start node driver
VIR_ERR_INVALID_NODE_DEVICE | = | 52 | : invalid node device object
VIR_ERR_NO_NODE_DEVICE | = | 53 | : node device not found
VIR_ERR_NO_SECURITY_MODEL | = | 54 | : security model not found
VIR_ERR_OPERATION_INVALID | = | 55 | : operation is not applicable at this time
VIR_WAR_NO_INTERFACE | = | 56 | : failed to start interface driver
VIR_ERR_NO_INTERFACE | = | 57 | : interface driver not running
VIR_ERR_INVALID_INTERFACE | = | 58 | : invalid interface object

    }

### Functions

### `virConnCopyLastError`

    int	virConnCopyLastError		(virConnectPtr conn,
    					 virErrorPtr to)

Copy the content of the last error caught on that connection This method is not protected against access from multiple threads. In a multi-threaded application, always use the global virGetLastError() API which is backed by thread local storage. If the connection object was discovered to be invalid by an API call, then the error will be reported against the global error object. Since 0.6.0, all errors reported in the per-connection object are also duplicated in the global error object. As such an application can always use virGetLastError(). This method remains for backwards compatability. One will need to free the result with virResetError()

`conn`: | pointer to the hypervisor connection
`to`: | target to receive the copy
`Returns`: | 0 if no error was found and the error code otherwise and -1 in case of parameter error.

### `virConnGetLastError`

    virErrorPtr	virConnGetLastError	(virConnectPtr conn)

Provide a pointer to the last error caught on that connection This method is not protected against access from multiple threads. In a multi-threaded application, always use the global virGetLastError() API which is backed by thread local storage. If the connection object was discovered to be invalid by an API call, then the error will be reported against the global error object. Since 0.6.0, all errors reported in the per-connection object are also duplicated in the global error object. As such an application can always use virGetLastError(). This method remains for backwards compatability.

`conn`: | pointer to the hypervisor connection
`Returns`: | a pointer to the last error or NULL if none occurred.

### `virConnResetLastError`

    void	virConnResetLastError		(virConnectPtr conn)

The error object is kept in thread local storage, so separate threads can safely access this concurrently. Reset the last error caught on that connection

`conn`: | pointer to the hypervisor connection

### `virConnSetErrorFunc`

    void	virConnSetErrorFunc		(virConnectPtr conn,
    					 void * userData,
    					 virErrorFunc handler)

Set a connection error handling function, if @handler is NULL it will reset to default which is to pass error back to the global library handler.

`conn`: | pointer to the hypervisor connection
`userData`: | pointer to the user data provided in the handler callback
`handler`: | the function to get called in case of error or NULL

### `virCopyLastError`

    int	virCopyLastError		(virErrorPtr to)

Copy the content of the last error caught at the library level The error object is kept in thread local storage, so separate threads can safely access this concurrently. One will need to free the result with virResetError()

`to`: | target to receive the copy
`Returns`: | 0 if no error was found and the error code otherwise and -1 in case of parameter error.

### `virDefaultErrorFunc`

    void	virDefaultErrorFunc		(virErrorPtr err)

Default routine reporting an error to stderr.

`err`: | pointer to the error.

### `virErrorFunc`

    typedef void	(*virErrorFunc		)	(void * userData,
    					 virErrorPtr error)

Signature of a function to use when there is an error raised by the library.

`userData`: | user provided data for the error callback
`error`: | the error being raised.

### `virFreeError`

    void	virFreeError			(virErrorPtr err)

Resets and frees the given error.

`err`: | error to free

### `virGetLastError`

    virErrorPtr	virGetLastError		(void)

Provide a pointer to the last error caught at the library level The error object is kept in thread local storage, so separate threads can safely access this concurrently.

`Returns`: | a pointer to the last error or NULL if none occurred.

### `virResetError`

    void	virResetError			(virErrorPtr err)

Reset the error being pointed to

`err`: | pointer to the virError to clean up

### `virResetLastError`

    void	virResetLastError		(void)

Reset the last error caught at the library level. The error object is kept in thread local storage, so separate threads can safely access this concurrently, only resetting their own error object.

### `virSaveLastError`

    virErrorPtr	virSaveLastError	(void)

Save the last error into a new error object.

`Returns`: | a pointer to the copied error or NULL if allocation failed. It is the caller's responsibility to free the error with virFreeError().

### `virSetErrorFunc`

    void	virSetErrorFunc			(void * userData,
    					 virErrorFunc handler)

Set a library global error handling function, if @handler is NULL, it will reset to default printing on stderr. The error raised there are those for which no handler at the connection level could caught.

`userData`: | pointer to the user data provided in the handler callback
`handler`: | the function to get called in case of error or NULL