getgrent(3C)

NAME

getgrent(), getgrent_r(), getgrgid(), getgrgid_r(), getgrnam(), getgrnam_r(), setgrent(), setgrent_r(), endgrent(), endgrent_r(), fgetgrent(), fgetgrent_r() − get group file entry

SYNOPSIS

#include <grp.h>

struct group *getgrent(void);

int getgrent_r(

struct group *result,
char *buffer,
int buflen,
FILE **grfp);

struct group *getgrgid(gid_t gid);

int getgrgid_r(

gid_t gid,
struct group *result,
char *buffer,
int buflen);

struct group *getgrnam(const char *name);

int getgrnam_r(

const char *name,
struct group *result,
char *buffer,
int buflen);

void setgrent(void);

void setgrent_r(FILE **grfp);

void endgrent(void);

void endgrent_r(FILE **grfp);

struct group *fgetgrent(FILE *stream);

int fgetgrent_r(

FILE *stream,
struct group *result,
char *buffer,
int buflen);

DESCRIPTION

getgrent(), getgrgid(), and getgrnam() locate an entry in the /etc/group file, and return a pointer to an object of type struct group.

The group structure is defined in <grp.h> and includes the following members:

char *gr_name;    /* the name of the group */
char *gr_passwd; /* the encrypted group password */
gid_t gr_gid;      /* the numerical group ID */
char **gr_mem;    /* null-terminated array of pointers
                      to member names */

getgrent() When first called, getgrent() returns a pointer to the first group structure in the file; thereafter, it returns a pointer to the next group structure in the file. In this way, successive calls can be used to search the entire file. getgrent() opens the /etc/group file prior to doing its work and leaves the file open afterward;

setgrent() Has the effect of rewinding this file to allow repeated searches;

endgrent() Can be called to close the file when processing is complete.

getgrgid() Searches from the beginning of the file until a numeric group ID matching gid is found, and returns a pointer to the particular structure in which it was found.

getgrnam() Searches from the beginning of the file until a group name matching name is found, and returns a pointer to the particular structure in which it was found.

fgetgrent() Returns a pointer to the next group structure in the standard I/O stream stream, which should be open for reading, and its contents should match the format of /etc/group.

Reentrant Interfaces

getgrgid_r(), getgrnam_r() and fgetgrent_r() expect to be passed three extra parameters:

1. The address of a struct group where the result will be stored;

2. A buffer to store character strings, such as the group name, to which fields in the struct group will point;

3. The length of the user-supplied buffer.

In addition to the above three parameters, getgrent_r() requires a pointer to a (FILE *) variable into which is stored the result of an fopen() call on the /etc/group file. This parameter allows threads to independently scan through the /etc/group file. setgrent_r() and endgrent_r() are to be used only in conjunction with getgrent_r() and take the same pointer to a (FILE *) variable as a parameter. setgrent_r() can be used to rewind or open the /etc/group file. endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file.

Note that the (FILE *) variable must be initialized to NULL before it is passed to either getgrent_r() or setgrent_r() for the first time. Thereafter it should not be modified in any way.

A buffer length of 1024 is recommended.

NETWORKING FEATURES

NFS

If an entry beginning with a plus sign (+) or a minus sign (−) is found, these routines try to use the Network Information Service network database for data. See group(4) for proper syntax and operation.

RETURN VALUE

getgrent(), getgrgid(), getgrnam(), and fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid group structure.

getgrent_r(), getgrgid_r(), getgrnam_r(), and fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned.

ERRORS

getgrent(), getgrgid(), getgrnam() and fgetgrent() fail if any of the following are true:

[EIO] An I/O error has occurred.

[EMFILE] OPEN_MAX file descriptors are currently open in the calling process.

[ENFILE] The maximum allowable number of files is currently open in the system.

EXAMPLE

The following code excerpt counts the number of entries in the /etc/group file:

int count = 0;
struct group gpbuf;
char buffer[1024];
FILE *grf = NULL;
setgrent_r(&grf);
while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1)
count++;
endgrent_r(&grf);

WARNINGS

The above routines use <stdio.h> and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected.

The value returned by getgrent(), getgrgid(), getgrnam(), and fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved.

getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(), and fgetgrent() are unsafe in multi-thread applications. getgrent_r(), getgrgid_r(), getgrnam_r(), setgrent_r(), endgrent_r(), and fgetgrent_r() are MT-Safe and should be used instead.

Users of getgrent_r() and getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard.

DEPENDENCIES

NFS:

FILES

/var/yp/domainname/group.byname
/var/yp/domainname/group.bygid

SEE ALSO:

ypcat(1).

FILES

/etc/group

STANDARDS CONFORMANCE

getgrent(): SVID2, SVID3, XPG2

endgrent(): SVID2, SVID3, XPG2

fgetgrent(): SVID2, SVID3, XPG2

getgrgid(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

getgrnam(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

setgrent(): SVID2, SVID3, XPG2

Hewlett-Packard Company — HP-UX Release 10.20: July 1996

Museum

Related Articles