getpwuid (BPX1GPU, BPX4GPU) — Access the user database by user ID

Function

The getpwuid callable service gets information about a user. You specify the user by user ID (UID).

Requirements

Parameters

User_ID

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the user ID of the user you want information about.

Return_value

Returned parameter

Type:

Address

Length:

Fullword

The name of a fullword to which the getpwuid returns an address, or 0. If no entry for the specified user ID is found, Return_value is set to 0. If an entry is found, Return_value is set to the address of the BPXYGIDN mapping macro. 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 getpwuid service stores the return code. The getpwuid service returns Return_code only if Return_value is 0. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The getpwuid 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 or Get UMAP service had an error.
EMVSSAFEXTRERR	The SAF or RACF RACROUTE EXTRACT call had an error.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the getpwuid service stores the reason code. The getpwuid service returns Reason_code only if Return_value is 0. 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	4	For a search by GID: the GID is not defined. For a search by group name: the current group is not defined.
8	8	The group name is not defined.
8	12	There was an internal error during RACF processing.
8	16	Recovery could not be established.
8	20	The current group is incompletely defined.

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

RACF return code	RACF reason code	Explanation
8	4	For a search by UID: the UID is not defined. For a search by user ID: The user is not defined.
8	8	The user ID is not defined.
8	12	An internal error occurred during RACF processing.
8	16	Unable to establish recovery.
8	20	The user is incompletely defined.

Usage notes

1. Return_value points to data that can change or go away after the next getpwuid, getpwnam, or getpwent service request from the task. Each task manages its own storage separately. Move data to the program's dynamic storage if the program needs it for future reference.
2. The storage is key 0 nonfetch-protected storage that is managed by z/OS UNIX.
3. Most systems have multiple user IDs defined to have UID=0. It is impossible to predict which user ID will be returned on a call to getpwuid with a UID=0.
4. Performance degradation can occur if you use this service when the Virtual Lookaside Facility (VLF) is not active. For more information, see Tuning performance and the section on establishing UNIX security in z/OS UNIX System Services Planning.

Related services

• getpwent (BPX1GPE, BPX4GPE) — Sequentially access the user database
• getpwnam (BPX1GPN, BPX4GPN) — Access the user database by user name
• getlogin (BPX1GLG, BPX4GLG) — Get the user login name

Characteristics and restrictions

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