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

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

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.