entity

entity — Functions for manipulating lu_ent structures.

Synopsis

#include <libuser/error.h>

struct              lu_ent;
typedef             lu_ent_t;
#define             LU_USERNAME
#define             LU_USERPASSWORD
#define             LU_UIDNUMBER
#define             LU_GIDNUMBER
#define             LU_GECOS
#define             LU_HOMEDIRECTORY
#define             LU_LOGINSHELL
#define             LU_GROUPNAME
#define             LU_GROUPPASSWORD
#define             LU_MEMBERNAME
#define             LU_ADMINISTRATORNAME
#define             LU_SHADOWNAME
#define             LU_SHADOWPASSWORD
#define             LU_SHADOWLASTCHANGE
#define             LU_SHADOWMIN
#define             LU_SHADOWMAX
#define             LU_SHADOWWARNING
#define             LU_SHADOWINACTIVE
#define             LU_SHADOWEXPIRE
#define             LU_SHADOWFLAG
#define             LU_COMMONNAME
#define             LU_GIVENNAME
#define             LU_SN
#define             LU_ROOMNUMBER
#define             LU_TELEPHONENUMBER
#define             LU_HOMEPHONE
#define             LU_EMAIL
struct lu_ent *     lu_ent_new                          (void);
void                lu_ent_free                         (struct lu_ent *ent);
void                lu_ent_copy                         (struct lu_ent *source,
                                                         struct lu_ent *dest);
void                lu_ent_commit                       (struct lu_ent *ent);
void                lu_ent_revert                       (struct lu_ent *ent);
void                lu_ent_add                          (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);
void                lu_ent_add_current                  (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);
void                lu_ent_clear                        (struct lu_ent *ent,
                                                         const char *attr);
void                lu_ent_clear_all                    (struct lu_ent *ent);
void                lu_ent_clear_all_current            (struct lu_ent *ent);
void                lu_ent_clear_current                (struct lu_ent *ent,
                                                         const char *attr);
void                lu_ent_del                          (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);
void                lu_ent_del_current                  (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);
void                lu_ent_dump                         (struct lu_ent *ent,
                                                         FILE *fp);
GValueArray *       lu_ent_get                          (struct lu_ent *ent,
                                                         const char *attribute);
const char *        lu_ent_get_first_string             (struct lu_ent *ent,
                                                         const char *attribute);
const char *        lu_ent_get_first_string_current     (struct lu_ent *ent,
                                                         const char *attribute);
char *              lu_ent_get_first_value_strdup       (struct lu_ent *ent,
                                                         const char *attribute);
char *              lu_ent_get_first_value_strdup_current
                                                        (struct lu_ent *ent,
                                                         const char *attribute);
id_t                lu_ent_get_first_id                 (struct lu_ent *ent,
                                                         const char *attribute);
id_t                lu_ent_get_first_id_current         (struct lu_ent *ent,
                                                         const char *attribute);
GList *             lu_ent_get_attributes               (struct lu_ent *ent);
GList *             lu_ent_get_attributes_current       (struct lu_ent *ent);
GValueArray *       lu_ent_get_current                  (struct lu_ent *ent,
                                                         const char *attribute);
gboolean            lu_ent_has                          (struct lu_ent *ent,
                                                         const char *attribute);
gboolean            lu_ent_has_current                  (struct lu_ent *ent,
                                                         const char *attribute);
void                lu_ent_set                          (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValueArray *values);
void                lu_ent_set_current                  (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValueArray *values);
void                lu_ent_set_string                   (struct lu_ent *ent,
                                                         const char *attr,
                                                         const char *value);
void                lu_ent_set_string_current           (struct lu_ent *ent,
                                                         const char *attr,
                                                         const char *value);
void                lu_ent_set_id                       (struct lu_ent *ent,
                                                         const char *attr,
                                                         id_t value);
void                lu_ent_set_id_current               (struct lu_ent *ent,
                                                         const char *attr,
                                                         id_t value);
void                lu_ent_set_long                     (struct lu_ent *ent,
                                                         const char *attr,
                                                         long int value);
void                lu_ent_set_long_current             (struct lu_ent *ent,
                                                         const char *attr,
                                                         long int value);

Description

entity.h declares functions for manipulating lu_ent structures, which are used by libuser, its modules, and applications to hold data about a particular user or group account.

Details

struct lu_ent

struct lu_ent;

An opaque structure used to hold data about a particular user or group account.

Each struct lu_ent contains two sets of attributes: pending and current. The pending attributes are modified by default, the current attributes are modified by functions ending with _current.

Each attribute contains a list of values. The list is never empty; removing the last entry from the list removes the list completely.


lu_ent_t

typedef struct lu_ent lu_ent_t;

Warning

lu_ent_t has been deprecated since version 0.57.3 and should not be used in newly-written code. Use struct lu_ent directly.

An alias for struct lu_ent.


LU_USERNAME

#define LU_USERNAME		"pw_name"

User name, a G_TYPE_STRING.


LU_USERPASSWORD

#define LU_USERPASSWORD		"pw_passwd"

User password, a G_TYPE_STRING. If shadow passwords are used, this is the placeholder password.

Don't modify passwords by changing this attribute directly, use one of the specialized functions.


LU_UIDNUMBER

#define LU_UIDNUMBER		"pw_uid"

User ID, an id_t.


LU_GIDNUMBER

#define LU_GIDNUMBER		"pw_gid"

Group ID, an id_t.


LU_GECOS

#define LU_GECOS		"pw_gecos"

Usually user's real name, a G_TYPE_STRING. Often contains user's real name, office name, office phone, home phone, separated by commas.


LU_HOMEDIRECTORY

#define LU_HOMEDIRECTORY "pw_dir"

User's home directory, a G_TYPE_STRING.


LU_LOGINSHELL

#define LU_LOGINSHELL		"pw_shell"

User's login shell, a G_TYPE_STRING.


LU_GROUPNAME

#define LU_GROUPNAME		"gr_name"

Group name, a G_TYPE_STRING.


LU_GROUPPASSWORD

#define LU_GROUPPASSWORD "gr_passwd"

Group password, a G_TYPE_STRING.

Don't modify passwords by changing this attribute directly, use one of the specialized functions.


LU_MEMBERNAME

#define LU_MEMBERNAME		"gr_mem"

Group member names; each member is represented by a separate G_TYPE_STRING value.


LU_ADMINISTRATORNAME

#define LU_ADMINISTRATORNAME "gr_adm"

Group administrator names; each administrator is represented by a separate G_TYPE_STRING value.


LU_SHADOWNAME

#define LU_SHADOWNAME		LU_USERNAME

User name, a G_TYPE_STRING. Note that LU_SHADOWNAME is not distinct from LU_USERNAME.


LU_SHADOWPASSWORD

#define LU_SHADOWPASSWORD "sp_pwdp"

User password in the shadow file, a G_TYPE_STRING.

Don't modify passwords by changing this attribute directly, use one of the specialized functions.


LU_SHADOWLASTCHANGE

#define LU_SHADOWLASTCHANGE "sp_lstchg"

The number of days since the epoch to the day when the password was last changed, a G_TYPE_LONG.

May be -1 to indicate that the field exists without a value. This should be handled the same as if the attribute was missing altogether, and consistently with shadow(5).


LU_SHADOWMIN

#define LU_SHADOWMIN		"sp_min"

Minimum password lifetime in days before it can be changed, a G_TYPE_LONG.

May be -1 to indicate that the field exists without a value. This should be handled the same as if the attribute was missing altogether, and consistently with shadow(5).


LU_SHADOWMAX

#define LU_SHADOWMAX		"sp_max"

Maximum password lifetime in days before it must be changed, a G_TYPE_LONG.

May be -1 to indicate that the field exists without a value. This should be handled the same as if the attribute was missing altogether, and consistently with shadow(5).


LU_SHADOWWARNING

#define LU_SHADOWWARNING "sp_warn"

Days before the password lifetime expires when the user should start to be warned, a G_TYPE_LONG.

May be -1 to indicate that the field exists without a value. This should be handled the same as if the attribute was missing altogether, and consistently with shadow(5).


LU_SHADOWINACTIVE

#define LU_SHADOWINACTIVE "sp_inact"

Days after the password lifetime expires when the user account is disabled (because it is considered inactive), a G_TYPE_LONG. -1 to disable inactive account disabling.


LU_SHADOWEXPIRE

#define LU_SHADOWEXPIRE		"sp_expire"

The number of days since the epoch to the day when the account expires and is disabled, a G_TYPE_LONG. -1 to disable account expiration.


LU_SHADOWFLAG

#define LU_SHADOWFLAG		"sp_flag"

A reserved value "for future use", a G_TYPE_LONG. In most cases the value is -1.


LU_COMMONNAME

#define LU_COMMONNAME		"cn"

User's real name, a G_TYPE_STRING.


LU_GIVENNAME

#define LU_GIVENNAME		"givenName"

User's given name, a G_TYPE_STRING.


LU_SN

#define LU_SN			"sn"

User's surname, a G_TYPE_STRING.


LU_ROOMNUMBER

#define LU_ROOMNUMBER		"roomNumber"

User's room number, a G_TYPE_STRING.


LU_TELEPHONENUMBER

#define LU_TELEPHONENUMBER "telephoneNumber"

User's telephone number, a G_TYPE_STRING.


LU_HOMEPHONE

#define LU_HOMEPHONE		"homePhone"

User's home telephone number, a G_TYPE_STRING.


LU_EMAIL

#define LU_EMAIL		"mail"

User's email address, a G_TYPE_STRING.


lu_ent_new ()

struct lu_ent *     lu_ent_new                          (void);

Creates a new, empty struct lu_ent.

Returns :

The created entity, which should be deallocated by lu_ent_free()

lu_ent_free ()

void                lu_ent_free                         (struct lu_ent *ent);

Frees an struct lu_ent, including all strings it owns.

ent :

The entity to free

lu_ent_copy ()

void                lu_ent_copy                         (struct lu_ent *source,
                                                         struct lu_ent *dest);

Copies one struct lu_ent over another.

source :

The entity to copy

dest :

The destination space, must be already allocated by lu_ent_new()

lu_ent_commit ()

void                lu_ent_commit                       (struct lu_ent *ent);

Sets pending attribute changes as current values of the entity.

ent :

An entity

lu_ent_revert ()

void                lu_ent_revert                       (struct lu_ent *ent);

Replaces all attributes with changes pending by their current values, forgetting the pending changes.

ent :

an entity

lu_ent_add ()

void                lu_ent_add                          (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);

Appends value to pending attribute attr in a struct lu_ent if value is not yet in the list of attr values.

ent :

An entity

attr :

Attribute name

value :

New attribute value

lu_ent_add_current ()

void                lu_ent_add_current                  (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);

Appends value to current attribute attr in a struct lu_ent if value is not yet in the list of attr values.

ent :

An entity

attr :

Attribute name

value :

New attribute value

lu_ent_clear ()

void                lu_ent_clear                        (struct lu_ent *ent,
                                                         const char *attr);

Removes all values of pending attribute attribute from a struct lu_ent.

ent :

An entity

attr :

Attribute name

lu_ent_clear_all ()

void                lu_ent_clear_all                    (struct lu_ent *ent);

Removes all pending attributes from a struct lu_ent.

ent :

an entity

lu_ent_clear_all_current ()

void                lu_ent_clear_all_current            (struct lu_ent *ent);

Removes all current attributes from a struct lu_ent.

ent :

an entity

lu_ent_clear_current ()

void                lu_ent_clear_current                (struct lu_ent *ent,
                                                         const char *attr);

Removes all values of current attribute attribute from a struct lu_ent.

ent :

An entity

attr :

Attribute name

lu_ent_del ()

void                lu_ent_del                          (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);

Removes a pending attribute attr value value from a struct lu_ent, if present.

ent :

An entity

attr :

Attribute name

value :

Attribute value

lu_ent_del_current ()

void                lu_ent_del_current                  (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValue *value);

Removes a current attribute attr value value from a struct lu_ent, if present.

ent :

An entity

attr :

Attribute name

value :

Attribute value

lu_ent_dump ()

void                lu_ent_dump                         (struct lu_ent *ent,
                                                         FILE *fp);

Dumps a struct lu_ent to a file in text form, for debugging.

ent :

The entity to dump

fp :

Destination file

lu_ent_get ()

GValueArray *       lu_ent_get                          (struct lu_ent *ent,
                                                         const char *attribute);

Returns values associated with a pending attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

a GValueArray of values, valid at least until they are modified or deleted. The array is never empty and it should not be freed by the caller. Returns NULL if the attribute is not present at all or on error.

lu_ent_get_first_string ()

const char *        lu_ent_get_first_string             (struct lu_ent *ent,
                                                         const char *attribute);

Returns the first string associated with a pending attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

a string pointer valid at least the value is modified or deleted if the attribute is present and the first value is a string. Returns NULL if the attribute is not present, the first value is not a string, or on error.

lu_ent_get_first_string_current ()

const char *        lu_ent_get_first_string_current     (struct lu_ent *ent,
                                                         const char *attribute);

Returns the first string associated with a current attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

a string pointer valid at least the value is modified or deleted if the attribute is present and the first value is a string. Returns NULL if the attribute is not present, the first value is not a string, or on error.

lu_ent_get_first_value_strdup ()

char *              lu_ent_get_first_value_strdup       (struct lu_ent *ent,
                                                         const char *attribute);

Returns a string representation (as if by lu_value_strdup()) of the first value associated with a pending attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

a string, should be freed by g_free() if the attribute is present. Returns NULL if the attribute is not present or on error.

lu_ent_get_first_value_strdup_current ()

char *              lu_ent_get_first_value_strdup_current
                                                        (struct lu_ent *ent,
                                                         const char *attribute);

Returns a string representation (as if by lu_value_strdup()) of the first value associated with a current attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

a string, should be freed by g_free() if the attribute is present. Returns NULL if the attribute is not present or on error.

lu_ent_get_first_id ()

id_t                lu_ent_get_first_id                 (struct lu_ent *ent,
                                                         const char *attribute);

Returns the first id_t value associated with a pending attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

ID value the attribute is present and can be converted into id_t. Returns LU_VALUE_INVALID_ID if the attribute is not present, the first value cannot be converted, or on error.

lu_ent_get_first_id_current ()

id_t                lu_ent_get_first_id_current         (struct lu_ent *ent,
                                                         const char *attribute);

Returns the first id_t value associated with a current attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

ID value the attribute is present and can be converted into id_t. Returns LU_VALUE_INVALID_ID if the attribute is not present, the first value cannot be converted, or on error.

lu_ent_get_attributes ()

GList *             lu_ent_get_attributes               (struct lu_ent *ent);

Returns a list of all pending attributes in a struct lu_ent.

ent :

An entity

Returns :

a GList of attribute names. The list (but not the strings in the list) should be freed by the caller.

lu_ent_get_attributes_current ()

GList *             lu_ent_get_attributes_current       (struct lu_ent *ent);

Returns a list of all current attributes in a struct lu_ent.

ent :

An entity

Returns :

a GList of attribute names. The list (but not the strings in the list) should be freed by the caller.

lu_ent_get_current ()

GValueArray *       lu_ent_get_current                  (struct lu_ent *ent,
                                                         const char *attribute);

Returns values associated with a current attribute in a struct lu_ent.

ent :

An entity

attribute :

Attribute name

Returns :

a GValueArray of values, valid at least until they are modified or deleted. The array is never empty and it should not be freed by the caller. Returns NULL if the attribute is not present at all or on error.

lu_ent_has ()

gboolean            lu_ent_has                          (struct lu_ent *ent,
                                                         const char *attribute);

Checks if a struct lu_ent has at least one pending attribute attribute.

ent :

An entity

attribute :

Attribute name

Returns :

TRUE if attribute has a value in ent.

lu_ent_has_current ()

gboolean            lu_ent_has_current                  (struct lu_ent *ent,
                                                         const char *attribute);

Checks if a struct lu_ent has at least one current attribute attribute.

ent :

An entity

attribute :

Attribute name

Returns :

TRUE if attribute has a value in ent.

lu_ent_set ()

void                lu_ent_set                          (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValueArray *values);

Replaces all pending attributes attr in a struct lu_ent by a copy of values. If values is empty, it removes the pending attribute completely.

ent :

An entity

attr :

Attribute name

values :

An array of values

lu_ent_set_current ()

void                lu_ent_set_current                  (struct lu_ent *ent,
                                                         const char *attr,
                                                         const GValueArray *values);

Replaces all current attributes attr in a struct lu_ent by a copy of values. If values is empty, it removes the pending attribute completely.

ent :

An entity

attr :

Attribute name

values :

An array of values

lu_ent_set_string ()

void                lu_ent_set_string                   (struct lu_ent *ent,
                                                         const char *attr,
                                                         const char *value);

Replaces all pending attributes attr in a struct lu_ent by a copy of string value.

ent :

An entity

attr :

Attribute name

value :

A string

lu_ent_set_string_current ()

void                lu_ent_set_string_current           (struct lu_ent *ent,
                                                         const char *attr,
                                                         const char *value);

Replaces all current attributes attr in a struct lu_ent by a copy of string value.

ent :

An entity

attr :

Attribute name

value :

A string

lu_ent_set_id ()

void                lu_ent_set_id                       (struct lu_ent *ent,
                                                         const char *attr,
                                                         id_t value);

Replaces all pending attributes attr in a struct lu_ent by an id_t value.

ent :

An entity

attr :

Attribute name

value :

An id_t value

lu_ent_set_id_current ()

void                lu_ent_set_id_current               (struct lu_ent *ent,
                                                         const char *attr,
                                                         id_t value);

Replaces all current attributes attr in a struct lu_ent by an id_t value.

ent :

An entity

attr :

Attribute name

value :

An id_t value

lu_ent_set_long ()

void                lu_ent_set_long                     (struct lu_ent *ent,
                                                         const char *attr,
                                                         long int value);

Replaces all pending attributes attr in a struct lu_ent by a long value.

ent :

An entity

attr :

Attribute name

value :

A value

lu_ent_set_long_current ()

void                lu_ent_set_long_current             (struct lu_ent *ent,
                                                         const char *attr,
                                                         long int value);

Replaces all current attributes attr in a struct lu_ent by a long value.

ent :

An entity

attr :

Attribute name

value :

A value