#ifndef VLIBC_PWD_H
#define VLIBC_PWD_H

/*
 * vlibc — <pwd.h>.
 *
 * The password database (todo 37). struct passwd mirrors /etc/passwd, whose
 * records are name:passwd:uid:gid:gecos:dir:shell — seven ':'-separated
 * fields. Everything here is POSIX.1-2008 base (Level 1).
 *
 * The non-reentrant forms getpwnam/getpwuid/getpwent return a pointer to a
 * static structure whose contents — including the strings it points at —
 * are overwritten by the next call to any of the three, so the result must
 * be copied out before the next database call. getpwnam/getpwuid open and
 * scan the whole file per call; getpwent walks a cursor that setpwent
 * rewinds and endpwent closes.
 *
 * The getpwnam_r/getpwuid_r/getpwent_r forms write the entry into
 * caller-supplied storage (struct, char buffer of bufsize bytes) and
 * return 0 on success with *result pointing at the filled struct, or an
 * error number as the return value with *result left NULL: ERANGE when the
 * buffer is too small for the entry, 0 with *result NULL when no entry
 * matches (or the stream is exhausted). errno is never touched by any _r
 * function: the error number IS the return value.
 */

#include <vlibc/features.h>

#include <stddef.h>
#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/* One password database entry (/etc/passwd record). */
struct passwd
{
    char *pw_name;   /* user's login name */
    char *pw_passwd; /* encrypted password; often "x" with shadow files */
    uid_t pw_uid;    /* numeric user id */
    gid_t pw_gid;    /* numeric group id */
    char *pw_gecos;  /* user information (comment) field */
    char *pw_dir;    /* home directory */
    char *pw_shell;  /* login shell */
};

/*
 * Look up the first entry whose name matches; NULL when absent. The result
 * points into shared static storage valid only until the next pwd call.
 */
struct passwd *
getpwnam(const char *name);

/*
 * Look up the first entry whose uid matches; NULL when absent. Result
 * storage is shared with getpwnam/getpwent as described above.
 */
struct passwd *
getpwuid(uid_t uid);

/*
 * Return the next entry from the password stream, opening it on the first
 * call; NULL at end of file. The stream cursor advances per call.
 */
struct passwd *
getpwent(void);

/* Rewind the password stream to its first entry. */
void
setpwent(void);

/* Close the password stream; a later getpwent reopens from the start. */
void
endpwent(void);

int
getpwnam_r(const char *name, struct passwd *pw, char *buf, size_t bufsize, struct passwd **result);

int
getpwuid_r(uid_t uid, struct passwd *pw, char *buf, size_t bufsize, struct passwd **result);

int
getpwent_r(struct passwd *pw, char *buf, size_t bufsize, struct passwd **result);

#ifdef __cplusplus
}
#endif

#endif /* VLIBC_PWD_H */