getgrgid_r()--Get Group Information Using Group ID

Syntax

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

 int getgrgid_r(gid_t gid, struct group *grp,  
 char *buffer, size_t bufsize, struct group
 **result);

  Service Program Name: QSYPAPI

  Default Public Authority: *USE

  Threadsafe: Yes

The getgrgid_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 a matching GID.

Parameters

gid: (Input) Group ID.
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 if 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 gid. If the user does not have *READ authority, only the name of the group and the group ID values are returned.

Return Value

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

Error Conditions

If getgrgid_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 GID is currently locked by another process.
[EC2]	Detected pointer that is not valid.
[EINVAL]	Value is not valid. Check the job log for messages.
[ENOENT]	The user profile associated with the GID was not found.
[ENOMEM]	The user profile associated with the GID has exceeded its storage limit.
[ENOSPC]	Machine storage limit exceeded.
[ERANGE]	Insufficient storage was supplied by buffer and bufsize to contain the data to be referenced by the resulting group structure.

Related Information

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

Example

The following example gets the group information for the gid of 91. The group name is GROUP1. 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 ((getgrgid_r(91,grpptr,grpbuffer,grplinelen,&tempGrpPtr))!=0)
     perror("getgrgid_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 ]