Error reporting: Libvirt GLib Reference Manual

Error reporting

Error reporting — Convert libvirt error reports to GLib error reports

Stability Level

Stable, unless otherwise indicated

Functions

GError *	gvir_error_new ()
GError *	gvir_error_new_literal ()
GError *	gvir_error_new_valist ()
void	gvir_set_error ()
void	gvir_set_error_literal ()
void	gvir_set_error_valist ()
void	gvir_critical ()
void	gvir_warning ()

Includes

#include <libvirt-glib/libvirt-glib.h>

Description

The libvirt API uses the virError structure for reporting errors back to the application programmer. The libvirt API errors are provided in thread-local variables, while the GLib standard practice is to return errors via out parameters. This library provides a simple way to fill in GError ** output parameters with the contents of the most recent libvirt error object in the current thread.

The gvir_error_new, gvir_error_new_literal and

gvir_error_new_valist methods all return a newly created GError * object instance, differing only in the way the

message needs to be provided. For most usage though, it is preferable to use the gvir_set_error, gvir_set_error_literal and gvir_set_error_valist methods. These all accept a

GError ** argument and take care to only fill it if it

points to a non-NULL location.

Example 2. Reporting GLib errors with libvirt APIs

gboolean myapp_start_guest(const gchar *xml, GError **error)
{
    if (virDomainCreate(conn, xml, 0) &lt; 0) {
        gvir_set_error_literal(error, "Unable to start virtual machine");
       return FALSE;
    }

    return TRUE;
}

Functions

gvir_error_new ()

GError *
gvir_error_new (GQuark domain,
                gint code,
                const gchar *format,
                ...);

Creates a new GError with the given domain and code , and a message formatted with format .

Parameters

domain	error domain
code	error code
format	printf()-style format for error message
...	parameters for message format

Returns

a new GError

gvir_error_new_literal ()

GError *
gvir_error_new_literal (GQuark domain,
                        gint code,
                        const gchar *message);

Creates a new GError; unlike gvir_error_new(), message is not a printf()-style format string. Use this function if message contains text you don't have control over, that could include printf() escape sequences.

Parameters

domain	error domain
code	error code
message	error message

Returns

a new GError

gvir_error_new_valist ()

GError *
gvir_error_new_valist (GQuark domain,
                       gint code,
                       const gchar *format,
                       va_list args);

Creates a new GError with the given domain and code , and a message formatted with format .

Parameters

domain	error domain
code	error code
format	printf()-style format for error message
args	va_list of parameters for the message format

Returns

a new GError

gvir_set_error ()

void
gvir_set_error (GError **error,
                GQuark domain,
                gint code,
                const gchar *format,
                ...);

If error is NULL this does nothing. Otherwise it creates a new GError with the given domain and code , and a message formatted with format , and stores it in error .

Parameters

error	pointer to error location
domain	error domain
code	error code
format	printf()-style format for error message
...	parameters for message format

gvir_set_error_literal ()

void
gvir_set_error_literal (GError **error,
                        GQuark domain,
                        gint code,
                        const gchar *message);

If error is NULL this does nothing. Otherwise it creates a new GError and stores it in error ; unlike gvir_set_error(), message is not a printf()-style format string. Use this function if message contains text you don't have control over, that could include printf() escape sequences.

Parameters

error	pointer to error location
domain	error domain
code	error code
message	error message

gvir_set_error_valist ()

void
gvir_set_error_valist (GError **error,
                       GQuark domain,
                       gint code,
                       const gchar *format,
                       va_list args);

If error is NULL this does nothing. Otherwise it creates a new GError with the given domain and code , and a message formatted with format , and stores it in error .

Parameters

error	pointer to error location
domain	error domain
code	error code
format	printf()-style format for error message
args	va_list of parameters for the message format

gvir_critical ()

void
gvir_critical (const gchar *format,
               ...);

gvir_warning ()

void
gvir_warning (const gchar *format,
              ...);