man2/ioctl_iflags.2

   1 .\" Copyright (c) 2017 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\"
   6 .TH IOCTL_IFLAGS 2 2019-11-19 "Linux" "Linux Programmer's Manual"
   7 .SH NAME
   8 ioctl_iflags \- ioctl() operations for inode flags
   9 .SH DESCRIPTION
  10 Various Linux filesystems support the notion of
  11 .IR "inode flags" \(emattributes
  12 that modify the semantics of files and directories.
  13 These flags can be retrieved and modified using two
  14 .BR ioctl (2)
  15 operations:
  16 .PP
  17 .in +4n
  18 .EX
  19 int attr;
  20 fd = open("pathname", ...);
  21
  22 ioctl(fd, FS_IOC_GETFLAGS, &attr);  /* Place current flags
  23                                        in \(aqattr\(aq */
  24 attr |= FS_NOATIME_FL;              /* Tweak returned bit mask */
  25 ioctl(fd, FS_IOC_SETFLAGS, &attr);  /* Update flags for inode
  26                                        referred to by \(aqfd\(aq */
  27 .EE
  28 .in
  29 .PP
  30 The
  31 .BR lsattr (1)
  32 and
  33 .BR chattr (1)
  34 shell commands provide interfaces to these two operations,
  35 allowing a user to view and modify the inode flags associated with a file.
  36 .PP
  37 The following flags are supported
  38 (shown along with the corresponding letter used to indicate the flag by
  39 .BR lsattr (1)
  40 and
  41 .BR chattr (1)):
  42 .TP
  43 .BR FS_APPEND_FL " \(aqa\(aq"
  44 The file can be opened only with the
  45 .B O_APPEND
  46 flag.
  47 (This restriction applies even to the superuser.)
  48 Only a privileged process
  49 .RB ( CAP_LINUX_IMMUTABLE )
  50 can set or clear this attribute.
  51 .TP
  52 .BR FS_COMPR_FL " \(aqc\(aq"
  53 Store the file in a compressed format on disk.
  54 This flag is
  55 .I not
  56 supported by most of the mainstream filesystem implementations;
  57 one exception is
  58 .BR btrfs (5).
  59 .TP
  60 .BR FS_DIRSYNC_FL " \(aqD\(aq (since Linux 2.6.0)"
  61 Write directory changes synchronously to disk.
  62 This flag provides semantics equivalent to the
  63 .BR mount  (2)
  64 .B MS_DIRSYNC
  65 option, but on a per-directory basis.
  66 This flag can be applied only to directories.
  67 .\" .TP
  68 .\" .BR FS_EXTENT_FL " \(aqe\(aq"
  69 .\" FIXME Some support on ext4? (EXT4_EXTENTS_FL)
  70 .TP
  71 .BR FS_IMMUTABLE_FL " \(aqi\(aq"
  72 The file is immutable:
  73 no changes are permitted to the file contents or metadata
  74 (permissions, timestamps, ownership, link count, and so on).
  75 (This restriction applies even to the superuser.)
  76 Only a privileged process
  77 .RB ( CAP_LINUX_IMMUTABLE )
  78 can set or clear this attribute.
  79 .TP
  80 .BR FS_JOURNAL_DATA_FL " \(aqj\(aq"
  81 Enable journaling of file data on
  82 .BR ext3 (5)
  83 and
  84 .BR ext4 (5)
  85 filesystems.
  86 On a filesystem that is journaling in
  87 .I ordered
  88 or
  89 .I writeback
  90 mode, a privileged
  91 .RB ( CAP_SYS_RESOURCE )
  92 process can set this flag to enable journaling of data updates on
  93 a per-file basis.
  94 .TP
  95 .BR FS_NOATIME_FL " \(aqA\(aq"
  96 Don't update the file last access time when the file is accessed.
  97 This can provide I/O performance benefits for applications that do not care
  98 about the accuracy of this timestamp.
  99 This flag provides functionality similar to the
 100 .BR mount (2)
 101 .BR MS_NOATIME
 102 flag, but on a per-file basis.
 103 .\" .TP
 104 .\" .BR FS_NOCOMP_FL " \(aq\(aq"
 105 .\" FIXME Support for FS_NOCOMP_FL on Btrfs?
 106 .TP
 107 .BR FS_NOCOW_FL " \(aqC\(aq (since Linux 2.6.39)"
 108 The file will not be subject to copy-on-write updates.
 109 This flag has an effect only on filesystems that support copy-on-write
 110 semantics, such as Btrfs.
 111 See
 112 .BR chattr (1)
 113 and
 114 .BR btrfs (5).
 115 .TP
 116 .BR FS_NODUMP_FL " \(aqd\(aq"
 117 Don't include this file in backups made using
 118 .BR dump (8).
 119 .TP
 120 .BR FS_NOTAIL_FL " \(aqt\(aq"
 121 This flag is supported only on Reiserfs.
 122 It disables the Reiserfs tail-packing feature,
 123 which tries to pack small files (and the final fragment of larger files)
 124 into the same disk block as the file metadata.
 125 .TP
 126 .BR FS_PROJINHERIT_FL " \(aqP\(aq (since Linux 4.5)"
 127 .\" commit 040cb3786d9b25293b8b0b05b90da0f871e1eb9b
 128 .\" Flag name was added in Linux 4.4
 129 .\" FIXME Not currently supported because not in FS_FL_USER_MODIFIABLE?
 130 Inherit the quota project ID.
 131 Files and subdirectories will inherit the project ID of the directory.
 132 This flag can be applied only to directories.
 133 .TP
 134 .BR FS_SECRM_FL " \(aqs\(aq"
 135 Mark the file for secure deletion.
 136 This feature is not implemented by any filesystem,
 137 since the task of securely erasing a file from a recording medium
 138 is surprisingly difficult.
 139 .TP
 140 .BR FS_SYNC_FL " \(aqS\(aq"
 141 Make file updates synchronous.
 142 For files, this makes all writes synchronous
 143 (as though all opens of the file were with the
 144 .BR O_SYNC
 145 flag).
 146 For directories, this has the same effect as the
 147 .BR FS_DIRSYNC_FL
 148 flag.
 149 .TP
 150 .BR FS_TOPDIR_FL " \(aqT\(aq"
 151 Mark a directory for special treatment under the Orlov block-allocation
 152 strategy.
 153 See
 154 .BR chattr (1)
 155 for details.
 156 This flag can be applied only to directories and
 157 has an effect only for ext2, ext3, and ext4.
 158 .TP
 159 .BR FS_UNRM_FL " \(aqu\(aq"
 160 Allow the file to be undeleted if it is deleted.
 161 This feature is not implemented by any filesystem,
 162 since it is possible to implement file-recovery mechanisms outside the kernel.
 163 .PP
 164 In most cases,
 165 when any of the above flags is set on a directory,
 166 the flag is inherited by files and subdirectories
 167 created inside that directory.
 168 Exceptions include
 169 .BR FS_TOPDIR_FL ,
 170 which is not inheritable, and
 171 .BR FS_DIRSYNC_FL ,
 172 which is inherited only by subdirectories.
 173 .SH CONFORMING TO
 174 Inode flags are a nonstandard Linux extension.
 175 .SH NOTES
 176 In order to change the inode flags of a file using the
 177 .BR FS_IOC_SETFLAGS
 178 operation,
 179 the effective user ID of the caller must match the owner of the file,
 180 or the caller must have the
 181 .BR CAP_FOWNER
 182 capability.
 183 .PP
 184 The type of the argument given to the
 185 .BR FS_IOC_GETFLAGS
 186 and
 187 .BR FS_IOC_SETFLAGS
 188 operations is
 189 .IR "int\ *" ,
 190 notwithstanding the implication in the kernel source file
 191 .I include/uapi/linux/fs.h
 192 that the argument is
 193 .IR "long\ *" .
 194 .SH SEE ALSO
 195 .BR chattr (1),
 196 .BR lsattr (1),
 197 .BR mount (2),
 198 .BR btrfs (5),
 199 .BR ext4 (5),
 200 .BR xfs (5),
 201 .BR xattr (7),
 202 .BR mount (8)