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

chown.3p (10092B)


  1. '\" et
  2. .TH CHOWN "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. chown, fchownat
  12. \(em change owner and group of a file
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int chown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP);
  19. .P
  20. #include <fcntl.h>
  21. .P
  22. int fchownat(int \fIfd\fP, const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP,
  23. int \fIflag\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. \fIchown\fR()
  28. function shall change the user and group ownership of a file.
  29. .P
  30. The
  31. .IR path
  32. argument points to a pathname naming a file. The user ID and group ID
  33. of the named file shall be set to the numeric values contained in
  34. .IR owner
  35. and
  36. .IR group ,
  37. respectively.
  38. .P
  39. Only processes with an effective user ID equal to the user ID of the
  40. file or with appropriate privileges may change the ownership of a
  41. file. If _POSIX_CHOWN_RESTRICTED is in effect for
  42. .IR path :
  43. .IP " *" 4
  44. Changing the user ID is restricted to processes with appropriate
  45. privileges.
  46. .IP " *" 4
  47. Changing the group ID is permitted to a process with an effective user
  48. ID equal to the user ID of the file, but without appropriate
  49. privileges, if and only if
  50. .IR owner
  51. is equal to the file's user ID or (\c
  52. .BR uid_t )\-1
  53. and
  54. .IR group
  55. is equal either to the calling process' effective group ID or to one of
  56. its supplementary group IDs.
  57. .P
  58. If the specified file is a regular file, one or more of the S_IXUSR,
  59. S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does
  60. not have appropriate privileges, the set-user-ID (S_ISUID) and
  61. set-group-ID (S_ISGID) bits of the file mode shall be cleared upon
  62. successful return from
  63. \fIchown\fR().
  64. If the specified file is a regular file, one or more of the S_IXUSR,
  65. S_IXGRP, or S_IXOTH bits of the file mode are set, and the process has
  66. appropriate privileges, it is implementation-defined whether the
  67. set-user-ID and set-group-ID bits are altered. If the
  68. \fIchown\fR()
  69. function is successfully invoked on a file that is not a regular file
  70. and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file
  71. mode are set, the set-user-ID and set-group-ID bits may be cleared.
  72. .P
  73. If
  74. .IR owner
  75. or
  76. .IR group
  77. is specified as (\c
  78. .BR uid_t )\-1
  79. or (\c
  80. .BR gid_t )\-1,
  81. respectively, the corresponding ID of the file shall not be changed.
  82. .P
  83. Upon successful completion,
  84. \fIchown\fR()
  85. shall mark for update the last file status change timestamp of the
  86. file, except that if
  87. .IR owner
  88. is (\c
  89. .BR uid_t )\-1
  90. and
  91. .IR group
  92. is (\c
  93. .BR gid_t )\-1,
  94. the file status change timestamp need not be marked for update.
  95. .P
  96. The
  97. \fIfchownat\fR()
  98. function shall be equivalent to the
  99. \fIchown\fR()
  100. and
  101. \fIlchown\fR()
  102. functions except in the case where
  103. .IR path
  104. specifies a relative path. In this case the file to be changed is
  105. determined relative to the directory associated with the file
  106. descriptor
  107. .IR fd
  108. instead of the current working directory. If the access mode of
  109. the open file description associated with the file descriptor is not
  110. O_SEARCH, the function shall check whether directory searches are
  111. permitted using the current permissions of the directory underlying
  112. the file descriptor. If the access mode is O_SEARCH, the function
  113. shall not perform the check.
  114. .P
  115. Values for
  116. .IR flag
  117. are constructed by a bitwise-inclusive OR of flags from the following
  118. list, defined in
  119. .IR <fcntl.h> :
  120. .IP AT_SYMLINK_NOFOLLOW 6
  121. .br
  122. If
  123. .IR path
  124. names a symbolic link, ownership of the symbolic link is changed.
  125. .P
  126. If
  127. \fIfchownat\fR()
  128. is passed the special value AT_FDCWD in the
  129. .IR fd
  130. parameter, the current working directory shall be used and the behavior
  131. shall be identical to a call to
  132. \fIchown\fR()
  133. or
  134. \fIlchown\fR()
  135. respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit
  136. is set in the
  137. .IR flag
  138. argument.
  139. .SH "RETURN VALUE"
  140. Upon successful completion, these functions shall return 0.
  141. Otherwise, these functions shall return \-1 and set
  142. .IR errno
  143. to indicate the error. If \-1 is returned, no changes are
  144. made in the user ID and group ID of the file.
  145. .SH ERRORS
  146. These functions shall fail if:
  147. .TP
  148. .BR EACCES
  149. Search permission is denied on a component of the path prefix.
  150. .TP
  151. .BR ELOOP
  152. A loop exists in symbolic links encountered during resolution of the
  153. .IR path
  154. argument.
  155. .TP
  156. .BR ENAMETOOLONG
  157. .br
  158. The length of a component of a pathname is longer than
  159. {NAME_MAX}.
  160. .TP
  161. .BR ENOENT
  162. A component of
  163. .IR path
  164. does not name an existing file or
  165. .IR path
  166. is an empty string.
  167. .TP
  168. .BR ENOTDIR
  169. A component of the path prefix names an existing file that is neither
  170. a directory nor a symbolic link to a directory, or the
  171. .IR path
  172. argument contains at least one non-\c
  173. <slash>
  174. character and ends with one or more trailing
  175. <slash>
  176. characters and the last pathname component names an existing file
  177. that is neither a directory nor a symbolic link to a directory.
  178. .TP
  179. .BR EPERM
  180. The effective user ID does not match the owner of the file, or the
  181. calling process does not have appropriate privileges and
  182. _POSIX_CHOWN_RESTRICTED indicates that such privilege is required.
  183. .TP
  184. .BR EROFS
  185. The named file resides on a read-only file system.
  186. .P
  187. The
  188. \fIfchownat\fR()
  189. function shall fail if:
  190. .TP
  191. .BR EACCES
  192. The access mode of the open file description associated with
  193. .IR fd
  194. is not O_SEARCH and the permissions of the directory underlying
  195. .IR fd
  196. do not permit directory searches.
  197. .TP
  198. .BR EBADF
  199. The
  200. .IR path
  201. argument does not specify an absolute path and the
  202. .IR fd
  203. argument is neither AT_FDCWD nor a valid file descriptor open
  204. for reading or searching.
  205. .TP
  206. .BR ENOTDIR
  207. The
  208. .IR path
  209. argument is not an absolute path and
  210. .IR fd
  211. is a file descriptor associated with a non-directory file.
  212. .P
  213. These functions may fail if:
  214. .TP
  215. .BR EIO
  216. An I/O error occurred while reading or writing to the file system.
  217. .TP
  218. .BR EINTR
  219. The
  220. \fIchown\fR()
  221. function was interrupted by a signal which was caught.
  222. .TP
  223. .BR EINVAL
  224. The owner or group ID supplied is not a value supported by the
  225. implementation.
  226. .TP
  227. .BR ELOOP
  228. More than
  229. {SYMLOOP_MAX}
  230. symbolic links were encountered during resolution of the
  231. .IR path
  232. argument.
  233. .TP
  234. .BR ENAMETOOLONG
  235. .br
  236. The length of a pathname exceeds
  237. {PATH_MAX},
  238. or pathname resolution of a symbolic link produced an intermediate
  239. result with a length that exceeds
  240. {PATH_MAX}.
  241. .br
  242. .P
  243. The
  244. \fIfchownat\fR()
  245. function may fail if:
  246. .TP
  247. .BR EINVAL
  248. The value of the
  249. .IR flag
  250. argument is not valid.
  251. .LP
  252. .IR "The following sections are informative."
  253. .SH EXAMPLES
  254. None.
  255. .SH "APPLICATION USAGE"
  256. Although
  257. \fIchown\fR()
  258. can be used on some implementations by the file owner to change the owner
  259. and group to any desired values, the only portable use of this function
  260. is to change the group of a file to the effective GID of the calling
  261. process or to a member of its group set.
  262. .SH RATIONALE
  263. System III and System V allow a user to give away files;
  264. that is, the owner of a file may change its user ID to anything. This
  265. is a serious problem for implementations that are intended to meet
  266. government security regulations.
  267. Version 7 and 4.3 BSD permit only the superuser
  268. to change the user ID of a file. Some government agencies (usually not
  269. ones concerned directly with security) find this limitation too
  270. confining. This volume of POSIX.1\(hy2017 uses \fImay\fP to permit secure implementations
  271. while not disallowing System V.
  272. .P
  273. System III and System V allow the owner of a file to change the
  274. group ID to anything. Version 7 permits only the superuser to change
  275. the group ID of a file.
  276. 4.3 BSD permits the owner to change the group ID of a file
  277. to its effective group ID
  278. or to any of the groups in the list of supplementary group IDs, but to
  279. no others.
  280. .P
  281. The POSIX.1\(hy1990 standard requires that the
  282. \fIchown\fR()
  283. function invoked by a non-appropriate privileged process clear the
  284. S_ISGID and the S_ISUID bits for regular files, and permits them to be
  285. cleared for other types of files. This is so that changes in
  286. accessibility do not accidentally cause files to become security holes.
  287. Unfortunately, requiring these bits to be cleared on non-executable
  288. data files also clears the mandatory file locking bit (shared with
  289. S_ISGID), which is an extension on many implementations (it first
  290. appeared in System V). These bits should only be required to be
  291. cleared on regular files that have one or more of their execute bits
  292. set.
  293. .P
  294. The purpose of the
  295. \fIfchownat\fR()
  296. function is to enable changing ownership of files in directories other
  297. than the current working directory without exposure to race
  298. conditions. Any part of the path of a file could be changed in
  299. parallel to a call to
  300. \fIchown\fR()
  301. or
  302. \fIlchown\fR(),
  303. resulting in unspecified behavior. By opening a file descriptor for
  304. the target directory and using the
  305. \fIfchownat\fR()
  306. function it can be guaranteed that the changed file is located relative
  307. to the desired directory.
  308. .SH "FUTURE DIRECTIONS"
  309. None.
  310. .SH "SEE ALSO"
  311. .IR "\fIchmod\fR\^(\|)",
  312. .IR "\fIfpathconf\fR\^(\|)",
  313. .IR "\fIlchown\fR\^(\|)"
  314. .P
  315. The Base Definitions volume of POSIX.1\(hy2017,
  316. .IR "\fB<fcntl.h>\fP",
  317. .IR "\fB<sys_types.h>\fP",
  318. .IR "\fB<unistd.h>\fP"
  319. .\"
  320. .SH COPYRIGHT
  321. Portions of this text are reprinted and reproduced in electronic form
  322. from IEEE Std 1003.1-2017, Standard for Information Technology
  323. -- Portable Operating System Interface (POSIX), The Open Group Base
  324. Specifications Issue 7, 2018 Edition,
  325. Copyright (C) 2018 by the Institute of
  326. Electrical and Electronics Engineers, Inc and The Open Group.
  327. In the event of any discrepancy between this version and the original IEEE and
  328. The Open Group Standard, the original IEEE and The Open Group Standard
  329. is the referee document. The original Standard can be obtained online at
  330. http://www.opengroup.org/unix/online.html .
  331. .PP
  332. Any typographical or formatting errors that appear
  333. in this page are most likely
  334. to have been introduced during the conversion of the source files to
  335. man page format. To report such errors, see
  336. https://www.kernel.org/doc/man-pages/reporting_bugs.html .