man2/chown.2

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