libnsss
nsss
Software
skarnet.org
The nsss/nsss-switch.h functions in libnsss provide a clean interface to get user/group data from a nsss daemon, for instance one implemented via nsssd-unix or nsssd-nslcd. They are the C client library to such a daemon.
Most of the following functions take, in addition to their obvious arguments, a tain_t const * argument conventionally named deadline and a tain_t * argument conventionally named stamp. These two arguments are there to ensure that the function, which connects to another process in an otherwise synchronous manner, does not block forever. How to use these arguments is explained, for instance, here. A function foobar also has a version named foobar_g that only takes the deadline argument, assuming the current timestamp is held in the STAMP global variable.
All the functions take as their first argument a pointer to a handle that has the nsss_switch_t type. This handle must be declared and initialized to NSSS_SWITCH_ZERO prior to any call. It can be declared in the stack.
int nsss_switch_start (nsss_switch_t *a, unsigned int what, char const *path, tain_t const *deadline, tain_t *stamp)Opens a session with a nsss daemon listening to a Unix domain socket located at path. *a must be NSSS_SWITCH_ZERO prior to the call. The nature of the session depends on the what argument, which should be one of NSSS_SWITCH_PWD, NSSS_SWITCH_GRP or NSSS_SWITCH_SHADOW depending on whether subsequent requests will query the user, group or shadow database. On error, the function returns 0, and sets errno. On success, it returns 1, and *a is a handle to a session with the nsssd daemon. This function must be called for every batch of communication with a nsssd service, not only for enumerations.
void nsss_switch_end (nsss_switch_t *a, unsigned int what)Closes the current session. The what argument must be the same one that has been given to nsss_switch_start. After this function returns, *a can be reused.
int nsss_switch_pwd_rewind (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a setpwent() operation on the current session. Returns 1 on success, and 0 (and sets errno) on error.
int nsss_switch_pwd_end (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a endpwent() operation on the current session, i.e. ends an enumeration. Returns 1 on success, and 0 (and sets errno) on error.
int nsss_switch_pwd_getbyname (nsss_switch_t *a, struct passwd *pw, stralloc *sa, char const *name, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a getpwnam(name) on the current 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_switch_pwd_getbyuid (nsss_switch_t *a, struct passwd *pw, stralloc *sa, uid_t uid, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a getpwuid(uid) on the current 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_switch_pwd_get (nsss_switch_t *a, struct passwd *pw, stralloc *sa, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a a getpwent() on the current session, i.e. get the next entry 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_switch_grp_rewind (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a setgrent() operation on the current session. Returns 1 on success, and 0 (and sets errno) on error.
void nsss_switch_grp_end (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a endgrent() operation on the current session, i.e. ends an enumeration. Returns 1 on success, and 0 (and sets errno) on error.
int nsss_switch_grp_getbyname (nsss_switch_t *a, struct group *gr, stralloc *sa, genalloc *ga, char const *name, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a a getgrnam(name) on the current 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_switch_grp_getbygid (nsss_switch_t *a, struct group *gr, stralloc *sa, genalloc *ga, gid_t gid, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a getgrgid(gid) on the current 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_switch_grp_get (nsss_switch_t *a, struct group *gr, stralloc *sa, genalloc *ga, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a getgrent() on the current session, i.e. get the next entry 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_switch_shadow_rewind (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a setspent() operation on the current session. Returns 1 on success, and 0 (and sets errno) on error.
int nsss_switch_shadow_end (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a endspent() operation on the current session, i.e. ends an enumeration. Returns 1 on success, and 0 (and sets errno) on error.
int nsss_switch_shadow_getbyname (nsss_switch_t *a, struct spwd *sp, stralloc *sa, char const *name, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a getspnam(name) on the current 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_switch_shadow_get (nsss_switch_t *a, struct spwd *sp, stralloc *sa, tain_t const *deadline, tain_t *stamp)Performs the equivalent of a getspent() on the current session, i.e. get the next entry 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.