Provided by: manpages-posix-dev_2.16-1_all bug


       setuid - set user ID


       #include <unistd.h>

       int setuid(uid_t uid);


       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.


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


       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.






       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 the appropriate privilege, the function set
       the calling  process'  real  user  ID,  effective  user  ID,  and  saved  set-user  ID  on
       implementations that supported it. When the caller did not have the appropriate privilege,
       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 IEEE Std 1003.1-2001.  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.

       IEEE Std 1003.1-2001  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 the (implementation-
       defined) appropriate privilege. 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  IEEE Std 1003.1-2001.  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 IEEE Std 1003.1-2001
       for privileged users), and seteuid() (which always sets just the effective user  ID,  like
       setuid()   in   IEEE Std 1003.1-2001   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 IEEE Std 1003.1-2001  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.




       exec() , getegid() , geteuid() , getgid() , getuid() , setegid() , seteuid() , setgid()  ,
       setregid()   ,   setreuid()   ,  the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
       <sys/types.h>, <unistd.h>


       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at .