Split getpw{nam,uid} off into their own man page. Hopefully, this

will help people understand that endpwent() is not normally needed.
OK deraadt@ jmc@

3 files changed, 252 insertions, 107 deletions

diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index a9ebf74aeaa..e88bd1bd6ed 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/lib/libc/gen/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.46 2009/04/21 09:34:51 martynas Exp $
+#	$OpenBSD: Makefile.inc,v 1.47 2009/06/01 21:52:03 millert Exp $
 
 # gen sources
 .PATH: ${LIBCSRCDIR}/arch/${MACHINE_ARCH}/gen ${LIBCSRCDIR}/gen
@@ -51,6 +51,7 @@ MAN+=	alarm.3 auth_subr.3 authenticate.3 basename.3 clock.3 confstr.3 \
 	getbsize.3 getcap.3 getcwd.3 getdomainname.3 getdiskbyname.3 \
 	getfsent.3 getgrent.3 getgrouplist.3 gethostname.3 getloadavg.3 \
 	getmntinfo.3 getnetgrent.3 getpagesize.3 getpass.3 getpwent.3 \
+	getpwnam.3 \
 	getttyent.3 getusershell.3 glob.3 initgroups.3 isalnum.3 isalpha.3 \
 	isascii.3 isblank.3 iscntrl.3 isdigit.3 isfdtype.3 isgraph.3 \
 	isgreater.3 islower.3 isprint.3 ispunct.3 isspace.3 isupper.3 \
@@ -107,9 +108,8 @@ MLINKS+=getgrent.3 endgrent.3 getgrent.3 setgroupent.3 getgrent.3 getgrgid.3 \
 MLINKS+=gethostname.3 sethostname.3
 MLINKS+=getnetgrent.3 endnetgrent.3 getnetgrent.3 innetgr.3 \
 	getnetgrent.3 setnetgrent.3
-MLINKS+=getpwent.3 endpwent.3 getpwent.3 setpassent.3 getpwent.3 getpwnam.3 \
-	getpwent.3 getpwuid.3 getpwent.3 setpwent.3 getpwent.3 setpwfile.3
-MLINKS+=getpwent.3 getpwnam_r.3 getpwent.3 getpwuid_r.3
+MLINKS+=getpwent.3 endpwent.3 getpwent.3 setpassent.3 getpwent.3 setpwent.3
+MLINKS+=getpwnam.3 getpwuid.3 getpwnam.3 getpwnam_r.3 getpwnam.3 getpwuid_r.3
 MLINKS+=getttyent.3 endttyent.3 getttyent.3 getttynam.3 getttyent.3 setttyent.3
 MLINKS+=getusershell.3 endusershell.3 getusershell.3 setusershell.3
 MLINKS+=glob.3 globfree.3
diff --git a/lib/libc/gen/getpwent.3 b/lib/libc/gen/getpwent.3
index bc5d092c23f..c0399f3215f 100644
--- a/lib/libc/gen/getpwent.3
+++ b/lib/libc/gen/getpwent.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: getpwent.3,v 1.23 2008/10/22 20:31:20 jmc Exp $
+.\"	$OpenBSD: getpwent.3,v 1.24 2009/06/01 21:52:03 millert Exp $
 .\"
 .\" Copyright (c) 1988, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,34 +27,19 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: October 22 2008 $
+.Dd $Mdocdate: June 1 2009 $
 .Dt GETPWENT 3
 .Os
 .Sh NAME
 .Nm getpwent ,
-.Nm getpwnam ,
-.Nm getpwuid ,
-.Nm getpwnam_r ,
-.Nm getpwuid_r ,
-.Nm setpassent ,
 .Nm setpwent ,
 .Nm endpwent
-.Nd password database operations
+.Nd sequential password database access
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
 .Fd #include <pwd.h>
 .Ft struct passwd *
 .Fn getpwent void
-.Ft struct passwd *
-.Fn getpwnam "const char *login"
-.Ft struct passwd *
-.Fn getpwuid "uid_t uid"
-.Ft int
-.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result"
-.Ft int
-.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result"
-.Ft int
-.Fn setpassent "int stayopen"
 .Ft void
 .Fn setpwent void
 .Ft void
@@ -81,60 +66,38 @@ struct passwd {
 };
 .Ed
 .Pp
-The functions
-.Fn getpwnam
-and
-.Fn getpwuid
-search the password database for the given login name or user ID,
-respectively, always returning the first one encountered.
-.Pp
-The re-entrant functions
-.Fn getpwnam_r
-and
-.Fn getpwuid_r
-search the password database for the given login name or user ID,
-respectively, always returning the first one encountered.
-The various strings associated with the result are stored in
-.Va buf ,
-and
-.Va pwstore
-is updated to point at those strings.
-.Pp
+The
 .Fn getpwent
-sequentially reads the password database and is intended for programs
+function sequentially reads the password database and is intended for programs
 that wish to process the complete list of users.
 .Pp
-.Fn setpassent
-accomplishes two purposes.
-First, it causes
-.Fn getpwent
-to
-.Dq rewind
-to the beginning of the database.
-Additionally, if
-.Fa stayopen
-is non-zero, file descriptors are left open, significantly speeding
-up subsequent accesses for all of the routines.
-(This latter functionality is unnecessary for
-.Fn getpwent
-as it doesn't close its file descriptors by default.)
-.Pp
 It is dangerous for long-running programs to keep the file descriptors
 open as the database will become out of date if it is updated while the
 program is running.
+Furthermore, programs that run child processes should be careful to call
+.Fn endpwent
+to close these descriptors before calling
+.Xr execve 2
+or
+.Xr system 3 .
 .Pp
 .Fn setpwent
-is equivalent to
-.Fn setpassent
-with an argument of zero.
+causes
+.Fn getpwent
+to
+.Dq rewind
+to the beginning of the database.
 .Pp
 The
 .Fn endpwent
-function closes any open files.
+function closes any file descriptors opened by
+.Fn setpwent
+or
+.Fn getpwent .
 .Pp
 These routines have been written to
 .Dq shadow
-the password file, i.e.,
+the password file, that is,
 allow only certain programs to have access to the encrypted password.
 If the process which calls them has an effective UID of 0 or has the
 .Dq _shadow
@@ -142,49 +105,22 @@ group in its group vector, the encrypted password will be returned, otherwise,
 the password field of the returned structure will point to the string
 .Ql * .
 .Sh YP SUPPORT
-If YP is active, the functions
-.Fn getpwent ,
-.Fn getpwnam ,
-and
-.Fn getpwnam_r
-also use the
+If YP is active,
+.Fn getpwent
+also uses the
 .Pa master.passwd.byname
 YP map (if available) or the
 .Pa passwd.byname
-YP map; and the functions
-.Fn getpwuid
-and
-.Fn getpwuid_r
-also use the
-.Pa master.passwd.byuid
-YP map (if available) or the
-.Pa passwd.byuid
 YP map.
 This is in addition to the passwd file,
 and respects the order of both normal and YP
 entries in the passwd file.
 .Sh RETURN VALUES
-The functions
-.Fn getpwent ,
-.Fn getpwnam ,
-and
-.Fn getpwuid
-return a valid pointer to a passwd structure on success
+The
+.Fn getpwent
+function returns a valid pointer to a passwd structure on success
 or a null pointer if end-of-file is reached or an error occurs.
 .Pp
-The functions
-.Fn getpwnam_r
-and
-.Fn getpwuid_r
-update
-.Va result
-to point to
-.Va pwstore
-and then return 0 on success.
-.Pp
-The
-.Fn setpassent
-function returns 0 on failure or 1 on success.
 The
 .Fn endpwent
 and
@@ -205,6 +141,7 @@ a Version 7 format password file
 .Xr getlogin 2 ,
 .Xr getgrent 3 ,
 .Xr getgrouplist 3 ,
+.Xr getpwnam 3 ,
 .Xr pw_dup 3 ,
 .Xr passwd 5 ,
 .Xr Makefile.yp 8 ,
@@ -214,36 +151,31 @@ a Version 7 format password file
 .Sh HISTORY
 The
 .Fn getpwent ,
-.Fn getpwnam ,
-.Fn getpwuid ,
 .Fn setpwent ,
 and
 .Fn endpwent
 functions appeared in
 .At v7 .
-The
-.Fn setpassent
-function appeared in
-.Bx 4.3 Reno .
 .Pp
 The historic function
 .Xr setpwfile 3 ,
 which allowed the specification of alternate password databases,
 has been deprecated and is no longer available.
 .Sh BUGS
-The functions
+The
+.Fn getpwent
+function stores its results in an internal static buffer and returns
+a pointer to that buffer.
+Subsequent calls to
 .Fn getpwent ,
 .Fn getpwnam ,
-and
+or
 .Fn getpwuid
-leave their results in an internal static object and return
-a pointer to that object.
-Subsequent calls to any of these functions will modify the same object.
+will overwrite the same buffer.
 .Pp
 The routines
 .Fn getpwent ,
 .Fn endpwent ,
-.Fn setpassent ,
 and
 .Fn setpwent
 are fairly useless in a networked environment and should be
diff --git a/lib/libc/gen/getpwnam.3 b/lib/libc/gen/getpwnam.3
new file mode 100644
index 00000000000..f963ae3288a
--- /dev/null
+++ b/lib/libc/gen/getpwnam.3
@@ -0,0 +1,213 @@
+.\"	$OpenBSD: getpwnam.3,v 1.1 2009/06/01 21:52:03 millert Exp $
+.\"
+.\" Copyright (c) 1988, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: June 1 2009 $
+.Dt GETPWNAM 3
+.Os
+.Sh NAME
+.Nm getpwnam ,
+.Nm getpwuid ,
+.Nm getpwnam_r ,
+.Nm getpwuid_r ,
+.Nm setpassent
+.Nd password database operations
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <pwd.h>
+.Ft struct passwd *
+.Fn getpwnam "const char *login"
+.Ft struct passwd *
+.Fn getpwuid "uid_t uid"
+.Ft int
+.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result"
+.Ft int
+.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result"
+.Ft int
+.Fn setpassent "int stayopen"
+.Sh DESCRIPTION
+These functions operate on the password database file which is described in
+.Xr passwd 5 .
+Each entry in the database is defined by the structure
+.Li struct passwd
+found in the include file
+.Aq Pa pwd.h :
+.Bd -literal -offset indent
+struct passwd {
+	char	*pw_name;	/* user name */
+	char	*pw_passwd;	/* encrypted password */
+	uid_t	pw_uid;		/* user uid */
+	gid_t	pw_gid;		/* user gid */
+	time_t	pw_change;	/* password change time */
+	char	*pw_class;	/* user access class */
+	char	*pw_gecos;	/* Honeywell login info */
+	char	*pw_dir;	/* home directory */
+	char	*pw_shell;	/* default shell */
+	time_t	pw_expire;	/* account expiration */
+};
+.Ed
+.Pp
+The functions
+.Fn getpwnam
+and
+.Fn getpwuid
+search the password database for the given login name or user ID,
+respectively, always returning the first one encountered.
+.Pp
+The re-entrant versions,
+.Fn getpwnam_r
+and
+.Fn getpwuid_r ,
+behave similarly but the various strings associated with the result
+are stored in
+.Va buf ,
+and
+.Va pwstore
+is updated to reference those strings.
+.Pp
+.Fn setpassent
+accomplishes two purposes.
+First, it causes
+.Fn getpwent
+to
+.Dq rewind
+to the beginning of the database.
+Additionally, if
+.Fa stayopen
+is non-zero, file descriptors are left open, significantly speeding
+up subsequent accesses for the lookup routines.
+These file descriptors can be closed by a call to
+.Fn endpwent .
+.Pp
+It is dangerous for long-running programs to keep the file descriptors
+open as the database will become out of date if it is updated while the
+program is running.
+Furthermore, programs that run child processes should be careful to call
+.Fn endpwent
+to close these descriptors before calling
+.Xr execve 2
+or
+.Xr system 3 .
+.Pp
+These routines have been written to
+.Dq shadow
+the password file, that is,
+allow only certain programs to have access to the encrypted password.
+If the process which calls them has an effective UID of 0 or has the
+.Dq _shadow
+group in its group vector, the encrypted password will be returned, otherwise,
+the password field of the returned structure will point to the string
+.Ql * .
+.Sh YP SUPPORT
+If YP is active, the functions
+.Fn getpwnam
+and
+.Fn getpwnam_r
+also use the
+.Pa master.passwd.byname
+YP map (if available) or the
+.Pa passwd.byname
+YP map; and the functions
+.Fn getpwuid
+and
+.Fn getpwuid_r
+also use the
+.Pa master.passwd.byuid
+YP map (if available) or the
+.Pa passwd.byuid
+YP map.
+This is in addition to the passwd file,
+and respects the order of both normal and YP
+entries in the passwd file.
+.Sh RETURN VALUES
+The functions
+.Fn getpwnam
+and
+.Fn getpwuid
+return a valid pointer to a passwd structure on success
+or a null pointer if end-of-file is reached or an error occurs.
+.Pp
+The functions
+.Fn getpwnam_r
+and
+.Fn getpwuid_r
+update
+.Va result
+to point to
+.Va pwstore
+and then return 0 on success.
+.Pp
+The
+.Fn setpassent
+function returns 0 on failure or 1 on success.
+.Sh FILES
+.Bl -tag -width /etc/master.passwd -compact
+.It Pa /etc/pwd.db
+insecure password database file
+.It Pa /etc/spwd.db
+secure password database file
+.It Pa /etc/master.passwd
+current password file
+.It Pa /etc/passwd
+a Version 7 format password file
+.El
+.Sh SEE ALSO
+.Xr getlogin 2 ,
+.Xr getgrent 3 ,
+.Xr getgrouplist 3 ,
+.Xr getpwent 3 ,
+.Xr pw_dup 3 ,
+.Xr passwd 5 ,
+.Xr Makefile.yp 8 ,
+.Xr pwd_mkdb 8 ,
+.Xr vipw 8 ,
+.Xr yp 8
+.Sh HISTORY
+The
+.Fn getpwnam
+and
+.Fn getpwuid
+functions appeared in
+.At v7 .
+The
+.Fn setpassent
+function appeared in
+.Bx 4.3 Reno .
+.Sh BUGS
+The
+.Fn getpwnam
+and
+.Fn getpwuid
+functions store their results in an internal static buffer and return
+a pointer to that buffer.
+Subsequent calls to
+.Fn getpwent ,
+.Fn getpwnam ,
+or
+.Fn getpwuid
+will overwrite the same buffer.