4.4BSD snapshot (revision 8.1)

[unix-history] / usr / src / lib / libc / gen / getpwent.3

diff --git a/usr/src/lib/libc/gen/getpwent.3 b/usr/src/lib/libc/gen/getpwent.3
index 68f696d..93b8170 100644 (file)
--- a/usr/src/lib/libc/gen/getpwent.3
+++ b/usr/src/lib/libc/gen/getpwent.3
@@ -1,109 +1,181 @@
-.\" Copyright (c) 1988 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1988, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\"    @(#)getpwent.3  6.4 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH GETPWENT 3  ""
-.AT 3
-.SH NAME
-getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file entry
-.SH SYNOPSIS
-.nf
-.B #include <pwd.h>
-.PP
-.B struct passwd *getpwuid(uid)
-.B uid_t uid;
-.PP
-.B struct passwd *getpwnam(name)
-.B char *name;
-.PP
-.B struct passwd *getpwent()
-.PP
-.B void setpwent()
-.PP
-.B void endpwent()
-.PP
-.B setpwfile(name)
-.B char *name;
-.fi
-.SH DESCRIPTION
-.I Getpwent,
-.I getpwuid
-and
-.I getpwnam
-each return a pointer to an object with the following structure,
-containing the broken-out fields of a line in the password file,
-as described in
-.IR < pwd.h > .
-.RS
-.PP
-.nf
+.\"     @(#)getpwent.3 8.1 (Berkeley) %G%
+.\"
+.Dd 
+.Dt GETPWENT 3
+.Os
+.Sh NAME
+.Nm getpwent ,
+.Nm getpwnam ,
+.Nm getpwuid ,
+.Nm setpassent ,
+.Nm setpwent ,
+.Nm endpwent
+.Nd password database operations
+.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 setpassent "int  stayopen"
+.Ft int
+.Fn setpwent void
+.Ft void
+.Fn endpwent void
+.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
+.Ar passwd
+found in the include
+file
+.Aq Pa pwd.h :
+.Bd -literal -offset indent

 struct passwd {
 struct passwd {

-       char    *pw_name;
-       char    *pw_passwd;
-       uid_t   pw_uid;
-       gid_t   pw_gid;
-       int     pw_quota;
-       char    *pw_comment;
-       char    *pw_gecos;
-       char    *pw_dir;
-       char    *pw_shell;
+       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 */

 };
 };

-.ft R
-.ad
-.fi
-.RE
-.PP
-The fields
-.I pw_quota
+.Ed
+.Pp
+The functions
+.Fn getpwnam

 and
 and

-.I pw_comment
-are unused; the others have meanings described in
-.IR passwd (5).
-.PP
-.I Setpwfile
-changes the default password file to
-.IR name ,
-thus allowing usage of alternate password files.  If \fIndbm\fP databases
-are available for any password files, they are used, otherwise the file
-itself is linearly searched.
-.PP
-.I Setpwent
-opens the database or file (closing any previously opened database or file)
-or rewinds it if it is already open.
-.PP
-.I Endpwent
-closes any open databases or files.
-.PP
-.I Getpwuid
+.Fn getpwuid
+search the password database for the given login name or user uid,
+respectively, always returning the first one encountered.
+.Pp
+The
+.Fn getpwent
+function
+sequentially reads the password database and is intended for programs
+that wish to process the complete list of users.
+.Pp
+The
+.Fn setpassent
+function
+accomplishes two purposes.
+First, it causes
+.Fn getpwent
+to ``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 the database will become out of date if it is updated while the
+program is running.
+.Pp
+The
+.Fn setpwent
+function
+is identical to
+.Fn setpassent
+with an argument of zero.
+.Pp
+The
+.Fn endpwent
+function
+closes any open files.
+.Pp
+These routines have been written to ``shadow'' the password file, e.g.
+allow only certain programs to have access to the encrypted password.
+If the process which calls them has an effective uid of 0, the encrypted
+password will be returned, otherwise, the password field of the retuned
+structure will point to the string
+.Ql * .
+.Sh RETURN VALUES
+The functions
+.Fn getpwent ,
+.Fn getpwnam ,

 and
 and

-.I getpwnam
-search the entire database or file (opening it if necessary) for a matching
-.I uid
-or
-.IR name .
-.PP
-For programs wishing to read the entire database,
-.I getpwent
-reads the next entry (opening the database or file if necessary).
-.SH FILES
-/etc/passwd
-.SH "SEE ALSO"
-getlogin(3), getgrent(3), passwd(5)
-.SH DIAGNOSTICS
-The routines
-.IR getpwent ,
-.IR getpwuid ,
+.Fn getpwuid ,
+return a valid pointer to a passwd structure on success
+and a null pointer if end-of-file is reached or an error occurs.
+The functions
+.Fn setpassent

 and
 and

-.IR getpwnam ,
-return a null pointer (0) on EOF or error.
-.I Setpwent
-returns 0 on failure, 1 on success.
-.I Endpwent
+.Fn setpwent
+return 0 on failure and 1 on success.
+The
+.Fn endpwent
+function
+has no return value.
+.Sh FILES
+.Bl -tag -width /etc/master.passwd -compact
+.It Pa /var/db/pwd.db
+The insecure password database file
+.It Pa /var/db/spwd.db
+The secure password database file
+.It Pa /etc/master.passwd
+The current password file
+.It Pa /etc/passwd
+A Version 7 format password file
+.El
+.Sh SEE ALSO
+.Xr getlogin 3 ,
+.Xr getgrent 3 ,
+.Xr passwd 5 ,
+.Xr pwd_mkdb 8 ,
+.Xr vipw 8
+.Sh HISTORY
+The
+.Nm getpwent ,
+.Nm getpwnam ,
+.Nm getpwuid ,
+.Nm setpwent,
+and
+.Nm endpwent
+functions appeared in
+.At v7 .
+The
+.Nm setpassent
+function appeared in
+.Bx 4.3 Reno .
+.Sh BUGS
+The functions
+.Fn getpwent ,
+.Fn getpwnam ,
+and
+.Fn getpwuid ,
+leave their results in an internal static object and return
+a pointer to that object. Subsequent calls to
+the same function
+will modify the same object.
+.Pp
+The routines
+.Fn getpwent ,
+.Fn endpwent ,
+.Fn setpassent ,

 and
 and

-.I setpwfile
-have no return value.
-.SH BUGS
-All information is contained in a static area so it must be
-copied if it is to be saved.
+.Fn setpwent
+are fairly useless in a networked environment and should be
+avoided, if possible.
+.Sh COMPATIBILITY
+The historic function
+.Xr setpwfile 3 ,
+which allowed the specification of alternate password databases,
+has been deprecated and is no longer available.