| 1 | .TH GETGRENT 3
|
|---|
| 2 | .SH NAME
|
|---|
| 3 | getgrent, getgrnam, getgrgid, setgrent, endgrent, setgrfile \- group file routines
|
|---|
| 4 | .SH SYNOPSIS
|
|---|
| 5 | .ft B
|
|---|
| 6 | .nf
|
|---|
| 7 | #include <grp.h>
|
|---|
| 8 |
|
|---|
| 9 | struct group *getgrent(void)
|
|---|
| 10 | struct group *getgrnam(const char *\fIname\fP)
|
|---|
| 11 | struct group *getgrgid(gid_t \fIgid\fP)
|
|---|
| 12 | int setgrent(void)
|
|---|
| 13 | void endgrent(void)
|
|---|
| 14 | void setgrfile(const char *\fIfile\fP)
|
|---|
| 15 | .fi
|
|---|
| 16 | .ft P
|
|---|
| 17 | .SH DESCRIPTION
|
|---|
| 18 | These functions are used to obtain information from the group file. They
|
|---|
| 19 | return this information in a
|
|---|
| 20 | .B struct group
|
|---|
| 21 | as defined by <grp.h>:
|
|---|
| 22 | .PP
|
|---|
| 23 | .nf
|
|---|
| 24 | .ta +4n +6n +15n
|
|---|
| 25 | struct group {
|
|---|
| 26 | char *gr_name; /* login name */
|
|---|
| 27 | char *gr_passwd; /* encrypted password */
|
|---|
| 28 | gid_t gr_gid; /* numeric group id */
|
|---|
| 29 | char **gr_mem; /* null-terminated list of group members */
|
|---|
| 30 | };
|
|---|
| 31 | .fi
|
|---|
| 32 | .PP
|
|---|
| 33 | .B Getgrent()
|
|---|
| 34 | reads the group file entry by entry.
|
|---|
| 35 | .B Getgrnam()
|
|---|
| 36 | scans the entire group file for the group with the given
|
|---|
| 37 | .IR name .
|
|---|
| 38 | .B Getgrgid()
|
|---|
| 39 | looks for the first group with the given
|
|---|
| 40 | .IR gid .
|
|---|
| 41 | The
|
|---|
| 42 | .B setgrent()
|
|---|
| 43 | and
|
|---|
| 44 | .B endgrent()
|
|---|
| 45 | functions are used to open and later close the group file. With
|
|---|
| 46 | .B setgrfile()
|
|---|
| 47 | one can specify the file to read other than the normal group file. This
|
|---|
| 48 | only sets the name, the next
|
|---|
| 49 | .B setgrent()
|
|---|
| 50 | call will open the file. Do not touch the file name while it is active.
|
|---|
| 51 | Use
|
|---|
| 52 | .B setgrfile(NULL)
|
|---|
| 53 | to revert back to the normal group file.
|
|---|
| 54 | .PP
|
|---|
| 55 | The usual way to scan the group file is (error checking omitted):
|
|---|
| 56 | .PP
|
|---|
| 57 | .RS
|
|---|
| 58 | .nf
|
|---|
| 59 | .DT
|
|---|
| 60 | setgrent();
|
|---|
| 61 | while ((gr = getgrent()) != NULL)
|
|---|
| 62 | if (appropriate_test(gr)) break;
|
|---|
| 63 | endgrent();
|
|---|
| 64 | .fi
|
|---|
| 65 | .RE
|
|---|
| 66 | .PP
|
|---|
| 67 | The
|
|---|
| 68 | .B gr
|
|---|
| 69 | variable contains the entry that is wanted if non-NULL. The
|
|---|
| 70 | .B getgrnam()
|
|---|
| 71 | and
|
|---|
| 72 | .B getgrgid()
|
|---|
| 73 | functions are implemented as in this example, with error checking of course.
|
|---|
| 74 | .PP
|
|---|
| 75 | .B Getgrent()
|
|---|
| 76 | calls
|
|---|
| 77 | .B setgrent()
|
|---|
| 78 | if this has not yet been done.
|
|---|
| 79 | .B Setgrent()
|
|---|
| 80 | first calls
|
|---|
| 81 | .B endgrent()
|
|---|
| 82 | if the group file is still open. (Other implementations may simply
|
|---|
| 83 | rewind the file.)
|
|---|
| 84 | .SH FILES
|
|---|
| 85 | .TP 15
|
|---|
| 86 | .B /etc/group
|
|---|
| 87 | The group file database.
|
|---|
| 88 | .SH "SEE ALSO"
|
|---|
| 89 | .BR getgroups (2),
|
|---|
| 90 | .BR initgroups (3),
|
|---|
| 91 | .BR getpwent (3),
|
|---|
| 92 | .BR passwd (5).
|
|---|
| 93 | .SH DIAGNOSTICS
|
|---|
| 94 | .B Setgrent()
|
|---|
| 95 | has the same return value and error codes as the
|
|---|
| 96 | .BR open (2)
|
|---|
| 97 | call it uses to open the group file. The
|
|---|
| 98 | .BI get xxx ()
|
|---|
| 99 | functions return NULL on end of file, entry not found, or error. You can
|
|---|
| 100 | set
|
|---|
| 101 | .B errno
|
|---|
| 102 | to zero before the call and check it after.
|
|---|
| 103 | .SH NOTES
|
|---|
| 104 | All
|
|---|
| 105 | .BI get xxx ()
|
|---|
| 106 | routines return a pointer to static storage that is overwritten in each call.
|
|---|
| 107 | .PP
|
|---|
| 108 | Only
|
|---|
| 109 | .B getgrnam()
|
|---|
| 110 | and
|
|---|
| 111 | .B getgrgid()
|
|---|
| 112 | are defined by \s-2POSIX\s+2. The
|
|---|
| 113 | .B _MINIX_SOURCE
|
|---|
| 114 | macro must be defined before including <grp.h> to make the other functions
|
|---|
| 115 | visible. The
|
|---|
| 116 | .B gr_passwd
|
|---|
| 117 | field is also not defined by \s-2POSIX\s+2, but is always visible.
|
|---|
| 118 | Portable code cannot reliably detect errors by setting
|
|---|
| 119 | .B errno
|
|---|
| 120 | to zero. Under MINIX 3 it is better to make a
|
|---|
| 121 | .B getgrent()
|
|---|
| 122 | scan if you need to look up several group-id's or names, but portable code
|
|---|
| 123 | had better use several
|
|---|
| 124 | .B getgrgid()
|
|---|
| 125 | or
|
|---|
| 126 | .B getgrnam()
|
|---|
| 127 | calls. The
|
|---|
| 128 | .B getgrent()
|
|---|
| 129 | is usually available on other systems, but may be very expensive. See
|
|---|
| 130 | .BR initgroups (3)
|
|---|
| 131 | if you are after supplementary group id's.
|
|---|
| 132 | .SH AUTHOR
|
|---|
| 133 | Kees J. Bot (kjb@cs.vu.nl)
|
|---|
| 134 |
|
|---|
| 135 | .\"
|
|---|
| 136 | .\" $PchId: getgrent.3,v 1.2 1996/04/11 06:35:01 philip Exp $
|
|---|
