logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

setuid.3p (9355B)

    

  1. '\" et
  2. .TH SETUID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. setuid
  12. \(em set user ID
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int setuid(uid_t \fIuid\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. If the process has appropriate privileges,
  22. \fIsetuid\fR()
  23. shall set the real user ID, effective user ID, and the saved
  24. set-user-ID of the calling process to
  25. .IR uid .
  26. .P
  27. If the process does not have appropriate privileges, but
  28. .IR uid
  29. is equal to the real user ID or the saved set-user-ID,
  30. \fIsetuid\fR()
  31. shall set the effective user ID to
  32. .IR uid ;
  33. the real user ID and saved set-user-ID shall remain unchanged.
  34. .P
  35. The
  36. \fIsetuid\fR()
  37. function shall not affect the supplementary group list in any way.
  38. .SH "RETURN VALUE"
  39. Upon successful completion, 0 shall be returned. Otherwise, \-1
  40. shall be returned and
  41. .IR errno
  42. set to indicate the error.
  43. .SH ERRORS
  44. The
  45. \fIsetuid\fR()
  46. function shall fail, return \-1, and set
  47. .IR errno
  48. to the corresponding value if one or more of the following are true:
  49. .TP
  50. .BR EINVAL
  51. The value of the
  52. .IR uid
  53. argument is invalid and not supported by the implementation.
  54. .TP
  55. .BR EPERM
  56. The process does not have appropriate privileges and
  57. .IR uid
  58. does not match the real user ID or the saved set-user-ID.
  59. .LP
  60. .IR "The following sections are informative."
  61. .SH EXAMPLES
  62. None.
  63. .SH "APPLICATION USAGE"
  64. None.
  65. .SH RATIONALE
  66. The various behaviors of the
  67. \fIsetuid\fR()
  68. and
  69. \fIsetgid\fR()
  70. functions when called by non-privileged processes reflect the behavior
  71. of different historical implementations. For portability, it is
  72. recommended that new non-privileged applications use the
  73. \fIseteuid\fR()
  74. and
  75. \fIsetegid\fR()
  76. functions instead.
  77. .P
  78. The saved set-user-ID capability allows a program to regain the
  79. effective user ID established at the last
  80. .IR exec
  81. call. Similarly, the saved set-group-ID capability allows a program to
  82. regain the effective group ID established at the last
  83. .IR exec
  84. call. These capabilities are derived from System V. Without them, a
  85. program might have to run as superuser in order to perform the same
  86. functions, because superuser can write on the user's files. This is a
  87. problem because such a program can write on any user's files, and so
  88. must be carefully written to emulate the permissions of the calling
  89. process properly. In System V, these capabilities have traditionally
  90. been implemented only via the
  91. \fIsetuid\fR()
  92. and
  93. \fIsetgid\fR()
  94. functions for non-privileged processes. The fact that the behavior of
  95. those functions was different for privileged processes made them
  96. difficult to use. The POSIX.1\(hy1990 standard defined the
  97. \fIsetuid\fR()
  98. function to behave differently for privileged and unprivileged users.
  99. When the caller had appropriate privileges, the function set the real
  100. user ID, effective user ID, and saved set-user ID of the calling process
  101. on implementations that supported it. When the caller did not have
  102. appropriate privileges, the function set only the effective user ID,
  103. subject to permission checks. The former use is generally needed for
  104. utilities like
  105. .IR login
  106. and
  107. .IR su ,
  108. which are not conforming applications and thus outside the scope of
  109. POSIX.1\(hy2008. These utilities wish to change the user ID irrevocably to a new
  110. value, generally that of an unprivileged user. The latter use is needed
  111. for conforming applications that are installed with the set-user-ID bit
  112. and need to perform operations using the real user ID.
  113. .P
  114. POSIX.1\(hy2008 augments the latter functionality with a mandatory feature named
  115. _POSIX_SAVED_IDS. This feature permits a set-user-ID application to
  116. switch its effective user ID back and forth between the values of its
  117. .IR exec -time
  118. real user ID and effective user ID. Unfortunately, the POSIX.1\(hy1990 standard did not
  119. permit a conforming application using this feature to work properly when
  120. it happened to be executed with (implementation-defined)
  121. appropriate privileges. Furthermore, the application did not even have a
  122. means to tell whether it had this privilege. Since the saved
  123. set-user-ID feature is quite desirable for applications, as evidenced
  124. by the fact that NIST required it in FIPS 151\(hy2, it has been mandated by
  125. POSIX.1\(hy2008. However, there are implementors who have been reluctant to
  126. support it given the limitation described above.
  127. .P
  128. The 4.3BSD system handles the problem by supporting separate
  129. functions:
  130. \fIsetuid\fR()
  131. (which always sets both the real and effective user IDs, like
  132. \fIsetuid\fR()
  133. in POSIX.1\(hy2008 for privileged users), and
  134. \fIseteuid\fR()
  135. (which always sets just the effective user ID, like
  136. \fIsetuid\fR()
  137. in POSIX.1\(hy2008 for non-privileged users). This separation of functionality
  138. into distinct functions seems desirable. 4.3BSD does not support the
  139. saved set-user-ID feature. It supports similar functionality of
  140. switching the effective user ID back and forth via
  141. \fIsetreuid\fR(),
  142. which permits reversing the real and effective user IDs. This model
  143. seems less desirable than the saved set-user-ID because the real user
  144. ID changes as a side-effect. The current 4.4BSD includes saved
  145. effective IDs and uses them for
  146. \fIseteuid\fR()
  147. and
  148. \fIsetegid\fR()
  149. as described above. The
  150. \fIsetreuid\fR()
  151. and
  152. \fIsetregid\fR()
  153. functions will be deprecated or removed.
  154. .P
  155. The solution here is:
  156. .IP " *" 4
  157. Require that all implementations support the functionality of the saved
  158. set-user-ID, which is set by the
  159. .IR exec
  160. functions and by privileged calls to
  161. \fIsetuid\fR().
  162. .IP " *" 4
  163. Add the
  164. \fIseteuid\fR()
  165. and
  166. \fIsetegid\fR()
  167. functions as portable alternatives to
  168. \fIsetuid\fR()
  169. and
  170. \fIsetgid\fR()
  171. for non-privileged and privileged processes.
  172. .P
  173. Historical systems have provided two mechanisms for a set-user-ID
  174. process to change its effective user ID to be the same as its real user
  175. ID in such a way that it could return to the original effective user
  176. ID: the use of the
  177. \fIsetuid\fR()
  178. function in the presence of a saved set-user-ID, or the use of the BSD
  179. \fIsetreuid\fR()
  180. function, which was able to swap the real and effective user IDs. The
  181. changes included in POSIX.1\(hy2008 provide a new mechanism using
  182. \fIseteuid\fR()
  183. in conjunction with a saved set-user-ID. Thus, all implementations with
  184. the new
  185. \fIseteuid\fR()
  186. mechanism will have a saved set-user-ID for each process, and most of
  187. the behavior controlled by _POSIX_SAVED_IDS has been changed
  188. to agree with the case where the option was defined. The
  189. \fIkill\fR()
  190. function is an exception. Implementors of the new
  191. \fIseteuid\fR()
  192. mechanism will generally be required to maintain compatibility with the
  193. older mechanisms previously supported by their systems. However,
  194. compatibility with this use of
  195. \fIsetreuid\fR()
  196. and with the _POSIX_SAVED_IDS behavior of
  197. \fIkill\fR()
  198. is unfortunately complicated. If an implementation with a saved
  199. set-user-ID allows a process to use
  200. \fIsetreuid\fR()
  201. to swap its real and effective user IDs, but were to leave the saved
  202. set-user-ID unmodified, the process would then have an effective user
  203. ID equal to the original real user ID, and both real and saved
  204. set-user-ID would be equal to the original effective user ID. In that
  205. state, the real user would be unable to kill the process, even though
  206. the effective user ID of the process matches that of the real user, if
  207. the
  208. \fIkill\fR()
  209. behavior of _POSIX_SAVED_IDS was used. This is obviously not
  210. acceptable. The alternative choice, which is used in at least one
  211. implementation, is to change the saved set-user-ID to the effective
  212. user ID during most calls to
  213. \fIsetreuid\fR().
  214. The standard developers considered that alternative to be less correct
  215. than the retention of the old behavior of
  216. \fIkill\fR()
  217. in such systems. Current conforming applications shall accommodate
  218. either behavior from
  219. \fIkill\fR(),
  220. and there appears to be no strong reason for
  221. \fIkill\fR()
  222. to check the saved set-user-ID rather than the effective user ID.
  223. .SH "FUTURE DIRECTIONS"
  224. None.
  225. .SH "SEE ALSO"
  226. .IR "\fIexec\fR\^",
  227. .IR "\fIgetegid\fR\^(\|)",
  228. .IR "\fIgeteuid\fR\^(\|)",
  229. .IR "\fIgetgid\fR\^(\|)",
  230. .IR "\fIgetuid\fR\^(\|)",
  231. .IR "\fIsetegid\fR\^(\|)",
  232. .IR "\fIseteuid\fR\^(\|)",
  233. .IR "\fIsetgid\fR\^(\|)",
  234. .IR "\fIsetregid\fR\^(\|)",
  235. .IR "\fIsetreuid\fR\^(\|)"
  236. .P
  237. The Base Definitions volume of POSIX.1\(hy2017,
  238. .IR "\fB<sys_types.h>\fP",
  239. .IR "\fB<unistd.h>\fP"
  240. .\"
  241. .SH COPYRIGHT
  242. Portions of this text are reprinted and reproduced in electronic form
  243. from IEEE Std 1003.1-2017, Standard for Information Technology
  244. -- Portable Operating System Interface (POSIX), The Open Group Base
  245. Specifications Issue 7, 2018 Edition,
  246. Copyright (C) 2018 by the Institute of
  247. Electrical and Electronics Engineers, Inc and The Open Group.
  248. In the event of any discrepancy between this version and the original IEEE and
  249. The Open Group Standard, the original IEEE and The Open Group Standard
  250. is the referee document. The original Standard can be obtained online at
  251. http://www.opengroup.org/unix/online.html .
  252. .PP
  253. Any typographical or formatting errors that appear
  254. in this page are most likely
  255. to have been introduced during the conversion of the source files to
  256. man page format. To report such errors, see
  257. https://www.kernel.org/doc/man-pages/reporting_bugs.html .