user

## user user — Functions for initializing the library, looking up information, and making changes to the system information store. |

## Synopsis

    #include <libuser/user.h>

    struct              lu_context;
    typedef             lu_context_t;
    struct lu_context * lu_start                            (const char *authname,
                                                             enum lu_entity_type auth_type,
                                                             const char *modules,
                                                             const char *create_modules,
                                                             lu_prompt_fn *prompter,
                                                             gpointer callback_data,
                                                             struct lu_error **error);
    void                lu_end                              (struct lu_context *context);
    void                lu_set_prompter                     (struct lu_context *context,
                                                             lu_prompt_fn *prompter,
                                                             gpointer callback_data);
    void                lu_get_prompter                     (struct lu_context *context,
                                                             lu_prompt_fn **prompter,
                                                             gpointer *callback_data);
    gboolean            lu_set_modules                      (struct lu_context *context,
                                                             const char *list,
                                                             struct lu_error **error);
    const char *        lu_get_modules                      (struct lu_context *context);
    gboolean            lu_uses_elevated_privileges         (struct lu_context *context);
    gboolean            lu_user_lookup_name                 (struct lu_context *context,
                                                             const char *name,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_lookup_id                   (struct lu_context *context,
                                                             uid_t uid,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_default                     (struct lu_context *ctx,
                                                             const char *name,
                                                             gboolean system_account,
                                                             struct lu_ent *ent);
    gboolean            lu_user_add                         (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_modify                      (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_delete                      (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_setpass                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             const char *newpass,
                                                             gboolean crypted,
                                                             struct lu_error **error);
    gboolean            lu_user_removepass                  (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_lock                        (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_unlock                      (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_unlock_nonempty             (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_user_islocked                    (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    GValueArray *       lu_users_enumerate                  (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);
    GValueArray *       lu_users_enumerate_by_group         (struct lu_context *context,
                                                             const char *group,
                                                             struct lu_error **error);
    GPtrArray *         lu_users_enumerate_full             (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);
    GPtrArray *         lu_users_enumerate_by_group_full    (struct lu_context *context,
                                                             const char *group,
                                                             struct lu_error **error);
    gboolean            lu_group_lookup_name                (struct lu_context *context,
                                                             const char *name,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_lookup_id                  (struct lu_context *context,
                                                             gid_t gid,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_default                    (struct lu_context *ctx,
                                                             const char *name,
                                                             gboolean system_account,
                                                             struct lu_ent *ent);
    gboolean            lu_group_add                        (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_modify                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_delete                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_setpass                    (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             const char *newpass,
                                                             gboolean crypted,
                                                             struct lu_error **error);
    gboolean            lu_group_removepass                 (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_lock                       (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_unlock                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_unlock_nonempty            (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_group_islocked                   (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    GValueArray *       lu_groups_enumerate                 (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);
    GValueArray *       lu_groups_enumerate_by_user         (struct lu_context *context,
                                                             const char *user,
                                                             struct lu_error **error);
    GPtrArray *         lu_groups_enumerate_full            (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);
    GPtrArray *         lu_groups_enumerate_by_user_full    (struct lu_context *context,
                                                             const char *user,
                                                             struct lu_error **error);

## Description

`user.h` contains declarations for functions which start up and shut down the libuser library, and for functions which perform lookup queries and modifications of the system information store.

## Details

### struct lu_context

    struct lu_context;

An opaque structure manipulated by the library, containing caller-related state (to allow several independent callers in a single process).

### lu_context_t

    typedef struct lu_context lu_context_t;

### Warning

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

An alias for struct lu_context.

### lu_start ()

    struct lu_context * lu_start                            (const char *authname,
                                                             enum lu_entity_type auth_type,
                                                             const char *modules,
                                                             const char *create_modules,
                                                             lu_prompt_fn *prompter,
                                                             gpointer callback_data,
                                                             struct lu_error **error);

Initializes the libuser library.

`authname` : | Suggested client name to use when connecting to servers, or `NULL`
`auth_type` : | Whether auth_name is a user or a group
`modules` : | A list of modules to use for queries (separated by whitespace or commas), or `NULL` to use modules specified in the config file
`create_modules` : | A list of modules to use for entity creation (separated by whitespace or commas), or `NULL` to use modules specified in the config file
`prompter` : | A function to use for getting information from the user
`callback_data` : | Data for `prompter`
`error` : | Filled with a lu_error if an error occurs
Returns : | a context which should be freed by `lu_end()` on success, `NULL` on failure

### lu_end ()

    void                lu_end                              (struct lu_context *context);

Destroys a libuser library context

`context` : | a context

### lu_set_prompter ()

    void                lu_set_prompter                     (struct lu_context *context,
                                                             lu_prompt_fn *prompter,
                                                             gpointer callback_data);

Changes the prompter function in a context

`context` : | A context
`prompter` : | A new function to user for getting information from the user
`callback_data` : | Data for `prompter`

### lu_get_prompter ()

    void                lu_get_prompter                     (struct lu_context *context,
                                                             lu_prompt_fn **prompter,
                                                             gpointer *callback_data);

Gets current prompter function from a context.

`context` : | A context
`prompter` : | If not `NULL`, points to a place where the current prompter function will be stored
`callback_data` : | If not `NULL`, points to a place where the current prompter function data will be stored

### lu_set_modules ()

    gboolean            lu_set_modules                      (struct lu_context *context,
                                                             const char *list,
                                                             struct lu_error **error);

Replaces the current set of modules for queries in `context` to `list`.

`context` : | A context
`list` : | A list of modules (separated by whitespace or commas)
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success, `FALSE` on failure

### lu_get_modules ()

    const char *        lu_get_modules                      (struct lu_context *context);

Returns a list of modules for queries in `context`.

`context` : | A context
Returns : | A list of modules separated by spaces, or `NULL` if the list of modules is empty. The list should not be freed by the caller.

### lu_uses_elevated_privileges ()

    gboolean            lu_uses_elevated_privileges         (struct lu_context *context);

Checks if any module uses elevated privileges (e.g. modifies files that normal users can't modify).

`context` : | A context
Returns : | `TRUE` if at least one module uses elevated privileges

### lu_user_lookup_name ()

    gboolean            lu_user_lookup_name                 (struct lu_context *context,
                                                             const char *name,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Looks up an user by name.

`context` : | A context
`name` : | User name
`ent` : | An entity filled with received information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success. If the user doesn't exist, returns `FALSE` without setting `error`.

### lu_user_lookup_id ()

    gboolean            lu_user_lookup_id                   (struct lu_context *context,
                                                             uid_t uid,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Looks up an user by UID.

`context` : | A context
`uid` : | User ID
`ent` : | An entity filled with received information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success. If the user doesn't exist, returns `FALSE` without setting `error`.

### lu_user_default ()

    gboolean            lu_user_default                     (struct lu_context *ctx,
                                                             const char *name,
                                                             gboolean system_account,
                                                             struct lu_ent *ent);

Fills out an user entity as specified by the config file and modules to prepare for creation of the user.

`ctx` : | A context
`name` : | New user name
`system_account` : | Non-zero if the user is a system user
`ent` : | An entity
Returns : | `TRUE` on success

### lu_user_add ()

    gboolean            lu_user_add                         (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Creates an user in all modules specified for entity creation.

`context` : | A context
`ent` : | An entity describing the user, on success updated with resulting account
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_modify ()

    gboolean            lu_user_modify                      (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Modifies an user entity.

`context` : | A context
`ent` : | An entity with pending modifications, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_delete ()

    gboolean            lu_user_delete                      (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Deletes an user.

`context` : | A context
`ent` : | An entity describing the user
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_setpass ()

    gboolean            lu_user_setpass                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             const char *newpass,
                                                             gboolean crypted,
                                                             struct lu_error **error);

Changes an user's password.

`context` : | A context
`ent` : | An entity describing the user, on success updated with current information and `LU_SHADOWLASTCHANGE`
`newpass` : | New password
`crypted` : | Non-zero if `newpass` is already encrypted
`error` : | Filled with an lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_removepass ()

    gboolean            lu_user_removepass                  (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Changes an user's password to an empty string.

`context` : | A context
`ent` : | An entity describing the user, on success updated with current information and `LU_SHADOWLASTCHANGE`
`error` : | Filled with an lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_lock ()

    gboolean            lu_user_lock                        (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Locks an user account.

`context` : | A context
`ent` : | An entity describing the user, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_unlock ()

    gboolean            lu_user_unlock                      (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Unlocks an user account.

`context` : | A context
`ent` : | An entity describing the user, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_unlock_nonempty ()

    gboolean            lu_user_unlock_nonempty             (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Unlocks an user account. If unlocking the account would result in an empty password field, it fails with `lu_error_unlock_empty`. Note that the password can still be empty.

`context` : | A context
`ent` : | An entity describing the user, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_user_islocked ()

    gboolean            lu_user_islocked                    (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Checks if an user account is locked.

`context` : | A context
`ent` : | An entity describing the user
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` if the account is locked in at least one module

### lu_users_enumerate ()

    GValueArray *       lu_users_enumerate                  (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);

Returns a list of all users matching a pattern.

`context` : | A context
`pattern` : | A glob-like pattern for user name
`error` : | Filled with a lu_error if an error occurs
Returns : | An array of strings, each representing one user name. The array should be freed by the caller.

### lu_users_enumerate_by_group ()

    GValueArray *       lu_users_enumerate_by_group         (struct lu_context *context,
                                                             const char *group,
                                                             struct lu_error **error);

Returns a list of all members of a group `group`.

`context` : | A context
`group` : | Group name
`error` : | Filled with a lu_error if an error occurs
Returns : | An array of strings, each representing one user name. The array should be freed by the caller.

### lu_users_enumerate_full ()

    GPtrArray *         lu_users_enumerate_full             (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);

Returns a list of entities, one for each user matching a pattern.

`context` : | A context
`pattern` : | A glob-like pattern for user name
`error` : | Filled with a lu_error if an error occurs
Returns : | A list of pointers to user entities. The entities and the list should be freed by the caller.

### lu_users_enumerate_by_group_full ()

    GPtrArray *         lu_users_enumerate_by_group_full    (struct lu_context *context,
                                                             const char *group,
                                                             struct lu_error **error);

Returns a list of entities, one for each member of a group `group`.

`context` : | A context
`group` : | Group name
`error` : | Filled with a lu_error if an error occurs
Returns : | A list of pointers to user entities. The entities and the list should be freed by the caller.

### lu_group_lookup_name ()

    gboolean            lu_group_lookup_name                (struct lu_context *context,
                                                             const char *name,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Looks up a group by name.

`context` : | A context
`name` : | Group name
`ent` : | An entity filled with received information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success. If the group doesn't exist, returns `FALSE` without setting `error`.

### lu_group_lookup_id ()

    gboolean            lu_group_lookup_id                  (struct lu_context *context,
                                                             gid_t gid,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Looks up a group by GID.

`context` : | A context
`gid` : | Group ID
`ent` : | An entity filled with received information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success. If the group doesn't exist, returns `FALSE` without setting `error`.

### lu_group_default ()

    gboolean            lu_group_default                    (struct lu_context *ctx,
                                                             const char *name,
                                                             gboolean system_account,
                                                             struct lu_ent *ent);

Fills out a group entity as specified by the config file and modules to prepare for creation of the group.

`ctx` : | A context
`name` : | New group name
`system_account` : | Non-zero if the group is a system group
`ent` : | An entity
Returns : | `TRUE` on success

### lu_group_add ()

    gboolean            lu_group_add                        (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Creates a group in all modules specified for entity creation.

`context` : | A context
`ent` : | An entity describing the group, on success updated with resulting account
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_modify ()

    gboolean            lu_group_modify                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Modifies a group entity.

`context` : | A context
`ent` : | An entity with pending modifications, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_delete ()

    gboolean            lu_group_delete                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Deletes a group.

`context` : | A context
`ent` : | An entity describing the group
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_setpass ()

    gboolean            lu_group_setpass                    (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             const char *newpass,
                                                             gboolean crypted,
                                                             struct lu_error **error);

Changes a group password.

`context` : | A context
`ent` : | An entity describing the group, on success updated with current information and `LU_SHADOWLASTCHANGE`
`newpass` : | New password
`crypted` : | Non-zero if `newpass` is already encrypted
`error` : | Filled with an lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_removepass ()

    gboolean            lu_group_removepass                 (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Changes a group password to an empty string.

`context` : | A context
`ent` : | An entity describing the group, on success udpated with current information and `LU_SHADOWLASTCHANGE`
`error` : | Filled with in lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_lock ()

    gboolean            lu_group_lock                       (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Locks a group account

`context` : | A context
`ent` : | An entity describing the group, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_unlock ()

    gboolean            lu_group_unlock                     (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Unlocks a group account.

`context` : | A context
`ent` : | An entity describing the group, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_unlock_nonempty ()

    gboolean            lu_group_unlock_nonempty            (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Unlocks a group account. If unlocking the account would result in an empty password field, it fails with `lu_error_unlock_empty`. Note that the password can still be empty.

`context` : | A context
`ent` : | An entity describing the group, on success updated with current information
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` on success

### lu_group_islocked ()

    gboolean            lu_group_islocked                   (struct lu_context *context,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Checks if a group account is locked.

`context` : | A context
`ent` : | An entity describing the group
`error` : | Filled with a lu_error if an error occurs
Returns : | `TRUE` if the account is locked in at least one module

### lu_groups_enumerate ()

    GValueArray *       lu_groups_enumerate                 (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);

Returns a list of all groups matching a pattern.

`context` : | A context
`pattern` : | A glob-like pattern for group name
`error` : | Filled with a lu_error if an error occurs
Returns : | An array of strings, each representing one group name. The array should be freed by the caller.

### lu_groups_enumerate_by_user ()

    GValueArray *       lu_groups_enumerate_by_user         (struct lu_context *context,
                                                             const char *user,
                                                             struct lu_error **error);

Returns a list of all groups containing an user `user`.

`context` : | A context
`user` : | User name
`error` : | Filled with a lu_error if an error occurs
Returns : | An array of strings, each representing one group name. The array should be freed by the caller.

### lu_groups_enumerate_full ()

    GPtrArray *         lu_groups_enumerate_full            (struct lu_context *context,
                                                             const char *pattern,
                                                             struct lu_error **error);

Returns a list of entities, one for each group matching a pattern.

`context` : | A context
`pattern` : | A glob-like pattern for group name
`error` : | Filled with a lu_error if an error occurs
Returns : | a list of pointers to group entities. The entities and the list should be freed by the caller.

### lu_groups_enumerate_by_user_full ()

    GPtrArray *         lu_groups_enumerate_by_user_full    (struct lu_context *context,
                                                             const char *user,
                                                             struct lu_error **error);

Returns a list of entities, one for each group containing an user `user`.

`context` : | A context
`user` : | User name
`error` : | Filled with a lu_error if an error occurs
Returns : | a list of pointers to group entities. The entities and the list should be freed by the caller.