svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
getgrnam(3c)
getgrnam(3C) Standard C Library Functions getgrnam(3C)
NAME
getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r, set‐
grent, endgrent, fgetgrent, fgetgrent_r - group database entry func‐
tions
SYNOPSIS
#include <grp.h>
struct group *getgrnam(const char *name);
int getgrnam_r(const char *name, struct group *grp, char *buffer,
size_t bufsize, struct group **result);
struct group *getgrent(void);
struct group *getgrent_r(struct group *grp, char *buffer, int bufsize);
struct group *getgrgid(gid_t gid);
int getgrgid_r(gid_t gid, struct group *grp, char *buffer,
size_t bufsize, struct group **result);
void setgrent(void);
void endgrent(void);
struct group *fgetgrent(FILE *f);
struct group *fgetgrent_r(FILE *f, struct group *grp, char *buffer,
int bufsize);
POSIX.1c Draft 6
#define __USE_DRAFT6_PROTOTYPES__
#include <grp.h>
struct group *getgrnam_r(const char *name, struct group *grp,
char *buffer, int bufsize);
struct group *getgrgid_r(gid_t gid, struct group *grp, char *buffer,
int bufsize);
DESCRIPTION
These functions are used to obtain entries describing user groups. En‐
tries can come from any of the sources for group specified in the nss‐
witch.conf(5) configuration.
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 enu‐
merate group entries from the database.
The setgrent() function effectively rewinds the group database 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 getgrent().
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 complete. 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,
using the format described in group(5).
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 recom‐
mended for multithreaded applications.
The parallel functions getgrnam_r(), getgrgid_r(), getgrent_r(), and
fgetgrent_r() provide reentrant interfaces for these operations.
Each reentrant interface performs the same operation as its non-reen‐
trant counterpart, named by removing the _r suffix. The reentrant in‐
terfaces, 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 multi‐
threaded applications.
Each reentrant interface takes the same arguments as its non-reentrant
counterpart, as well as the following additional parameters. The grp
argument must be a pointer to a struct group structure allocated by the
caller. On successful completion, the function returns the group entry
in this structure. Storage referenced by the group structure is allo‐
cated from the memory provided with the buffer argument that is bufsize
characters in size. The maximum size needed for this buffer can be de‐
termined with the _SC_GETGR_R_SIZE_MAX sysconf(3C) parameter. The
standard-conforming versions place a pointer to the modified grp struc‐
ture in the result parameter, instead of returning a pointer to this
structure. A null pointer is returned at the location pointed to by re‐
sult 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 set‐
grent() function can be used in a multithreaded application but resets
the enumeration position for all threads. If multiple threads inter‐
leave calls to getgrent_r(), the threads will enumerate disjoint sub‐
sets of the group database. Like their non-reentrant counterparts, get‐
grnam_r() and getgrgid_r() leave the enumeration position in an inde‐
terminate state.
group Structure
Group entries are represented by the struct group structure defined in
<grp.h>:
struct group {
char *gr_name; /* the name of the group */
char *gr_passwd; /* the encrypted group password */
gid_t gr_gid; /* the numerical group ID */
char **gr_mem; /* vector of pointers to member
names */
};
RETURN VALUES
The getgrnam() and getgrgid() functions each return a pointer to a
struct group if they successfully locate the requested entry. They re‐
turn 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 get‐
grnam_r() and getgrgid_r() functions return 0 upon success or an error
number in case of failure and do not set errno.
The getgrent(), getgrent_r(), fgetgrent(), and fgetgrent_r() 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
the thread is terminated or makes a subsequent call to any of these
functions if the data is to be saved.
When the pointer returned by the reentrant functions getgrent_r() and
fgetgrent_r() 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(), getgrent(), getgrent_r(), getgrgid(),
fgetgrent(), and fgetgrent_r(). If these functions return a null
pointer and errno is non-zero, an error occurred.
ERRORS
The getgrent_r(), fgetgrent(), and fgetgrent_r() 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.
The getgrent_r() function will fail if:
EMFILE There are {OPEN_MAX} file descriptors currently open in the
calling process.
ENFILE The maximum allowable number of files is currently open in
the system.
The getgrnam(), getgrnam_r(), getgrgid(), getgrgid_r(), and getgrent()
functions may fail if:
EINTR A signal was caught during the operation.
EIO An I/O error has occurred.
EMFILE There are {OPEN_MAX} file descriptors currently open in the
calling process.
ENFILE The maximum allowable number of files is currently open in
the system.
The getgrnam_r() and getgrgid_r() 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.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(1.83i) |cw(3.67i) lw(1.83i) |lw(3.67i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSee Reentrant
Interfaces in DESCRIPTION. _ StandardSee below.
For endgrent(), getgrent(), getgrgid(), getgrgid_r(), getgrnam(), get‐
grnam_r(), and setgrent() see standards(7).
SEE ALSO
getgrouplist(3C), getpwnam(3C), group(5), nsswitch.conf(5), passwd(5),
attributes(7), standards(7)
NOTES
Use of the enumeration interfaces getgrent() and getgrent_r() is dis‐
couraged; enumeration is supported for the group file and NIS, but in
general is not efficient and might not be supported for all database
sources. The semantics of enumeration are discussed further in nss‐
witch.conf(5). getgrouplist(3C) provides an alternative to the enumera‐
tion interfaces to get the list of groups for an individual user.
Prior to Oracle Solaris 11.4, the default compilation environment pro‐
vided definitions of the getgrnam_r() and getgrgid_r() functions as
specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
interfaces for getgrnam_r() and getgrgid_r(). To allow applications
that were written to use the obsolete Draft-6 interfaces to continue to
be compiled and run, the __USE_DRAFT6_PROTOTYPES__ macro must be de‐
fined:
cc -D__USE_DRAFT6_PROTOTYPES__ ...
Support for the Draft-6 interfaces is provided for source compatibility
only and might not be supported in future releases. Old applications
should be converted to use the standard definitions.
HISTORY
Oracle Solaris 11.4.0 made the standards-conforming versions of getgr‐
nam_r() and getgrgid_r() the default definitions, removing the require‐
ment to define _POSIX_C_SOURCE or _POSIX_PTHREAD_SEMANTICS before in‐
cluding the header, and adding the requirement to define
__USE_DRAFT6_PROTOTYPES__ to expose the Draft 6 versions instead.
In Solaris 2.5, the final POSIX.1c standard versions of getgrgid_r()
and getgrnam_r() were added, but only exposed in the header if
_POSIX_C_SOURCE was set to 199506 or higher, or _POSIX_PTHREAD_SEMAN‐
TICS was defined, before including the <grp.h> header.
Solaris 2.3 added definitions of the getgrgid_r() and getgrnam_r()
functions as specified in POSIX.1c Draft 6, and of the non-standard
getgrent_r() and fgetgrent_r() functions.
The getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(), and
fgetgrent() functions have been included in all Sun and Oracle releases
of Solaris.
Oracle Solaris 11.4 27 Aug 2025 getgrnam(3C)