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