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