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 is0
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. 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 a list of reason codes, see Reason codes in 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 getGMAP (IRRSGM00): Get GID-to-Group-Name mapping in 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 RACROUTE REQUEST=AUTH (standard form) in 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.
Usage notes
- 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. - 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.
- The storage is key 0 nonfetch-protected storage that is managed by z/OS UNIX services.
- 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.