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.
Generated by GTK-Doc V1.19