setreuid (BPX1SRU, BPX4SRU) —Set the real and effective UIDs
Function
The setreuid callable service sets the real and effective UIDs for the calling process to the values that are specified by the input real and effective UID values. If a specified value is equal to -1, the corresponding real or effective UID of the calling process is left unchanged.
Requirements
| Operation | Environment |
|---|---|
| Authorization: | Supervisor or problem state, any PSW key |
| Dispatchable unit mode: | Task |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1SRU): | 31-bit |
| AMODE (BPX4SRU): | 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
The syntax format is as follows:
|
AMODE 64 callers use BPX4SRU with the same parameters.
Parameters
- RUID
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the real UID to be set in the calling process. If RUID is -1, the real UID for the calling process is left unchanged.
- EUID
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the effective UID to be set in the calling process. If EUID is -1, the effective UID for the calling process is left unchanged.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the setreuid service returns -1 if it is not successful. If it is successful, the setreuid service returns 0.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the setreuid service stores the return code. The setreuid service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The setreuid service can return one of the following values in the Return_code parameter:Return_code Explanation EINVAL The value of RUID or EUID is not valid. EPERM The process does not have appropriate privileges to set the real UID or the effective UID. Refer to Authorization for information on appropriate privileges. EMVSSAF2ERR The SAF call IRRSSU00 incurred an error. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the setreuid service stores the reason code. The setreuid service returns Reason_code only if Return_value is -1. 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 contains the RACF® return and reason codes, respectively, in the two low-order bytes. For a more detailed description of the RACF SETUID 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 For a more detailed description of the RACF CKPRIV service return and reason code values, see the following table:RACF return code RACF reason code Explanation 8 4 User is not privileged 8 12 Internal error during RACF processing
Usage notes for setreuid
If a UNIX set-user-ID privileged program switches
its UID to other than that of the set-user-ID program and it causes
the real, effective and saved UID of the caller to be equal, then
the set-user-ID privilege of the program is given up.
- A process with appropriate privileges (see Authorization) can set the real and effective UID to any valid UID value. An unprivileged process can set the effective UID only if the EUID argument is equal to the real, effective, or saved UID of the process. An unprivileged process can set the real UID only if the RUID argument is equal to the real, effective, or saved UID of the process.
- The setreuid service is allowed in a TSO address space so long as the caller does not attempt to change the MVS™ identity. MVS identity changes are triggered by changing the effective UID. The real UID can always be changed if the invoker has appropriate privileges.
- For information about changing MVS identities, and other restrictions, see the UsageNotes for setuid (BPX1SUI, BPX4SUI) — Set user IDs.
- To attach the security environment of the caller of the setuid service to the security environment of the target UID (which then creates a nested ACEE for the target), use the _BPXK_DAEMON_ATTACH environment variable. The new client can then access RACF delegated resources for which the daemon, but not necessarily the client, has access. (The delegated resources are designated by the APPDATA text of 'RACF-DELEGATED' in the RACF profile protecting the resource.) For more information about nested ACEEs and delegated resources, see z/OS Security Server RACF Security Administrator's Guide.
Related services
- exec (BPX1EXC, BPX4EXC) — Run a program
- geteuid (BPX1GEU, BPX4GEU) — Get the effective user ID
- getuid (BPX1GUI, BPX4GUI) — Get the real user ID
- seteuid (BPX1SEU, BPX4SEU) — Set the effective user ID
- setgid (BPX1SGI, BPX4SGI) — Set the group ID
- setuid (BPX1SUI, BPX4SUI) — Set user IDs
- setregid (BPX1SRG, BPX4SRG) — Set the real and/or effective GIDs
Characteristics and restrictions
See the list of restrictions in setuid (BPX1SUI, BPX4SUI) — Set user IDs.
See also Usage notes for setreuid.
Examples
For an example of this callable service, see BPX1SRU (setreuid) example.