man2/ioctl_iflags.2

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