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 .\" 3. 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 30, 2020
  32 .Dt CHFLAGS 2
  33 .Os
  34 .Sh NAME
  35 .Nm chflags ,
  36 .Nm lchflags ,
  37 .Nm fchflags ,
  38 .Nm chflagsat
  39 .Nd set file flags
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/stat.h
  44 .In unistd.h
  45 .Ft int
  46 .Fn chflags "const char *path" "unsigned long flags"
  47 .Ft int
  48 .Fn lchflags "const char *path" "unsigned long flags"
  49 .Ft int
  50 .Fn fchflags "int fd" "unsigned long flags"
  51 .Ft int
  52 .Fn chflagsat "int fd" "const char *path" "unsigned long flags" "int atflag"
  53 .Sh DESCRIPTION
  54 The file whose name
  55 is given by
  56 .Fa path
  57 or referenced by the descriptor
  58 .Fa fd
  59 has its flags changed to
  60 .Fa flags .
  61 .Pp
  62 The
  63 .Fn lchflags
  64 system call is like
  65 .Fn chflags
  66 except in the case where the named file is a symbolic link,
  67 in which case
  68 .Fn lchflags
  69 will change the flags of the link itself,
  70 rather than the file it points to.
  71 .Pp
  72 The
  73 .Fn chflagsat
  74 is equivalent to either
  75 .Fn chflags
  76 or
  77 .Fn lchflags
  78 depending on the
  79 .Fa atflag
  80 except in the case where
  81 .Fa path
  82 specifies a relative path.
  83 In this case the file to be changed is determined relative to the directory
  84 associated with the file descriptor
  85 .Fa fd
  86 instead of the current working directory.
  87 The values for the
  88 .Fa atflag
  89 are constructed by a bitwise-inclusive OR of flags from the following list,
  90 defined in
  91 .In fcntl.h :
  92 .Bl -tag -width indent
  93 .It Dv AT_SYMLINK_NOFOLLOW
  94 If
  95 .Fa path
  96 names a symbolic link, then the flags of the symbolic link are changed.
  97 .It Dv AT_BENEATH
  98 Only allow to change flags for a file which is beneath of
  99 the topping directory.
 100 See the description of the
 101 .Dv O_BENEATH
 102 flag in the
 103 .Xr open 2
 104 manual page.
 105 .El
 106 .Pp
 107 If
 108 .Fn chflagsat
 109 is passed the special value
 110 .Dv AT_FDCWD
 111 in the
 112 .Fa fd
 113 parameter, the current working directory is used.
 114 If also
 115 .Fa atflag
 116 is zero, the behavior is identical to a call to
 117 .Fn chflags .
 118 .Pp
 119 The flags specified are formed by
 120 .Em or Ns 'ing
 121 the following values
 122 .Pp
 123 .Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent
 124 .It Dv SF_APPEND
 125 The file may only be appended to.
 126 .It Dv SF_ARCHIVED
 127 The file has been archived.
 128 This flag means the opposite of the DOS, Windows and CIFS
 129 FILE_ATTRIBUTE_ARCHIVE attribute.
 130 This flag has been deprecated, and may be removed in a future release.
 131 .It Dv SF_IMMUTABLE
 132 The file may not be changed.
 133 .It Dv SF_NOUNLINK
 134 The file may not be renamed or deleted.
 135 .It Dv SF_SNAPSHOT
 136 The file is a snapshot file.
 137 .It Dv UF_APPEND
 138 The file may only be appended to.
 139 .It Dv UF_ARCHIVE
 140 The file needs to be archived.
 141 This flag has the same meaning as the DOS, Windows and CIFS
 142 FILE_ATTRIBUTE_ARCHIVE attribute.
 143 Filesystems in FreeBSD may or may not have special handling for this flag.
 144 For instance, ZFS tracks changes to files and will set this bit when a
 145 file is updated.
 146 UFS only stores the flag, and relies on the application to change it when
 147 needed.
 148 .It Dv UF_HIDDEN
 149 The file may be hidden from directory listings at the application's
 150 discretion.
 151 The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_HIDDEN attribute.
 152 .It Dv UF_IMMUTABLE
 153 The file may not be changed.
 154 .It Dv UF_NODUMP
 155 Do not dump the file.
 156 .It Dv UF_NOUNLINK
 157 The file may not be renamed or deleted.
 158 .It Dv UF_OFFLINE
 159 The file is offline, or has the Windows and CIFS FILE_ATTRIBUTE_OFFLINE
 160 attribute.
 161 Filesystems in FreeBSD store and display this flag, but do not provide any
 162 special handling when it is set.
 163 .It Dv UF_OPAQUE
 164 The directory is opaque when viewed through a union stack.
 165 .It Dv UF_READONLY
 166 The file is read only, and may not be written or appended.
 167 Filesystems may use this flag to maintain compatibility with the DOS, Windows
 168 and CIFS FILE_ATTRIBUTE_READONLY attribute.
 169 .It Dv UF_REPARSE
 170 The file contains a Windows reparse point and has the Windows and CIFS
 171 FILE_ATTRIBUTE_REPARSE_POINT attribute.
 172 .It Dv UF_SPARSE
 173 The file has the Windows FILE_ATTRIBUTE_SPARSE_FILE attribute.
 174 This may also be used by a filesystem to indicate a sparse file.
 175 .It Dv UF_SYSTEM
 176 The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_SYSTEM attribute.
 177 Filesystems in FreeBSD may store and display this flag, but do not provide
 178 any special handling when it is set.
 179 .El
 180 .Pp
 181 If one of
 182 .Dv SF_IMMUTABLE , SF_APPEND ,
 183 or
 184 .Dv SF_NOUNLINK
 185 is set a non-super-user cannot change any flags and even the super-user
 186 can change flags only if securelevel is 0.
 187 (See
 188 .Xr init 8
 189 for details.)
 190 .Pp
 191 The
 192 .Dv UF_IMMUTABLE , UF_APPEND , UF_NOUNLINK , UF_NODUMP ,
 193 and
 194 .Dv UF_OPAQUE
 195 flags may be set or unset by either the owner of a file or the super-user.
 196 .Pp
 197 The
 198 .Dv SF_IMMUTABLE , SF_APPEND , SF_NOUNLINK ,
 199 and
 200 .Dv SF_ARCHIVED
 201 flags may only be set or unset by the super-user.
 202 Attempts to toggle these flags by non-super-users are rejected.
 203 These flags may be set at any time, but normally may only be unset when
 204 the system is in single-user mode.
 205 (See
 206 .Xr init 8
 207 for details.)
 208 .Pp
 209 The implementation of all flags is filesystem-dependent.
 210 See the description of the
 211 .Dv UF_ARCHIVE
 212 flag above for one example of the differences in behavior.
 213 Care should be exercised when writing applications to account for
 214 support or lack of support of these flags in various filesystems.
 215 .Pp
 216 The
 217 .Dv SF_SNAPSHOT
 218 flag is maintained by the system and cannot be toggled.
 219 .Sh RETURN VALUES
 220 .Rv -std
 221 .Sh ERRORS
 222 The
 223 .Fn chflags
 224 system call will fail if:
 225 .Bl -tag -width Er
 226 .It Bq Er ENOTDIR
 227 A component of the path prefix is not a directory.
 228 .It Bq Er ENAMETOOLONG
 229 A component of a pathname exceeded 255 characters,
 230 or an entire path name exceeded 1023 characters.
 231 .It Bq Er ENOENT
 232 The named file does not exist.
 233 .It Bq Er EACCES
 234 Search permission is denied for a component of the path prefix.
 235 .It Bq Er ELOOP
 236 Too many symbolic links were encountered in translating the pathname.
 237 .It Bq Er EPERM
 238 The effective user ID does not match the owner of the file and
 239 the effective user ID is not the super-user.
 240 .It Bq Er EPERM
 241 One of
 242 .Dv SF_IMMUTABLE , SF_APPEND ,
 243 or
 244 .Dv SF_NOUNLINK
 245 is set and the user is either not the super-user or
 246 securelevel is greater than 0.
 247 .It Bq Er EPERM
 248 A non-super-user attempted to toggle one of
 249 .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND ,
 250 or
 251 .Dv SF_NOUNLINK .
 252 .It Bq Er EPERM
 253 An attempt was made to toggle the
 254 .Dv SF_SNAPSHOT
 255 flag.
 256 .It Bq Er EROFS
 257 The named file resides on a read-only file system.
 258 .It Bq Er EFAULT
 259 The
 260 .Fa path
 261 argument
 262 points outside the process's allocated address space.
 263 .It Bq Er EIO
 264 An
 265 .Tn I/O
 266 error occurred while reading from or writing to the file system.
 267 .It Bq Er EINTEGRITY
 268 Corrupted data was detected while reading from the file system.
 269 .It Bq Er EOPNOTSUPP
 270 The underlying file system does not support file flags, or
 271 does not support all of the flags set in
 272 .Fa flags .
 273 .El
 274 .Pp
 275 The
 276 .Fn fchflags
 277 system call will fail if:
 278 .Bl -tag -width Er
 279 .It Bq Er EBADF
 280 The descriptor is not valid.
 281 .It Bq Er EINVAL
 282 The
 283 .Fa fd
 284 argument
 285 refers to a socket, not to a file.
 286 .It Bq Er EPERM
 287 The effective user ID does not match the owner of the file and
 288 the effective user ID is not the super-user.
 289 .It Bq Er EPERM
 290 One of
 291 .Dv SF_IMMUTABLE , SF_APPEND ,
 292 or
 293 .Dv SF_NOUNLINK
 294 is set and the user is either not the super-user or
 295 securelevel is greater than 0.
 296 .It Bq Er EPERM
 297 A non-super-user attempted to toggle one of
 298 .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND ,
 299 or
 300 .Dv SF_NOUNLINK .
 301 .It Bq Er EPERM
 302 An attempt was made to toggle the
 303 .Dv SF_SNAPSHOT
 304 flag.
 305 .It Bq Er EROFS
 306 The file resides on a read-only file system.
 307 .It Bq Er EIO
 308 An
 309 .Tn I/O
 310 error occurred while reading from or writing to the file system.
 311 .It Bq Er EINTEGRITY
 312 Corrupted data was detected while reading from the file system.
 313 .It Bq Er EOPNOTSUPP
 314 The underlying file system does not support file flags, or
 315 does not support all of the flags set in
 316 .Fa flags .
 317 .It Bq Er ENOTCAPABLE
 318 .Fa path
 319 is an absolute path,
 320 or contained a ".." component leading to a
 321 directory outside of the directory hierarchy specified by
 322 .Fa fd ,
 323 and the process is in capability mode.
 324 .It Bq Er ENOTCAPABLE
 325 The
 326 .Dv AT_BENEATH
 327 flag was provided to
 328 .Fn chflagsat ,
 329 and the absolute
 330 .Fa path
 331 does not have its tail fully contained under the topping directory,
 332 or the relative
 333 .Fa path
 334 escapes it.
 335 .El
 336 .Sh SEE ALSO
 337 .Xr chflags 1 ,
 338 .Xr fflagstostr 3 ,
 339 .Xr strtofflags 3 ,
 340 .Xr init 8 ,
 341 .Xr mount_unionfs 8
 342 .Sh HISTORY
 343 The
 344 .Fn chflags
 345 and
 346 .Fn fchflags
 347 system calls first appeared in
 348 .Bx 4.4 .
 349 The
 350 .Fn lchflags
 351 system call first appeared in
 352 .Fx 5.0 .
 353 The
 354 .Fn chflagsat
 355 system call first appeared in
 356 .Fx 10.0 .