from scratch; write to /dev/tty if possible, block interrupts

[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..68f696d 100644 (file)
--- a/usr/src/lib/libc/gen/getpwent.3
+++ b/usr/src/lib/libc/gen/getpwent.3
@@ -1,38 +1,55 @@
-.\"    @(#)getpwent.3  5.1 (Berkeley) %G%
+.\" Copyright (c) 1988 Regents of the University of California.
+.\" All rights reserved.  The Berkeley software License Agreement
+.\" specifies the terms and conditions for redistribution.

 .\"
 .\"

-.TH GETPWENT 3  "19 January 1983"
+.\"    @(#)getpwent.3  6.4 (Berkeley) %G%
+.\"
+.TH GETPWENT 3  ""

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

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

 .SH SYNOPSIS
 .nf
 .B #include <pwd.h>
 .PP
 .SH SYNOPSIS
 .nf
 .B #include <pwd.h>
 .PP

-.B struct passwd *getpwent()
-.PP

 .B struct passwd *getpwuid(uid)
 .B struct passwd *getpwuid(uid)

-.B int uid;
+.B uid_t uid;

 .PP
 .B struct passwd *getpwnam(name)
 .B char *name;
 .PP
 .PP
 .B struct passwd *getpwnam(name)
 .B char *name;
 .PP

-.B int setpwent()
+.B struct passwd *getpwent()
+.PP
+.B void setpwent()
+.PP
+.B void endpwent()

 .PP
 .PP

-.B int endpwent()
+.B setpwfile(name)
+.B char *name;

 .fi
 .SH DESCRIPTION
 .I Getpwent,
 .I getpwuid
 and
 .I getpwnam
 .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.
+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
 .RS
 .PP
 .nf

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

 .ft R
 .ad
 .fi
 .ft R
 .ad
 .fi


@@ -45,33 +62,48 @@ and
 are unused; the others have meanings described in
 .IR passwd (5).
 .PP
 are unused; the others have meanings described in
 .IR passwd (5).
 .PP

-.I Getpwent
-reads the next
-line (opening the file if necessary);
-.I setpwent
-rewinds the file;
-.I endpwent
-closes it.
+.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
 and
 .I getpwnam
 .PP
 .I Getpwuid
 and
 .I getpwnam

-search from the beginning until a matching
+search the entire database or file (opening it if necessary) for a matching

 .I uid
 or
 .I uid
 or

-.I name
-is found
-(or until EOF is encountered).
+.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
 .SH FILES
 /etc/passwd
 .SH "SEE ALSO"
 getlogin(3), getgrent(3), passwd(5)
 .SH DIAGNOSTICS

-Null pointer
-(0) returned on EOF or error.
+The routines
+.IR getpwent ,
+.IR getpwuid ,
+and
+.IR getpwnam ,
+return a null pointer (0) on EOF or error.
+.I Setpwent
+returns 0 on failure, 1 on success.
+.I Endpwent
+and
+.I setpwfile
+have 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 area so it must be
+copied if it is to be saved.