1CHOWN(1P) POSIX Programmer's Manual CHOWN(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 chown — change the file ownership
13
15 chown [-h] owner[:group] file...
16 chown -R [-H|-L|-P] owner[:group] file...
18
20 The chown utility shall set the user ID of the file named by each file
21 operand to the user ID specified by the owner operand.
22 For each file operand, or, if the -R option is used, each file encoun‐
24 tered while walking the directory trees specified by the file operands,
25 the chown utility shall perform actions equivalent to the chown() func‐
26 tion defined in the System Interfaces volume of POSIX.1‐2017, called
27 with the following arguments:
28 1. The file operand shall be used as the path argument.
30 2. The user ID indicated by the owner portion of the first operand
32 shall be used as the owner argument.
33 3. If the group portion of the first operand is given, the group ID
35 indicated by it shall be used as the group argument; otherwise, the
36 group ownership shall not be changed.
37 Unless chown is invoked by a process with appropriate privileges, the
39 set-user-ID and set-group-ID bits of a regular file shall be cleared
40 upon successful completion; the set-user-ID and set-group-ID bits of
41 other file types may be cleared.
42
44 The chown utility shall conform to the Base Definitions volume of
45 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
46 The following options shall be supported by the implementation:
48 -h For each file operand that names a file of type symbolic
50 link, chown shall attempt to set the user ID of the symbolic
51 link. If a group ID was specified, for each file operand that
52 names a file of type symbolic link, chown shall attempt to
53 set the group ID of the symbolic link.
54 -H If the -R option is specified and a symbolic link referencing
56 a file of type directory is specified on the command line,
57 chown shall change the user ID (and group ID, if specified)
58 of the directory referenced by the symbolic link and all
59 files in the file hierarchy below it.
60 -L If the -R option is specified and a symbolic link referencing
62 a file of type directory is specified on the command line or
63 encountered during the traversal of a file hierarchy, chown
64 shall change the user ID (and group ID, if specified) of the
65 directory referenced by the symbolic link and all files in
66 the file hierarchy below it.
67 -P If the -R option is specified and a symbolic link is speci‐
69 fied on the command line or encountered during the traversal
70 of a file hierarchy, chown shall change the owner ID (and
71 group ID, if specified) of the symbolic link. The chown util‐
72 ity shall not follow the symbolic link to any other part of
73 the file hierarchy.
74 -R Recursively change file user and group IDs. For each file op‐
76 erand that names a directory, chown shall change the user ID
77 (and group ID, if specified) of the directory and all files
78 in the file hierarchy below it. Unless a -H, -L, or -P option
79 is specified, it is unspecified which of these options will
80 be used as the default.
81 Specifying more than one of the mutually-exclusive options -H, -L, and
83 -P shall not be considered an error. The last option specified shall
84 determine the behavior of the utility.
85
87 The following operands shall be supported:
88 owner[:group]
90 A user ID and optional group ID to be assigned to file. The
91 owner portion of this operand shall be a user name from the
92 user database or a numeric user ID. Either specifies a user
93 ID which shall be given to each file named by one of the file
94 operands. If a numeric owner operand exists in the user data‐
95 base as a user name, the user ID number associated with that
96 user name shall be used as the user ID. Similarly, if the
97 group portion of this operand is present, it shall be a group
98 name from the group database or a numeric group ID. Either
99 specifies a group ID which shall be given to each file. If a
100 numeric group operand exists in the group database as a group
101 name, the group ID number associated with that group name
102 shall be used as the group ID.
103 file A pathname of a file whose user ID is to be modified.
105
107 Not used.
108
110 None.
111
113 The following environment variables shall affect the execution of
114 chown:
115 LANG Provide a default value for the internationalization vari‐
117 ables that are unset or null. (See the Base Definitions vol‐
118 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
119 ables for the precedence of internationalization variables
120 used to determine the values of locale categories.)
121 LC_ALL If set to a non-empty string value, override the values of
123 all the other internationalization variables.
124 LC_CTYPE Determine the locale for the interpretation of sequences of
126 bytes of text data as characters (for example, single-byte as
127 opposed to multi-byte characters in arguments).
128 LC_MESSAGES
130 Determine the locale that should be used to affect the format
131 and contents of diagnostic messages written to standard
132 error.
133 NLSPATH Determine the location of message catalogs for the processing
135 of LC_MESSAGES.
136
138 Default.
139
141 Not used.
142
144 The standard error shall be used only for diagnostic messages.
145
147 None.
148
150 None.
151
153 The following exit values shall be returned:
154 0 The utility executed successfully and all requested changes were
156 made.
157 >0 An error occurred.
159
161 Default.
162 The following sections are informative.
164
166 Only the owner of a file or the user with appropriate privileges may
167 change the owner or group of a file.
168 Some implementations restrict the use of chown to a user with appropri‐
170 ate privileges.
171
173 None.
174
176 The System V and BSD versions use different exit status codes. Some
177 implementations used the exit status as a count of the number of errors
178 that occurred; this practice is unworkable since it can overflow the
179 range of valid exit status values. These are masked by specifying only
180 0 and >0 as exit values.
181 The functionality of chown is described substantially through refer‐
183 ences to functions in the System Interfaces volume of POSIX.1‐2017. In
184 this way, there is no duplication of effort required for describing the
185 interactions of permissions, multiple groups, and so on.
186 The 4.3 BSD method of specifying both owner and group was included in
188 this volume of POSIX.1‐2017 because:
189 * There are cases where the desired end condition could not be
191 achieved using the chgrp and chown (that only changed the user ID)
192 utilities. (If the current owner is not a member of the desired
193 group and the desired owner is not a member of the current group,
194 the chown() function could fail unless both owner and group are
195 changed at the same time.)
196 * Even if they could be changed independently, in cases where both
198 are being changed, there is a 100% performance penalty caused by
199 being forced to invoke both utilities.
200 The BSD syntax user[.group] was changed to user[:group] in this volume
202 of POSIX.1‐2017 because the <period> is a valid character in login
203 names (as specified by the Base Definitions volume of POSIX.1‐2017,
204 login names consist of characters in the portable filename character
205 set). The <colon> character was chosen as the replacement for the
206 <period> character because it would never be allowed as a character in
207 a user name or group name on historical implementations.
208 The -R option is considered by some observers as an undesirable depar‐
210 ture from the historical UNIX system tools approach; since a tool,
211 find, already exists to recurse over directories, there seemed to be no
212 good reason to require other tools to have to duplicate that function‐
213 ality. However, the -R option was deemed an important user conve‐
214 nience, is far more efficient than forking a separate process for each
215 element of the directory hierarchy, and is in widespread historical
216 use.
217
219 None.
220
222 chgrp, chmod
223 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
225 Variables, Section 12.2, Utility Syntax Guidelines
226 The System Interfaces volume of POSIX.1‐2017, chown()
228
230 Portions of this text are reprinted and reproduced in electronic form
231 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
232 table Operating System Interface (POSIX), The Open Group Base Specifi‐
233 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
234 Electrical and Electronics Engineers, Inc and The Open Group. In the
235 event of any discrepancy between this version and the original IEEE and
236 The Open Group Standard, the original IEEE and The Open Group Standard
237 is the referee document. The original Standard can be obtained online
238 at http://www.opengroup.org/unix/online.html .
239 Any typographical or formatting errors that appear in this page are
241 most likely to have been introduced during the conversion of the source
242 files to man page format. To report such errors, see https://www.ker‐
243 nel.org/doc/man-pages/reporting_bugs.html .
244IEEE/The Open Group 2017 CHOWN(1P)