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.