getgrnam()--Get Group Information Using Group Name

 #include <grp.h>

 struct group  *getgrnam(const char *name);  

The getgrnam() function returns a pointer to an object of type struct group containing an entry from the user database with a matching name.

Parameters

name

(Input) A pointer to a group profile name.

Authorities

*READ authority is required to the user profile associated with the name. If the user does not have *READ authority, only the name of the group and the group ID values are returned.

Return Value

struct group *

getgrnam() was successful. The return value points to static data of the format struct group, which is defined in the grp.h header file. This storage is overwritten on each call to this function. This static storage area is also used by the getgrgid() function. The struct group has the following elements:

char *	gr_name	Name of the group
gid_t	gr_gid	Group ID
char **	gr_mem	A null-terminated list of pointers to the individual member profile names. If the group profile does not have any members or if the caller does not have *READ authority to the group profile, the list will be empty.

NULL pointer

getgrnam was not successful. The errno global variable is set to indicate the error.

Error Conditions

If getgrnam() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Related Information

• The <grp.h> file (see Header Files for UNIX^®-Type Functions)
  
• getgrnam_r()--Get Group Information Using Group Name

Example

The following example gets the group information for the group GROUP1. The gid is 91. There are two group members, CLIFF and PATRICK.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <grp.h>
#include <stdio.h>

main()
{
  struct group *grp;
  short int    lp;

  if (NULL == (grp = getgrnam("GROUP1")))
     perror("getgrnam() error.");
  else
  {
     printf("The group name is: %s\n", grp->gr_name);
     printf("The gid        is: %u\n", grp->gr_gid);
     for (lp = 1; NULL != *(grp->gr_mem); lp++, (grp->gr_mem)++)
        printf("Group member %d is: %s\n", lp, *(grp->gr_mem));
  }

}

Output:

  The group name is: GROUP1
  The gid        is: 91
  Group member 1 is: CLIFF
  Group member 2 is: PATRICK

[ Back to top | UNIX-Type APIs | APIs by category ]