original/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) 2007, 2008 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 permission bit).
  37 .\"
  38 .TH CHOWN 2 2010-11-22 "Linux" "Linux Programmer's Manual"
  39 .SH NAME
  40 chown, fchown, lchown \- change ownership of a file
  41 .SH SYNOPSIS
  42 .B #include <unistd.h>
  43 .sp
  44 .BI "int chown(const char *" path ", uid_t " owner ", gid_t " group );
  45 .br
  46 .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
  47 .br
  48 .BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group );
  49 .sp
  50 .in -4n
  51 Feature Test Macro Requirements for glibc (see
  52 .BR feature_test_macros (7)):
  53 .in
  54 .sp
  55 .BR fchown (),
  56 .BR lchown ():
  57 .PD 0
  58 .ad l
  59 .RS 4
  60 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  61 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  62 .br
  63 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  64 .RE
  65 .ad
  66 .PD
  67 .SH DESCRIPTION
  68 These system calls change the owner and group of a file.
  69 They differ only in how the file is specified:
  70 .IP * 2
  71 .BR chown ()
  72 changes the ownership of the file specified by
  73 .IR path ,
  74 which is dereferenced if it is a symbolic link.
  75 .IP *
  76 .BR fchown ()
  77 changes the ownership of the file referred to by the open file descriptor
  78 .IR fd .
  79 .IP *
  80 .BR lchown ()
  81 is like
  82 .BR chown (),
  83 but does not dereference symbolic links.
  84 .PP
  85 Only a privileged process (Linux: one with the
  86 .B CAP_CHOWN
  87 capability) may change the owner of a file.
  88 The owner of a file may change the group of the file
  89 to any group of which that owner is a member.
  90 A privileged process (Linux: with
  91 .BR CAP_CHOWN )
  92 may change the group arbitrarily.
  93
  94 If the
  95 .I owner
  96 or
  97 .I group
  98 is specified as \-1, then that ID is not changed.
  99
 100 When the owner or group of an executable file are
 101 changed by an unprivileged user the
 102 .B S_ISUID
 103 and
 104 .B S_ISGID
 105 mode bits are cleared.
 106 POSIX does not specify whether
 107 this also should happen when root does the
 108 .BR chown ();
 109 the Linux behavior depends on the kernel version.
 110 .\" In Linux 2.0 kernels, superuser was like everyone else
 111 .\" In 2.2, up to 2.2.12, these bits were not cleared for superuser.
 112 .\" Since 2.2.13, superuser is once more like everyone else.
 113 In case of a non-group-executable file (i.e., one for which the
 114 .B S_IXGRP
 115 bit is not set) the
 116 .B S_ISGID
 117 bit indicates mandatory locking, and is not cleared by a
 118 .BR chown ().
 119 .SH RETURN VALUE
 120 On success, zero is returned.
 121 On error, \-1 is returned, and
 122 .I errno
 123 is set appropriately.
 124 .SH ERRORS
 125 Depending on the file system, other errors can be returned.
 126 The more general errors for
 127 .BR chown ()
 128 are listed below.
 129 .TP
 130 .B EACCES
 131 Search permission is denied on a component of the path prefix.
 132 (See also
 133 .BR path_resolution (7).)
 134 .TP
 135 .B EFAULT
 136 .I path
 137 points outside your accessible address space.
 138 .TP
 139 .B ELOOP
 140 Too many symbolic links were encountered in resolving
 141 .IR path .
 142 .TP
 143 .B ENAMETOOLONG
 144 .I path
 145 is too long.
 146 .TP
 147 .B ENOENT
 148 The file does not exist.
 149 .TP
 150 .B ENOMEM
 151 Insufficient kernel memory was available.
 152 .TP
 153 .B ENOTDIR
 154 A component of the path prefix is not a directory.
 155 .TP
 156 .B EPERM
 157 The calling process did not have the required permissions
 158 (see above) to change owner and/or group.
 159 .TP
 160 .B EROFS
 161 The named file resides on a read-only file system.
 162 .PP
 163 The general errors for
 164 .BR fchown ()
 165 are listed below:
 166 .TP
 167 .B EBADF
 168 The descriptor is not valid.
 169 .TP
 170 .B EIO
 171 A low-level I/O error occurred while modifying the inode.
 172 .TP
 173 .B ENOENT
 174 See above.
 175 .TP
 176 .B EPERM
 177 See above.
 178 .TP
 179 .B EROFS
 180 See above.
 181 .SH CONFORMING TO
 182 4.4BSD, SVr4, POSIX.1-2001.
 183
 184 The 4.4BSD version can be
 185 used only by the superuser (that is, ordinary users cannot give away files).
 186 .\" chown():
 187 .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
 188 .\" ENOMEM.  POSIX.1 does not document ENOMEM or ELOOP error conditions.
 189 .\" fchown():
 190 .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
 191 .\" error conditions.
 192 .SH NOTES
 193 The original Linux
 194 .BR chown (),
 195 .BR fchown (),
 196 and
 197 .BR lchown ()
 198 system calls supported only 16-bit user and group IDs.
 199 Subsequently, Linux 2.4 added
 200 .BR chown32 (),
 201 .BR fchown32 (),
 202 and
 203 .BR lchown32 (),
 204 supporting 32-bit IDs.
 205 The glibc
 206 .BR chown (),
 207 .BR fchown (),
 208 and
 209 .BR lchown ()
 210 wrapper functions transparently deal with the variations across kernel versions.
 211
 212 When a new file is created (by, for example,
 213 .BR open (2)
 214 or
 215 .BR mkdir (2)),
 216 its owner is made the same as the file system user ID of the
 217 creating process.
 218 The group of the file depends on a range of factors,
 219 including the type of file system,
 220 the options used to mount the file system,
 221 and whether or not the set-group-ID permission bit is enabled
 222 on the parent directory.
 223 If the file system supports the
 224 .I "\-o\ grpid"
 225 (or, synonymously
 226 .IR "\-o\ bsdgroups" )
 227 and
 228 .I "\-o\ nogrpid"
 229 (or, synonymously
 230 .IR "\-o\ sysvgroups" )
 231 .BR mount (8)
 232 options, then the rules are as follows:
 233 .IP * 2
 234 If the file system is mounted with
 235 .IR "\-o\ grpid" ,
 236 then the group of a new file is made
 237 the same as that of the parent directory.
 238 .IP *
 239 If the file system is mounted with
 240 .IR "\-o\ nogrpid"
 241 and the set-group-ID bit is disabled on the parent directory,
 242 then the group of a new file is made the same as the
 243 process's file system GID.
 244 .IP *
 245 If the file system is mounted with
 246 .IR "\-o\ nogrpid"
 247 and the set-group-ID bit is enabled on the parent directory,
 248 then the group of a new file is made
 249 the same as that of the parent directory.
 250 .PP
 251 As at Linux 2.6.25,
 252 the
 253 .IR "\-o\ grpid"
 254 and
 255 .IR "\-o\ nogrpid"
 256 mount options are supported by ext2, ext3, ext4, and XFS.
 257 File systems that don't support these mount options follow the
 258 .IR "\-o\ nogrpid"
 259 rules.
 260 .PP
 261 The
 262 .BR chown ()
 263 semantics are deliberately violated on NFS file systems
 264 which have UID mapping enabled.
 265 Additionally, the semantics of all system
 266 calls which access the file contents are violated, because
 267 .BR chown ()
 268 may cause immediate access revocation on already open files.
 269 Client side
 270 caching may lead to a delay between the time where ownership have
 271 been changed to allow access for a user and the time where the file can
 272 actually be accessed by the user on other clients.
 273
 274 In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
 275 .BR chown ()
 276 did not follow symbolic links.
 277 Since Linux 2.1.81,
 278 .BR chown ()
 279 does follow symbolic links, and there is a new system call
 280 .BR lchown ()
 281 that does not follow symbolic links.
 282 Since Linux 2.1.86, this new call (that has the same semantics
 283 as the old
 284 .BR chown ())
 285 has got the same syscall number, and
 286 .BR chown ()
 287 got the newly introduced number.
 288 .SH EXAMPLE
 289 .PP
 290 The following program changes the ownership of the file named in
 291 its second command-line argument to the value specified in its
 292 first command-line argument.
 293 The new owner can be specified either as a numeric user ID,
 294 or as a username (which is converted to a user ID by using
 295 .BR getpwnam (3)
 296 to perform a lookup in the system password file).
 297 .nf
 298
 299 #include <pwd.h>
 300 #include <stdio.h>
 301 #include <stdlib.h>
 302 #include <unistd.h>
 303
 304 int
 305 main(int argc, char *argv[])
 306 {
 307     uid_t uid;
 308     struct passwd *pwd;
 309     char *endptr;
 310
 311     if (argc != 3 || argv[1][0] == \(aq\\0\(aq) {
 312         fprintf(stderr, "%s <owner> <file>\\n", argv[0]);
 313         exit(EXIT_FAILURE);
 314     }
 315
 316     uid = strtol(argv[1], &endptr, 10);  /* Allow a numeric string */
 317
 318     if (*endptr != \(aq\\0\(aq) {         /* Was not pure numeric string */
 319         pwd = getpwnam(argv[1]);   /* Try getting UID for username */
 320         if (pwd == NULL) {
 321             perror("getpwnam");
 322             exit(EXIT_FAILURE);
 323         }
 324
 325         uid = pwd\->pw_uid;
 326     }
 327
 328     if (chown(argv[2], uid, \-1) == \-1) {
 329         perror("chown");
 330         exit(EXIT_FAILURE);
 331     }
 332
 333     exit(EXIT_SUCCESS);
 334 }
 335 .fi
 336 .SH SEE ALSO
 337 .BR chmod (2),
 338 .BR fchownat (2),
 339 .BR flock (2),
 340 .BR path_resolution (7),
 341 .BR symlink (7)