Debian Codegraph @

upstream/debian-unstable/man2/F_GET_SEALS.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH F_GET_SEALS 2const 2025-07-20 "Linux man-pages 6.18"
6 .SH NAME
7 F_GET_SEALS,
8 F_ADD_SEALS
9 \-
10 get/add file seals
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <fcntl.h>
17 .P
18 .BI "int fcntl(int " fd ", F_ADD_SEALS, int " arg );
19 .BI "int fcntl(int " fd ", F_GET_SEALS);"
20 .fi
21 .SH DESCRIPTION
22 File seals limit the set of allowed operations on a given file.
23 For each seal that is set on a file,
24 a specific set of operations will fail with
25 .B EPERM
26 on this file from now on.
27 The file is said to be sealed.
28 The default set of seals depends on the type of the underlying
29 file and filesystem.
30 For an overview of file sealing, a discussion of its purpose,
31 and some code examples, see
32 .BR memfd_create (2).
33 .P
34 Currently,
35 file seals can be applied only to a file descriptor returned by
36 .BR memfd_create (2)
37 (if the
38 .B MFD_ALLOW_SEALING
39 was employed).
40 On other filesystems, all
41 .BR fcntl ()
42 operations that operate on seals will return
43 .BR EINVAL .
44 .P
45 Seals are a property of an inode.
46 Thus, all open file descriptors referring to the same inode share
47 the same set of seals.
48 Furthermore, seals can never be removed, only added.
49 .TP
50 .B F_ADD_SEALS
51 Add the seals given in the bit-mask argument
52 .I arg
53 to the set of seals of the inode referred to by the file descriptor
54 .IR fd .
55 Seals cannot be removed again.
56 Once this call succeeds, the seals are enforced by the kernel immediately.
57 If the current set of seals includes
58 .B F_SEAL_SEAL
59 (see below), then this call will be rejected with
60 .BR EPERM .
61 Adding a seal that is already set is a no-op, in case
62 .B F_SEAL_SEAL
63 is not set already.
64 In order to place a seal, the file descriptor
65 .I fd
66 must be writable.
67 .TP
68 .B F_GET_SEALS
69 Return (as the function result) the current set of seals
70 of the inode referred to by
71 .IR fd .
72 If no seals are set, 0 is returned.
73 If the file does not support sealing, \-1 is returned and
74 .I errno
75 is set to
76 .BR EINVAL .
77 .P
78 The following seals are available:
79 .TP
80 .B F_SEAL_SEAL
81 If this seal is set, any further call to
82 .BR fcntl ()
83 with
84 .B F_ADD_SEALS
85 fails with the error
86 .BR EPERM .
87 Therefore, this seal prevents any modifications to the set of seals itself.
88 If the initial set of seals of a file includes
89 .BR F_SEAL_SEAL ,
90 then this effectively causes the set of seals to be constant and locked.
91 .TP
92 .B F_SEAL_SHRINK
93 If this seal is set, the file in question cannot be reduced in size.
94 This affects
95 .BR open (2)
96 with the
97 .B O_TRUNC
98 flag as well as
99 .BR truncate (2)
100 and
101 .BR ftruncate (2).
102 Those calls fail with
103 .B EPERM
104 if you try to shrink the file in question.
105 Increasing the file size is still possible.
106 .TP
107 .B F_SEAL_GROW
108 If this seal is set, the size of the file in question cannot be increased.
109 This affects
110 .BR write (2)
111 beyond the end of the file,
112 .BR truncate (2),
113 .BR ftruncate (2),
114 and
115 .BR fallocate (2).
116 These calls fail with
117 .B EPERM
118 if you use them to increase the file size.
119 If you keep the size or shrink it, those calls still work as expected.
120 .TP
121 .B F_SEAL_WRITE
122 If this seal is set, you cannot modify the contents of the file.
123 Note that shrinking or growing the size of the file is
124 still possible and allowed.
125 .\" One or more other seals are typically used with F_SEAL_WRITE
126 .\" because, given a file with the F_SEAL_WRITE seal set, then,
127 .\" while it would no longer be possible to (say) write zeros into
128 .\" the last 100 bytes of a file, it would still be possible
129 .\" to (say) shrink the file by 100 bytes using ftruncate(), and
130 .\" then increase the file size by 100 bytes, which would have
131 .\" the effect of replacing the last hundred bytes by zeros.
132 .\"
133 Thus, this seal is normally used in combination with one of the other seals.
134 This seal affects
135 .BR write (2)
136 and
137 .BR fallocate (2)
138 (only in combination with the
139 .B FALLOC_FL_PUNCH_HOLE
140 flag).
141 Those calls fail with
142 .B EPERM
143 if this seal is set.
144 Furthermore, trying to create new shared, writable memory-mappings via
145 .BR mmap (2)
146 will also fail with
147 .BR EPERM .
148 .IP
149 Using the
150 .B F_ADD_SEALS
151 operation to set the
152 .B F_SEAL_WRITE
153 seal fails with
154 .B EBUSY
155 if any writable, shared mapping exists.
156 Such mappings must be unmapped before you can add this seal.
157 Furthermore, if there are any asynchronous I/O operations
158 .RB ( io_submit (2))
159 pending on the file,
160 all outstanding writes will be discarded.
161 .TP
162 .BR F_SEAL_FUTURE_WRITE " (since Linux 5.1)"
163 The effect of this seal is similar to
164 .BR F_SEAL_WRITE ,
165 but the contents of the file can still be modified via
166 shared writable mappings that were created prior to the seal being set.
167 Any attempt to create a new writable mapping on the file via
168 .BR mmap (2)
169 will fail with
170 .BR EPERM .
171 Likewise, an attempt to write to the file via
172 .BR write (2)
173 will fail with
174 .BR EPERM .
175 .IP
176 Using this seal,
177 one process can create a memory buffer that it can continue to modify
178 while sharing that buffer on a "read-only" basis with other processes.
179 .SH RETURN VALUE
180 .TP
181 .B F_GET_SEALS
182 A bit mask identifying the seals that have been set
183 for the inode referred to by
184 .IR fd .
185 .TP
186 .B F_ADD_SEALS
187 Zero.
188 .P
189 On error, \-1 is returned, and
190 .I errno
191 is set to indicate the error.
192 .SH ERRORS
193 See
194 .BR fcntl (2).
195 .TP
196 .B EBUSY
197 .I op
198 is
199 .BR F_ADD_SEALS ,
200 .I arg
201 includes
202 .BR F_SEAL_WRITE ,
203 and there exists a writable, shared mapping on the file referred to by
204 .IR fd .
205 .TP
206 .B EINVAL
207 .I op
208 is
209 .B F_ADD_SEALS
210 and
211 .I arg
212 includes an unrecognized sealing bit.
213 .TP
214 .B EINVAL
215 The filesystem containing the inode referred to by
216 .I fd
217 does not support sealing.
218 .TP
219 .B EPERM
220 .I op
221 was
222 .BR F_ADD_SEALS ,
223 but
224 .I fd
225 was not open for writing
226 or the current set of seals on the file already includes
227 .BR F_SEAL_SEAL .
228 .SH STANDARDS
229 Linux.
230 .\" FIXME . Once glibc adds support, add a note about FTM requirements
231 .SH HISTORY
232 Linux 3.17.
233 .SH SEE ALSO
234 .BR fcntl (2)