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