getgrnam()--Get Group Information Using Group Name
Syntax
#include <grp.h> struct group *getgrnam(const char *name);Service Program Name: QSYPAPI
Default Public Authority: *USE
Threadsafe: No
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.
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. |
[EUNKNOWN] |
Unknown system state. Check the job log for a CPF9872 message. |
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
API introduced: V3R1