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