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{
intcode : The error code, a virErrorNumber
intdomain : What part of the library raised this error
char *message : human-readable informative error message
virErrorLevellevel : how consequent is the error
virConnectPtrconn : connection if available, deprecated see note above
virDomainPtrdom : domain if available, deprecated see note above
char *str1 : extra string information
char *str2 : extra string information
char *str3 : extra string information
intint1 : extra number information
intint2 : extra number information
virNetworkPtrnet : 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
}

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
}

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