libnsss
nsss
Software
skarnet.org

The nsss-unix library interface

General information

The nsss/nsss-unix.h functions in libnsss provide a clean interface to get user/group data from the regular /etc/passwd, /etc/group and /etc/shadow text files.

All the following functions take as their first argument a pointer to a handle that has the nsss_unix_t type. This handle must be declared and initialized to NSSS_UNIX_ZERO prior to any call. It can be declared in the stack.

Programming

int nsss_unix_pwd_start (nsss_unix_t *a)

Opens a session with /etc/passwd. *a must be NSSS_UNIX_ZERO prior to the call. On error, returns 0, and sets errno. On success, returns 1, and *a is a handle to an /etc/passwd session. This function must be called even for a non-enumeration lookup.

int nsss_unix_pwd_maybe_start (nsss_unix_t *a)

Opens a session with /etc/passwd if it hasn't been opened yet. On error, returns 0, and sets errno. On success, returns 1, and *a is a handle to an /etc/passwd session. Calling this function when *a is already opened to an /etc/passwd session simply returns 1.

int nsss_unix_pwd_rewind (nsss_unix_t *a)

Performs a setpwent() operation on the current session. Returns 1 on success, and 0 (and sets errno) on error.

void nsss_unix_pwd_end (nsss_unix_t *a)

Closes the current /etc/passwd session. After this function returns, *a can be reused with another nsss_unix_*_start() function.

int nsss_unix_pwd_getbyname (nsss_unix_t *a, struct passwd *pw, stralloc *sa, char const *name)

Performs a getpwnam(name) on the current, open, /etc/passwd session. On error, returns 0 and sets errno. On success, returns 1, and stores the result into *pw, using the *sa stralloc to store strings. If name is not found, the function returns 0 without changing errno.

int nsss_unix_pwd_getbyuid (nsss_unix_t *a, struct passwd *pw, stralloc *sa, uid_t uid)

Performs a getpwuid(uid) on the current, open, /etc/passwd session. On error, returns 0 and sets errno. On success, returns 1, and stores the result into *pw, using the *sa stralloc to store strings. If uid is not found, the function returns 0 without changing errno.

int nsss_unix_pwd_get (nsss_unix_t *a, struct passwd *pw, stralloc *sa)

Performs a getpwent() on the current, open, /etc/passwd session (i.e. get the next entry in the file, as part of an enumeration). On error, returns 0 and sets errno. On success, returns 1, and stores the result into *pw, using the *sa stralloc to store strings. On EOF, the function returns 0 without changing errno.

int nsss_unix_grp_start (nsss_unix_t *a)

Opens a session with /etc/group. *a must be NSSS_UNIX_ZERO prior to the call. On error, returns 0, and sets errno. On success, returns 1, and *a is a handle to an /etc/group session. This function must be called even for a non-enumeration lookup.

int nsss_unix_grp_maybe_start (nsss_unix_t *a)

Opens a session with /etc/group if it hasn't been opened yet. On error, returns 0, and sets errno. On success, returns 1, and *a is a handle to an /etc/group session. Calling this function when *a is already opened to an /etc/group session simply returns 1.

int nsss_unix_grp_rewind (nsss_unix_t *a)

Performs a setgrent() operation on the current session. Returns 1 on success, and 0 (and sets errno) on error.

void nsss_unix_grp_end (nsss_unix_t *a)

Closes the current /etc/group session. After this function returns, *a can be reused with another nsss_unix_*_start() function.

int nsss_unix_grp_getbyname (nsss_unix_t *a, struct group *gr, stralloc *sa, genalloc *ga, char const *name)

Performs a getgrnam(name) on the current, open, /etc/group session. On error, returns 0 and sets errno. On success, returns 1, and stores the result into *gr, using the *sa stralloc to store strings, and the *ga genalloc, which must be able to hold objects of type char *, to store pointers for the gr->gr_mem field. If name is not found, the function returns 0 without changing errno.

int nsss_unix_grp_getbygid (nsss_unix_t *a, struct group *gr, stralloc *sa, genalloc *ga, gid_t gid)

Performs a getgrgid(gid) on the current, open, /etc/group session. On error, returns 0 and sets errno. On success, returns 1, and stores the result into *gr, using the *sa stralloc to store strings, and the *ga genalloc, which must be able to hold objects of type char *, to store pointers for the gr->gr_mem field. If gid is not found, the function returns 0 without changing errno.

int nsss_unix_grp_get (nsss_unix_t *a, struct group *gr, stralloc *sa, genalloc *ga)

Performs a getgrent() on the current, open, /etc/group session (i.e. get the next entry in the file, as part of an enumeration). On error, returns 0 and sets errno. On success, returns 1, and stores the result into *gr, using the *sa stralloc to store strings, and the *ga genalloc, which must be able to hold objects of type char *, to store pointers for the gr->gr_mem field. On EOF, the function returns 0 without changing errno.

int nsss_unix_shadow_start (nsss_unix_t *a)

Opens a session with /etc/shadow. *a must be NSSS_UNIX_ZERO prior to the call. On error, returns 0, and sets errno. On success, returns 1, and *a is a handle to an /etc/shadow session. This function must be called even for a non-enumeration lookup.

int nsss_unix_shadow_maybe_start (nsss_unix_t *a)

Opens a session with /etc/shadow if it hasn't been opened yet. On error, returns 0, and sets errno. On success, returns 1, and *a is a handle to an /etc/shadow session. Calling this function when *a is already opened to an /etc/shadow session simply returns 1.

int nsss_unix_shadow_rewind (nsss_unix_t *a)

Performs a setspent() operation on the current session. Returns 1 on success, and 0 (and sets errno) on error.

void nsss_unix_shadow_end (nsss_unix_t *a)

Closes the current /etc/shadow session. After this function returns, *a can be reused with another nsss_unix_*_start() function.

int nsss_unix_shadow_getbyname (nsss_unix_t *a, struct spwd *sp, stralloc *sa, char const *name)

Performs a getspnam(name) on the current, open, /etc/shadow session. On error, returns 0 and sets errno. On success, returns 1, and stores the result into *sp, using the *sa stralloc to store strings. If name is not found, the function returns 0 without changing errno.

int nsss_unix_shadow_get (nsss_unix_t *a, struct spwd *sp, stralloc *sa)

Performs a getspent() on the current, open, /etc/shadow session (i.e. get the next entry in the file, as part of an enumeration). On error, returns 0 and sets errno. On success, returns 1, and stores the result into *sp, using the *sa stralloc to store strings. On EOF, the function returns 0 without changing errno.