GETGRENT

Section: C Library Functions (3)
Index Return to Main Contents

BSD mandoc
 

NAME

getgrent getgrnam getgrgid setgroupent setgrent endgrent - group database operations  

SYNOPSIS

Fd #include <grp.h> Ft struct group * Fn getgrent void Ft struct group * Fn getgrname const char *name Ft struct group * Fn getgrgid gid_t gid Ft struct group * Fn setgroupent int stayopen Ft int Fn setgrent void Ft void Fn endgrent void  

DESCRIPTION

These functions operate on the group database file /etc/group which is described in group(5). Each line of the database is defined by the structure group found in the include file Aq Pa grp.h :
struct group {
        char    *gr_name;       /* group name */
        char    *gr_passwd;     /* group password */
        gid_t   gr_gid;         /* group id */
        char    **gr_mem;       /* group members */
};

The functions Fn getgrnam and Fn getgrgid search the group database for the given group name pointed to by name or the group id pointed to by gid respectively, returning the first one encountered. Identical group names or group gids may result in undefined behavior.

The Fn getgrent function sequentially reads the group database and is intended for programs that wish to step through the complete list of groups.

All three routines will open the group file for reading, if necesssary.

The Fn setgroupent function opens the file, or rewinds it if it is already open. If Fa stayopen is non-zero, file descriptors are left open, significantly speeding functions subsequent calls. This functionality is unnecessary for Fn getgrent as it doesn't close its file descriptors by default. It should also be noted that it is dangerous for long-running programs to use this functionality as the group file may be updated.

The Fn setgrent function is identical to Fn setgroupent with an argument of zero.

The Fn endgrent function closes any open files.  

RETURN VALUES

The functions Fn getgrent , Fn getgrnam , and Fn getgrgid , return a pointer to the group entry if successful; if end-of-file is reached or an error occurs a null pointer is returned. The functions Fn setgroupent and Fn setgrent return the value 1 if successful, otherwise the value 0 is returned. The functions Fn endgrent and Fn setgrfile have no return value.  

FILES

/etc/group
group database file

 

SEE ALSO

Fn getpwent 3 , Fn group 5  

HISTORY

The functions Fn endgrent , Fn getgrent , Fn getgrnam , Fn getgrgid , and Fn setgrent appeared in AT&T System v7 . The functions Fn setgrfile and Fn setgroupent appeared in BSD 4.3 Reno  

COMPATIBILITY

The historic function Fn setgrfile , which allowed the specification of alternate password databases, has been deprecated and is no longer available.  

BUGS

The functions Fn getgrent , Fn getgrnam , Fn getgrgid , Fn setgroupent and Fn setgrent leave their results in an internal static object and return a pointer to that object. Subsequent calls to the same function will modify the same object.

The functions Fn getgrent , Fn endgrent , Fn setgroupent , and Fn setgrent are fairly useless in a networked environment and should be avoided, if possible.


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUES
FILES
SEE ALSO
HISTORY
COMPATIBILITY
BUGS

This document was created by man2html, using the manual pages.
Time: 06:45:31 GMT, May 19, 2025