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