]>
Commit | Line | Data |
---|---|---|
cfb3e187 MK |
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 | .\" | |
a5409de9 | 26 | .TH IOCTL_IFLAGS 2 2019-11-19 "Linux" "Linux Programmer's Manual" |
cfb3e187 MK |
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: | |
e646a1ba | 36 | .PP |
cfb3e187 | 37 | .in +4n |
b8302363 | 38 | .EX |
cfb3e187 MK |
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 */ | |
b8302363 | 47 | .EE |
e646a1ba MK |
48 | .in |
49 | .PP | |
cfb3e187 MK |
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. | |
e646a1ba | 56 | .PP |
cfb3e187 MK |
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 | |
c7fc938f MK |
146 | .BR FS_PROJINHERIT_FL " \(aqP\(aq (since Linux 4.5)" |
147 | .\" commit 040cb3786d9b25293b8b0b05b90da0f871e1eb9b | |
148 | .\" Flag name was added in Linux 4.4 | |
ba71223d | 149 | .\" FIXME Not currently supported because not in FS_FL_USER_MODIFIABLE? |
c7fc938f MK |
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 | |
cfb3e187 MK |
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. | |
1172adfa MK |
193 | .SH CONFORMING TO |
194 | Inode flags are a nonstandard Linux extension. | |
cfb3e187 MK |
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. | |
1373b981 MK |
203 | .PP |
204 | The type of the argument given to the | |
205 | .BR FS_IOC_GETFLAGS | |
206 | and | |
207 | .BR FS_IOC_SETFLAGS | |
208 | operations is | |
209 | .IR "int\ *" , | |
210 | notwithstanding the implication in the kernel source file | |
211 | .I include/uapi/linux/fs.h | |
212 | that the argument is | |
213 | .IR "long\ *" . | |
cfb3e187 MK |
214 | .SH SEE ALSO |
215 | .BR chattr (1), | |
216 | .BR lsattr (1), | |
217 | .BR mount (2), | |
218 | .BR btrfs (5), | |
219 | .BR ext4 (5), | |
220 | .BR xfs (5), | |
221 | .BR xattr (7), | |
222 | .BR mount (8) |