BSD 4_4 release

[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 e28fd4f..e69f092 100644 (file)
--- a/usr/src/lib/libc/gen/getpwent.3
+++ b/usr/src/lib/libc/gen/getpwent.3
@@ -1,185 +1,207 @@
-.\" Copyright (c) 1988 The Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1988, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\" Redistribution and use in source and binary forms are permitted
-.\" provided that the above copyright notice and this paragraph are
-.\" duplicated in all such forms and that any documentation,
-.\" advertising materials, and other materials related to such
-.\" distribution and use acknowledge that the software was developed
-.\" by the University of California, Berkeley.  The name of the
-.\" University may not be used to endorse or promote products derived
-.\" from this software without specific prior written permission.
-.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
-.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. 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.

 .\"
 .\"

-.\"    @(#)getpwent.3  6.5 (Berkeley) %G%
+.\" 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.

 .\"
 .\"

-.TH GETPWENT 3  ""
-.AT 3
-.SH NAME
-getpwent, getpwnam, getpwuid, setpassent,
-setpwfile, setpwent, endpwent \- get password file entries
-.SH SYNOPSIS
-.nf
-.B #include <sys/types.h>
-.B #include <pwd.h>
-.PP
-.B struct passwd *getpwent()
-.PP
-.B struct passwd *getpwnam(login)
-.B char *login;
-.PP
-.B struct passwd *getpwuid(uid)
-.B uid_t uid;
-.PP
-.B int setpassent(stayopen)
-.B int stayopen;
-.PP
-.B void setpwfile(file)
-.B char *file;
-.PP
-.B int setpwent()
-.PP
-.B void endpwent()
-.fi
-.SH DESCRIPTION
-.IR Getpwent ,
-.IR getpwuid ,
-and
-.I getpwnam
-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
-.RS
-.nf
+.\"     @(#)getpwent.3 8.1 (Berkeley) 6/4/93
+.\"
+.Dd June 4, 1993
+.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;                       /* user name */
-       char    *pw_passwd;             /* encrypted password */
+       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 */
        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 */
+       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 */
 };
        time_t  pw_expire;      /* account expiration */
 };

-.fi
-.RE
-.PP
-These fields are more completely described in
-.IR passwd (5).
-.PP
-.I Getpwnam
+.Ed
+.Pp
+The functions
+.Fn getpwnam

 and
 and

-.I getpwuid
-search the password database for a matching user name or user uid,
-respectively, returning the first one encountered.  Identical
-user names or user uids may result in undefined behavior.
-.PP
-.I Getpwent
+.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
 sequentially reads the password database and is intended for programs

-that wish to step through the complete list of users.
-.PP
-All three routines will open the password file for reading, if
-necessary.
-.PP
-.I Setpwfile
-changes the default password file to
-.IR file ,
-thus allowing the use of alternate password files.
-.PP
-.I Setpassent
-opens the file or rewinds it if it is already open.  If
-.I stayopen
+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
 is non-zero, file descriptors are left open, significantly speeding

-up subsequent calls.  This functionality is unnecessary for
-.I getpwent
-as it doesn't close its file descriptors by default.  It should also
-be noted that it is dangerous for long-running programs to use this
-functionality as the password file may be updated by
-.IR chpass (1),
-.IR passwd (1),
-or
-.IR vipw (8).
-.PP
-.I Setpwent
+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
 is identical to

-.I setpassent
+.Fn setpassent

 with an argument of zero.
 with an argument of zero.

-.PP
-.I Endpwent
+.Pp
+The
+.Fn endpwent
+function

 closes any open files.
 closes any open files.

-.PP
+.Pp

 These routines have been written to ``shadow'' the password file, e.g.
 allow only certain programs to have access to the encrypted password.
 These routines have been written to ``shadow'' the password file, e.g.
 allow only certain programs to have access to the encrypted password.

-This is done by using the
-.IR mkpasswd (8)
-program, which creates
-.IR ndbm (3)
-databases that correspond to the password file, with the single exception
-that, rather than storing the encrypted password in the database, it stores
-the offset in the password file where the encrypted password may be found.
-.IR Getpwent ,
-.IR getpwnam ,
-and
-.I getpwuid
-will use the
-.I ndbm
-files in preference to the ``real'' password files, only reading the
-password file itself, to obtain the encrypted password, if the process
-is running with an effective user id equivalent to super-user.
-If the password file itself is protected, and the
-.I ndbm
-files are not, this makes the password available only to programs
-running with super-user privileges.
-.SH FILES
-/etc/passwd
-.SH "SEE ALSO"
-getlogin(3), getgrent(3), ndbm(3), passwd(5)
-.SH DIAGNOSTICS
-The routines
-.IR getpwent ,
-.IR getpwnam ,
+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

-.IR getpwuid ,
-return a null pointer on EOF or error.
-.I Setpassent
+.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

-.I setpwent
+.Fn setpwent

 return 0 on failure and 1 on success.
 return 0 on failure and 1 on success.

-.I Endpwent
+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
 and

-.I setpwfile
-have no return value.
-.SH BUGS
-All information is contained in a static buffer which is overwritten
-by each new call.  It must be copied elsewhere to be retained.
-.PP
-Intermixing calls to
-.IR getpwent
-with calls to
-.I getpwnam
-or
-.IR getpwuid ,
-or intermixing calls to
-.I getpwnam
+.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
 and

-.IR getpwuid ,
-after using
-.I setpassent
-to require that file descriptors be left open, may result
-in undefined behavior.
-.PP
+.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
 The routines

-.IR getpwent ,
-.IR endpwent ,
-.IR setpassent ,
+.Fn getpwent ,
+.Fn endpwent ,
+.Fn setpassent ,

 and
 and

-.IR setpwent
+.Fn setpwent

 are fairly useless in a networked environment and should be
 avoided, if possible.
 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.