# setuid

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           setuid — set user ID
    


## SYNOPSIS



           #include <unistd.h>
    
           int setuid(uid_t _uid_);
    


## DESCRIPTION



           If the process has appropriate privileges, _setuid_() shall set the
           real user ID, effective user ID, and the saved set-user-ID of the
           calling process to _uid_.
    
           If the process does not have appropriate privileges, but _uid_ is
           equal to the real user ID or the saved set-user-ID, _setuid_() shall
           set the effective user ID to _uid_ ; the real user ID and saved set-
           user-ID shall remain unchanged.
    
           The _setuid_() function shall not affect the supplementary group
           list in any way.
    


## RETURN VALUE



           Upon successful completion, 0 shall be returned. Otherwise, -1
           shall be returned and _errno_ set to indicate the error.
    


## ERRORS



           The _setuid_() function shall fail, return -1, and set _errno_ to the
           corresponding value if one or more of the following are true:
    
           **EINVAL** The value of the _uid_ argument is invalid and not supported
                  by the implementation.
    
           **EPERM** The process does not have appropriate privileges and _uid_
                  does not match the real user ID or the saved set-user-ID.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           The various behaviors of the _setuid_() and _setgid_() functions when
           called by non-privileged processes reflect the behavior of
           different historical implementations. For portability, it is
           recommended that new non-privileged applications use the _seteuid_()
           and _setegid_() functions instead.
    
           The saved set-user-ID capability allows a program to regain the
           effective user ID established at the last _exec_ call. Similarly,
           the saved set-group-ID capability allows a program to regain the
           effective group ID established at the last _exec_ call. These
           capabilities are derived from System V. Without them, a program
           might have to run as superuser in order to perform the same
           functions, because superuser can write on the user's files. This
           is a problem because such a program can write on any user's files,
           and so must be carefully written to emulate the permissions of the
           calling process properly. In System V, these capabilities have
           traditionally been implemented only via the _setuid_() and _setgid_()
           functions for non-privileged processes. The fact that the behavior
           of those functions was different for privileged processes made
           them difficult to use. The POSIX.1‐1990 standard defined the
           _setuid_() function to behave differently for privileged and
           unprivileged users.  When the caller had appropriate privileges,
           the function set the real user ID, effective user ID, and saved
           set-user ID of the calling process on implementations that
           supported it. When the caller did not have appropriate privileges,
           the function set only the effective user ID, subject to permission
           checks. The former use is generally needed for utilities like
           _login_ and _su_ , which are not conforming applications and thus
           outside the scope of POSIX.1‐2008. These utilities wish to change
           the user ID irrevocably to a new value, generally that of an
           unprivileged user. The latter use is needed for conforming
           applications that are installed with the set-user-ID bit and need
           to perform operations using the real user ID.
    
           POSIX.1‐2008 augments the latter functionality with a mandatory
           feature named _POSIX_SAVED_IDS. This feature permits a set-user-ID
           application to switch its effective user ID back and forth between
           the values of its _exec_ -time real user ID and effective user ID.
           Unfortunately, the POSIX.1‐1990 standard did not permit a
           conforming application using this feature to work properly when it
           happened to be executed with (implementation-defined) appropriate
           privileges. Furthermore, the application did not even have a means
           to tell whether it had this privilege. Since the saved set-user-ID
           feature is quite desirable for applications, as evidenced by the
           fact that NIST required it in FIPS 151‐2, it has been mandated by
           POSIX.1‐2008. However, there are implementors who have been
           reluctant to support it given the limitation described above.
    
           The 4.3BSD system handles the problem by supporting separate
           functions: _setuid_() (which always sets both the real and effective
           user IDs, like _setuid_() in POSIX.1‐2008 for privileged users), and
           _seteuid_() (which always sets just the effective user ID, like
           _setuid_() in POSIX.1‐2008 for non-privileged users). This
           separation of functionality into distinct functions seems
           desirable. 4.3BSD does not support the saved set-user-ID feature.
           It supports similar functionality of switching the effective user
           ID back and forth via _setreuid_(), which permits reversing the real
           and effective user IDs. This model seems less desirable than the
           saved set-user-ID because the real user ID changes as a side-
           effect. The current 4.4BSD includes saved effective IDs and uses
           them for _seteuid_() and _setegid_() as described above. The
           _setreuid_() and _setregid_() functions will be deprecated or removed.
    
           The solution here is:
    
            *  Require that all implementations support the functionality of
               the saved set-user-ID, which is set by the _exec_ functions and
               by privileged calls to _setuid_().
    
            *  Add the _seteuid_() and _setegid_() functions as portable
               alternatives to _setuid_() and _setgid_() for non-privileged and
               privileged processes.
    
           Historical systems have provided two mechanisms for a set-user-ID
           process to change its effective user ID to be the same as its real
           user ID in such a way that it could return to the original
           effective user ID: the use of the _setuid_() function in the
           presence of a saved set-user-ID, or the use of the BSD _setreuid_()
           function, which was able to swap the real and effective user IDs.
           The changes included in POSIX.1‐2008 provide a new mechanism using
           _seteuid_() in conjunction with a saved set-user-ID. Thus, all
           implementations with the new _seteuid_() mechanism will have a saved
           set-user-ID for each process, and most of the behavior controlled
           by _POSIX_SAVED_IDS has been changed to agree with the case where
           the option was defined. The _kill_() function is an exception.
           Implementors of the new _seteuid_() mechanism will generally be
           required to maintain compatibility with the older mechanisms
           previously supported by their systems. However, compatibility with
           this use of _setreuid_() and with the _POSIX_SAVED_IDS behavior of
           _kill_() is unfortunately complicated. If an implementation with a
           saved set-user-ID allows a process to use _setreuid_() to swap its
           real and effective user IDs, but were to leave the saved set-user-
           ID unmodified, the process would then have an effective user ID
           equal to the original real user ID, and both real and saved set-
           user-ID would be equal to the original effective user ID. In that
           state, the real user would be unable to kill the process, even
           though the effective user ID of the process matches that of the
           real user, if the _kill_() behavior of _POSIX_SAVED_IDS was used.
           This is obviously not acceptable. The alternative choice, which is
           used in at least one implementation, is to change the saved set-
           user-ID to the effective user ID during most calls to _setreuid_().
           The standard developers considered that alternative to be less
           correct than the retention of the old behavior of _kill_() in such
           systems. Current conforming applications shall accommodate either
           behavior from _kill_(), and there appears to be no strong reason for
           _kill_() to check the saved set-user-ID rather than the effective
           user ID.
    


## FUTURE DIRECTIONS



           None.
    


* * *