getpwent (BPX1GPE, BPX4GPE) — Sequentially access the user database

Function

The getpwent callable service gets information about a user. Each time you use the getpwent service, you get information about the next user entry in the user database.

Requirements

Parameters

Return_value

Returned parameter

Type:

Address

Length:

Fullword

The name of a fullword in which the getpwent service returns an address, or 0.

If no more user entries exist in the user 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 that is mapped by the BPXYGIDN macro. The first area contains the fullword length of the user name, followed by the user name padded with blanks. See BPXYGIDN — Map data returned for getpwnam and getpwuid.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the getpwent service stores the return code, or 0. The getpwent service returns Return_code only if Return_value is 0. Return_code is 0 when no more user entries exist in the database. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The getpwent 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 in which the getpwent service stores the reason code, or 0. The getpwent service returns Reason_code only if Return_value is 0. Reason_code is 0 when no more user 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 for 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 current user is incompletely defined.

Usage notes

1. The getpwent service is intended to be used to search the user database sequentially. The first call to this service from a given task returns a pointer to the first user entry in the user database. Subsequent calls from the same task return a pointer to the next user entry found that is a defined OMVS user. When the end of the database is reached, a null pointer is returned (RV and RS are both set to 0).
   A user entry is not returned for users that are not defined as OMVS users. This includes:

   • Users that do not have a RACF OMVS segment defined
   • Users with a RACF OMVS segment defined but with no UID defined
   • Users whose DFLTGRP does not have a valid OMVS GID defined

   If a user does not have a RACF OMVS segment but is given access to the OMVS DEFAULT user, no entry is returned on a getpwent call. This is because the user is not defined as an OMVS user in the user database.

2. The setpwent service can be used to reset this sequential search. The next getpwent service used from the same task after a call to the setpwent service returns a pointer to the first user entry. The next getpwent service used after an end-of-file indication (a null pointer) is returned also returns a pointer to the first user entry. The use of setpwent after end-of-file is therefore optional.
3. The return value points to data that may change or go away after the next getpwuid, getpwnam, or getpwent 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

• getpwnam (BPX1GPN, BPX4GPN) — Access the user database by user name
• getpwuid (BPX1GPU, BPX4GPU) — Access the user database by user ID
• setpwent (BPX1SPE, BPX4SPE) — Reset the user database

Characteristics and restrictions

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