getgrnam()

NAME

getgrnam(), getgrgid(), getgrgid_ex(), getgrent(), getgrnam_nomembers(), getgrgid_nomembers(), getgrent_nomembers() - user account database operations

SYNOPSIS

#include <grp.h>


struct group * getgrnam (const char *groupname)
struct group * getgrgid (gid_t gid)
struct group * getgrgid_ex (gid_t gid, int flags)
struct group * getgrent (void)
int setgrent (void)
void endgrent (void)

DESCRIPTION

These functions operate on the user account database file. They return information in a struct group structure, defined in the include file <grp.h>:

struct group {
		char * gr_name; group name (null-terminated string)
		gid_t gr_gid;   group ID
		char ** gr_mem; group members (null-terminated array of pointers)
};

The functions getgrnam(2) and getgrgid(2) search the group database for the given group name pointed to by groupname or the group ID pointed to by gid. The getgrent(2) function sequentially reads the database and is intended for programs that would step through the complete list of groups.

The getgrgid_ex(2) function is the same as getgrgid(2) when the flags argument is zero. If GR_FULLNAME is set in flags, all names returned in the resulting struct group are fully qualified by their domain. For example, instead of "+Administrators", the result is "computername+Administrators". If GR_NOMEMBERS is set, it has the same effect as getgrgid_nomembers(). Both flags may be set.

The gr_name member is a null-terminated string. The gr_mem member is a null-terminated array of pointers to null-terminated strings. The gr_passwd member is always "*". These strings identify all the user and group members in this group.

Refer to the getpwnam(2) reference page for a description of the domain scheme in Windows networking.

The return value points to an area that is reused on subsequent calls. The information must be copied elsewhere before the next call to these functions. The names returned in gr_name and gr_mem are in the form domain+name.

The *_nomembers versions of these functions are identical, but do not fill in the gr_mem member, which can result in much faster performance, depending upon the system and the location of the user database.

RETURN VALUES

The functions getgrnam(2) and getgrgid(2) return a pointer to the group entry if successful, or a null pointer if no matching entry is found (which is not considered an error).

If an error occurs, the functions return a null pointer and set the value of errno.

ERRORS

The getgrgid(2) and getgrnam(2) calls may fail for the following reasons:

[EIO]: An I/O error occurred.
[EINTR]: A signal was caught during the call.
[EMFILE]: The calling process already had {OPEN_MAX} file descriptors open.
[ENFILE]: The system already had the maximum allowable number of files open.

NOTES

Some built-in groups always report 0 members, even though the id(1) command will report a given user as a member. These groups (with gid values in the 0x10xxx hex range) do not keep member lists internally, probably because almost all users are members. (the anonymous user is sometimes excluded).