Standard C Library Functions getgrnam(3C)
NAME
getgrnam, getgrnamr, getgrent, getgrentr, getgrgid,
getgrgidr, setgrent, endgrent, fgetgrent, fgetgrentr -
group database entry functions
SYNOPSIS
#include
struct group *getgrnam(const char *name);
struct group *getgrnamr(const char *name, struct group *grp,
char *buffer, int bufsize);
struct group *getgrent(void);
struct group *getgrentr(struct group *grp, char *buffer, int bufsize);
struct group *getgrgid(gidt gid);
struct group *getgrgidr(gidt gid, struct group *grp, char *buffer,
int bufsize);
void setgrent(void);
void endgrent(void);
struct group *fgetgrent(FILE *f);
struct group *fgetgrentr(FILE *f, struct group *grp, char *buffer,
int bufsize);
Standard comforming
cc [ flag... ] file... -DPOSIXPTHREADSEMANTICS [ library... ]
int getgrnamr(const char *name, struct group *grp, char *buffer,
sizet bufsize, struct group **result);
int getgrgidr(gidt gid, struct group *grp, char *buffer,
sizet bufsize, struct group **result);
SunOS 5.11 Last change: 5 Apr 2004 1
Standard C Library Functions getgrnam(3C)
DESCRIPTION
These functions are used to obtain entries describing user
groups. Entries can come from any of the sources for group
specified in the /etc/nsswitch.conf file (see
nsswitch.conf(4)).
The getgrnam() function searches the group database for an
entry with the group name specified by the character string
parameter name.
The getgrgid() function searches the group database for an
entry with the (numeric) group id specified by gid.
The setgrent(), getgrent(), and endgrent() functions are
used to enumerate group entries from the database.
The setgrent() function effectively rewinds the group data-
base to allow repeated searches. It sets (or resets) the
enumeration to the beginning of the set of group entries.
This function should be called before the first call to get-
grent().
The getgrent() function returns a pointer to a structure
containing the broken-out fields of an entry in the group
database. When first called, getgrent() returns a pointer
to a group structure containing the next group structure in
the group database. Successive calls can be used to search
the entire database.
The endgrent() function can be called to close the group
database and deallocate resources when processing is com-
plete. It is permissible, though possibly less efficient,
for the process to call more group functions after calling
endgrent().
The fgetgrent() function, unlike the other functions above,
does not use nsswitch.conf. It reads and parses the next
line from the stream f, which is assumed to have the format
of the group file (see group(4)).
Reentrant Interfaces
The getgrnam(), getgrgid(), getgrent(), and fgetgrent()
functions use thread-specific storage that is reused in each
call to one of these functions by the same thread, making
them safe to use but not recommended for multithreaded
SunOS 5.11 Last change: 5 Apr 2004 2
Standard C Library Functions getgrnam(3C)
applications.
The parallel functions getgrnamr(), getgrgidr(),
getgrentr(), and fgetgrentr() provide reentrant interfaces
for these operations.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the r suffix.
The reentrant interfaces, however, use buffers supplied by
the caller to store returned results instead of using
thread-specific data that can be overwritten by each call.
They are safe for use in both single-threaded and mul-
tithreaded applications.
Each reentrant interface takes the same arguments as its
non-reentrant counterpart, as well as the following addi-
tional parameters. The grp argument must be a pointer to a
struct group structure allocated by the caller. On success-
ful completion, the function returns the group entry in this
structure. Storage referenced by the group structure is
allocated from the memory provided with the buffer argument
that is bufsize characters in size. The maximum size needed
for this buffer can be determined with the
SCGETGRSIZEMAX sysconf(3C) parameter. The standard-
conforming versions place a pointer to the modified grp
structure in the result parameter, instead of returning a
pointer to this structure. A null pointer is returned at the
location pointed to by result on error or if the requested
entry is not found.
For enumeration in multithreaded applications, the position
within the enumeration is a process-wide property shared by
all threads. The setgrent() function can be used in a mul-
tithreaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to
getgrentr(), the threads will enumerate disjoint subsets of
the group database. Like their non-reentrant counterparts,
getgrnamr() and getgrgidr() leave the enumeration position
in an indeterminate state.
group Structure
Group entries are represented by the struct group structure
defined in :
struct group {
char *grname; /* the name of the group */
char *grpasswd; /* the encrypted group password */
gidt grgid; /* the numerical group ID */
SunOS 5.11 Last change: 5 Apr 2004 3
Standard C Library Functions getgrnam(3C)
char **grmem; /* vector of pointers to member
names */
};
RETURN VALUES
The getgrnam(), getgrnamr(), getgrgid(), and getgrgidr()
functions each return a pointer to a struct group if they
successfully locate the requested entry. They return a null
pointer if either the requested entry was not found or an
error occurred. On error, errno is set to indicate the
error. The standard-conforming functions getgrnamr() and
getgrgidr() return 0 upon success or an error number in
case of failure.
The getgrent(), getgrentr(), fgetgrent(), and
fgetgrentr() functions each return a pointer to a struct
group if they successfully enumerate an entry; otherwise
they return a null pointer on end-of-file or error. On
error, errno is set to indicate the error.
The getgrnam(), getgrgid(), getgrent(), and fgetgrent()
functions use thread-specific data storage, so returned data
must be copied before a subsequent call to any of these
functions if the data are to be saved.
When the pointer returned by the reentrant functions
getgrnamr(), getgrgidr(), getgrentr(), and fgetgrentr()
is non-null, it is always equal to the grp pointer that was
supplied by the caller.
Applications wishing to check for error situations should
set errno to 0 before calling getgrnam(), getgrnamr(), get-
grent(), getgrentr()getgrgid(), getgrgidr(), fgetgrent(),
and fgetgrentr(). If these functions return a null pointer
and errno is non-zero, an error occurred.
ERORS
The getgrentr(), fgetgrent(), and fgetgrentr() functions
will fail if:
EIO An I/O error has occurred.
ERANGE Insufficient storage was supplied by buffer and
bufsize to contain the data to be referenced by
the resulting group structure.
SunOS 5.11 Last change: 5 Apr 2004 4
Standard C Library Functions getgrnam(3C)
The getgrentr() function will fail if:
EMFILE There are {OPENMAX} file descriptors currently
open in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
The getgrnam(), getgrnamr(), getgrgid(), getgrgidr(), and
getgrent() functions may fail if:
EINTR A signal was caught during the operation.
EIO An I/O error has occurred.
EMFILE There are {OPENMAX} file descriptors currently
open in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
The getgrnamr() and getgrgidr() functions may fail if:
ERANGE Insufficient storage was supplied by buffer and
bufsize to contain the data to be referenced by
the resulting group structure.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Apr 2004 5
Standard C Library Functions getgrnam(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability See below.
MT-Level See Reentrant Interfaces in DESCRIPTION.
The endgrent(), getgrent(), getgrgid(), getgrgidr(), get-
grnam(), getgrnamr(), and setgrent() functions are Stan-
dard.
SEE ALSO
Intro(3), getpwnam(3C), group(4), nsswitch.conf(4),
passwd(4), attributes(5), standards(5)
NOTES
When compiling multithreaded programs, see Intro(3).
Use of the enumeration interfaces getgrent() and
getgrentr() is discouraged; enumeration is supported for
the group file, NIS, and NIS], but in general is not effi-
cient and might not be supported for all database sources.
The semantics of enumeration are discussed further in
nsswitch.conf(4).
Previous releases allowed the use of ``]'' and ``-'' entries
in /etc/group to selectively include and exclude entries
from NIS. The primary usage of these entries is superseded
by the name service switch, so the ``]/-'' form might not be
supported in future releases.
If required, the ``]/-'' functionality can still be obtained
for NIS by specifying compat as the source for group.
If the ``]/-'' functionality is required in conjunction with
NIS], specify both compat as the source for group and
nisplus as the source for the pseudo-database groupcompat.
See group(4), and nsswitch.conf(4) for details.
Solaris 2.4 and earlier releases provided definitions of the
getgrnamr() and getgrgidr() functions as specified in
POSIX.1c Draft 6. The final POSIX.1c standard changed the
interface for these functions. Support for the Draft 6
interface is provided for compatibility only and might not
SunOS 5.11 Last change: 5 Apr 2004 6
Standard C Library Functions getgrnam(3C)
be supported in future releases. New applications and
libraries should use the standard-conforming interface.
For POSIX.1c-conforming applications, the
POSIXPTHREADSEMANTICS and RENTRANT flags are automati-
cally turned on by defining the POSIXCSOURCE flag with a
value >199506L.
SunOS 5.11 Last change: 5 Apr 2004 7
|
