OSF  —  Environment_Note_Added

NAME

getgrent, getgrent_r, getgrgid, getgrgid_r, getgrnam, getgrnam_r, setgrent, endgrent  − Accesses the basic group information in the group database

SYNOPSIS

#include <grp.h>

struct group ∗getgrent ( void )

int getgrent_r (
struct group ∗result ,
char ∗buffer ,
int len );

struct group ∗getgrgid (
gid_t gid );

int getgrgid_r (
gid_t gid,
struct group ∗result,
char ∗buffer,
int len );

struct group ∗getgrnam(
const char ∗name );

int getgrnam_r(
const char ∗name,
struct group ∗result,
char ∗buffer,
int len );

void setgrent ( void )

void endgrent ( void )

PARAMETERS

nameSpecifies the name of the group for which the basic attributes are to be read. 

gidSpecifies the group ID of the group for which the basic attributes are to be read. 

resultPoints to a group structure containing the entry returned by the getgrnam_r(), getgrgid_r(), or getgrent_r() function. 

bufferPoints to a character array to contain the strings associated with the entry returned by the getgrnam_r(), getgruid_r(), or getgrent_r() function. 

lenSpecifies the length of buffer. 

DESCRIPTION

The getgrent(), getgrgid(), getgrnam(), setgrent(), and endgrent() functions may be used to access the basic group attributes. 

The getgrgid_r(), getgrnam_r(), and getgrent_r() functions are the reentrant versions of getgrgid(), getgrnam(), and getgrent() respectively.  Upon successful completion, the result is stored in two parts.  The struct group (which includes pointers) is stored in result, and the strings themselves are stored in buffer. 

The setgrent() function opens the group database (if not already open) and rewinds the cursor to point to the first group entry in the database. 

The getgrent(), getgrnam(), and getgrgid() functions return information about the requested group.  The getgrent() function returns the next group in the sequential search.  The getgrnam() function returns the first group in the database with the gr_name field that matches the name parameter.  The getgrgid() function returns the first group in the database with a gr_gid field that matches the gid parameter.  The endgrent() function closes the group database. 

The group structure, which is returned by the getgrent(), getgrnam(), and getgrgid() functions, is defined in the grp.h header file, and contains the following members:

gr_nameThe name of the group. 

gr_passwdThe password of the group.  (Note that this field is no longer used by the system, so its value is meaningless.) 

gr_gidThe ID of the group. 

gr_memThe members of the group. 

LIBRARY

Standard C Library (libc.a)

For the reentrant routines, libc_r must be loaded. 

NOTES

The data that is returned by the gretgrent(), getgrnam(), and getgrgid() functions is stored in a static area and will be overwritten on subsequent calls to these routines.  If it is to be saved, it should be copied. 

AES Support Level:
Full use (getgrgid(), getgrnam())

ERRORS

If the getgrnam_r(), getgruid_r(), or getgrent_r() function fails, errno may be set to one of the following values:

[EINVAL]The result or buffer parameter is a NULL pointer, or the len parameter is less than one. 

[ENOENT]The entry could not be found. 

RETURN VALUES

Upon successful completion, the getgrent(), getgrnam(), and getgrgid() functions return a pointer to a valid group structure containing a matching entry.  Otherwise, null is returned. 

Upon successful completion, the getgrnam_r(), getgruid_r(), and getgrent_r() functions return a value of 0 (zero).  Otherwise, -1 is returned and errno is set to indicate the error. 

ENVIRONMENT NOTES

This section describes system features that are not generic to OSF/1 but that are provided in this OSF/1 implementation. 

Digital Extensions

The system searches either the local /etc/group file or the NIS distributed group file for the requested information.  To determine which file or files to search, and in which order, the system uses the switches in the /etc/svc.conf file. 
 
 

RELATED INFORMATION

Functions: getpwent(3)