error

## error error — Functions for allocating and manipulating lu_error structures. |

## Synopsis

    #include <libuser/error.h>

    struct              lu_error;
    typedef             lu_error_t;
    #define             LU_ERROR_CHECK                      (err_p_p)
    void                lu_error_new                        (struct lu_error **error,
                                                             enum lu_status code,
                                                             const char *fmt,
                                                             ...);
    void                lu_error_free                       (struct lu_error **error);
    gboolean            lu_error_is_success                 (enum lu_status status);
    gboolean            lu_error_is_warning                 (enum lu_status status);
    gboolean            lu_error_is_error                   (enum lu_status status);
    const char *        lu_strerror                         (struct lu_error *error);

## Description

`error.h` includes declarations for allocating and manipulating lu_error structures. These structures hold error and status information passed between libuser, its modules, and applications.

A struct lu_error contains an error code and a human-readable, possibly translated error string. The error string uses the encoding specified by the `LC_CTYPE` locale category.

## Details

### struct lu_error

    struct lu_error;

Error and status information.

### lu_error_t

    typedef struct lu_error lu_error_t;

### Warning

`lu_error_t` has been deprecated since version 0.57.3 and should not be used in newly-written code. Use struct lu_error directly.

An alias for struct lu_error.

### LU_ERROR_CHECK()

    #define             LU_ERROR_CHECK(err_p_p)

Checks that the given pointer to a pointer to a struct does not already point to a valid lu_error structure, and calls `abort()` on failure. This macro is used by many internal functions to check that an error has not already occurred when they are invoked.

`err_p_p` : | A pointer to a struct lu_error * which will be checked.

### lu_error_new ()

    void                lu_error_new                        (struct lu_error **error,
                                                             enum lu_status code,
                                                             const char *fmt,
                                                             ...);

Creates a new lu_error structure.

`error` : | A pointer to a struct lu_error * which will hold the newly-created error structure. It must point to NULL before calling this function.
`code` : | An error code
`fmt` : | Format string describing the error. If NULL, a default string is used.
`...` : | Arguments for `fmt`, if necessary

### lu_error_free ()

    void                lu_error_free                       (struct lu_error **error);

Frees an lu_error structure.

`error` : | A pointer to a pointer to the structure to be freed. The pointer is set to `NULL` after the error is freed.

### lu_error_is_success ()

    gboolean            lu_error_is_success                 (enum lu_status status);

Check if the error code held by an error structure is a success code.

`status` : | An error code
Returns : | a gboolean indicating whether or not the error is a success code.

### lu_error_is_warning ()

    gboolean            lu_error_is_warning                 (enum lu_status status);

Check if the error code held by an error structure is a warning code.

`status` : | An error code
Returns : | a gboolean indicating whether or not the error is a warning code.

### lu_error_is_error ()

    gboolean            lu_error_is_error                   (enum lu_status status);

Check if the error code held by an error structure is an error code.

`status` : | An error code
Returns : | a gboolean indicating whether or not the error is an error code.

### lu_strerror ()

    const char *        lu_strerror                         (struct lu_error *error);

Converts an lu_error structure to a string describing the error. If the `error->string` is `NULL`, returns a text representation of `error->code`.

`error` : | An error
Returns : | An error string valid at least until `error` is freed.