lib/libc/sys/chmod.2

   1 .\"     $NetBSD: chmod.2,v 1.40 2012/03/04 11:58:31 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)chmod.2     8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd March 3, 2012
  33 .Dt CHMOD 2
  34 .Os
  35 .Sh NAME
  36 .Nm chmod ,
  37 .Nm lchmod ,
  38 .Nm fchmod
  39 .Nd change mode of file
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/stat.h
  44 .Ft int
  45 .Fn chmod "const char *path" "mode_t mode"
  46 .Ft int
  47 .Fn lchmod "const char *path" "mode_t mode"
  48 .Ft int
  49 .Fn fchmod "int fd" "mode_t mode"
  50 .Sh DESCRIPTION
  51 The function
  52 .Fn chmod
  53 sets the file permission bits
  54 of the file
  55 specified by the pathname
  56 .Fa path
  57 to
  58 .Fa mode .
  59 .Fn fchmod
  60 sets the permission bits of the specified
  61 file descriptor
  62 .Fa fd .
  63 .Fn lchmod
  64 is like
  65 .Fn chmod
  66 except in the case where the named file is a symbolic link,
  67 in which case
  68 .Fn lchmod
  69 sets the permission bits of the link,
  70 while
  71 .Fn chmod
  72 sets the bits of the file the link references.
  73 .Fn chmod
  74 verifies that the process owner (user) either owns
  75 the file specified by
  76 .Fa path
  77 (or
  78 .Fa fd ) ,
  79 or
  80 is the super-user.
  81 A mode is created from
  82 .Em or'd
  83 permission bit masks
  84 defined in
  85 .In sys/stat.h :
  86 .Bd -literal -offset indent -compact
  87 #define S_IRWXU 0000700    /* RWX mask for owner */
  88 #define S_IRUSR 0000400    /* R for owner */
  89 #define S_IWUSR 0000200    /* W for owner */
  90 #define S_IXUSR 0000100    /* X for owner */
  91
  92 #define S_IRWXG 0000070    /* RWX mask for group */
  93 #define S_IRGRP 0000040    /* R for group */
  94 #define S_IWGRP 0000020    /* W for group */
  95 #define S_IXGRP 0000010    /* X for group */
  96
  97 #define S_IRWXO 0000007    /* RWX mask for other */
  98 #define S_IROTH 0000004    /* R for other */
  99 #define S_IWOTH 0000002    /* W for other */
 100 #define S_IXOTH 0000001    /* X for other */
 101
 102 #define S_ISUID 0004000    /* set user id on execution */
 103 #define S_ISGID 0002000    /* set group id on execution */
 104 #define S_ISVTX 0001000    /* sticky bit */
 105 .Ed
 106 .Pp
 107 The mode
 108 .Dv ISVTX
 109 (the
 110 .Sq sticky bit )
 111 can be set on regular files, but has no effect.
 112 For historical reasons this can be done only by the super-user.
 113 .Pp
 114 If mode
 115 .Dv ISVTX
 116 (the
 117 .Sq sticky bit )
 118 is set on a directory,
 119 an unprivileged user may not delete or rename
 120 files of other users in that directory.
 121 The sticky bit may be set by any user on a directory which the user
 122 owns or has appropriate permissions.
 123 .Pp
 124 For more information about the history and properties of the sticky bit, see
 125 .Xr sticky 7 .
 126 .Pp
 127 Changing the owner of a file
 128 turns off the set-user-id and set-group-id bits;
 129 writing to a file
 130 turns off the set-user-id and set-group-id bits
 131 unless the user is the super-user.
 132 This makes the system somewhat more secure
 133 by protecting set-user-id (set-group-id) files
 134 from remaining set-user-id (set-group-id) if they are modified,
 135 at the expense of a degree of compatibility.
 136 .Sh RETURN VALUES
 137 Upon successful completion, a value of 0 is returned.
 138 Otherwise, a value of \-1 is returned and
 139 .Va errno
 140 is set to indicate the error.
 141 .Sh ERRORS
 142 .Fn chmod
 143 and
 144 .Fn lchmod
 145 will fail and the file mode will be unchanged if:
 146 .Bl -tag -width Er
 147 .It Bq Er EACCES
 148 Search permission is denied for a component of the path prefix.
 149 .It Bq Er EFAULT
 150 .Fa path
 151 points outside the process's allocated address space.
 152 .It Bq Er EFTYPE
 153 The effective user ID is not the super-user, the
 154 .Fa mode
 155 includes the sticky bit
 156 .Pq Dv S_ISVTX ,
 157 and
 158 .Fa path
 159 does not refer to a directory.
 160 .It Bq Er EIO
 161 An I/O error occurred while reading from or writing to the file system.
 162 .It Bq Er ELOOP
 163 Too many symbolic links were encountered in translating the pathname.
 164 .It Bq Er ENAMETOOLONG
 165 A component of a pathname exceeded
 166 .Brq Dv NAME_MAX
 167 characters, or an entire path name exceeded
 168 .Brq Dv PATH_MAX
 169 characters.
 170 .It Bq Er ENOENT
 171 The named file does not exist.
 172 .It Bq Er ENOTDIR
 173 A component of the path prefix is not a directory.
 174 .It Bq Er EPERM
 175 The effective user ID does not match the owner of the file and
 176 the effective user ID is not the super-user; or
 177 the mode includes the setgid bit
 178 .Pq Dv S_ISGID
 179 but the file's group is neither the effective group ID nor is it in the
 180 group access list.
 181 .It Bq Er EROFS
 182 The named file resides on a read-only file system.
 183 .El
 184 .Pp
 185 .Fn fchmod
 186 will fail if:
 187 .Bl -tag -width Er
 188 .It Bq Er EBADF
 189 The descriptor is not valid.
 190 .It Bq Er EFTYPE
 191 The effective user ID is not the super-user, the
 192 .Fa mode
 193 includes the sticky bit
 194 .Pq Dv S_ISVTX ,
 195 and
 196 .Fa fd
 197 does not refer to a directory.
 198 .It Bq Er EINVAL
 199 .Fa fd
 200 refers to a socket, not to a file.
 201 .It Bq Er EIO
 202 An I/O error occurred while reading from or writing to the file system.
 203 .It Bq Er EPERM
 204 The effective user ID does not match the owner of the file and
 205 the effective user ID is not the super-user; or
 206 the mode includes the setgid bit
 207 .Pq Dv S_ISGID
 208 but the file's group is neither the effective group ID nor is it in the
 209 group access list.
 210 .It Bq Er EROFS
 211 The file resides on a read-only file system.
 212 .El
 213 .Sh SEE ALSO
 214 .Xr chmod 1 ,
 215 .Xr chflags 2 ,
 216 .Xr chown 2 ,
 217 .Xr open 2 ,
 218 .Xr stat 2 ,
 219 .Xr getmode 3 ,
 220 .Xr setmode 3 ,
 221 .Xr sticky 7 ,
 222 .Xr symlink 7
 223 .Sh STANDARDS
 224 The
 225 .Fn chmod
 226 function conforms to
 227 .St -p1003.1-90 .
 228 .Sh HISTORY
 229 The
 230 .Fn fchmod
 231 function call
 232 appeared in
 233 .Bx 4.2 .
 234 The
 235 .Fn lchmod
 236 function call appeared in
 237 .Nx 1.3 .