lib/libc/sys/chflags.2

   1 .\" Copyright (c) 1989, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)chflags.2   8.3 (Berkeley) 5/2/95
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 22, 2013
  32 .Dt CHFLAGS 2
  33 .Os
  34 .Sh NAME
  35 .Nm chflags ,
  36 .Nm lchflags ,
  37 .Nm fchflags
  38 .Nd set file flags
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/stat.h
  43 .In unistd.h
  44 .Ft int
  45 .Fn chflags "const char *path" "unsigned long flags"
  46 .Ft int
  47 .Fn lchflags "const char *path" "unsigned long flags"
  48 .Ft int
  49 .Fn fchflags "int fd" "unsigned long flags"
  50 .Ft int
  51 .Fn chflagsat "int fd" "const char *path" "unsigned long flags" "int atflag"
  52 .Sh DESCRIPTION
  53 The file whose name
  54 is given by
  55 .Fa path
  56 or referenced by the descriptor
  57 .Fa fd
  58 has its flags changed to
  59 .Fa flags .
  60 .Pp
  61 The
  62 .Fn lchflags
  63 system call is like
  64 .Fn chflags
  65 except in the case where the named file is a symbolic link,
  66 in which case
  67 .Fn lchflags
  68 will change the flags of the link itself,
  69 rather than the file it points to.
  70 .Pp
  71 The
  72 .Fn chflagsat
  73 is equivalent to either
  74 .Fn chflags
  75 or
  76 .Fn lchflags
  77 depending on the
  78 .Fa atflag
  79 except in the case where
  80 .Fa path
  81 specifies a relative path.
  82 In this case the file to be changed is determined relative to the directory
  83 associated with the file descriptor
  84 .Fa fd
  85 instead of the current working directory.
  86 The values for the
  87 .Fa atflag
  88 are constructed by a bitwise-inclusive OR of flags from the following list,
  89 defined in
  90 .In fcntl.h :
  91 .Bl -tag -width indent
  92 .It Dv AT_SYMLINK_NOFOLLOW
  93 If
  94 .Fa path
  95 names a symbolic link, then the flags of the symbolic link are changed.
  96 .El
  97 .Pp
  98 If
  99 .Fn chflagsat
 100 is passed the special value
 101 .Dv AT_FDCWD
 102 in the
 103 .Fa fd
 104 parameter, the current working directory is used.
 105 If also
 106 .Fa atflag
 107 is zero, the behavior is identical to a call to
 108 .Fn chflags .
 109 .Pp
 110 The flags specified are formed by
 111 .Em or Ns 'ing
 112 the following values
 113 .Pp
 114 .Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent
 115 .It Dv SF_APPEND
 116 The file may only be appended to.
 117 .It Dv SF_ARCHIVED
 118 The file has been archived.
 119 This flag means the opposite of the DOS, Windows and CIFS
 120 FILE_ATTRIBUTE_ARCHIVE attribute.
 121 This flag has been deprecated, and may be removed in a future release.
 122 .It Dv SF_IMMUTABLE
 123 The file may not be changed.
 124 .It Dv SF_NOUNLINK
 125 The file may not be renamed or deleted.
 126 .It Dv SF_SNAPSHOT
 127 The file is a snapshot file.
 128 .It Dv UF_APPEND
 129 The file may only be appended to.
 130 .It Dv UF_ARCHIVE
 131 The file needs to be archived.
 132 This flag has the same meaning as the DOS, Windows and CIFS
 133 FILE_ATTRIBUTE_ARCHIVE attribute.
 134 Filesystems in FreeBSD may or may not have special handling for this flag.
 135 For instance, ZFS tracks changes to files and will set this bit when a
 136 file is updated.
 137 UFS only stores the flag, and relies on the application to change it when
 138 needed.
 139 .It Dv UF_HIDDEN
 140 The file may be hidden from directory listings at the application's
 141 discretion.
 142 The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_HIDDEN attribute.
 143 .It Dv UF_IMMUTABLE
 144 The file may not be changed.
 145 .It Dv UF_NODUMP
 146 Do not dump the file.
 147 .It Dv UF_NOUNLINK
 148 The file may not be renamed or deleted.
 149 .It Dv UF_OFFLINE
 150 The file is offline, or has the Windows and CIFS FILE_ATTRIBUTE_OFFLINE
 151 attribute.
 152 Filesystems in FreeBSD store and display this flag, but do not provide any
 153 special handling when it is set.
 154 .It Dv UF_OPAQUE
 155 The directory is opaque when viewed through a union stack.
 156 .It Dv UF_READONLY
 157 The file is read only, and may not be written or appended.
 158 Filesystems may use this flag to maintain compatibility with the DOS, Windows
 159 and CIFS FILE_ATTRIBUTE_READONLY attribute.
 160 .It Dv UF_REPARSE
 161 The file contains a Windows reparse point and has the Windows and CIFS
 162 FILE_ATTRIBUTE_REPARSE_POINT attribute.
 163 .It Dv UF_SPARSE
 164 The file has the Windows FILE_ATTRIBUTE_SPARSE_FILE attribute.
 165 This may also be used by a filesystem to indicate a sparse file.
 166 .It Dv UF_SYSTEM
 167 The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_SYSTEM attribute.
 168 Filesystems in FreeBSD may store and display this flag, but do not provide
 169 any special handling when it is set.
 170 .El
 171 .Pp
 172 If one of
 173 .Dv SF_IMMUTABLE , SF_APPEND ,
 174 or
 175 .Dv SF_NOUNLINK
 176 is set a non-super-user cannot change any flags and even the super-user
 177 can change flags only if securelevel is 0.
 178 (See
 179 .Xr init 8
 180 for details.)
 181 .Pp
 182 The
 183 .Dv UF_IMMUTABLE , UF_APPEND , UF_NOUNLINK , UF_NODUMP ,
 184 and
 185 .Dv UF_OPAQUE
 186 flags may be set or unset by either the owner of a file or the super-user.
 187 .Pp
 188 The
 189 .Dv SF_IMMUTABLE , SF_APPEND , SF_NOUNLINK ,
 190 and
 191 .Dv SF_ARCHIVED
 192 flags may only be set or unset by the super-user.
 193 Attempts to toggle these flags by non-super-users are rejected.
 194 These flags may be set at any time, but normally may only be unset when
 195 the system is in single-user mode.
 196 (See
 197 .Xr init 8
 198 for details.)
 199 .Pp
 200 The implementation of all flags is filesystem-dependent.
 201 See the description of the
 202 .Dv UF_ARCHIVE
 203 flag above for one example of the differences in behavior.
 204 Care should be exercised when writing applications to account for
 205 support or lack of support of these flags in various filesystems.
 206 .Pp
 207 The
 208 .Dv SF_SNAPSHOT
 209 flag is maintained by the system and cannot be toggled.
 210 .Sh RETURN VALUES
 211 .Rv -std
 212 .Sh ERRORS
 213 The
 214 .Fn chflags
 215 system call will fail if:
 216 .Bl -tag -width Er
 217 .It Bq Er ENOTDIR
 218 A component of the path prefix is not a directory.
 219 .It Bq Er ENAMETOOLONG
 220 A component of a pathname exceeded 255 characters,
 221 or an entire path name exceeded 1023 characters.
 222 .It Bq Er ENOENT
 223 The named file does not exist.
 224 .It Bq Er EACCES
 225 Search permission is denied for a component of the path prefix.
 226 .It Bq Er ELOOP
 227 Too many symbolic links were encountered in translating the pathname.
 228 .It Bq Er EPERM
 229 The effective user ID does not match the owner of the file and
 230 the effective user ID is not the super-user.
 231 .It Bq Er EPERM
 232 One of
 233 .Dv SF_IMMUTABLE , SF_APPEND ,
 234 or
 235 .Dv SF_NOUNLINK
 236 is set and the user is either not the super-user or
 237 securelevel is greater than 0.
 238 .It Bq Er EPERM
 239 A non-super-user attempted to toggle one of
 240 .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND ,
 241 or
 242 .Dv SF_NOUNLINK .
 243 .It Bq Er EPERM
 244 An attempt was made to toggle the
 245 .Dv SF_SNAPSHOT
 246 flag.
 247 .It Bq Er EROFS
 248 The named file resides on a read-only file system.
 249 .It Bq Er EFAULT
 250 The
 251 .Fa path
 252 argument
 253 points outside the process's allocated address space.
 254 .It Bq Er EIO
 255 An
 256 .Tn I/O
 257 error occurred while reading from or writing to the file system.
 258 .It Bq Er EOPNOTSUPP
 259 The underlying file system does not support file flags, or
 260 does not support all of the flags set in
 261 .Fa flags .
 262 .El
 263 .Pp
 264 The
 265 .Fn fchflags
 266 system call will fail if:
 267 .Bl -tag -width Er
 268 .It Bq Er EBADF
 269 The descriptor is not valid.
 270 .It Bq Er EINVAL
 271 The
 272 .Fa fd
 273 argument
 274 refers to a socket, not to a file.
 275 .It Bq Er EPERM
 276 The effective user ID does not match the owner of the file and
 277 the effective user ID is not the super-user.
 278 .It Bq Er EPERM
 279 One of
 280 .Dv SF_IMMUTABLE , SF_APPEND ,
 281 or
 282 .Dv SF_NOUNLINK
 283 is set and the user is either not the super-user or
 284 securelevel is greater than 0.
 285 .It Bq Er EPERM
 286 A non-super-user attempted to toggle one of
 287 .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND ,
 288 or
 289 .Dv SF_NOUNLINK .
 290 .It Bq Er EPERM
 291 An attempt was made to toggle the
 292 .Dv SF_SNAPSHOT
 293 flag.
 294 .It Bq Er EROFS
 295 The file resides on a read-only file system.
 296 .It Bq Er EIO
 297 An
 298 .Tn I/O
 299 error occurred while reading from or writing to the file system.
 300 .It Bq Er EOPNOTSUPP
 301 The underlying file system does not support file flags, or
 302 does not support all of the flags set in
 303 .Fa flags .
 304 .El
 305 .Sh SEE ALSO
 306 .Xr chflags 1 ,
 307 .Xr fflagstostr 3 ,
 308 .Xr strtofflags 3 ,
 309 .Xr init 8 ,
 310 .Xr mount_unionfs 8
 311 .Sh HISTORY
 312 The
 313 .Fn chflags
 314 and
 315 .Fn fchflags
 316 system calls first appeared in
 317 .Bx 4.4 .
 318 The
 319 .Fn lchflags
 320 system call first appeared in
 321 .Fx 5.0 .
 322 The
 323 .Fn chflagsat
 324 system call first appeared in
 325 .Fx 10.0 .