Debian Codegraph @

upstream/debian-unstable/man2/chown.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright 1998, Andries E. Brouwer <[email protected]>
3 .\" Copyright 2006-2014, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH chown 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 chown, fchown, lchown, fchownat \- change ownership of a file
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <unistd.h>
17 .P
18 .BI "int chown(const char *" path ", uid_t " owner ", gid_t " group );
19 .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
20 .BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group );
21 .P
22 .BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
23 .B #include <unistd.h>
24 .P
25 .BI "int fchownat(int " dirfd ", const char *" path ,
26 .BI " uid_t " owner ", gid_t " group ", int " flags );
27 .fi
28 .P
29 .RS -4
30 Feature Test Macro Requirements for glibc (see
31 .BR feature_test_macros (7)):
32 .RE
33 .P
34 .BR fchown (),
35 .BR lchown ():
36 .nf
37 /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
38 || _XOPEN_SOURCE >= 500
39 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
40 || /* glibc <= 2.19: */ _BSD_SOURCE
41 .fi
42 .P
43 .BR fchownat ():
44 .nf
45 Since glibc 2.10:
46 _POSIX_C_SOURCE >= 200809L
47 Before glibc 2.10:
48 _ATFILE_SOURCE
49 .fi
50 .SH DESCRIPTION
51 These system calls change the owner and group of a file.
52 The
53 .BR chown (),
54 .BR fchown (),
55 and
56 .BR lchown ()
57 system calls differ only in how the file is specified:
58 .IP \[bu] 3
59 .BR chown ()
60 changes the ownership of the file specified by
61 .IR path ,
62 which is dereferenced if it is a symbolic link.
63 .IP \[bu]
64 .BR fchown ()
65 changes the ownership of the file referred to by the open file descriptor
66 .IR fd .
67 .IP \[bu]
68 .BR lchown ()
69 is like
70 .BR chown (),
71 but does not dereference symbolic links.
72 .P
73 Only a privileged process (Linux: one with the
74 .B CAP_CHOWN
75 capability) may change the owner of a file.
76 The owner of a file may change the group of the file
77 to any group of which that owner is a member.
78 A privileged process (Linux: with
79 .BR CAP_CHOWN )
80 may change the group arbitrarily.
81 .P
82 If the
83 .I owner
84 or
85 .I group
86 is specified as \-1, then that ID is not changed.
87 .P
88 When the owner or group of an executable file is
89 changed by an unprivileged user, the
90 .B S_ISUID
91 and
92 .B S_ISGID
93 mode bits are cleared.
94 POSIX does not specify whether
95 this also should happen when root does the
96 .BR chown ();
97 the Linux behavior depends on the kernel version,
98 and since Linux 2.2.13, root is treated like other users.
99 .\" In Linux 2.0 kernels, superuser was like everyone else
100 .\" In Linux 2.2, up to Linux 2.2.12, these bits were not cleared for superuser.
101 .\" Since Linux 2.2.13, superuser is once more like everyone else.
102 In case of a non-group-executable file (i.e., one for which the
103 .B S_IXGRP
104 bit is not set) the
105 .B S_ISGID
106 bit indicates mandatory locking, and is not cleared by a
107 .BR chown ().
108 .P
109 When the owner or group of an executable file is changed (by any user),
110 all capability sets for the file are cleared.
111 .\"
112 .SS fchownat()
113 The
114 .BR fchownat ()
115 system call operates in exactly the same way as
116 .BR chown (),
117 except for the differences described here.
118 .P
119 If
120 .I path
121 is relative, then it is interpreted relative to the directory
122 referred to by the file descriptor
123 .I dirfd
124 (rather than relative to the current working directory of
125 the calling process, as is done by
126 .BR chown ()
127 for a relative pathname).
128 .P
129 If
130 .I path
131 is relative and
132 .I dirfd
133 is the special value
134 .BR AT_FDCWD ,
135 then
136 .I path
137 is interpreted relative to the current working
138 directory of the calling process (like
139 .BR chown ()).
140 .P
141 If
142 .I path
143 is absolute, then
144 .I dirfd
145 is ignored.
146 .P
147 The
148 .I flags
149 argument is a bit mask created by ORing together
150 0 or more of the following values;
151 .TP
152 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
153 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
154 If
155 .I path
156 is an empty string, operate on the file referred to by
157 .I dirfd
158 (which may have been obtained using the
159 .BR open (2)
160 .B O_PATH
161 flag).
162 In this case,
163 .I dirfd
164 can refer to any type of file, not just a directory.
165 If
166 .I dirfd
167 is
168 .BR AT_FDCWD ,
169 the call operates on the current working directory.
170 This flag is Linux-specific;
171 define
172 .B _GNU_SOURCE
173 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
174 to obtain its definition.
175 .TP
176 .B AT_SYMLINK_NOFOLLOW
177 If
178 .I path
179 is a symbolic link, do not dereference it:
180 instead operate on the link itself, like
181 .BR lchown ().
182 (By default,
183 .BR fchownat ()
184 dereferences symbolic links, like
185 .BR chown ().)
186 .P
187 See
188 .BR openat (2)
189 for an explanation of the need for
190 .BR fchownat ().
191 .SH RETURN VALUE
192 On success, zero is returned.
193 On error, \-1 is returned, and
194 .I errno
195 is set to indicate the error.
196 .SH ERRORS
197 Depending on the filesystem,
198 errors other than those listed below can be returned.
199 .P
200 The more general errors for
201 .BR chown ()
202 are listed below.
203 .TP
204 .B EACCES
205 Search permission is denied on a component of the path prefix.
206 (See also
207 .BR path_resolution (7).)
208 .TP
209 .B EBADF
210 .RB ( fchown ())
211 .I fd
212 is not a valid open file descriptor.
213 .TP
214 .B EBADF
215 .RB ( fchownat ())
216 .I path
217 is relative but
218 .I dirfd
219 is neither
220 .B AT_FDCWD
221 nor a valid file descriptor.
222 .TP
223 .B EFAULT
224 .I path
225 points outside your accessible address space.
226 .TP
227 .B EINVAL
228 .RB ( fchownat ())
229 Invalid flag specified in
230 .IR flags .
231 .TP
232 .B EIO
233 .RB ( fchown ())
234 A low-level I/O error occurred while modifying the inode.
235 .TP
236 .B ELOOP
237 Too many symbolic links were encountered in resolving
238 .IR path .
239 .TP
240 .B ENAMETOOLONG
241 .I path
242 is too long.
243 .TP
244 .B ENOENT
245 The file does not exist.
246 .TP
247 .B ENOMEM
248 Insufficient kernel memory was available.
249 .TP
250 .B ENOTDIR
251 A component of the path prefix is not a directory.
252 .TP
253 .B ENOTDIR
254 .RB ( fchownat ())
255 .I path
256 is relative and
257 .I dirfd
258 is a file descriptor referring to a file other than a directory.
259 .TP
260 .B EPERM
261 The calling process did not have the required permissions
262 (see above) to change owner and/or group.
263 .TP
264 .B EPERM
265 The file is marked immutable or append-only.
266 (See
267 .BR FS_IOC_SETFLAGS (2const).)
268 .TP
269 .B EROFS
270 The named file resides on a read-only filesystem.
271 .SH VERSIONS
272 The 4.4BSD version can be
273 used only by the superuser (that is, ordinary users cannot give away files).
274 .\" chown():
275 .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
276 .\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions.
277 .\" fchown():
278 .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
279 .\" error conditions.
280 .SH STANDARDS
281 POSIX.1-2024.
282 .SH HISTORY
283 .TP
284 .BR chown ()
285 SVr4,
286 POSIX.1-1988,
287 4.4BSD.
288 .TP
289 .BR fchown ()
290 SVr4,
291 4.4BSD,
292 SUSv1,
293 POSIX.1-2001.
294 .TP
295 .BR lchown ()
296 SVr4,
297 4.4BSD,
298 SUSv1,
299 POSIX.1-2001 XSI,
300 POSIX.1-2008.
301 .TP
302 .BR fchownat ()
303 POSIX.1-2008.
304 Linux 2.6.16,
305 glibc 2.4.
306 .SH NOTES
307 .SS Ownership of new files
308 When a new file is created (by, for example,
309 .BR open (2)
310 or
311 .BR mkdir (2)),
312 its owner is made the same as the filesystem user ID of the
313 creating process.
314 The group of the file depends on a range of factors,
315 including the type of filesystem,
316 the options used to mount the filesystem,
317 and whether or not the set-group-ID mode bit is enabled
318 on the parent directory.
319 If the filesystem supports the
320 .B "\-o\ grpid"
321 (or, synonymously
322 .BR "\-o\ bsdgroups" )
323 and
324 .B "\-o\ nogrpid"
325 (or, synonymously
326 .BR "\-o\ sysvgroups" )
327 .BR mount (8)
328 options, then the rules are as follows:
329 .IP \[bu] 3
330 If the filesystem is mounted with
331 .BR "\-o\ grpid" ,
332 then the group of a new file is made
333 the same as that of the parent directory.
334 .IP \[bu]
335 If the filesystem is mounted with
336 .B \-o\ nogrpid
337 and the set-group-ID bit is disabled on the parent directory,
338 then the group of a new file is made the same as the
339 process's filesystem GID.
340 .IP \[bu]
341 If the filesystem is mounted with
342 .B \-o\ nogrpid
343 and the set-group-ID bit is enabled on the parent directory,
344 then the group of a new file is made
345 the same as that of the parent directory.
346 .P
347 As at Linux 4.12,
348 the
349 .B \-o\ grpid
350 and
351 .B \-o\ nogrpid
352 mount options are supported by ext2, ext3, ext4, and XFS.
353 Filesystems that don't support these mount options follow the
354 .B \-o\ nogrpid
355 rules.
356 .SS glibc notes
357 On older kernels where
358 .BR fchownat ()
359 is unavailable, the glibc wrapper function falls back to the use of
360 .BR chown ()
361 and
362 .BR lchown ().
363 When
364 .I path
365 is relative,
366 glibc constructs a pathname based on the symbolic link in
367 .I /proc/self/fd
368 that corresponds to the
369 .I dirfd
370 argument.
371 .SS NFS
372 The
373 .BR chown ()
374 semantics are deliberately violated on NFS filesystems
375 which have UID mapping enabled.
376 Additionally, the semantics of all system
377 calls which access the file contents are violated, because
378 .BR chown ()
379 may cause immediate access revocation on already open files.
380 Client side
381 caching may lead to a delay between the time where ownership have
382 been changed to allow access for a user and the time where the file can
383 actually be accessed by the user on other clients.
384 .SS Historical details
385 The original Linux
386 .BR chown (),
387 .BR fchown (),
388 and
389 .BR lchown ()
390 system calls supported only 16-bit user and group IDs.
391 Subsequently, Linux 2.4 added
392 .BR chown32 (),
393 .BR fchown32 (),
394 and
395 .BR lchown32 (),
396 supporting 32-bit IDs.
397 The glibc
398 .BR chown (),
399 .BR fchown (),
400 and
401 .BR lchown ()
402 wrapper functions transparently deal with the variations across kernel versions.
403 .P
404 Before Linux 2.1.81 (except 2.1.46),
405 .BR chown ()
406 did not follow symbolic links.
407 Since Linux 2.1.81,
408 .BR chown ()
409 does follow symbolic links, and there is a new system call
410 .BR lchown ()
411 that does not follow symbolic links.
412 Since Linux 2.1.86, this new call (that has the same semantics
413 as the old
414 .BR chown ())
415 has got the same syscall number, and
416 .BR chown ()
417 got the newly introduced number.
418 .SH EXAMPLES
419 The following program changes the ownership of the file named in
420 its second command-line argument to the value specified in its
421 first command-line argument.
422 The new owner can be specified either as a numeric user ID,
423 or as a username (which is converted to a user ID by using
424 .BR getpwnam (3)
425 to perform a lookup in the system password file).
426 .SS Program source
427 .\" SRC BEGIN (chown.c)
428 .EX
429 #include <pwd.h>
430 #include <stdio.h>
431 #include <stdlib.h>
432 #include <sys/types.h>
433 #include <unistd.h>
434 \&
435 int
436 main(int argc, char *argv[])
437 {
438 char *endptr;
439 uid_t uid;
440 struct passwd *pwd;
441 \&
442 if (argc != 3 || argv[1][0] == \[aq]\[rs]0\[aq]) {
443 fprintf(stderr, "%s <owner> <file>\[rs]n", argv[0]);
444 exit(EXIT_FAILURE);
445 }
446 \&
447 uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */
448 \&
449 if (*endptr != \[aq]\[rs]0\[aq]) { /* Was not pure numeric string */
450 pwd = getpwnam(argv[1]); /* Try getting UID for username */
451 if (pwd == NULL) {
452 perror("getpwnam");
453 exit(EXIT_FAILURE);
454 }
455 \&
456 uid = pwd\->pw_uid;
457 }
458 \&
459 if (chown(argv[2], uid, \-1) == \-1) {
460 perror("chown");
461 exit(EXIT_FAILURE);
462 }
463 \&
464 exit(EXIT_SUCCESS);
465 }
466 .EE
467 .\" SRC END
468 .SH SEE ALSO
469 .BR chgrp (1),
470 .BR chown (1),
471 .BR chmod (2),
472 .BR flock (2),
473 .BR path_resolution (7),
474 .BR symlink (7)