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