|  |  |  | libuser Reference Manual | |
|---|---|---|---|---|
| useruser — Functions for initializing the library, looking up information, and making changes to the system information store. | 
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);
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.
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.
| 
 | suggested client name to use when connecting to servers, or NULL | 
| 
 | whether auth_name is a user or a group | 
| 
 | a list of modules to use for queries (separated by whitespace or
commas), or NULLto use modules specified in the config file | 
| 
 | a list of modules to use for entity creation (separated by
whitespace or commas), or NULLto use modules specified in the config file | 
| 
 | a function to use for getting information from the user | 
| 
 | data for prompter | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | a context which should be freed by lu_end()on success,NULLon
failure | 
void lu_end (lu_context_t *context);
Destroys a libuser library context
| 
 | a context | 
void                lu_set_prompter                     (lu_context_t *context,
                                                         lu_prompt_fn *prompter,
                                                         gpointer callback_data);
Changes the prompter function in a context
| 
 | a context | 
| 
 | a new function to user for getting information from the user | 
| 
 | data for prompter | 
void                lu_get_prompter                     (lu_context_t *context,
                                                         lu_prompt_fn **prompter,
                                                         gpointer *callback_data);
Gets current prompter function from a context
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.
const char* lu_get_modules (lu_context_t *context);
Returns a list of modules for queries in context.
| 
 | a context | 
| Returns : | a list of modules separated by spaces, or NULLif the list of
modules is empty.  The list should not be freed by the caller. | 
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).
| 
 | a context | 
| Returns : | TRUEif at least one module uses elevated privileges | 
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.
| 
 | a context | 
| 
 | user name | 
| 
 | an entity filled with received information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | user ID | 
| 
 | an entity filled with received information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | new user name | 
| 
 | non-zero if the user is a system user | 
| 
 | an entity | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | an entity describing the user, on success updated with resulting account | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_user_modify (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Modifies an user entity.
| 
 | a context | 
| 
 | an entity with pending modifications, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_user_delete (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Deletes an user.
| 
 | a context | 
| 
 | an entity describing the user | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | an entity describing the user, on success updated with current information and LU_SHADOWLASTCHANGE | 
| 
 | new password | 
| 
 | non-zero if newpassis already encrypted | 
| 
 | filled with an lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | an entity describing the user, on success updated with current information and LU_SHADOWLASTCHANGE | 
| 
 | filled with an lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_user_lock (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Locks an user account.
| 
 | a context | 
| 
 | an entity describing the user, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_user_unlock (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Unlocks an user account.
| 
 | a context | 
| 
 | an entity describing the user, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | an entity describing the user, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_user_islocked (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Checks if an user account is locked.
| 
 | a context | 
| 
 | an entity describing the user | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEif the account is locked in at least one module | 
GValueArray* lu_users_enumerate (lu_context_t *context, const char *pattern, lu_error_t **error);
Returns a list of all users matching a pattern.
| 
 | a context | 
| 
 | a glob-like pattern for user name | 
| 
 | 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. | 
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.
| 
 | a context | 
| 
 | group name | 
| 
 | 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. | 
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.
| 
 | a context | 
| 
 | a glob-like pattern for user name | 
| 
 | 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. | 
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.
| 
 | a context | 
| 
 | group name | 
| 
 | an entity filled with received information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | group ID | 
| 
 | an entity filled with received information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | new group name | 
| 
 | non-zero if the group is a system group | 
| 
 | an entity | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | an entity describing the group, on success updated with resulting account | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_group_modify (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Modifies a group entity.
| 
 | a context | 
| 
 | an entity with pending modifications, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_group_delete (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Deletes a group.
| 
 | a context | 
| 
 | an entity describing the group | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a contect | 
| 
 | an entity describing the group, on success updated with current information and LU_SHADOWLASTCHANGE | 
| 
 | new password | 
| 
 | non-zero if newpassis already encrypted | 
| 
 | filled with an lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_group_removepass (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Changes a group password to an empty string.
| 
 | a context | 
| 
 | an entity describing the group, on success udpated with current information and LU_SHADOWLASTCHANGE | 
| 
 | filled with in lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_group_lock (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Locks a group account
| 
 | a context | 
| 
 | an entity describing the group, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_group_unlock (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Unlocks a group account.
| 
 | a context | 
| 
 | an entity describing the group, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
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.
| 
 | a context | 
| 
 | an entity describing the group, on success updated with current information | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEon success | 
gboolean lu_group_islocked (lu_context_t *context, struct lu_ent *ent, lu_error_t **error);
Checks if a group account is locked.
| 
 | a context | 
| 
 | an entity describing the group | 
| 
 | filled with a lu_error if an error occurs | 
| Returns : | TRUEif the account is locked in at least one module | 
GValueArray* lu_groups_enumerate (lu_context_t *context, const char *pattern, lu_error_t **error);
Returns a list of all groups matching a pattern.
| 
 | a context | 
| 
 | a glob-like pattern for group name | 
| 
 | 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. | 
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.
| 
 | a context | 
| 
 | user name | 
| 
 | 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. | 
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.
| 
 | a context | 
| 
 | a glob-like pattern for group name | 
| 
 | 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. |