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 <sys/types.h> Fd #include <grp.h> Ft struct group * Fn getgrent void Ft struct group * Fn getgrnam const char *name Ft struct group * Fn getgrgid gid_t gid Ft int Fn setgroupent int stayopen Ft void 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 necessary.

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 equivalent 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 Fn setgroupent function returns the value 1 if successful, otherwise the value 0 is returned. The Fn endgrent and Fn setgrent functions have no return value.

FILES

/etc/group: group database file

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.

This document was created by man2html, using the manual pages.
Time: 15:52:54 GMT, January 15, 2023