Debian Codegraph @

upstream/debian-trixie/man2/chown.2

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