## error

error — Functions for allocating and manipulating lu_error structures.

## Functions

#define | LU_ERROR_CHECK()
void | lu_error_new ()
void | lu_error_free ()
gboolean | lu_error_is_success ()
gboolean | lu_error_is_warning ()
gboolean | lu_error_is_error ()
const char * | lu_strerror ()

## Types and Values

enum | lu_status
struct | lu_error
typedef | lu_error_t

## Includes

    #include <libuser/error.h>

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

error | An error |

#### Returns

An error string valid at least until `error` is freed.

## Types and Values

### enum lu_status

Program-readable error/status codes. Note that new ones may be added in the future, even for existing operations.

#### Members

lu_success | Success. |
lu_warning_config_disabled | Module disabled by configuration. |
lu_error_generic | Generic error. |
lu_error_privilege | Not enough privileges. |
lu_error_access_denied | Access denied. |
lu_error_name_bad | Bad user/group name. |
lu_error_id_bad | Bad user/group id. |
lu_error_name_used | User/group name in use. |
lu_error_id_used | User/group id in use. |
lu_error_terminal | Error manipulating terminal attributes. |
lu_error_open | Error opening file. |
lu_error_lock | Error locking file. |
lu_error_stat | Error statting file. |
lu_error_read | Error reading file. |
lu_error_write | Error writing to file. |
lu_error_search | Data not found in file. |
lu_error_init | Internal initialization error. |
lu_error_module_load | Error loading module. |
lu_error_module_sym | Error resolving symbol in module. |
lu_error_module_version | Library/module version mismatch. |
lu_error_unlock_empty | Unlocking would make the password field empty. Since: 0.53 |
lu_error_invalid_attribute_value | Invalid attribute value. Since: 0.56 |
lu_error_invalid_module_combination | Invalid module combination. Since: 0.57 |
lu_error_homedir_not_owned | User's home directory not owned by them. Since: 0.60 |

### struct lu_error

    struct lu_error {
    	enum lu_status code;
    	char *string;
    };

Error and status information.

#### Members

enum lu_status `code`; | A program-readable error code. |
char *`string`; | A human-readable, possibly translated error string. The error string uses the encoding specified by the `LC_CTYPE` locale category. |

### lu_error_t

    typedef struct lu_error lu_error_t;

`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.