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