manual/LDP_man-pages/original/man2/chown.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   4 .\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl)
   5 .\" and Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   6 .\"
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  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 2008-06-16 "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 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
  58 .SH DESCRIPTION
  59 These system calls change the owner and group of a file.
  60 The differ only in how the file is specified:
  61 .IP * 2
  62 .BR chown ()
  63 changes the ownership of the file specified by
  64 .IR path ,
  65 which is dereferenced if it is a symbolic link.
  66 .IP *
  67 .BR fchown ()
  68 changes the ownership of the file referred to by the open file descriptor
  69 .IR fd .
  70 .IP *
  71 .BR lchown ()
  72 is like
  73 .BR chown (),
  74 but does not dereference symbolic links.
  75 .PP
  76 Only a privileged process (Linux: one with the
  77 .B CAP_CHOWN
  78 capability) may change the owner of a file.
  79 The owner of a file may change the group of the file
  80 to any group of which that owner is a member.
  81 A privileged process (Linux: with
  82 .BR CAP_CHOWN )
  83 may change the group arbitrarily.
  84
  85 If the
  86 .I owner
  87 or
  88 .I group
  89 is specified as \-1, then that ID is not changed.
  90
  91 When the owner or group of an executable file are
  92 changed by an unprivileged user the
  93 .B S_ISUID
  94 and
  95 .B S_ISGID
  96 mode bits are cleared.
  97 POSIX does not specify whether
  98 this also should happen when root does the
  99 .BR chown ();
 100 the Linux behavior depends on the kernel version.
 101 .\" In Linux 2.0 kernels, superuser was like everyone else
 102 .\" In 2.2, up to 2.2.12, these bits were not cleared for superuser.
 103 .\" Since 2.2.13, superuser is once more like everyone else.
 104 In case of a non-group-executable file (i.e., one for which the
 105 .B S_IXGRP
 106 bit is not set) the
 107 .B S_ISGID
 108 bit indicates mandatory locking, and is not cleared by a
 109 .BR chown ().
 110 .SH "RETURN VALUE"
 111 On success, zero is returned.
 112 On error, \-1 is returned, and
 113 .I errno
 114 is set appropriately.
 115 .SH ERRORS
 116 Depending on the file system, other errors can be returned.
 117 The more general errors for
 118 .BR chown ()
 119 are listed below.
 120 .TP
 121 .B EACCES
 122 Search permission is denied on a component of the path prefix.
 123 (See also
 124 .BR path_resolution (7).)
 125 .TP
 126 .B EFAULT
 127 .I path
 128 points outside your accessible address space.
 129 .TP
 130 .B ELOOP
 131 Too many symbolic links were encountered in resolving
 132 .IR path .
 133 .TP
 134 .B ENAMETOOLONG
 135 .I path
 136 is too long.
 137 .TP
 138 .B ENOENT
 139 The file does not exist.
 140 .TP
 141 .B ENOMEM
 142 Insufficient kernel memory was available.
 143 .TP
 144 .B ENOTDIR
 145 A component of the path prefix is not a directory.
 146 .TP
 147 .B EPERM
 148 The calling process did not have the required permissions
 149 (see above) to change owner and/or group.
 150 .TP
 151 .B EROFS
 152 The named file resides on a read-only file system.
 153 .PP
 154 The general errors for
 155 .BR fchown ()
 156 are listed below:
 157 .TP
 158 .B EBADF
 159 The descriptor is not valid.
 160 .TP
 161 .B EIO
 162 A low-level I/O error occurred while modifying the inode.
 163 .TP
 164 .B ENOENT
 165 See above.
 166 .TP
 167 .B EPERM
 168 See above.
 169 .TP
 170 .B EROFS
 171 See above.
 172 .SH "CONFORMING TO"
 173 4.4BSD, SVr4, POSIX.1-2001.
 174
 175 The 4.4BSD version can only be
 176 used by the superuser (that is, ordinary users cannot give away files).
 177 .\" chown():
 178 .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
 179 .\" ENOMEM.  POSIX.1 does not document ENOMEM or ELOOP error conditions.
 180 .\" fchown():
 181 .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
 182 .\" error conditions.
 183 .SH NOTES
 184 When a new file is created (by, for example,
 185 .BR open (2)
 186 or
 187 .BR mkdir (2)),
 188 its owner is made the same as the file system user ID of the
 189 creating process.
 190 The group of the file depends on a range of factors,
 191 including the type of file system,
 192 the options used to mount the file system,
 193 and whether or not the set-group-ID permission bit is enabled
 194 on the parent directory.
 195 If the file system supports the
 196 .I "\-o\ grpid"
 197 (or, synonymously
 198 .IR "\-o\ bsdgroups" )
 199 and
 200 .I "\-o\ nogrpid"
 201 (or, synonymously
 202 .IR "\-o\ sysvgroups" )
 203 .BR mount (8)
 204 options, then the rules are as follows:
 205 .IP * 2
 206 If the file system is mounted with
 207 .IR "\-o\ grpid" ,
 208 then the group of a new file is made
 209 the same as that of the parent directory.
 210 .IP *
 211 If the file system is mounted with
 212 .IR "\-o\ nogrpid"
 213 and the set-group-ID bit is disabled on the parent directory,
 214 then the group of a new file is made the same as the
 215 process's file system GID.
 216 .IP *
 217 If the file system is mounted with
 218 .IR "\-o\ nogrpid"
 219 and the set-group-ID bit is enabled on the parent directory,
 220 then the group of a new file is made
 221 the same as that of the parent directory.
 222 .PP
 223 As at Linux 2.6.25,
 224 the
 225 .IR "\-o\ grpid"
 226 and
 227 .IR "\-o\ nogrpid"
 228 mount options are supported by ext2, ext3, ext4, and XFS.
 229 File systems that don't support these mount options follow the
 230 .IR "\-o\ nogrpid"
 231 rules.
 232 .PP
 233 The
 234 .BR chown ()
 235 semantics are deliberately violated on NFS file systems
 236 which have UID mapping enabled.
 237 Additionally, the semantics of all system
 238 calls which access the file contents are violated, because
 239 .BR chown ()
 240 may cause immediate access revocation on already open files.
 241 Client side
 242 caching may lead to a delay between the time where ownership have
 243 been changed to allow access for a user and the time where the file can
 244 actually be accessed by the user on other clients.
 245
 246 In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
 247 .BR chown ()
 248 did not follow symbolic links.
 249 Since Linux 2.1.81,
 250 .BR chown ()
 251 does follow symbolic links, and there is a new system call
 252 .BR lchown ()
 253 that does not follow symbolic links.
 254 Since Linux 2.1.86, this new call (that has the same semantics
 255 as the old
 256 .BR chown ())
 257 has got the same syscall number, and
 258 .BR chown ()
 259 got the newly introduced number.
 260 .SH EXAMPLE
 261 .PP
 262 The following program changes the ownership of the file named in
 263 its second command-line argument to the value specified in its
 264 first command-line argument.
 265 The new owner can be specified either as a numeric user ID,
 266 or as a username (which is converted to a user ID by using
 267 .BR getpwnam (3)
 268 to perform a lookup in the system password file).
 269 .nf
 270
 271 #include <pwd.h>
 272 #include <stdio.h>
 273 #include <stdlib.h>
 274 #include <unistd.h>
 275
 276 int
 277 main(int argc, char *argv[])
 278 {
 279     uid_t uid;
 280     struct passwd *pwd;
 281     char *endptr;
 282
 283     if (argc != 3 || argv[1][0] == \(aq\\0\(aq) {
 284         fprintf(stderr, "%s <owner> <file>\\n", argv[0]);
 285         exit(EXIT_FAILURE);
 286     }
 287
 288     uid = strtol(argv[1], &endptr, 10);  /* Allow a numeric string */
 289
 290     if (*endptr != \(aq\\0\(aq) {         /* Was not pure numeric string */
 291         pwd = getpwnam(argv[1]);   /* Try getting UID for username */
 292         if (pwd == NULL) {
 293             perror("getpwnam");
 294             exit(EXIT_FAILURE);
 295         }
 296
 297         uid = pwd\->pw_uid;
 298     }
 299
 300     if (chown(argv[2], uid, \-1) == \-1) {
 301         perror("chown");
 302         exit(EXIT_FAILURE);
 303     } /* if */
 304
 305     exit(EXIT_SUCCESS);
 306 } /* main */
 307 .fi
 308 .SH "SEE ALSO"
 309 .BR chmod (2),
 310 .BR fchownat (2),
 311 .BR flock (2),
 312 .BR path_resolution (7),
 313 .BR symlink (7)