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