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 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;
}

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,
              ...);

Types and Values

Generated by GTK-Doc V1.28