1CHOWN(1P)                  POSIX Programmer's Manual                 CHOWN(1P)
2
3
4

PROLOG

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
11

NAME

13       chown — change the file ownership
14

SYNOPSIS

16       chown [−h] owner[:group] file...
17
18       chown −R [−H|−L|−P] owner[:group] file...
19

DESCRIPTION

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
24       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
30        1. The file operand shall be used as the path argument.
31
32        2. The  user  ID  indicated  by the owner portion of the first operand
33           shall be used as the owner argument.
34
35        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
39       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

OPTIONS

45       The  chown  utility  shall  conform  to  the Base Definitions volume of
46       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
47
48       The following options shall be supported by the implementation:
49
50       −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
56       −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
62       −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
69       −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
76       −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
83       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

OPERANDS

88       The following operands shall be supported:
89
90       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
105       file      A pathname of a file whose user ID is to be modified.
106

STDIN

108       Not used.
109

INPUT FILES

111       None.
112

ENVIRONMENT VARIABLES

114       The  following  environment  variables  shall  affect  the execution of
115       chown:
116
117       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
123       LC_ALL    If set to a non-empty string value, override  the  values  of
124                 all the other internationalization variables.
125
126       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
130       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
135       NLSPATH   Determine the location of message catalogs for the processing
136                 of LC_MESSAGES.
137

ASYNCHRONOUS EVENTS

139       Default.
140

STDOUT

142       Not used.
143

STDERR

145       The standard error shall be used only for diagnostic messages.
146

OUTPUT FILES

148       None.
149

EXTENDED DESCRIPTION

151       None.
152

EXIT STATUS

154       The following exit values shall be returned:
155
156        0    The utility executed successfully and all requested changes  were
157             made.
158
159       >0    An error occurred.
160

CONSEQUENCES OF ERRORS

162       Default.
163
164       The following sections are informative.
165

APPLICATION USAGE

167       Only  the  owner  of a file or the user with appropriate privileges may
168       change the owner or group of a file.
169
170       Some implementations restrict the use of chown to a user with appropri‐
171       ate privileges.
172

EXAMPLES

174       None.
175

RATIONALE

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
183       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
188       The 4.3 BSD method of specifying both owner and group was  included  in
189       this volume of POSIX.1‐2008 because:
190
191        *  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
198        *  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
202       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
210       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

FUTURE DIRECTIONS

220       None.
221

SEE ALSO

223       chgrp, chmod
224
225       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
226       Variables, Section 12.2, Utility Syntax Guidelines
227
228       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
242       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 .
246
247
248
249IEEE/The Open Group                  2013                            CHOWN(1P)
Impressum