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