getgrent(3C) DG/UX 5.4R3.00 getgrent(3C)
NAME
getgrent, getgrentr, getgrgid, getgrgidr, getgrnam, getgrnamr,
setgrent, endgrent, fgetgrent, fgetgrentr - get group file entry
SYNOPSIS
#include <grp.h>
struct group *getgrent(void)
struct group *getgrentr(struct group *result, char *buffer, int buflen)
struct group *getgrgid(gidt gid)
struct group *getgrgidr(gidt gid, struct group *result, char *buffer,
int buflen)
struct group *getgrnam(const char *name)
struct group *getgrnamr(const char *name, struct group *result,
char *buffer, int buflen)
void setgrent(void)
void endgrent(void)
struct group *fgetgrent(FILE *f)
struct group *fgetgrentr(FILE *f, struct group *result, char *buffer,
int buflen)
DESCRIPTION
getgrent, getgrentr, getgrgid, getgrgidr, getgrnam, and getgrnamr
each return pointers to an object with the following structure
containing the broken-out fields of a line in the group file.
struct group {
char *grname;
char *grpasswd;
gidt grgid;
char **grmem;
};
The members of this structure are:
grname The name of the group.
grpasswd The encrypted password of the group.
grgid The numerical group-ID.
grmem Null-terminated vector of pointers to the individual
member names.
getgrent and getgrentr simply read the next line while getgrgid,
getgrgidr, getgrnam, and getgrnamr search until a matching gid or
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
Licensed material--property of copyright holder(s) 1
getgrent(3C) DG/UX 5.4R3.00 getgrent(3C)
the entire file.
A call to setgrent has the effect of rewinding the group file to
allow repeated searches. endgrent may be called to close the group
file when processing is complete.
fgetgrent and fgetgrentr return a pointer to the next group
structure in the stream f, which must refer to an open file in the
same format as the group file /etc/group.
The functions getgrentr, getgrgidr, getgrnamr, and fgetgrentr
differ from their non r counterparts by the addition of three
arguments. When calling these, the group structure pointed to by
result will be updated. In addition, a pointer to a buffer and
buflen (the length of the buffer) must be passed. These new
arguments are used to rid the r functions' dependencies on static
data. Storage referenced by the group structure will be allocated
from the memory provided by buffer.
Considerations for Threads Programming
+------------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+------------+-----------------------------+
|endgrent | Y N N |
|fgetgrent | N - - |
|fgetgrentr | Y N N |
|getgrent | N - - |
|getgrentr | Y N N |
|getgrgid | N - - |
|getgrgidr | Y Y N |
|getgrnam | N - - |
|getgrnamr | Y Y N |
|setgrent | Y N N |
+------------+-----------------------------+
When the getgrentr, getgrgidr, getgrnamr, and fgetgrentr
functions are used in a threaded application, they share the same
state information (position in file, etc.) so they can work
cooperatively. In other words, if a number of threads are repeatedly
calling the getgrentr function, each routine call will pick up where
the other left off so successive calls in all threads may be used to
search the entire file.
FILES
/etc/group
DIAGNOSTICS
A null pointer (0) is returned on EOF or error.
If the functions getgrentr, getgrgidr, getgrnamr, and fgetgrentr
are called with insufficient storage supplied via buffer and buflen
to contain the data to be referenced by the resulting struct group
structure, the function will return a NULL and errno will be set to
Licensed material--property of copyright holder(s) 2
getgrent(3C) DG/UX 5.4R3.00 getgrent(3C)
ERANGE.
NOTES
The functions getgrentr, getgrgidr, getgrnamr, and fgetgrentr are
only available in the shared library libc.so.
The functions getgrentr and fgetgrentr are only visible when the
DGUXTHREADSEXTENSIONS macro is defined during compilation (cc
-DDGUXTHREADSEXTENSIONS). This is because these functions are not
part of the 1003.4a Draft.
SEE ALSO
bcscat(1M), ypserv(1M), reentrant(3), getlogin(3C), getpwent(3C),
group(4).
BUGS
In all of the above functions except getgrentr, getgrgidr,
getgrnamr, and fgetgrentr, the information is contained in a static
area, so it must be copied if it is to be saved.
STANDARDS
When using m88kbcs as the Software Development Environment target,
the functions mentioned above will be implemented on top of the
bcscat command. Because of this, some performance degradation may
be noticed in comparison to using these routines in /lib/libc.a.
Licensed material--property of copyright holder(s) 3