## user

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

## Functions

struct lu_context * | lu_start ()
void | lu_end ()
void | lu_set_prompter ()
void | lu_get_prompter ()
gboolean | lu_set_modules ()
const char * | lu_get_modules ()
gboolean | lu_uses_elevated_privileges ()
gboolean | lu_user_lookup_name ()
gboolean | lu_user_lookup_id ()
gboolean | lu_user_default ()
gboolean | lu_user_add ()
gboolean | lu_user_modify ()
gboolean | lu_user_delete ()
gboolean | lu_user_setpass ()
gboolean | lu_user_removepass ()
gboolean | lu_user_lock ()
gboolean | lu_user_unlock ()
gboolean | lu_user_unlock_nonempty ()
gboolean | lu_user_islocked ()
GValueArray * | lu_users_enumerate ()
GValueArray * | lu_users_enumerate_by_group ()
GPtrArray * | lu_users_enumerate_full ()
GPtrArray * | lu_users_enumerate_by_group_full ()
gboolean | lu_group_lookup_name ()
gboolean | lu_group_lookup_id ()
gboolean | lu_group_default ()
gboolean | lu_group_add ()
gboolean | lu_group_modify ()
gboolean | lu_group_delete ()
gboolean | lu_group_setpass ()
gboolean | lu_group_removepass ()
gboolean | lu_group_lock ()
gboolean | lu_group_unlock ()
gboolean | lu_group_unlock_nonempty ()
gboolean | lu_group_islocked ()
GValueArray * | lu_groups_enumerate ()
GValueArray * | lu_groups_enumerate_by_user ()
GPtrArray * | lu_groups_enumerate_full ()
GPtrArray * | lu_groups_enumerate_by_user_full ()

## Types and Values

enum | lu_entity_type
struct | lu_context
typedef | lu_context_t

## Includes

    #include <libuser/user.h>

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

## Functions

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

## Types and Values

### enum lu_entity_type

Defines whether we are talking about an user or a group in cases where it is ambiguous.

#### Members

lu_user | An user. |
lu_group | A group of users. |

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

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