define new library function getgrouplist

[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..9f1c892 100644 (file)
--- a/usr/src/lib/libc/gen/getgrent.3
+++ b/usr/src/lib/libc/gen/getgrent.3
@@ -1,106 +1,166 @@
-.\"    @(#)getgrent.3  6.2 (Berkeley) %G%
+.\" Copyright (c) 1989, 1991 The Regents of the University of California.
+.\"  All rights reserved.

 .\"
 .\"

-.TH GETGRENT 3  ""
-.AT 3
-.SH NAME
-getgrent, getgrgid, getgrnam, setgrent, endgrent setgrfile \- get group file entry
-.SH SYNOPSIS
-.nf
-.B #include <grp.h>
-.PP
-.B struct group *getgrent()
-.PP
-.B struct group *getgrgid(gid)
-.B int gid;
-.PP
-.B struct group *getgrnam(name)
-.B char *name;
-.PP
-.B setgrent()
-.PP
-.B endgrent()
-.PP
-.B setgrfile(name)
-.B char *name;
-.fi
-.SH DESCRIPTION
-.I Getgrent,
-.I getgrgid
+.\" %sccs.include.redist.man%
+.\"
+.\"     @(#)getgrent.3 6.8 (Berkeley) %G%
+.\"
+.Dd 
+.Dt GETGRENT 3
+.Os
+.Sh NAME
+.Nm getgrent ,
+.Nm getgrnam ,
+.Nm getgrgid ,
+.Nm setgroupent ,
+.\" .Nm setgrfile ,
+.Nm setgrent ,
+.Nm endgrent
+.Nd group database operations
+.Sh SYNOPSIS
+.Fd #include <grp.h>
+.Ft struct group *
+.Fn getgrent void
+.Ft struct group *
+.Fn getgrname "const char *name"
+.Ft struct group *
+.Fn getgrgid "gid_t gid"
+.Ft struct group *
+.Fn setgroupent "int stayopen"
+.\" .Ft void
+.\" .Fn setgrfile "const char *name"
+.Ft int
+.Fn setgrent void
+.Ft void
+.Fn endgrent void
+.Sh DESCRIPTION
+These functions operate on the group database file
+.Pa /etc/group
+which is described
+in
+.Xr group 5 .
+Each line of the database is defined by the structure
+.Ar group
+found in the include
+file
+.Aq Pa grp.h :
+.Bd -literal -offset indent
+struct group {
+       char    *gr_name;       /* group name */
+       char    *gr_passwd;     /* group password */
+       gid_t   gr_gid;         /* group id */
+       char    **gr_mem;       /* group members */
+};
+.Ed
+.Pp
+The functions
+.Fn getgrnam
+and
+.Fn getgrgid
+search the group database for the given group name pointed to by
+.Ar name
+or the group id pointed to by
+.Ar gid ,
+respectively, returning the first one encountered.  Identical group
+names or group gids may result in undefined behavior.
+.Pp
+The
+.Fn getgrent
+function
+sequentially reads the group database and is intended for programs
+that wish to step through the complete list of groups.
+.Pp
+All three routines will open the group file for reading, if necesssary.
+.Pp
+The
+.Fn setgroupent
+function
+opens the file, or rewinds it if it is already open.  If
+.Fa stayopen
+is non-zero, file descriptors are left open, significantly speeding
+functions subsequent calls.  This functionality is unnecessary for
+.Fn getgrent
+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 group file may be updated.
+.Pp
+The
+.Fn setgrent
+function
+is identical to
+.Fn setgroupent
+with an argument of zero.
+.Pp
+The
+.Fn endgrent
+function
+closes any open files.
+.Sh RETURN VALUES
+The functions
+.Fn getgrent ,
+.Fn getgrnam ,
+and
+.Fn getgrgid ,
+return a pointer to the group entry if successful; if end-of-file
+is reached or an error occurs a null pointer is returned.
+The functions
+.Fn setgroupent
+and
+.Fn setgrent
+return the value 1 if successful, otherwise the value
+0 is returned.
+The functions
+.Fn endgrent
+and
+.Fn setgrfile
+have no return value.
+.Sh FILES
+.Bl -tag -width /etc/group -compact
+.It Pa /etc/group
+group database file
+.El
+.Sh SEE ALSO
+.Fn getpwent 3 ,
+.Fn group 5
+.Sh HISTORY
+The functions
+.Fn endgrent ,
+.Fn getgrent ,
+.Fn getgrnam ,
+.Fn getgrgid ,
+and
+.Fn setgrent
+appeared in
+.At v7 .
+The functions
+.Fn setgrfile
+and
+.Fn setgroupent
+appeared in
+.Bx 4.3 Reno .
+.Sh COMPATIBILITY
+The historic function
+.Fn setgrfile ,
+which allowed the specification of alternate password databases, has
+been deprecated and is no longer available.
+.Sh BUGS
+The functions
+.Fn getgrent ,
+.Fn getgrnam ,
+.Fn getgrgid ,
+.Fn setgroupent

 and
 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.
-.RS
-.PP
-.nf
-.so /usr/include/grp.h
-.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.
-.PP
-.I Getgrent
-simply reads the next
-line while
-.I getgrgid
+.Fn setgrent
+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 functions
+.Fn getgrent ,
+.Fn endgrent ,
+.Fn setgroupent ,

 and
 and

-.I getgrnam
-search until a matching
-.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.
-.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.
-.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.
-.SH BUGS
-All information is contained in a static area so it must be copied if it is
-to be saved.
+.Fn setgrent
+are fairly useless in a networked environment and should be
+avoided, if possible.