getpwnam (BPX1GPN, BPX4GPN) — Access the user database by user name

Function

The getpwnam callable service gets information about a user. You specify the user by user name.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1GPN): 31-bit
AMODE (BPX4GPN): 64-bit
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1GPN,(User_name_length,
              User_name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4GPN with the same parameters.

Parameters

User_name_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the length of User_name.

User_name
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Specified by the User_name_length parameter

The name of a field of length User_name_length that contains the name of the user that the program wants information about. The name is specified in the Resource Access Control Facility (RACF®) command that defines the user to the system.

Return_value
Returned parameter
Type:
Address
Length:
Fullword

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

If no entry for the specified group name is found, Return_value is set to 0.

If an entry is found, Return_value is set to the address of the BPXYGIDN 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 getpwnam service stores the return code. The getpwnam 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 getpwnam service can return one of the following values in the Return_code parameter:
Return_code Explanation
EINVAL User_name_length is incorrect; or the user name has an illegal first character (JRUserNameBad).
EMVSSAF2ERR The system authorization facility (SAF) Get GMAP service had an error.
EMVSSAFEXTRERR The SAF RACROUTE EXTRACT service had an error.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the getpwnam service stores the reason code. The getpwnam 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.

In the case of EMVSSAF2ERR or EMVSSAFEXTRERR, the reason code contains the RACF return and reason codes, respectively, in the two low-order bytes, as follows:
  • For EMVSSAF2ERR, the reason code contains the return code and reason code from the RACF getGMAP service. For a detailed description of the return code and reason code values for the getGMAP service, see z/OS Security Server RACF Callable Services.
  • For EMVSSAFEXTRERR, the reason code contains the return code and reason code from the RACROUTE REQUEST=EXTRACT service. For a detailed description of the return code and reason code values for the RACROUTE service, see z/OS Security Server RACROUTE Macro Reference.
RACF Get GMAP service return and reason code values include the following:
RACF Return Code RACF Reason Code Explanation
8 0 No profile found.
8 4 If the search is by GID: The GID is not defined. If the search is 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 GMAP service return and reason code values, see z/OS Security Server RACROUTE Macro Reference.

Usage notes

  1. If an entry for the specified User_name is not found in the user database, an address of 0 is returned as the Return_value parameter.
  2. 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 your own dynamic storage if you need it for future reference.
  3. The storage is key 0 nonfetch-protected storage that is managed by z/OS UNIX services.
  4. If the BPX.UNIQUE.USER profile is defined, a call to BPX1GPN for a user ID that does not have an OMVS segment configured as part of its security profile causes BPX1GPN to assign OMVS segments to the user ID. See Setting up default OMVS segments in z/OS UNIX System Services Planning .

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1GPN (getpwnam) example.

Parent topic: Callable services descriptions