setreuid() — Set real and effective user IDs

Standards

Standards / Extensions C or C++ Dependencies

XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <unistd.h>

int setreuid(uid_t ruid, uid_t euid);

General description

The setreuid() function sets the real and/or effective UIDs for the calling process to the values 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.

A process with appropriate privileges can set the real and effective UID to any valid UID value. An unprivileged process can only set the effective UID if the EUID argument is equal to either the real, effective, or saved UID of the process. An unprivileged process can only set the real UID if the RUID argument is equal to either the real, effective, or saved UID of the process.

The setreuid() function is not supported from an address space running multiple processes, since it would cause all processes in the address space to have their security environment changed unexpectedly.

setreuid() can be used by daemon processes to change the identity of a process in order for the process to be used to run work on behalf of a user. In z/OS® UNIX, changing the identify of a process is done by changing the real and effective UIDs and the auxiliary groups. In order to change the identity of the process on MVS™ completely, it is necessary to also change the MVS security environment. The identity change will only occur if the EUID value is specified, changing just the real UID will have no effect on the MVS environment.

The setreuid() function invokes MVS SAF services to change the MVS identity of the address space. The MVS identity that is used is determined as follows:
  • If an MVS user ID is already known by the kernel from a previous call to a kernel function (for example, getpwnam()) and the UID for this user ID matches the UID specified on the setreuid() call, then this user ID is used.
  • For nonzero target UIDs, if there is no saved user ID or the UID for the saved user ID does not match the UID requested on the setreuid() call, the setreuid() function queries the security database (for example, using getpwnam()) to retrieve a user ID. The retrieved user ID is then used.
  • If the target UID=0 and a user ID is not known, the setreuid() function always sets the MVS user ID to BPXROOT or the value specified on the SUPERUSER parm in sysparms. BPXROOT is set up during system initialization as a superuser with a UID=0. The BPXROOT user ID is not defined to the BPX.DAEMON FACILITY class profile. This special processing is necessary to prevent a superuser from gaining daemon authority.
  • A nondaemon superuser that attempts to set a user ID to a daemon superuser UID fails with an EPERM.

When the MVS identity is changed, the auxiliary list of groups is also set to the list of groups for the new user ID.

If the setreuid() function is issued from multiple tasks within one address space, use synchronization to ensure that the setreuid() functions are not performed concurrently. The execution of setreuid() function concurrently within one address space can yield unpredictable results.

Returned value

If successful, setreuid() returns 0.

If unsuccessful, neither of the group IDs will be changed, setreuid() returns -1, and sets errno to one of the following values:
Error Code
Description
EINVAL
The value of the rgid or egid argument is invalid or out-of-range.
EMVSSAF2ERR
The SAF call IRRSSU00 incurred an error.
EPERM
The processes does not have appropriate privileges and a change other than changing the real group ID to the saved set-group-ID, or changing the effective group ID to the real group ID or the saved group ID, was requested.

Related information

Parent topic: Library functions