[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

getgrent, getgrgid, getgrnam, setgrent, or endgrent Subroutine


Accesses the basic group information in the user database.


Standard C Library (libc.a)


#include <sys/types.h>
#include <grp.h>

struct group *getgrent ( );

struct group *getgrgid (GID)
gid_t  GID;

struct group *getgrnam (Name)
const char * Name;

void setgrent ( );

void endgrent ( );


Attention: The information returned by the getgrent, getgrnam, and getgrgid subroutines is stored in a static area and is overwritten on subsequent calls. You must copy this information to save it.

Attention: These subroutines should not be used with the getgroupattr subroutine. The results are unpredictable.

The setgrent subroutine opens the user database if it is not already open. Then, this subroutine sets the cursor to point to the first group entry in the database.

The getgrent, getgrnam, and getgrgid subroutines return information about the requested group. The getgrent subroutine returns the next group in the sequential search. The getgrnam subroutine returns the first group in the database whose name matches that of the Name parameter. The getgrgid subroutine returns the first group in the database whose group ID matches the GID parameter. The endgrent subroutine closes the user database.

Note: An ! (exclamation mark) is written into the gr_passwd field. This field is ignored and is present only for compatibility with older versions of UNIX.

The Group Structure

The group structure is defined in the grp.h file and has the following fields:

gr_name Contains the name of the group.
gr_passwd Contains the password of the group.

Note: This field is no longer used.
gr_gid Contains the ID of the group.
gr_mem Contains the members of the group.

If the Network Information Service (NIS) is enabled on the system, these subroutines attempt to retrieve the group information from the NIS authentication server.


GID Specifies the group ID.
Name Specifies the group name.

Group Specifies the basic group information to enter into the user database.

Return Values

If successful, the getgrent, getgrnam, and getgrgid subroutines return a pointer to a valid group structure. Otherwise, a null pointer is returned.

Error Codes

These subroutines fail if one or more of the following are returned:

EIO Indicates that an input/output (I/O) error has occurred.
EINTR Indicates that a signal was caught during the getgrnam or getgrgid subroutine.
EMFILE Indicates that the maximum number of file descriptors specified by the OPEN_MAX value are currently open in the calling process.
ENFILE Indicates that the maximum allowable number of files is currently open in the system.

To check an application for error situations, set the errno global variable to a value of 0 before calling the getgrgid subroutine. If the errno global variable is set on return, an error occurred.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.


/etc/group Contains basic group attributes.

Related Information

List of Security and Auditing Subroutines, Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]