entity

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