entity

entity — Functions for manipulating lu_ent structures.

Synopsis




#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
lu_ent_t*   lu_ent_new                      (void);
void        lu_ent_free                     (lu_ent_t *ent);
void        lu_ent_copy                     (lu_ent_t *source,
                                             lu_ent_t *dest);
void        lu_ent_commit                   (lu_ent_t *ent);
void        lu_ent_revert                   (lu_ent_t *ent);
void        lu_ent_add                      (lu_ent_t *ent,
                                             const char *attr,
                                             const GValue *value);
void        lu_ent_add_current              (lu_ent_t *ent,
                                             const char *attr,
                                             const GValue *value);
void        lu_ent_clear                    (lu_ent_t *ent,
                                             const char *attr);
void        lu_ent_clear_all                (lu_ent_t *ent);
void        lu_ent_clear_all_current        (lu_ent_t *ent);
void        lu_ent_clear_current            (lu_ent_t *ent,
                                             const char *attr);
void        lu_ent_del                      (lu_ent_t *ent,
                                             const char *attr,
                                             const GValue *value);
void        lu_ent_del_current              (lu_ent_t *ent,
                                             const char *attr,
                                             const GValue *value);
void        lu_ent_dump                     (lu_ent_t *ent,
                                             FILE *fp);
GValueArray* lu_ent_get                     (lu_ent_t *ent,
                                             const char *attribute);
GList*      lu_ent_get_attributes           (lu_ent_t *ent);
GList*      lu_ent_get_attributes_current   (lu_ent_t *ent);
GValueArray* lu_ent_get_current             (lu_ent_t *ent,
                                             const char *attribute);
gboolean    lu_ent_has                      (lu_ent_t *ent,
                                             const char *attribute);
gboolean    lu_ent_has_current              (lu_ent_t *ent,
                                             const char *attribute);
void        lu_ent_set                      (lu_ent_t *ent,
                                             const char *attr,
                                             const GValueArray *values);
void        lu_ent_set_current              (lu_ent_t *ent,
                                             const char *attr,
                                             const GValueArray *values);

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.

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.

Details

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.


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.


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.


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.


LU_SHADOWMIN

#define LU_SHADOWMIN		"sp_min"

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


LU_SHADOWMAX

#define LU_SHADOWMAX		"sp_max"

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


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.


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 ()

lu_ent_t*   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                     (lu_ent_t *ent);

Frees an struct lu_ent, including all strings it owns.

ent : the entity to free

lu_ent_copy ()

void        lu_ent_copy                     (lu_ent_t *source,
                                             lu_ent_t *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                   (lu_ent_t *ent);

Sets pending attribute changes as current values of the entity.

ent : an entity

lu_ent_revert ()

void        lu_ent_revert                   (lu_ent_t *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                      (lu_ent_t *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              (lu_ent_t *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                    (lu_ent_t *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                (lu_ent_t *ent);

Removes all pending attributes from a struct lu_ent.

ent : an entity

lu_ent_clear_all_current ()

void        lu_ent_clear_all_current        (lu_ent_t *ent);

Removes all current attributes from a struct lu_ent.

ent : an entity

lu_ent_clear_current ()

void        lu_ent_clear_current            (lu_ent_t *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                      (lu_ent_t *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              (lu_ent_t *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                     (lu_ent_t *ent,
                                             FILE *fp);

Dumps an 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                     (lu_ent_t *ent,
                                             const char *attribute);

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

ent : an entity
attribute : attribute name
Returns : an array 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_attributes ()

GList*      lu_ent_get_attributes           (lu_ent_t *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   (lu_ent_t *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             (lu_ent_t *ent,
                                             const char *attribute);

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

ent : an entity
attribute : attribute name
Returns : a list of values, valid at least until they are modified or deleted. The list 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                      (lu_ent_t *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              (lu_ent_t *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                      (lu_ent_t *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              (lu_ent_t *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 current attribute completely.

ent : an entity
attr : attribute name
values : an array of values