getgrgid_r(2)                                             getgrgid_r(2)

  getgrnam()

  NAME

    getgrnam(), getgrnam_r(), getgrgid(), getgrgid_r(), getgrgid_ex(),
    getgrgid_ex_r(), getgrent(), getgrnam_nomembers(), getgrnam_nomembers_r(),
    getgrgid_nomembers(), getgrgid_nomembers_r(), getgrent_nomembers() - user
    account database operations

  SYNOPSIS

    #include 

    struct group * getgrnam (const char *groupname)
    int getgrnam_r (const char *name, struct group *grp, char *buffer,
           size_t bufsize, struct group **result);
    struct group * getgrgid (gid_t gid)
    int getgrgid_r (gid_t gid, struct group *grp, char *buffer,
           size_t bufsize, struct group **result)
    struct group * getgrgid_ex (gid_t gid, int flags)
    int getgrgid_ex_r (gid_t gid, int flags,
           struct group *grp, char *buffer,
           size_t bufsize, struct group **result)
    struct group * getgrent (void)
    struct group * getgrnam_nomembers (const char *groupname)
    int getgrnam_nomembers_r (const char *groupname,
           struct group *grp, char *buffer,
           size_t bufsize, struct group **result)
    struct group * getgrgid_nomembers (gid_t gid)
    int getgrgid_nomembers_r (gid_t gid, struct group *grp,
           char *buffer, size_t bufsize, struct group **result)
    struct group * getgrent_nomembers (void)

  DESCRIPTION

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

    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 reentrant getgrnam_r(2) function updates the group structure
    identified by grp and stores a pointer to that structure at the location
    identified by result. The structure contains an entry from the group
    database with a name that matches the name argument. Storage referenced by
    the group structure is allocated from the memory provided by the buffer
    argument, which is bufsize bytes in size. The maximum size needed for this
    buffer can be determined with the {_SC_GETGR_R_SIZE_MAX} sysconf(2)
    parameter. A null pointer is returned at the location identified by result
    on error or if the requested entry is not found.

    The reetnrant getgrgid_r(2) function updates the group structure
    identified by the grp argument and stores a pointer to that structure at
    the location identified by result. The structure contains an entry from
    the group database with a gid that matches gid. Storage referenced by the
    group structure is allocated from the memory provided with the buffer
    argument, which is bufsize bytes in size. The maximum size needed for this
    buffer can be determined with the {_SC_GETGR_R_SIZE_MAX} sysconf(2)
    parameter. A null pointer IS returned at the location pointed to by result
    on error or if the requested entry is not found.

    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 reentrant getgrgid_ex_r(2) function is the same as getgrgid_r(2) when
    the flags argument is zero. If GR_FULLNAME is set in flags, all names
    returned in the resulting group structure 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_r(2). 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 and *_nomembers_r 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), 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), getgrgid_r(2), getgrnam(2), and getgrnam_r(2) calls may
    fail for the following reasons:

    [EIO]
        An I/O error occurred.

    [EINTR]
        A signal was caught during the call.

    The reentrant *_r(2) calls may fail for the following reason:

    [ERANGE]
        The buffer and bufsize arguments specify insufficient storage to
        contain the data to be referenced by the resulting group structure.

  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 hexadecimal range) do not keep member lists
    internally, probably because almost all users are members. (the anonymous
    user is sometimes excluded).

  SEE ALSO

    getgroups(2)

    getlogin(2)

    getpwnam(2)

    getpwuid(2)

  USAGE NOTES

    The following functions are thread safe: getgrnam_r, getgrgid_r,
    getgrgid_ex_r, getgrnam_nomembers_r, getgrgid_nomembers_r. The following
    functions are not thread safe: getgrnam, getgrgid, getgrgid_ex, getgrent,
    getgrnam_nomembers, getgrgid_nomembers, getgrent_nomembers.

    None of these functions are async-signal safe.