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-unix.html | 203 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 1 deletion(-) (limited to 'doc/libnsss/nsss-unix.html') diff --git a/doc/libnsss/nsss-unix.html b/doc/libnsss/nsss-unix.html index b51985b..931e532 100644 --- a/doc/libnsss/nsss-unix.html +++ b/doc/libnsss/nsss-unix.html @@ -21,9 +21,210 @@

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

-

TODO: to be completed.

+

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

-- cgit v1.3.1