getgrent (BPX1GGE, BPX4GGE) — Sequentially access the group database

Function

The getgrent callable service gets information about a group and its members. Each time you use the getgrent service, you get information about the next group entry in the group database.

Requirements

Parameters

Return_value

Returned parameter

Type:

Address

Length:

Fullword

The name of a fullword in which the getgrent service returns an address, or 0. If no more group entries exist in the group database, or if an error is encountered, Return_value is set to 0.

If an entry is found, Return_value is set to the address of a data area mapped by the BPXYGIDS macro. The first area contains the fullword length of the group name, followed by the group name, padded with blanks. See BPXYGIDS — Map data returned for getgrnam and getgrpid. The address returned is 31 bits for both AMODE=31 and AMODE 64 callers.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the getgrent service stores the return code or 0. The getgrent service returns Return_code only if Return_value is 0. Return_code is 0 when no more group entries exist in the database. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The getgrent service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EMVSSAF2ERR	The system authorization facility (SAF) or RACF® Get GMAP service had an error.
EMVSSAFEXTRERR	The SAF or RACF RACROUTE EXTRACT service had an error.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword where the getgrent service stores the reason code or 0. The getgrent service returns Reason_code only if Return_value is 0. Reason_code is 0 when no more group entries exist in the database. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

The reason code in the case of EMVSSAF2ERR or EMVSSAFEXTRERR contains the RACF return and reason codes, respectively, in the two low-order bytes.

For a more detailed description of the RACF Get GMAP service return and reason code values, see the following table:

RACF return code	RACF reason code	Explanation
8	12	Internal error during RACF processing
8	16	Unable to establish recovery
8	20	The group is incompletely defined.

Usage notes

1. The getgrent service is intended to be used to search the group database sequentially. The first call to this service from a given task returns a pointer to the first group entry in the group database. Subsequent calls from the same task return a pointer to the next group entry found, until no more entries exist. At this point a null pointer is returned.
2. The setgrent service can be used to reset this sequential search. The next getgrent service used from the same task after a call to setgrent returns a pointer to the first group entry. The next getgrent service used after an end of file indication (a null pointer) has been returned also returns a pointer to the first group entry. The use of setgrent after end of file is therefore optional.
3. The return value points to data that may change or go away after the next getgrgid, getgrnam, or getgrent service request from that task. Each task manages its own storage separately. Move data to the program's storage if it is needed for future reference.
4. The storage is key 0 nonfetch-protected storage that is managed by z/OS UNIX.

Related services

• getgrgid (BPX1GGI, BPX4GGI) — Access the group database by ID
• getgrnam (BPX1GGN, BPX4GGN) — Access the group database by name
• getlogin (BPX1GLG, BPX4GLG) — Get the user login name
• setgrent (BPX1SGE, BPX4SGE) — Reset the group database

Characteristics and restrictions

There are no restrictions on the use of the getgrent service.