rework get{gr,pw,fs}ent to all be about the same;

fix some obvious problems, document that set{gr,pw,fs}ent closes any
open files

SCCS-vsn: lib/libc/gen/getgrent.3 6.3
SCCS-vsn: lib/libc/gen/getpwent.3 6.4
SCCS-vsn: lib/libc/gen/getfsent.3 6.6

diff --git a/usr/src/lib/libc/gen/getfsent.3 b/usr/src/lib/libc/gen/getfsent.3
index 5effbe1..b4ca66e 100644 (file)
--- a/usr/src/lib/libc/gen/getfsent.3
+++ b/usr/src/lib/libc/gen/getfsent.3
@@ -13,7 +13,7 @@
 .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
 .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"

-.\"    @(#)getfsent.3  6.5 (Berkeley) %G%
+.\"    @(#)getfsent.3  6.6 (Berkeley) %G%

 .\"
 .TH GETFSENT 3  ""
 .UC 4
 .\"
 .TH GETFSENT 3  ""
 .UC 4


@@ -62,11 +62,9 @@ struct fstab {
 The fields have meanings described in
 .IR fstab (5).
 .PP
 The fields have meanings described in
 .IR fstab (5).
 .PP

-.I Getfsent
-reads the next line of the file, opening the file if necessary.
-.PP

 .I Setfsent
 .I Setfsent

-opens the file, or rewinds it if it is already open.
+opens the file (closing any previously opened file) or rewinds it
+if it is already open.

 .PP
 .I Endfsent
 closes the file.
 .PP
 .I Endfsent
 closes the file.


@@ -74,11 +72,15 @@ closes the file.
 .I Getfsspec
 and
 .I getfsfile
 .I Getfsspec
 and
 .I getfsfile

-sequentially search from the beginning of the file until a matching
-special file name or file system file name is found, or until EOF is
-encountered.
+search the entire file (opening it if necessary) for a matching special
+file name or file system file name.
+.PP
+For programs wishing to read the entire database,
+.I getfsent
+reads the next entry (opening the file if necessary).

 .PP
 .PP

-Entries in the file with a type field equivalent to \fIFSTAB_XX\fP
+All entries in the file with a type field equivalent to
+.I FSTAB_XX

 are ignored.
 .SH FILES
 /etc/fstab
 are ignored.
 .SH FILES
 /etc/fstab


@@ -91,7 +93,7 @@ and
 .I getfsfile
 return a null pointer (0) on EOF or error.
 .I Setfsent
 .I getfsfile
 return a null pointer (0) on EOF or error.
 .I Setfsent

-returns 0 on success, 1 on failure.
+returns 0 on failure, 1 on success.

 .I Endfsent
 returns nothing.
 .SH BUGS
 .I Endfsent
 returns nothing.
 .SH BUGS

diff --git a/usr/src/lib/libc/gen/getgrent.3 b/usr/src/lib/libc/gen/getgrent.3
index 5af5b0a..2e687e7 100644 (file)
--- a/usr/src/lib/libc/gen/getgrent.3
+++ b/usr/src/lib/libc/gen/getgrent.3
@@ -1,4 +1,8 @@
-.\"    @(#)getgrent.3  6.2 (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.
+.\"
+.\"    @(#)getgrent.3  6.3 (Berkeley) %G%

 .\"
 .TH GETGRENT 3  ""
 .AT 3
 .\"
 .TH GETGRENT 3  ""
 .AT 3


@@ -6,21 +10,22 @@
 getgrent, getgrgid, getgrnam, setgrent, endgrent setgrfile \- get group file entry
 .SH SYNOPSIS
 .nf
 getgrent, getgrgid, getgrnam, setgrent, endgrent setgrfile \- get group file entry
 .SH SYNOPSIS
 .nf

+.B #include <sys/types.h>

 .B #include <grp.h>
 .PP
 .B struct group *getgrent()
 .PP
 .B struct group *getgrgid(gid)
 .B #include <grp.h>
 .PP
 .B struct group *getgrent()
 .PP
 .B struct group *getgrgid(gid)

-.B int gid;
+.B gid_t gid;

 .PP
 .B struct group *getgrnam(name)
 .B char *name;
 .PP
 .B setgrent()
 .PP
 .PP
 .B struct group *getgrnam(name)
 .B char *name;
 .PP
 .B setgrent()
 .PP

-.B endgrent()
+.B void endgrent()

 .PP
 .PP

-.B setgrfile(name)
+.B void setgrfile(name)

 .B char *name;
 .fi
 .SH DESCRIPTION
 .B char *name;
 .fi
 .SH DESCRIPTION


@@ -28,79 +33,67 @@ getgrent, getgrgid, getgrnam, setgrent, endgrent setgrfile \- get group file ent
 .I getgrgid
 and
 .I getgrnam
 .I getgrgid
 and
 .I getgrnam

-each return pointers
-to an object
-with the following structure
-containing the broken-out
-fields of a line in the group file.
+each return pointers to an object with the following structure
+containing the broken-out fields of a line in the group file,
+as described in
+.IR < grp.h > .

 .RS
 .PP
 .nf
 .RS
 .PP
 .nf

-.so /usr/include/grp.h
+struct group {
+       char    *gr_name;
+       char    *gr_passwd;
+       gid_t   gr_gid;
+       char    **gr_mem;
+};
+.ft R
+.ad

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

-The members of this structure are:
-.TP \w'gr_passwd'u+2n
-gr_name
-The name of the group.
-.br
-.ns
-.TP \w'gr_passwd'u+2n
-gr_passwd
-The encrypted password of the group.
-.br
-.ns
-.TP \w'gr_passwd'u+2n
-gr_gid
-The numerical group-ID.
-.br
-.ns
-.TP \w'gr_passwd'u+2n
-gr_mem
-Null-terminated vector
-of pointers to the individual
-member names.
+The fields have meanings described in
+.IR grp (5).

 .PP
 .PP

-.I Getgrent
-simply reads the next
-line while
-.I getgrgid
+.I Setgrfile
+changes the default group file to
+.IR name ,
+thus allowing usage of alternate group files.
+.PP
+.I Setgrent
+opens the file (closing any previously opened file) or rewinds it
+if it it already open.
+.PP
+.I Endgrent
+closes any open files.
+.PP
+.I Getgrgid

 and
 .I getgrnam
 and
 .I getgrnam

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

 .I gid
 or
 .I gid
 or

-.I name
-is found
-(or until EOF is encountered).
-Each routine picks up
-where the others leave off
-so successive calls may be used
-to search the entire file.
+.IR name .

 .PP
 .PP

-A call to
-.I setgrent
-has the effect of rewinding
-the group file
-to allow
-repeated searches.
-.I Endgrent
-may be called to
-close the group file
-when processing is complete.
-.PP
-\fISetgrfile\fP changes the default group file to \fIname\fP thus allowing
-alternate grioup files to be used.  Note that it does \fInot\fP close the
-previous file.  If this is desired, \fIendgrent\fP should be called prior
-to it.
+For programs wishing to read the entire database,
+.I getgrent
+reads the next entry (opening the file if necessary).

 .SH FILES
 /etc/group
 .SH "SEE ALSO"
 getlogin(3), getpwent(3), group(5)
 .SH DIAGNOSTICS
 .SH FILES
 /etc/group
 .SH "SEE ALSO"
 getlogin(3), getpwent(3), group(5)
 .SH DIAGNOSTICS

-A null pointer
-(0) is returned on EOF or error.
+The routines
+.IR getgrent ,
+.IR getgruid ,
+and
+.IR getgrnam ,
+return a null pointer (0) on EOF or error.
+.I Setgrent
+returns 0 on failure, 1 on success.
+.I Endgrent
+and
+.I setgrfile
+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.
+All information is contained in a static area so it must be
+copied if it is to be saved.

diff --git a/usr/src/lib/libc/gen/getpwent.3 b/usr/src/lib/libc/gen/getpwent.3
index c38d887..68f696d 100644 (file)
--- a/usr/src/lib/libc/gen/getpwent.3
+++ b/usr/src/lib/libc/gen/getpwent.3
@@ -1,4 +1,8 @@
-.\"    @(#)getpwent.3  6.3 (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.
+.\"
+.\"    @(#)getpwent.3  6.4 (Berkeley) %G%

 .\"
 .TH GETPWENT 3  ""
 .AT 3
 .\"
 .TH GETPWENT 3  ""
 .AT 3


@@ -9,16 +13,16 @@ getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file
 .B #include <pwd.h>
 .PP
 .B struct passwd *getpwuid(uid)
 .B #include <pwd.h>
 .PP
 .B struct passwd *getpwuid(uid)

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

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

-.B setpwent()
+.B void setpwent()

 .PP
 .PP

-.B endpwent()
+.B void endpwent()

 .PP
 .B setpwfile(name)
 .B char *name;
 .PP
 .B setpwfile(name)
 .B char *name;


@@ -28,14 +32,24 @@ getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file
 .I getpwuid
 and
 .I getpwnam
 .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


@@ -48,41 +62,31 @@ 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

-Searching of the password file is done using the \fIndbm\fP
-database access routines.
+.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
 .I Setpwent

-opens the database;
-.I endpwent
-closes it.
+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
 .I Getpwuid
 and
 .I getpwnam

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

 .I uid
 or
 .IR name .
 .I uid
 or
 .IR name .

-EOF is returned if there is no entry.

 .PP
 For programs wishing to read the entire database,
 .I getpwent
 .PP
 For programs wishing to read the entire database,
 .I getpwent

-reads the next
-line (opening the database if necessary).
-In addition to opening the database,
-.I setpwent
-can be used to make
-.I getpwent
-begin its search from the beginning of the database.
-.PP
-.I Setpwfile
-changes the default password file to
-.I name
-thus allowing alternate password files to be used.
-Note that it does
-.I not
-close the previous file.
-If this is desired,
-.I endpwent
-should be called prior to it.
+reads the next entry (opening the database or file if necessary).

 .SH FILES
 /etc/passwd
 .SH "SEE ALSO"
 .SH FILES
 /etc/passwd
 .SH "SEE ALSO"


@@ -94,8 +98,12 @@ The routines
 and
 .IR getpwnam ,
 return a null pointer (0) on EOF or error.
 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.
+All information is contained in a static area so it must be
+copied if it is to be saved.