feat(passwd): getpw*/getgr*/setpwent/endpwent family

include/pwd.h

@@ -0,0 +1,90 @@
+#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 */