gtpc2m3uC/C++ Language Support User's Guide

getgrnam-Access the Group Database by Name

This function accesses the group structure containing an entry from the group database with the specified name.

Format

#include <grp.h>
struct group *getgrnam(const char *name);

name
A pointer to a character string of a group name (NULL-terminated).

Normal Return

If successful, the getgrnam function returns a pointer to a group structure containing an entry from the group database with the specified name. The return value is a pointer to static data that is overwritten by each call.

This group structure, defined in the grp.h header file, contains the following members:

gr_name
Pointer to the group name character string.

gr_gid
The numeric group ID (GID).

gr_mem
A NULL-terminated array of pointers to the individual member names in this group.

Error Return

If unsuccessful, the getgrnam function returns a NULL pointer and sets errno to one of the following:

EINVAL
Indicates that the length of the name parameter is incorrect. The length of name must be equal to the length of the group name in the group file; it must also be less than 256 characters.

EIO
An input/output (I/O) error occurred.

EMFILE
The process has already reached its maximum number of open file descriptors. This limit is given by OPEN_MAX, which is defined in the limits.h header file.

ENFILE
The TPF system has already reached its maximum number of open files.

Programming Considerations

Examples

The following example provides the members of a group.

#include <grp.h>
#include <stdio.h>
 
int main(void) {
 
char   grpname[] = "users", **curr;
 
struct group *grp;
 
if ((grp = getgrnam(grpname)) == NULL)
     perror ( "getgrnam() error" );
  else {
       printf( "The following are members of group %s:\n", grpname );
       for (curr=grp->gr_mem; (*curr) != NULL; curr++ )
         printf("  %s\n", *curr);
       }
  return 0;
}

Output

The following members of group users:
tpfuser1
tpfuser2
tpfuser3

Related Information