Error reporting

## 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);
    void                gvir_critical                       (const gchar *format,
                                                             ...);
    void                gvir_warning                        (const gchar *format,
                                                             ...);

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

### gvir_critical ()

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

### gvir_warning ()

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