user: libuser Reference Manual

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.