1 files changed, 27 insertions, 0 deletions
diff --git a/doc/passwd b/doc/passwd
new file mode 100644
index 0000000..42d41c6
--- /dev/null
+++ b/doc/passwd
@@ -0,0 +1,27 @@
+Pseudo provides limited support for faking up password file access.
+
+Routines such as setpwent(), getpwent(), and so on, are modified to
+possibly pick a password file other than /etc/passwd, and likewise
+for setgrent() and /etc/group.  The logic is as follows:
+
+* If a chroot directory is set, <chroot>/etc is tried first.
+* If PSEUDO_PASSWD is set, PSEUDO_PASSWD/etc is tried next.
+* Otherwise, fall back on /etc.
+
+In each case, failure to find a passwd or group file results in
+going on to trying the next case.
+
+The behavior of lckpwdf()/ulckpwdf() is a special case.  In this
+case, the same order of directories is tried, but pseudo attempts
+to create the files, rather than attempting to open existing files.
+
+The underlying implementation directs nearly everything to
+fgetpwent_r() and fgetgrent_r(), which are extensions available in
+glibc.  This allows pseudo to avoid having to actually implement yet
+another horrible passwd file parser which would inevitably have
+bugs that have already been fixed dozens of times in other
+implementations.
+
+Note that both the chroot directory and PSEUDO_PASSWD are assumed
+to be the parent directory of etc, not the directory containing the
+passwd and group files.