128 lines
4.8 KiB
HTML
128 lines
4.8 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>getgrent(3)</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>getgrent(3)</H1>
|
|
<HR>
|
|
<PRE>
|
|
|
|
</PRE>
|
|
<H2>NAME</H2><PRE>
|
|
getgrent, getgrnam, getgrgid, setgrent, endgrent, setgrfile - group file
|
|
routines
|
|
|
|
|
|
</PRE>
|
|
<H2>SYNOPSIS</H2><PRE>
|
|
<STRONG>#include</STRONG> <STRONG><grp.h></STRONG>
|
|
|
|
<STRONG>struct</STRONG> <STRONG>group</STRONG> <STRONG>*getgrent(void)</STRONG>
|
|
<STRONG>struct</STRONG> <STRONG>group</STRONG> <STRONG>*getgrnam(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>name</EM><STRONG>)</STRONG>
|
|
<STRONG>struct</STRONG> <STRONG>group</STRONG> <STRONG>*getgrgid(gid_t</STRONG> <EM>gid</EM><STRONG>)</STRONG>
|
|
<STRONG>int</STRONG> <STRONG>setgrent(void)</STRONG>
|
|
<STRONG>void</STRONG> <STRONG>endgrent(void)</STRONG>
|
|
<STRONG>void</STRONG> <STRONG>setgrfile(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>file</EM><STRONG>)</STRONG>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
These functions are used to obtain information from the group file. They
|
|
return this information in a <STRONG>struct</STRONG> <STRONG>group</STRONG> as defined by <grp.h>:
|
|
|
|
struct group {
|
|
char *gr_name; /* login name */
|
|
char *gr_passwd; /* encrypted password */
|
|
gid_t gr_gid; /* numeric group id */
|
|
char **gr_mem; /* null-terminated list of group members */
|
|
};
|
|
|
|
<STRONG>Getgrent()</STRONG> reads the group file entry by entry. <STRONG>Getgrnam()</STRONG> scans the
|
|
entire group file for the group with the given <EM>name</EM>. <STRONG>Getgrgid()</STRONG> looks
|
|
for the first group with the given <EM>gid</EM>. The <STRONG>setgrent()</STRONG> and <STRONG>endgrent()</STRONG>
|
|
functions are used to open and later close the group file. With
|
|
<STRONG>setgrfile()</STRONG> one can specify the file to read other than the normal group
|
|
file. This only sets the name, the next <STRONG>setgrent()</STRONG> call will open the
|
|
file. Do not touch the file name while it is active. Use
|
|
<STRONG>setgrfile(NULL)</STRONG> to revert back to the normal group file.
|
|
|
|
The usual way to scan the group file is (error checking omitted):
|
|
|
|
setgrent();
|
|
while ((gr = getgrent()) != NULL)
|
|
if (appropriate_test(gr)) break;
|
|
endgrent();
|
|
|
|
The <STRONG>gr</STRONG> variable contains the entry that is wanted if non-NULL. The
|
|
<STRONG>getgrnam()</STRONG> and <STRONG>getgrgid()</STRONG> functions are implemented as in this example,
|
|
with error checking of course.
|
|
|
|
<STRONG>Getgrent()</STRONG> calls <STRONG>setgrent()</STRONG> if this has not yet been done. <STRONG>Setgrent()</STRONG>
|
|
first calls <STRONG>endgrent()</STRONG> if the group file is still open. (Other
|
|
implementations may simply rewind the file.)
|
|
|
|
|
|
|
|
</PRE>
|
|
<H2>FILES</H2><PRE>
|
|
|
|
<STRONG>/etc/group</STRONG> The group file database.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
<STRONG><A HREF="../man2/getgroups.2.html">getgroups(2)</A></STRONG>, <STRONG><A HREF="../man3/initgroups.3.html">initgroups(3)</A></STRONG>, <STRONG><A HREF="../man3/getpwent.3.html">getpwent(3)</A></STRONG>, <STRONG><A HREF="../man5/passwd.5.html">passwd(5)</A></STRONG>.
|
|
|
|
|
|
</PRE>
|
|
<H2>DIAGNOSTICS</H2><PRE>
|
|
<STRONG>Setgrent()</STRONG> has the same return value and error codes as the <STRONG><A HREF="../man2/open.2.html">open(2)</A></STRONG> call
|
|
it uses to open the group file. The <STRONG>get</STRONG><EM>xxx</EM><STRONG>()</STRONG> functions return NULL on
|
|
end of file, entry not found, or error. You can set <STRONG>errno</STRONG> to zero before
|
|
the call and check it after.
|
|
|
|
|
|
</PRE>
|
|
<H2>NOTES</H2><PRE>
|
|
All <STRONG>get</STRONG><EM>xxx</EM><STRONG>()</STRONG> routines return a pointer to static storage that is
|
|
overwritten in each call.
|
|
|
|
Only <STRONG>getgrnam()</STRONG> and <STRONG>getgrgid()</STRONG> are defined by POSIX. The <STRONG>_MINIX_SOURCE</STRONG>
|
|
macro must be defined before including <grp.h> to make the other
|
|
functions visible. The <STRONG>gr_passwd</STRONG> field is also not defined by POSIX, but
|
|
is always visible. Portable code cannot reliably detect errors by
|
|
setting <STRONG>errno</STRONG> to zero. Under Minix it is better to make a <STRONG>getgrent()</STRONG>
|
|
scan if you need to look up several group-id's or names, but portable
|
|
code had better use several <STRONG>getgrgid()</STRONG> or <STRONG>getgrnam()</STRONG> calls. The
|
|
<STRONG>getgrent()</STRONG> is usually available on other systems, but may be very
|
|
expensive. See <STRONG><A HREF="../man3/initgroups.3.html">initgroups(3)</A></STRONG> if you are after supplementary group id's.
|
|
|
|
|
|
</PRE>
|
|
<H2>AUTHOR</H2><PRE>
|
|
Kees J. Bot (kjb@cs.vu.nl)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</PRE>
|
|
</BODY>
|
|
</HTML>
|