entity

## 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