## virterror

virterror - error handling interfaces for the libvirt library

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

Author(s): Daniel Veillard <veillard@redhat.com>

## Synopsis

    typedef virError * virErrorPtr;
    typedef enum virErrorLevel;
    typedef enum virErrorDomain;
    typedef enum virErrorNumber;
    typedef struct _virError virError;
    int	virCopyLastError		(virErrorPtr to);
    void	virConnSetErrorFunc		(virConnectPtr conn,
    					 void * userData,
    					 virErrorFunc handler);
    void	virResetLastError		(void);
    typedef void virErrorFunc			(void * userData,
    					 virErrorPtr error);
    void	virResetError			(virErrorPtr err);
    virErrorPtr	virConnGetLastError	(virConnectPtr conn);
    void	virDefaultErrorFunc		(virErrorPtr err);
    virErrorPtr	virGetLastError		(void);
    void	virSetErrorFunc			(void * userData,
    					 virErrorFunc handler);
    int	virConnCopyLastError		(virConnectPtr conn,
    					 virErrorPtr to);
    void	virConnResetLastError		(virConnectPtr conn);

## Description

## Details

### Structure 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, see note above
        virDomainPtr	dom	: domain if available, 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, see note above
    } virError;

### Enum 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 */
    };

### Enum virErrorLevel

    enum virErrorLevel {
        VIR_ERR_NONE = 0
        VIR_ERR_WARNING = 1 /* A simple warning */
        VIR_ERR_ERROR = 2 /*  An error */
    };

### Enum 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 */
    };

### Typedef virErrorPtr

    virError * virErrorPtr;

### Function type virErrorFunc

    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.

### virConnCopyLastError ()

    int	virConnCopyLastError		(virConnectPtr conn,
    					 virErrorPtr to)

Copy the content of the last error caught on that connection 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 Simpler but may not be suitable for multithreaded accesses, in which case use virConnCopyLastError()

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

### virConnResetLastError ()

    void	virConnResetLastError		(virConnectPtr conn)

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 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.

### virGetLastError ()

    virErrorPtr	virGetLastError		(void)

Provide a pointer to the last error caught at the library level Simpler but may not be suitable for multithreaded accesses, in which case use virCopyLastError()

`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.

### 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