getgrnam_r()--Get Group Information Using Group Name

Syntax

 #include <sys/types.h>
 #include <grp.h>

 int getgrnam_r(const char *name, struct group *grp,  
 char *buffer, size_t bufsize, struct group
**result);

  Service Program Name: QSYPAPI

  Default Public Authority: *USE

  Threadsafe: Yes

The getgrnam_r() function updates the group structure pointed to by grp and stores a pointer to that structure in the location pointed to by result. The structure contains an entry from the user database with matching name.

Parameters

name: (Input) A pointer to a group profile name.
grp: (Input) A pointer to a group structure.
buffer: (Input) A pointer to a buffer from which memory is allocated to hold storage areas referenced by the group structure grp.
bufsize: (Input) The size of buffer in bytes.
result: (Input) A pointer to a location in which a pointer to the updated group structure is stored. If an error occurs or the requested entry cannot be found, a NULL pointer is stored in this location.

The struct group, which is defined in the grp.h header file, 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.

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

0: getgrnam_r was successful.
Any other value: Failure: The return value contains an error number indicating the error.

Error Conditions

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

Error condition	Additional information
[EAGAIN]	The user profile associated with the name is currently locked by another process.
[EC2]	Detected pointer that is not valid.
[EDAMAGE]	The user profile associated with the group name or an internal system object is damaged.
[EINVAL]	Value is not valid. Check the job log for messages.
[ENOENT]	The user profile associated with the name was not found or the profile name specified is not a group profile.
[ERANGE]	Insufficient storage was supplied by buffer and bufsize to contain the data to be referenced by the resulting group structure.
[EUNKNOWN]	Unknown system state. Check the job log for a CPF9872 message.

Related Information

The <grp.h> file (see )
getgrnam()--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 <sys/types.h>
#include <grp.h>
#include <stdio.h>
#include <errno.h>

main()
{ short int lp;
  struct group grp;
  struct group * grpptr=&grp;
  struct group * tempGrpPtr;
  char grpbuffer[200];
  int  grplinelen = sizeof(grpbuffer);

  if ((getgrnam_r("GROUP1",grpptr,grpbuffer,grplinelen,&tempGrpPtr))!=0)
     perror("getgrnam_r() error.");
  else
  {
     printf("\nThe 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

API introduced: V4R4

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