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) int virGetLastErrorCode (void) int virGetLastErrorDomain (void) const char * virGetLastErrorMessage (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

Indicates where an error may have come from. This should remain stable, with all additions placed at the end since libvirt 0.1.0.

enum virErrorDomain {
VIR_FROM_NONE = 0 (0x0)
VIR_FROM_XEN = 1 (0x1)
Error at Xen hypervisor layer
VIR_FROM_XEND = 2 (0x2)
Error at connection with xend daemon
VIR_FROM_XENSTORE = 3 (0x3)
Error at connection with xen store
VIR_FROM_SEXPR = 4 (0x4)
Error in the S-Expression code
VIR_FROM_XML = 5 (0x5)
Error in the XML code
VIR_FROM_DOM = 6 (0x6)
Error when operating on a domain
VIR_FROM_RPC = 7 (0x7)
Error in the XML-RPC code
VIR_FROM_PROXY = 8 (0x8)
Error in the proxy code; unused since 0.8.6
VIR_FROM_CONF = 9 (0x9)
Error in the configuration file handling
VIR_FROM_QEMU = 10 (0xa)
Error at the QEMU daemon
VIR_FROM_NET = 11 (0xb)
Error when operating on a network
VIR_FROM_TEST = 12 (0xc)
Error from test driver
VIR_FROM_REMOTE = 13 (0xd)
Error from remote driver
VIR_FROM_OPENVZ = 14 (0xe)
Error from OpenVZ driver
VIR_FROM_XENXM = 15 (0xf)
Error at Xen XM layer
VIR_FROM_STATS_LINUX = 16 (0x10)
Error in the Linux Stats code
VIR_FROM_LXC = 17 (0x11)
Error from Linux Container driver
VIR_FROM_STORAGE = 18 (0x12)
Error from storage driver
VIR_FROM_NETWORK = 19 (0x13)
Error from network config
VIR_FROM_DOMAIN = 20 (0x14)
Error from domain config
VIR_FROM_UML = 21 (0x15)
Error at the UML driver; unused since 5.0.0
VIR_FROM_NODEDEV = 22 (0x16)
Error from node device monitor
VIR_FROM_XEN_INOTIFY = 23 (0x17)
Error from xen inotify layer
VIR_FROM_SECURITY = 24 (0x18)
Error from security framework
VIR_FROM_VBOX = 25 (0x19)
Error from VirtualBox driver
VIR_FROM_INTERFACE = 26 (0x1a)
Error when operating on an interface
VIR_FROM_ONE = 27 (0x1b)
The OpenNebula driver no longer exists. Retained for ABI/API compat only
VIR_FROM_ESX = 28 (0x1c)
Error from ESX driver
VIR_FROM_PHYP = 29 (0x1d)
Error from the phyp driver, unused since 6.0.0
VIR_FROM_SECRET = 30 (0x1e)
Error from secret storage
VIR_FROM_CPU = 31 (0x1f)
Error from CPU driver
VIR_FROM_XENAPI = 32 (0x20)
Error from XenAPI
VIR_FROM_NWFILTER = 33 (0x21)
Error from network filter driver
VIR_FROM_HOOK = 34 (0x22)
Error from Synchronous hooks
VIR_FROM_DOMAIN_SNAPSHOT = 35 (0x23)
Error from domain snapshot
VIR_FROM_AUDIT = 36 (0x24)
Error from auditing subsystem
VIR_FROM_SYSINFO = 37 (0x25)
Error from sysinfo/SMBIOS
VIR_FROM_STREAMS = 38 (0x26)
Error from I/O streams
VIR_FROM_VMWARE = 39 (0x27)
Error from VMware driver
VIR_FROM_EVENT = 40 (0x28)
Error from event loop impl
VIR_FROM_LIBXL = 41 (0x29)
Error from libxenlight driver
VIR_FROM_LOCKING = 42 (0x2a)
Error from lock manager
VIR_FROM_HYPERV = 43 (0x2b)
Error from Hyper-V driver
VIR_FROM_CAPABILITIES = 44 (0x2c)
Error from capabilities
VIR_FROM_URI = 45 (0x2d)
Error from URI handling
VIR_FROM_AUTH = 46 (0x2e)
Error from auth handling
VIR_FROM_DBUS = 47 (0x2f)
Error from DBus
VIR_FROM_PARALLELS = 48 (0x30)
Error from Parallels
VIR_FROM_DEVICE = 49 (0x31)
Error from Device
VIR_FROM_SSH = 50 (0x32)
Error from libssh2 connection transport
VIR_FROM_LOCKSPACE = 51 (0x33)
Error from lockspace
VIR_FROM_INITCTL = 52 (0x34)
Error from initctl device communication
VIR_FROM_IDENTITY = 53 (0x35)
Error from identity code
VIR_FROM_CGROUP = 54 (0x36)
Error from cgroups
VIR_FROM_ACCESS = 55 (0x37)
Error from access control manager
VIR_FROM_SYSTEMD = 56 (0x38)
Error from systemd code
VIR_FROM_BHYVE = 57 (0x39)
Error from bhyve driver
VIR_FROM_CRYPTO = 58 (0x3a)
Error from crypto code
VIR_FROM_FIREWALL = 59 (0x3b)
Error from firewall
VIR_FROM_POLKIT = 60 (0x3c)
Error from polkit code
VIR_FROM_THREAD = 61 (0x3d)
Error from thread utils
VIR_FROM_ADMIN = 62 (0x3e)
Error from admin backend
VIR_FROM_LOGGING = 63 (0x3f)
Error from log manager
VIR_FROM_XENXL = 64 (0x40)
Error from Xen xl config code
VIR_FROM_PERF = 65 (0x41)
Error from perf
VIR_FROM_LIBSSH = 66 (0x42)
Error from libssh connection transport
VIR_FROM_RESCTRL = 67 (0x43)
Error from resource control
VIR_FROM_FIREWALLD = 68 (0x44)
Error from firewalld
VIR_FROM_DOMAIN_CHECKPOINT = 69 (0x45)
Error from domain checkpoint
VIR_FROM_TPM = 70 (0x46)
Error from TPM
VIR_FROM_BPF = 71 (0x47)
Error from BPF code
VIR_FROM_CH = 72 (0x48)
Error from Cloud-Hypervisor driver
VIR_ERR_DOMAIN_LAST = 73 (0x49)
}

virErrorLevel

Indicates the level of an error

enum virErrorLevel {
VIR_ERR_NONE = 0 (0x0)
VIR_ERR_WARNING = 1 (0x1)
A simple warning
VIR_ERR_ERROR = 2 (0x2)
An error
}

virErrorNumber

The full list of errors the library can generate This list should remain stable, with all additions placed at the end since libvirt 0.1.0. There is one exception: values added between libvirt 0.7.1 and libvirt 0.7.7 (VIR_WAR_NO_SECRET through VIR_ERR_MIGRATE_PERSIST_FAILED) were inadvertently relocated by four positions in 0.8.0. If you suspect version mismatch between a server and client, then you can decipher values as follows: switch (err.code) { case 60: // no way to tell VIR_WAR_NO_SECRET apart from VIR_WAR_NO_NWFILTER, // but both are very similar warnings break; case 61: case 62: case 63: if (err.domain != VIR_FROM_NWFILTER) err.code += 4; break; case 64: if (err.domain == VIR_FROM_QEMU) err.code += 4; break; case 65: if (err.domain == VIR_FROM_XEN) err.code += 4; break; default: }

enum virErrorNumber {
VIR_ERR_OK = 0 (0x0)
VIR_ERR_INTERNAL_ERROR = 1 (0x1)
internal error
VIR_ERR_NO_MEMORY = 2 (0x2)
memory allocation failure
VIR_ERR_NO_SUPPORT = 3 (0x3)
no support for this function
VIR_ERR_UNKNOWN_HOST = 4 (0x4)
could not resolve hostname
VIR_ERR_NO_CONNECT = 5 (0x5)
can't connect to hypervisor
VIR_ERR_INVALID_CONN = 6 (0x6)
invalid connection object
VIR_ERR_INVALID_DOMAIN = 7 (0x7)
invalid domain object
VIR_ERR_INVALID_ARG = 8 (0x8)
invalid function argument
VIR_ERR_OPERATION_FAILED = 9 (0x9)
a command to hypervisor failed
VIR_ERR_GET_FAILED = 10 (0xa)
a HTTP GET command to failed
VIR_ERR_POST_FAILED = 11 (0xb)
a HTTP POST command to failed
VIR_ERR_HTTP_ERROR = 12 (0xc)
unexpected HTTP error code
VIR_ERR_SEXPR_SERIAL = 13 (0xd)
failure to serialize an S-Expr
VIR_ERR_NO_XEN = 14 (0xe)
could not open Xen hypervisor control
VIR_ERR_XEN_CALL = 15 (0xf)
failure doing an hypervisor call
VIR_ERR_OS_TYPE = 16 (0x10)
unknown OS type
VIR_ERR_NO_KERNEL = 17 (0x11)
missing kernel information
VIR_ERR_NO_ROOT = 18 (0x12)
missing root device information
VIR_ERR_NO_SOURCE = 19 (0x13)
missing source device information
VIR_ERR_NO_TARGET = 20 (0x14)
missing target device information
VIR_ERR_NO_NAME = 21 (0x15)
missing domain name information
VIR_ERR_NO_OS = 22 (0x16)
missing domain OS information
VIR_ERR_NO_DEVICE = 23 (0x17)
missing domain devices information
VIR_ERR_NO_XENSTORE = 24 (0x18)
could not open Xen Store control
VIR_ERR_DRIVER_FULL = 25 (0x19)
too many drivers registered
VIR_ERR_CALL_FAILED = 26 (0x1a)
not supported by the drivers (DEPRECATED)
VIR_ERR_XML_ERROR = 27 (0x1b)
an XML description is not well formed or broken
VIR_ERR_DOM_EXIST = 28 (0x1c)
the domain already exist
VIR_ERR_OPERATION_DENIED = 29 (0x1d)
operation forbidden on read-only connections
VIR_ERR_OPEN_FAILED = 30 (0x1e)
failed to open a conf file
VIR_ERR_READ_FAILED = 31 (0x1f)
failed to read a conf file
VIR_ERR_PARSE_FAILED = 32 (0x20)
failed to parse a conf file
VIR_ERR_CONF_SYNTAX = 33 (0x21)
failed to parse the syntax of a conf file
VIR_ERR_WRITE_FAILED = 34 (0x22)
failed to write a conf file
VIR_ERR_XML_DETAIL = 35 (0x23)
detail of an XML error
VIR_ERR_INVALID_NETWORK = 36 (0x24)
invalid network object
VIR_ERR_NETWORK_EXIST = 37 (0x25)
the network already exist
VIR_ERR_SYSTEM_ERROR = 38 (0x26)
general system call failure
VIR_ERR_RPC = 39 (0x27)
some sort of RPC error
VIR_ERR_GNUTLS_ERROR = 40 (0x28)
error from a GNUTLS call
VIR_WAR_NO_NETWORK = 41 (0x29)
failed to start network
VIR_ERR_NO_DOMAIN = 42 (0x2a)
domain not found or unexpectedly disappeared
VIR_ERR_NO_NETWORK = 43 (0x2b)
network not found
VIR_ERR_INVALID_MAC = 44 (0x2c)
invalid MAC address
VIR_ERR_AUTH_FAILED = 45 (0x2d)
authentication failed
VIR_ERR_INVALID_STORAGE_POOL = 46 (0x2e)
invalid storage pool object
VIR_ERR_INVALID_STORAGE_VOL = 47 (0x2f)
invalid storage vol object
VIR_WAR_NO_STORAGE = 48 (0x30)
failed to start storage
VIR_ERR_NO_STORAGE_POOL = 49 (0x31)
storage pool not found
VIR_ERR_NO_STORAGE_VOL = 50 (0x32)
storage volume not found
VIR_WAR_NO_NODE = 51 (0x33)
failed to start node driver
VIR_ERR_INVALID_NODE_DEVICE = 52 (0x34)
invalid node device object
VIR_ERR_NO_NODE_DEVICE = 53 (0x35)
node device not found
VIR_ERR_NO_SECURITY_MODEL = 54 (0x36)
security model not found
VIR_ERR_OPERATION_INVALID = 55 (0x37)
operation is not applicable at this time
VIR_WAR_NO_INTERFACE = 56 (0x38)
failed to start interface driver
VIR_ERR_NO_INTERFACE = 57 (0x39)
interface driver not running
VIR_ERR_INVALID_INTERFACE = 58 (0x3a)
invalid interface object
VIR_ERR_MULTIPLE_INTERFACES = 59 (0x3b)
more than one matching interface found
VIR_WAR_NO_NWFILTER = 60 (0x3c)
failed to start nwfilter driver
VIR_ERR_INVALID_NWFILTER = 61 (0x3d)
invalid nwfilter object
VIR_ERR_NO_NWFILTER = 62 (0x3e)
nw filter pool not found
VIR_ERR_BUILD_FIREWALL = 63 (0x3f)
nw filter pool not found
VIR_WAR_NO_SECRET = 64 (0x40)
failed to start secret storage
VIR_ERR_INVALID_SECRET = 65 (0x41)
invalid secret
VIR_ERR_NO_SECRET = 66 (0x42)
secret not found
VIR_ERR_CONFIG_UNSUPPORTED = 67 (0x43)
unsupported configuration construct
VIR_ERR_OPERATION_TIMEOUT = 68 (0x44)
timeout occurred during operation
VIR_ERR_MIGRATE_PERSIST_FAILED = 69 (0x45)
a migration worked, but making the VM persist on the dest host failed
VIR_ERR_HOOK_SCRIPT_FAILED = 70 (0x46)
a synchronous hook script failed
VIR_ERR_INVALID_DOMAIN_SNAPSHOT = 71 (0x47)
invalid domain snapshot
VIR_ERR_NO_DOMAIN_SNAPSHOT = 72 (0x48)
domain snapshot not found
VIR_ERR_INVALID_STREAM = 73 (0x49)
stream pointer not valid
VIR_ERR_ARGUMENT_UNSUPPORTED = 74 (0x4a)
valid API use but unsupported by the given driver
VIR_ERR_STORAGE_PROBE_FAILED = 75 (0x4b)
storage pool probe failed
VIR_ERR_STORAGE_POOL_BUILT = 76 (0x4c)
storage pool already built
VIR_ERR_SNAPSHOT_REVERT_RISKY = 77 (0x4d)
force was not requested for a risky domain snapshot revert
VIR_ERR_OPERATION_ABORTED = 78 (0x4e)
operation on a domain was canceled/aborted by user
VIR_ERR_AUTH_CANCELLED = 79 (0x4f)
authentication cancelled
VIR_ERR_NO_DOMAIN_METADATA = 80 (0x50)
The metadata is not present
VIR_ERR_MIGRATE_UNSAFE = 81 (0x51)
Migration is not safe
VIR_ERR_OVERFLOW = 82 (0x52)
integer overflow
VIR_ERR_BLOCK_COPY_ACTIVE = 83 (0x53)
action prevented by block copy job
VIR_ERR_OPERATION_UNSUPPORTED = 84 (0x54)
The requested operation is not supported
VIR_ERR_SSH = 85 (0x55)
error in ssh transport driver
VIR_ERR_AGENT_UNRESPONSIVE = 86 (0x56)
guest agent is unresponsive, not running or not usable
VIR_ERR_RESOURCE_BUSY = 87 (0x57)
resource is already in use
VIR_ERR_ACCESS_DENIED = 88 (0x58)
operation on the object/resource was denied
VIR_ERR_DBUS_SERVICE = 89 (0x59)
error from a dbus service
VIR_ERR_STORAGE_VOL_EXIST = 90 (0x5a)
the storage vol already exists
VIR_ERR_CPU_INCOMPATIBLE = 91 (0x5b)
given CPU is incompatible with host CPU
VIR_ERR_XML_INVALID_SCHEMA = 92 (0x5c)
XML document doesn't validate against schema
VIR_ERR_MIGRATE_FINISH_OK = 93 (0x5d)
Finish API succeeded but it is expected to return NULL
VIR_ERR_AUTH_UNAVAILABLE = 94 (0x5e)
authentication unavailable
VIR_ERR_NO_SERVER = 95 (0x5f)
Server was not found
VIR_ERR_NO_CLIENT = 96 (0x60)
Client was not found
VIR_ERR_AGENT_UNSYNCED = 97 (0x61)
guest agent replies with wrong id to guest-sync command (DEPRECATED)
VIR_ERR_LIBSSH = 98 (0x62)
error in libssh transport driver
VIR_ERR_DEVICE_MISSING = 99 (0x63)
fail to find the desired device
VIR_ERR_INVALID_NWFILTER_BINDING = 100 (0x64)
invalid nwfilter binding
VIR_ERR_NO_NWFILTER_BINDING = 101 (0x65)
no nwfilter binding
VIR_ERR_INVALID_DOMAIN_CHECKPOINT = 102 (0x66)
invalid domain checkpoint
VIR_ERR_NO_DOMAIN_CHECKPOINT = 103 (0x67)
domain checkpoint not found
VIR_ERR_NO_DOMAIN_BACKUP = 104 (0x68)
domain backup job id not found
VIR_ERR_INVALID_NETWORK_PORT = 105 (0x69)
invalid network port object
VIR_ERR_NETWORK_PORT_EXIST = 106 (0x6a)
the network port already exist
VIR_ERR_NO_NETWORK_PORT = 107 (0x6b)
network port not found
VIR_ERR_NO_HOSTNAME = 108 (0x6c)
no domain's hostname found
VIR_ERR_CHECKPOINT_INCONSISTENT = 109 (0x6d)
checkpoint can't be used
VIR_ERR_MULTIPLE_DOMAINS = 110 (0x6e)
more than one matching domain found
VIR_ERR_NO_NETWORK_METADATA = 111 (0x6f)
Network metadata is not present
VIR_ERR_NUMBER_LAST = 112 (0x70)
}

virErrorPtr

typedef virError * virErrorPtr;

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

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

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
error code or -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.

virGetLastErrorCode

int	virGetLastErrorCode		(void)

Get the most recent error code (enum virErrorNumber).

Returns
the most recent error code, or VIR_ERR_OK if none is set.

virGetLastErrorDomain

int	virGetLastErrorDomain		(void)

Get the most recent error domain (enum virErrorDomain).

Returns
a numerical value of the most recent error's origin, or VIR_FROM_NONE if none is set.

virGetLastErrorMessage

const char *	virGetLastErrorMessage	(void)

Get the most recent error message

Returns
the most recent error message string in this thread, or a generic message if none is set

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. On success, errno is unchanged; on failure, errno is ENOMEM.

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