From 68594d15c56a21e3d4d8cd12fefbc5bbf0af002f Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 2 Aug 2018 22:17:55 +0000 Subject: Complete libnsssd and libnsss documentation --- doc/libnsss/nsss-switch.html | 188 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 187 insertions(+), 1 deletion(-) (limited to 'doc/libnsss/nsss-switch.html') diff --git a/doc/libnsss/nsss-switch.html b/doc/libnsss/nsss-switch.html index 224cea6..006b457 100644 --- a/doc/libnsss/nsss-switch.html +++ b/doc/libnsss/nsss-switch.html @@ -21,9 +21,195 @@

General information

+

+ 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. +

+

Programming

-

TODO: to be completed.

+

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. +

-- cgit v1.3.1