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