Description

The getuserattr(), getusernam(), and getuseruid() functions each return a user_attr(4) entry. Entries can
come from any of the sources specified in the nsswitch.conf(4) file. The
getuserattr() function enumerates user_attr entries. The getusernam() function searches for a user_attr entry
with a given user name name. The getuseruid() function searches for a
user_attr entry with a given user ID uid. Successive calls to these functions
return either successive user_attr entries or NULL.

The fgetuserattr() function does not use nsswitch.conf but reads and parses the
next line from the stream f. This stream is assumed to have
the format of the user_attr files.

The free_userattr() function releases memory allocated by the getusernam(), getuserattr(), and fgetuserattr()
functions.

The internal representation of a user_attr entry is a userattr_t structure defined
in <user_attr.h> with the following members:

The setuserattr() function “rewinds” to the beginning of the enumeration of user_attr
entries. Calls to getusernam() may leave the enumeration in an indeterminate
state, so setuserattr() should be called before the first call to getuserattr().

The enduserattr() function may be called to indicate that user_attr processing is
complete; the library may then close any open user_attr file, deallocate any
internal storage, and so forth.

Return Values

The getuserattr() function returns a pointer to a userattr_t if it successfully
enumerates an entry; otherwise it returns NULL, indicating the end of the
enumeration.

The getusernam() function returns a pointer to a userattr_t if it successfully
locates the requested entry; otherwise it returns NULL.

Usage

The getuserattr() and getusernam() functions both allocate memory for the pointers they
return. This memory should be deallocated with the free_userattr() function.

Individual attributes can be referenced in the attr structure by calling the
kva_match(3SECDB) function.

WARININGS

Because the list of legal keys is likely to expand, code
must be written to ignore unknown key-value pairs without error.