Error reporting

Error reporting — Convert libvirt error reports to GLib error reports

Stability Level

Stable, unless otherwise indicated

Synopsis

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

GError *            gvir_error_new                      (GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);
GError *            gvir_error_new_literal              (GQuark domain,
                                                         gint code,
                                                         const gchar *message);
GError *            gvir_error_new_valist               (GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         va_list args);
void                gvir_set_error                      (GError **error,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);
void                gvir_set_error_literal              (GError **error,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *message);
void                gvir_set_error_valist               (GError **error,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         va_list args);

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

1
2
3
4
5
6
7
8
9
 
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;
}


Details

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.

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.

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.

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.

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.

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.

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
Generated by GTK-Doc V1.18.1