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
13 chown — change the file ownership
14
16 chown [−h] owner[:group] file...
17 chown −R [−H|−L|−P] owner[:group] file...
19
21 The chown utility shall set the user ID of the file named by each file
22 operand to the user ID specified by the owner operand.
23 For each file operand, or, if the −R option is used, each file encoun‐
25 tered while walking the directory trees specified by the file operands,
26 the chown utility shall perform actions equivalent to the chown() func‐
27 tion defined in the System Interfaces volume of POSIX.1‐2008, called
28 with the following arguments:
29 1. The file operand shall be used as the path argument.
31 2. The user ID indicated by the owner portion of the first operand
33 shall be used as the owner argument.
34 3. If the group portion of the first operand is given, the group ID
36 indicated by it shall be used as the group argument; otherwise, the
37 group ownership shall not be changed.
38 Unless chown is invoked by a process with appropriate privileges, the
40 set-user-ID and set-group-ID bits of a regular file shall be cleared
41 upon successful completion; the set-user-ID and set-group-ID bits of
42 other file types may be cleared.
43
45 The chown utility shall conform to the Base Definitions volume of
46 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
47 The following options shall be supported by the implementation:
49 −h For each file operand that names a file of type symbolic
51 link, chown shall attempt to set the user ID of the symbolic
52 link. If a group ID was specified, for each file operand that
53 names a file of type symbolic link, chown shall attempt to
54 set the group ID of the symbolic link.
55 −H If the −R option is specified and a symbolic link referencing
57 a file of type directory is specified on the command line,
58 chown shall change the user ID (and group ID, if specified)
59 of the directory referenced by the symbolic link and all
60 files in the file hierarchy below it.
61 −L If the −R option is specified and a symbolic link referencing
63 a file of type directory is specified on the command line or
64 encountered during the traversal of a file hierarchy, chown
65 shall change the user ID (and group ID, if specified) of the
66 directory referenced by the symbolic link and all files in
67 the file hierarchy below it.
68 −P If the −R option is specified and a symbolic link is speci‐
70 fied on the command line or encountered during the traversal
71 of a file hierarchy, chown shall change the owner ID (and
72 group ID, if specified) of the symbolic link. The chown util‐
73 ity shall not follow the symbolic link to any other part of
74 the file hierarchy.
75 −R Recursively change file user and group IDs. For each file op‐
77 erand that names a directory, chown shall change the user ID
78 (and group ID, if specified) of the directory and all files
79 in the file hierarchy below it. Unless a −H, −L, or −P option
80 is specified, it is unspecified which of these options will
81 be used as the default.
82 Specifying more than one of the mutually-exclusive options −H, −L, and
84 −P shall not be considered an error. The last option specified shall
85 determine the behavior of the utility.
86
88 The following operands shall be supported:
89 owner[:group]
91 A user ID and optional group ID to be assigned to file. The
92 owner portion of this operand shall be a user name from the
93 user database or a numeric user ID. Either specifies a user
94 ID which shall be given to each file named by one of the file
95 operands. If a numeric owner operand exists in the user data‐
96 base as a user name, the user ID number associated with that
97 user name shall be used as the user ID. Similarly, if the
98 group portion of this operand is present, it shall be a group
99 name from the group database or a numeric group ID. Either
100 specifies a group ID which shall be given to each file. If a
101 numeric group operand exists in the group database as a group
102 name, the group ID number associated with that group name
103 shall be used as the group ID.
104 file A pathname of a file whose user ID is to be modified.
106
108 Not used.
109
111 None.
112
114 The following environment variables shall affect the execution of
115 chown:
116 LANG Provide a default value for the internationalization vari‐
118 ables that are unset or null. (See the Base Definitions vol‐
119 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
120 ables for the precedence of internationalization variables
121 used to determine the values of locale categories.)
122 LC_ALL If set to a non-empty string value, override the values of
124 all the other internationalization variables.
125 LC_CTYPE Determine the locale for the interpretation of sequences of
127 bytes of text data as characters (for example, single-byte as
128 opposed to multi-byte characters in arguments).
129 LC_MESSAGES
131 Determine the locale that should be used to affect the format
132 and contents of diagnostic messages written to standard
133 error.
134 NLSPATH Determine the location of message catalogs for the processing
136 of LC_MESSAGES.
137
139 Default.
140
142 Not used.
143
145 The standard error shall be used only for diagnostic messages.
146
148 None.
149
151 None.
152
154 The following exit values shall be returned:
155 0 The utility executed successfully and all requested changes were
157 made.
158 >0 An error occurred.
160
162 Default.
163 The following sections are informative.
165
167 Only the owner of a file or the user with appropriate privileges may
168 change the owner or group of a file.
169 Some implementations restrict the use of chown to a user with appropri‐
171 ate privileges.
172
174 None.
175
177 The System V and BSD versions use different exit status codes. Some
178 implementations used the exit status as a count of the number of errors
179 that occurred; this practice is unworkable since it can overflow the
180 range of valid exit status values. These are masked by specifying only
181 0 and >0 as exit values.
182 The functionality of chown is described substantially through refer‐
184 ences to functions in the System Interfaces volume of POSIX.1‐2008. In
185 this way, there is no duplication of effort required for describing the
186 interactions of permissions, multiple groups, and so on.
187 The 4.3 BSD method of specifying both owner and group was included in
189 this volume of POSIX.1‐2008 because:
190 * There are cases where the desired end condition could not be
192 achieved using the chgrp and chown (that only changed the user ID)
193 utilities. (If the current owner is not a member of the desired
194 group and the desired owner is not a member of the current group,
195 the chown() function could fail unless both owner and group are
196 changed at the same time.)
197 * Even if they could be changed independently, in cases where both
199 are being changed, there is a 100% performance penalty caused by
200 being forced to invoke both utilities.
201 The BSD syntax user[.group] was changed to user[:group] in this volume
203 of POSIX.1‐2008 because the <period> is a valid character in login
204 names (as specified by the Base Definitions volume of POSIX.1‐2008,
205 login names consist of characters in the portable filename character
206 set). The <colon> character was chosen as the replacement for the
207 <period> character because it would never be allowed as a character in
208 a user name or group name on historical implementations.
209 The −R option is considered by some observers as an undesirable depar‐
211 ture from the historical UNIX system tools approach; since a tool,
212 find, already exists to recurse over directories, there seemed to be no
213 good reason to require other tools to have to duplicate that function‐
214 ality. However, the −R option was deemed an important user conve‐
215 nience, is far more efficient than forking a separate process for each
216 element of the directory hierarchy, and is in widespread historical
217 use.
218
220 None.
221
223 chgrp, chmod
224 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
226 Variables, Section 12.2, Utility Syntax Guidelines
227 The System Interfaces volume of POSIX.1‐2008, chown()
229
231 Portions of this text are reprinted and reproduced in electronic form
232 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
233 -- Portable Operating System Interface (POSIX), The Open Group Base
234 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
235 cal and Electronics Engineers, Inc and The Open Group. (This is
236 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
237 event of any discrepancy between this version and the original IEEE and
238 The Open Group Standard, the original IEEE and The Open Group Standard
239 is the referee document. The original Standard can be obtained online
240 at http://www.unix.org/online.html .
241 Any typographical or formatting errors that appear in this page are
243 most likely to have been introduced during the conversion of the source
244 files to man page format. To report such errors, see https://www.ker‐
245 nel.org/doc/man-pages/reporting_bugs.html .
246IEEE/The Open Group 2013 CHOWN(1P)