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.1p (9934B)


  1. '\" et
  2. .TH CHOWN "1P" 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
  12. \(em change the file ownership
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. chown \fB[\fR-h\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR...
  17. .P
  18. chown -R \fB[\fR-H|-L|-P\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR...
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR chown
  23. utility shall set the user ID of the file named by each
  24. .IR file
  25. operand to the user ID specified by the
  26. .IR owner
  27. operand.
  28. .P
  29. For each
  30. .IR file
  31. operand, or, if the
  32. .BR \-R
  33. option is used, each file encountered while walking the directory
  34. trees specified by the
  35. .IR file
  36. operands, the
  37. .IR chown
  38. utility shall perform actions equivalent to the
  39. \fIchown\fR()
  40. function defined in the System Interfaces volume of POSIX.1\(hy2017, called with the following arguments:
  41. .IP " 1." 4
  42. The
  43. .IR file
  44. operand shall be used as the
  45. .IR path
  46. argument.
  47. .IP " 2." 4
  48. The user ID indicated by the
  49. .IR owner
  50. portion of the first operand shall be used as the
  51. .IR owner
  52. argument.
  53. .IP " 3." 4
  54. If the
  55. .IR group
  56. portion of the first operand is given, the group ID indicated by it
  57. shall be used as the
  58. .IR group
  59. argument; otherwise, the group ownership shall not be changed.
  60. .P
  61. Unless
  62. .IR chown
  63. is invoked by a process with appropriate privileges, the set-user-ID
  64. and set-group-ID bits of a regular file shall be cleared upon
  65. successful completion; the set-user-ID and set-group-ID bits of other
  66. file types may be cleared.
  67. .SH OPTIONS
  68. The
  69. .IR chown
  70. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  71. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  72. .P
  73. The following options shall be supported by the implementation:
  74. .IP "\fB\-h\fP" 10
  75. For each file operand that names a file of type symbolic link,
  76. .IR chown
  77. shall attempt to set the user ID of the symbolic link. If a group ID
  78. was specified, for each file operand that names a file of
  79. type symbolic link,
  80. .IR chown
  81. shall attempt to set the group ID of the symbolic link.
  82. .IP "\fB\-H\fP" 10
  83. If the
  84. .BR \-R
  85. option is specified and a symbolic link referencing a file of type
  86. directory is specified on the command line,
  87. .IR chown
  88. shall change the user ID (and group ID, if specified) of the directory
  89. referenced by the symbolic link and all files in the file hierarchy
  90. below it.
  91. .IP "\fB\-L\fP" 10
  92. If the
  93. .BR \-R
  94. option is specified and a symbolic link referencing a file of type
  95. directory is specified on the command line or encountered during the
  96. traversal of a file hierarchy,
  97. .IR chown
  98. shall change the user ID (and group ID, if specified) of the directory
  99. referenced by the symbolic link and all files in the file hierarchy
  100. below it.
  101. .IP "\fB\-P\fP" 10
  102. If the
  103. .BR \-R
  104. option is specified and a symbolic link is specified on the command
  105. line or encountered during the traversal of a file hierarchy,
  106. .IR chown
  107. shall change the owner ID (and group ID, if specified) of the symbolic
  108. link. The
  109. .IR chown
  110. utility shall not follow the symbolic link to any other part of the
  111. file hierarchy.
  112. .IP "\fB\-R\fP" 10
  113. Recursively change file user and group IDs. For each
  114. .IR file
  115. operand that names a directory,
  116. .IR chown
  117. shall change the user ID (and group ID, if specified) of the directory
  118. and all files in the file hierarchy below it. Unless a
  119. .BR \-H ,
  120. .BR \-L ,
  121. or
  122. .BR \-P
  123. option is specified, it is unspecified which of these options will be
  124. used as the default.
  125. .P
  126. Specifying more than one of the mutually-exclusive options
  127. .BR \-H ,
  128. .BR \-L ,
  129. and
  130. .BR \-P
  131. shall not be considered an error. The last option specified shall
  132. determine the behavior of the utility.
  133. .SH OPERANDS
  134. The following operands shall be supported:
  135. .IP "\fIowner\fB[\fR:\fIgroup\fB]\fR" 10
  136. A user ID and optional group ID to be assigned to
  137. .IR file .
  138. The
  139. .IR owner
  140. portion of this operand shall be a user name from the user database or
  141. a numeric user ID. Either specifies a user ID which shall be given to
  142. each file named by one of the
  143. .IR file
  144. operands. If a numeric
  145. .IR owner
  146. operand exists in the user database as a user name, the user ID number
  147. associated with that user name shall be used as the user ID. Similarly,
  148. if the
  149. .IR group
  150. portion of this operand is present, it shall be a group name from the
  151. group database or a numeric group ID. Either specifies a group ID which
  152. shall be given to each file. If a numeric group operand exists in the
  153. group database as a group name, the group ID number associated with
  154. that group name shall be used as the group ID.
  155. .IP "\fIfile\fR" 10
  156. A pathname of a file whose user ID is to be modified.
  157. .SH STDIN
  158. Not used.
  159. .SH "INPUT FILES"
  160. None.
  161. .SH "ENVIRONMENT VARIABLES"
  162. The following environment variables shall affect the execution of
  163. .IR chown :
  164. .IP "\fILANG\fP" 10
  165. Provide a default value for the internationalization variables that are
  166. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  167. .IR "Section 8.2" ", " "Internationalization Variables"
  168. for the precedence of internationalization variables used to determine
  169. the values of locale categories.)
  170. .IP "\fILC_ALL\fP" 10
  171. If set to a non-empty string value, override the values of all the
  172. other internationalization variables.
  173. .IP "\fILC_CTYPE\fP" 10
  174. Determine the locale for the interpretation of sequences of bytes of
  175. text data as characters (for example, single-byte as opposed to
  176. multi-byte characters in arguments).
  177. .IP "\fILC_MESSAGES\fP" 10
  178. .br
  179. Determine the locale that should be used to affect the format and
  180. contents of diagnostic messages written to standard error.
  181. .IP "\fINLSPATH\fP" 10
  182. Determine the location of message catalogs for the processing of
  183. .IR LC_MESSAGES .
  184. .SH "ASYNCHRONOUS EVENTS"
  185. Default.
  186. .SH STDOUT
  187. Not used.
  188. .SH STDERR
  189. The standard error shall be used only for diagnostic messages.
  190. .SH "OUTPUT FILES"
  191. None.
  192. .SH "EXTENDED DESCRIPTION"
  193. None.
  194. .SH "EXIT STATUS"
  195. The following exit values shall be returned:
  196. .IP "\00" 6
  197. The utility executed successfully and all requested changes were made.
  198. .IP >0 6
  199. An error occurred.
  200. .SH "CONSEQUENCES OF ERRORS"
  201. Default.
  202. .LP
  203. .IR "The following sections are informative."
  204. .SH "APPLICATION USAGE"
  205. Only the owner of a file or the user with appropriate privileges may
  206. change the owner or group of a file.
  207. .P
  208. Some implementations restrict the use of
  209. .IR chown
  210. to a user with appropriate privileges.
  211. .SH EXAMPLES
  212. None.
  213. .SH RATIONALE
  214. The System V and BSD versions use different exit status codes. Some
  215. implementations used the exit status as a count of the number of errors
  216. that occurred; this practice is unworkable since it can overflow the
  217. range of valid exit status values. These are masked by specifying only
  218. 0 and >0 as exit values.
  219. .P
  220. The functionality of
  221. .IR chown
  222. is described substantially through references to functions in the
  223. System Interfaces volume of POSIX.1\(hy2017. In this way, there is no duplication of effort required for
  224. describing the interactions of permissions, multiple groups, and so
  225. on.
  226. .P
  227. The 4.3 BSD method of specifying both owner and group was included in
  228. \&this volume of POSIX.1\(hy2017 because:
  229. .IP " *" 4
  230. There are cases where the desired end condition could not be achieved
  231. using the
  232. .IR chgrp
  233. and
  234. .IR chown
  235. (that only changed the user ID) utilities. (If the current owner is not
  236. a member of the desired group and the desired owner is not a member of
  237. the current group, the
  238. \fIchown\fR()
  239. function could fail unless both owner and group are changed at the same
  240. time.)
  241. .IP " *" 4
  242. Even if they could be changed independently, in cases where both are
  243. being changed, there is a 100% performance penalty caused by being
  244. forced to invoke both utilities.
  245. .P
  246. The BSD syntax
  247. .IR user [.\c
  248. .IR group ]
  249. was changed to
  250. .IR user [:\c
  251. .IR group ]
  252. in this volume of POSIX.1\(hy2017 because the
  253. <period>
  254. is a valid character in login names (as specified by the Base Definitions volume of POSIX.1\(hy2017, login
  255. names consist of characters in the portable filename character set). The
  256. <colon>
  257. character was chosen as the replacement for the
  258. <period>
  259. character because it would never be allowed as a character in a user
  260. name or group name on historical implementations.
  261. .P
  262. The
  263. .BR \-R
  264. option is considered by some observers as an undesirable departure from
  265. the historical UNIX system tools approach; since a tool,
  266. .IR find ,
  267. already exists to recurse over directories, there seemed to be no good
  268. reason to require other tools to have to duplicate that functionality.
  269. However, the
  270. .BR \-R
  271. option was deemed an important user convenience, is far more efficient
  272. than forking a separate process for each element of the directory
  273. hierarchy, and is in widespread historical use.
  274. .SH "FUTURE DIRECTIONS"
  275. None.
  276. .SH "SEE ALSO"
  277. .IR "\fIchgrp\fR\^",
  278. .IR "\fIchmod\fR\^"
  279. .P
  280. The Base Definitions volume of POSIX.1\(hy2017,
  281. .IR "Chapter 8" ", " "Environment Variables",
  282. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  283. .P
  284. The System Interfaces volume of POSIX.1\(hy2017,
  285. .IR "\fIchown\fR\^(\|)"
  286. .\"
  287. .SH COPYRIGHT
  288. Portions of this text are reprinted and reproduced in electronic form
  289. from IEEE Std 1003.1-2017, Standard for Information Technology
  290. -- Portable Operating System Interface (POSIX), The Open Group Base
  291. Specifications Issue 7, 2018 Edition,
  292. Copyright (C) 2018 by the Institute of
  293. Electrical and Electronics Engineers, Inc and The Open Group.
  294. In the event of any discrepancy between this version and the original IEEE and
  295. The Open Group Standard, the original IEEE and The Open Group Standard
  296. is the referee document. The original Standard can be obtained online at
  297. http://www.opengroup.org/unix/online.html .
  298. .PP
  299. Any typographical or formatting errors that appear
  300. in this page are most likely
  301. to have been introduced during the conversion of the source files to
  302. man page format. To report such errors, see
  303. https://www.kernel.org/doc/man-pages/reporting_bugs.html .