| 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) |