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 February 23, 2021
  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_RESOLVE_BENEATH
  98 Only walk paths below the directory specified by the
  99 .Ar fd
 100 descriptor.
 101 See the description of the
 102 .Dv O_RESOLVE_BENEATH
 103 flag in the
 104 .Xr open 2
 105 manual page.
 106 .El
 107 .Pp
 108 If
 109 .Fn chflagsat
 110 is passed the special value
 111 .Dv AT_FDCWD
 112 in the
 113 .Fa fd
 114 parameter, the current working directory is used.
 115 If also
 116 .Fa atflag
 117 is zero, the behavior is identical to a call to
 118 .Fn chflags .
 119 .Pp
 120 The flags specified are formed by
 121 .Em or Ns 'ing
 122 the following values
 123 .Pp
 124 .Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent
 125 .It Dv SF_APPEND
 126 The file may only be appended to.
 127 .It Dv SF_ARCHIVED
 128 The file has been archived.
 129 This flag means the opposite of the DOS, Windows and CIFS
 130 FILE_ATTRIBUTE_ARCHIVE attribute.
 131 This flag has been deprecated, and may be removed in a future release.
 132 .It Dv SF_IMMUTABLE
 133 The file may not be changed.
 134 .It Dv SF_NOUNLINK
 135 The file may not be renamed or deleted.
 136 .It Dv SF_SNAPSHOT
 137 The file is a snapshot file.
 138 .It Dv UF_APPEND
 139 The file may only be appended to.
 140 .It Dv UF_ARCHIVE
 141 The file needs to be archived.
 142 This flag has the same meaning as the DOS, Windows and CIFS
 143 FILE_ATTRIBUTE_ARCHIVE attribute.
 144 Filesystems in FreeBSD may or may not have special handling for this flag.
 145 For instance, ZFS tracks changes to files and will set this bit when a
 146 file is updated.
 147 UFS only stores the flag, and relies on the application to change it when
 148 needed.
 149 .It Dv UF_HIDDEN
 150 The file may be hidden from directory listings at the application's
 151 discretion.
 152 The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_HIDDEN attribute.
 153 .It Dv UF_IMMUTABLE
 154 The file may not be changed.
 155 .It Dv UF_NODUMP
 156 Do not dump the file.
 157 .It Dv UF_NOUNLINK
 158 The file may not be renamed or deleted.
 159 .It Dv UF_OFFLINE
 160 The file is offline, or has the Windows and CIFS FILE_ATTRIBUTE_OFFLINE
 161 attribute.
 162 Filesystems in FreeBSD store and display this flag, but do not provide any
 163 special handling when it is set.
 164 .It Dv UF_OPAQUE
 165 The directory is opaque when viewed through a union stack.
 166 .It Dv UF_READONLY
 167 The file is read only, and may not be written or appended.
 168 Filesystems may use this flag to maintain compatibility with the DOS, Windows
 169 and CIFS FILE_ATTRIBUTE_READONLY attribute.
 170 .It Dv UF_REPARSE
 171 The file contains a Windows reparse point and has the Windows and CIFS
 172 FILE_ATTRIBUTE_REPARSE_POINT attribute.
 173 .It Dv UF_SPARSE
 174 The file has the Windows FILE_ATTRIBUTE_SPARSE_FILE attribute.
 175 This may also be used by a filesystem to indicate a sparse file.
 176 .It Dv UF_SYSTEM
 177 The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_SYSTEM attribute.
 178 Filesystems in FreeBSD may store and display this flag, but do not provide
 179 any special handling when it is set.
 180 .El
 181 .Pp
 182 If one of
 183 .Dv SF_IMMUTABLE , SF_APPEND ,
 184 or
 185 .Dv SF_NOUNLINK
 186 is set a non-super-user cannot change any flags and even the super-user
 187 can change flags only if securelevel is 0.
 188 (See
 189 .Xr init 8
 190 for details.)
 191 .Pp
 192 The
 193 .Dv UF_IMMUTABLE , UF_APPEND , UF_NOUNLINK , UF_NODUMP ,
 194 and
 195 .Dv UF_OPAQUE
 196 flags may be set or unset by either the owner of a file or the super-user.
 197 .Pp
 198 The
 199 .Dv SF_IMMUTABLE , SF_APPEND , SF_NOUNLINK ,
 200 and
 201 .Dv SF_ARCHIVED
 202 flags may only be set or unset by the super-user.
 203 Attempts to toggle these flags by non-super-users are rejected.
 204 These flags may be set at any time, but normally may only be unset when
 205 the system is in single-user mode.
 206 (See
 207 .Xr init 8
 208 for details.)
 209 .Pp
 210 The implementation of all flags is filesystem-dependent.
 211 See the description of the
 212 .Dv UF_ARCHIVE
 213 flag above for one example of the differences in behavior.
 214 Care should be exercised when writing applications to account for
 215 support or lack of support of these flags in various filesystems.
 216 .Pp
 217 The
 218 .Dv SF_SNAPSHOT
 219 flag is maintained by the system and cannot be toggled.
 220 .Sh RETURN VALUES
 221 .Rv -std
 222 .Sh ERRORS
 223 The
 224 .Fn chflags
 225 system call will fail if:
 226 .Bl -tag -width Er
 227 .It Bq Er ENOTDIR
 228 A component of the path prefix is not a directory.
 229 .It Bq Er ENAMETOOLONG
 230 A component of a pathname exceeded 255 characters,
 231 or an entire path name exceeded 1023 characters.
 232 .It Bq Er ENOENT
 233 The named file does not exist.
 234 .It Bq Er EACCES
 235 Search permission is denied for a component of the path prefix.
 236 .It Bq Er ELOOP
 237 Too many symbolic links were encountered in translating the pathname.
 238 .It Bq Er EPERM
 239 The effective user ID does not match the owner of the file and
 240 the effective user ID is not the super-user.
 241 .It Bq Er EPERM
 242 One of
 243 .Dv SF_IMMUTABLE , SF_APPEND ,
 244 or
 245 .Dv SF_NOUNLINK
 246 is set and the user is either not the super-user or
 247 securelevel is greater than 0.
 248 .It Bq Er EPERM
 249 A non-super-user attempted to toggle one of
 250 .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND ,
 251 or
 252 .Dv SF_NOUNLINK .
 253 .It Bq Er EPERM
 254 An attempt was made to toggle the
 255 .Dv SF_SNAPSHOT
 256 flag.
 257 .It Bq Er EROFS
 258 The named file resides on a read-only file system.
 259 .It Bq Er EFAULT
 260 The
 261 .Fa path
 262 argument
 263 points outside the process's allocated address space.
 264 .It Bq Er EIO
 265 An
 266 .Tn I/O
 267 error occurred while reading from or writing to the file system.
 268 .It Bq Er EINTEGRITY
 269 Corrupted data was detected while reading from the file system.
 270 .It Bq Er EOPNOTSUPP
 271 The underlying file system does not support file flags, or
 272 does not support all of the flags set in
 273 .Fa flags .
 274 .El
 275 .Pp
 276 The
 277 .Fn fchflags
 278 system call will fail if:
 279 .Bl -tag -width Er
 280 .It Bq Er EBADF
 281 The descriptor is not valid.
 282 .It Bq Er EINVAL
 283 The
 284 .Fa fd
 285 argument
 286 refers to a socket, not to a file.
 287 .It Bq Er EPERM
 288 The effective user ID does not match the owner of the file and
 289 the effective user ID is not the super-user.
 290 .It Bq Er EPERM
 291 One of
 292 .Dv SF_IMMUTABLE , SF_APPEND ,
 293 or
 294 .Dv SF_NOUNLINK
 295 is set and the user is either not the super-user or
 296 securelevel is greater than 0.
 297 .It Bq Er EPERM
 298 A non-super-user attempted to toggle one of
 299 .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND ,
 300 or
 301 .Dv SF_NOUNLINK .
 302 .It Bq Er EPERM
 303 An attempt was made to toggle the
 304 .Dv SF_SNAPSHOT
 305 flag.
 306 .It Bq Er EROFS
 307 The file resides on a read-only file system.
 308 .It Bq Er EIO
 309 An
 310 .Tn I/O
 311 error occurred while reading from or writing to the file system.
 312 .It Bq Er EINTEGRITY
 313 Corrupted data was detected while reading from the file system.
 314 .It Bq Er EOPNOTSUPP
 315 The underlying file system does not support file flags, or
 316 does not support all of the flags set in
 317 .Fa flags .
 318 .It Bq Er ENOTCAPABLE
 319 .Fa path
 320 is an absolute path,
 321 or contained a ".." component leading to a
 322 directory outside of the directory hierarchy specified by
 323 .Fa fd ,
 324 and the process is in capability mode or the
 325 .Dv AT_RESOLVE_BENEATH
 326 flag was specified.
 327 .El
 328 .Sh SEE ALSO
 329 .Xr chflags 1 ,
 330 .Xr fflagstostr 3 ,
 331 .Xr strtofflags 3 ,
 332 .Xr init 8 ,
 333 .Xr mount_unionfs 8
 334 .Sh HISTORY
 335 The
 336 .Fn chflags
 337 and
 338 .Fn fchflags
 339 system calls first appeared in
 340 .Bx 4.4 .
 341 The
 342 .Fn lchflags
 343 system call first appeared in
 344 .Fx 5.0 .
 345 The
 346 .Fn chflagsat
 347 system call first appeared in
 348 .Fx 10.0 .