Make unvis() have more reasonable argument types.

[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 27bf978..e4ef707 100644 (file)
--- a/usr/src/lib/libc/gen/getpwent.3
+++ b/usr/src/lib/libc/gen/getpwent.3
@@ -1,77 +1,138 @@
-.\"    @(#)getpwent.3  5.1 (Berkeley) %G%
+.\" Copyright (c) 1988 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.TH GETPWENT 3  "19 January 1983"
+.\" %sccs.include.redist.man%
+.\"
+.\"    @(#)getpwent.3  6.7 (Berkeley) %G%
+.\"
+.TH GETPWENT 3  ""

 .AT 3
 .SH NAME
 .AT 3
 .SH NAME

-getpwent, getpwuid, getpwnam, setpwent, endpwent \- get password file entry
+getpwent, getpwnam, getpwuid, setpassent, setpwent,
+endpwent \- get password file entries

 .SH SYNOPSIS
 .nf
 .SH SYNOPSIS
 .nf

-.B #include <pwd.h>
-.PP
-.B struct passwd *getpwent()
-.PP
-.B struct passwd *getpwuid(uid)
-.B int uid;
-.PP
-.B struct passwd *getpwnam(name)
-.B char *name;
-.PP
-.B int setpwent()
-.PP
-.B int endpwent()
+.ft B
+#include <sys/types.h>
+#include <pwd.h>
+
+struct passwd *getpwent(void);
+struct passwd *getpwnam(char *login);
+struct passwd *getpwuid(uid_t uid);
+int setpassent(int stayopen);
+int setpwent(void);
+void endpwent(void);
+.ft R

 .fi
 .SH DESCRIPTION
 .fi
 .SH DESCRIPTION

-.I Getpwent,
-.I getpwuid
+.IR Getpwent ,
+.IR getpwuid ,

 and
 .I getpwnam
 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.
-.RS
+each return a pointer to a structure containing the broken-out
+fields of a line in the password file.  This structure is defined
+by the include file
+.IR < pwd.h > ,
+and contains the following fields:

 .PP
 .PP

+.RS

 .nf
 .nf

-.so /usr/include/pwd.h
-.ft R
-.ad
+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 */
+};

 .fi
 .RE
 .PP
 .fi
 .RE
 .PP

-The fields
-.I pw_quota
-and
-.I pw_comment
-are unused; the others have meanings described in
+These fields are more completely described in

 .IR passwd (5).
 .PP
 .IR passwd (5).
 .PP

+.I Getpwnam
+and
+.I getpwuid
+search the password database for a matching user name or user uid,
+respectively, always returning the first one encountered.
+.PP

 .I Getpwent
 .I Getpwent

-reads the next
-line (opening the file if necessary);
-.I setpwent
-rewinds the file;
-.I endpwent
-closes it.
+sequentially reads the password database and is intended for programs
+that wish to process the complete list of users.

 .PP
 .PP

-.I Getpwuid
-and
-.I getpwnam
-search from the beginning until a matching
-.I uid
-or
-.I name
-is found
-(or until EOF is encountered).
+.I Setpassent
+accomplishes two purposes.
+First, it causes
+.I getpwent
+to ``rewind'' to the beginning of the database.
+Additionally, if
+.I 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
+.I 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
+.I Setpwent
+is identical to
+.I setpassent
+with an argument of zero.
+.PP
+.I Endpwent
+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 ``*''.

 .SH FILES
 .SH FILES

-/etc/passwd
+/var/db/pwd.db                 The insecure password database file
+.br
+/var/db/spwd.db                The secure password database file
+.br
+/etc/master.passwd             The current password file
+.br
+/etc/passwd                    A Version 7 format password file

 .SH "SEE ALSO"
 .SH "SEE ALSO"

-getlogin(3), getgrent(3), passwd(5)
+getlogin(3), getgrent(3), passwd(5), pwd_mkdb(8), vipw(8)

 .SH DIAGNOSTICS
 .SH DIAGNOSTICS

-Null pointer
-(0) returned on EOF or error.
+The routines
+.IR getpwent ,
+.IR getpwnam ,
+and
+.IR getpwuid ,
+return a null pointer on EOF or error.
+.I Setpassent
+and
+.I setpwent
+return 0 on failure and 1 on success.
+.I Endpwent
+has no return value.

 .SH BUGS
 .SH BUGS

-All information
-is contained in a static area
-so it must be copied if it is
-to be saved.
-.br
+All information is contained in a static buffer which is overwritten
+by each new call.
+It must be copied elsewhere to be retained.
+.PP
+The routines
+.IR getpwent ,
+.IR endpwent ,
+.IR setpassent ,
+and
+.IR setpwent
+are fairly useless in a networked environment and should be
+avoided, if possible.
+.SH COMPATIBILITY
+The historic function
+.IR setpwfile ,
+which allowed the specification of alternate password databases,
+has been deprecated and is no longer available.