user

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

## Synopsis

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

### lu_start ()

    lu_context_t*       lu_start                            (const char *authname,
                                                             lu_entity_type_t auth_type,
                                                             const char *modules,
                                                             const char *create_modules,
                                                             lu_prompt_fn *prompter,
                                                             gpointer callback_data,
                                                             lu_error_t **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                              (lu_context_t *context);

Destroys a libuser library context

`context` : | a context

### lu_set_prompter ()

    void                lu_set_prompter                     (lu_context_t *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                     (lu_context_t *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                      (lu_context_t *context,
                                                             const char *list,
                                                             lu_error_t **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                      (lu_context_t *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         (lu_context_t *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                 (lu_context_t *context,
                                                             const char *name,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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

### lu_user_lookup_id ()

    gboolean            lu_user_lookup_id                   (lu_context_t *context,
                                                             uid_t uid,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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

### lu_user_default ()

    gboolean            lu_user_default                     (lu_context_t *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                         (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                      (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                      (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                     (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             const char *newpass,
                                                             gboolean crypted,
                                                             lu_error_t **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                  (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                        (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                      (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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             (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                    (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                  (lu_context_t *context,
                                                             const char *pattern,
                                                             lu_error_t **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         (lu_context_t *context,
                                                             const char *group,
                                                             lu_error_t **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             (lu_context_t *context,
                                                             const char *pattern,
                                                             lu_error_t **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_group_lookup_name ()

    gboolean            lu_group_lookup_name                (lu_context_t *context,
                                                             const char *name,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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

### lu_group_lookup_id ()

    gboolean            lu_group_lookup_id                  (lu_context_t *context,
                                                             gid_t gid,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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

### lu_group_default ()

    gboolean            lu_group_default                    (lu_context_t *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                        (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                     (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                     (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                    (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             const char *newpass,
                                                             gboolean crypted,
                                                             lu_error_t **error);

Changes a group password.

`context` : | a contect
`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                 (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                       (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                     (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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            (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                   (lu_context_t *context,
                                                             struct lu_ent *ent,
                                                             lu_error_t **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                 (lu_context_t *context,
                                                             const char *pattern,
                                                             lu_error_t **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         (lu_context_t *context,
                                                             const char *user,
                                                             lu_error_t **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            (lu_context_t *context,
                                                             const char *pattern,
                                                             lu_error_t **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.