Debian Codegraph @

upstream/debian-trixie/man2/memfd_create.2

raw
1 .\" Copyright (C) 2014 Michael Kerrisk <[email protected]>
2 .\" and Copyright (C) 2014 David Herrmann <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH memfd_create 2 2024-06-15 "Linux man-pages 6.9.1"
7 .SH NAME
8 memfd_create \- create an anonymous file
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ", " \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #include <sys/mman.h>
16 .P
17 .BI "int memfd_create(const char *" name ", unsigned int " flags ");"
18 .fi
19 .SH DESCRIPTION
20 .BR memfd_create ()
21 creates an anonymous file and returns a file descriptor that refers to it.
22 The file behaves like a regular file, and so can be modified,
23 truncated, memory-mapped, and so on.
24 However, unlike a regular file,
25 it lives in RAM and has a volatile backing storage.
26 Once all references to the file are dropped, it is automatically released.
27 Anonymous memory is used for all backing pages of the file.
28 Therefore, files created by
29 .BR memfd_create ()
30 have the same semantics as other anonymous
31 .\" David Herrmann:
32 .\" memfd uses VM_NORESERVE so each page is accounted on first access.
33 .\" This means, the overcommit-limits (see __vm_enough_memory()) and the
34 .\" memory-cgroup limits (mem_cgroup_try_charge()) are applied. Note that
35 .\" those are accounted on "current" and "current->mm", that is, the
36 .\" process doing the first page access.
37 memory allocations such as those allocated using
38 .BR mmap (2)
39 with the
40 .B MAP_ANONYMOUS
41 flag.
42 .P
43 The initial size of the file is set to 0.
44 Following the call, the file size should be set using
45 .BR ftruncate (2).
46 (Alternatively, the file may be populated by calls to
47 .BR write (2)
48 or similar.)
49 .P
50 The name supplied in
51 .I name
52 is used as a filename and will be displayed
53 as the target of the corresponding symbolic link in the directory
54 .IR /proc/self/fd/ .
55 The displayed name is always prefixed with
56 .I memfd:
57 and serves only for debugging purposes.
58 Names do not affect the behavior of the file descriptor,
59 and as such multiple files can have the same name without any side effects.
60 .P
61 The following values may be bitwise ORed in
62 .I flags
63 to change the behavior of
64 .BR memfd_create ():
65 .TP
66 .B MFD_CLOEXEC
67 Set the close-on-exec
68 .RB ( FD_CLOEXEC )
69 flag on the new file descriptor.
70 See the description of the
71 .B O_CLOEXEC
72 flag in
73 .BR open (2)
74 for reasons why this may be useful.
75 .TP
76 .B MFD_ALLOW_SEALING
77 Allow sealing operations on this file.
78 See the discussion of the
79 .B F_ADD_SEALS
80 and
81 .B F_GET_SEALS
82 operations in
83 .BR fcntl (2),
84 and also NOTES, below.
85 The initial set of seals is empty.
86 If this flag is not set, the initial set of seals will be
87 .BR F_SEAL_SEAL ,
88 meaning that no other seals can be set on the file.
89 .\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default?
90 .\" Is it worth adding some text explaining this?
91 .TP
92 .BR MFD_HUGETLB " (since Linux 4.14)"
93 .\" commit 749df87bd7bee5a79cef073f5d032ddb2b211de8
94 The anonymous file will be created in the hugetlbfs filesystem using
95 huge pages.
96 See the Linux kernel source file
97 .I Documentation/admin\-guide/mm/hugetlbpage.rst
98 for more information about hugetlbfs.
99 .\" commit 47b9012ecdc747f6936395265e677d41e11a31ff
100 Specifying both
101 .B MFD_HUGETLB
102 and
103 .B MFD_ALLOW_SEALING
104 in
105 .I flags
106 is supported since Linux 4.16.
107 .TP
108 .B MFD_HUGE_2MB
109 .TQ
110 .B MFD_HUGE_1GB
111 .TQ
112 \&.\|.\|.
113 Used in conjunction with
114 .B MFD_HUGETLB
115 to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...)
116 on systems that support multiple hugetlb page sizes.
117 Definitions for known
118 huge page sizes are included in the header file
119 .I <linux/memfd.h>.
120 .IP
121 For details on encoding huge page sizes not included in the header file,
122 see the discussion of the similarly named constants in
123 .BR mmap (2).
124 .P
125 Unused bits in
126 .I flags
127 must be 0.
128 .P
129 As its return value,
130 .BR memfd_create ()
131 returns a new file descriptor that can be used to refer to the file.
132 This file descriptor is opened for both reading and writing
133 .RB ( O_RDWR )
134 and
135 .B O_LARGEFILE
136 is set for the file descriptor.
137 .P
138 With respect to
139 .BR fork (2)
140 and
141 .BR execve (2),
142 the usual semantics apply for the file descriptor created by
143 .BR memfd_create ().
144 A copy of the file descriptor is inherited by the child produced by
145 .BR fork (2)
146 and refers to the same file.
147 The file descriptor is preserved across
148 .BR execve (2),
149 unless the close-on-exec flag has been set.
150 .SH RETURN VALUE
151 On success,
152 .BR memfd_create ()
153 returns a new file descriptor.
154 On error, \-1 is returned and
155 .I errno
156 is set to indicate the error.
157 .SH ERRORS
158 .TP
159 .B EFAULT
160 The address in
161 .I name
162 points to invalid memory.
163 .TP
164 .B EINVAL
165 .I flags
166 included unknown bits.
167 .TP
168 .B EINVAL
169 .I name
170 was too long.
171 (The limit is
172 .\" NAME_MAX - strlen("memfd:")
173 249 bytes, excluding the terminating null byte.)
174 .TP
175 .B EINVAL
176 Both
177 .B MFD_HUGETLB
178 and
179 .B MFD_ALLOW_SEALING
180 were specified in
181 .IR flags .
182 .TP
183 .B EMFILE
184 The per-process limit on the number of open file descriptors has been reached.
185 .TP
186 .B ENFILE
187 The system-wide limit on the total number of open files has been reached.
188 .TP
189 .B ENOMEM
190 There was insufficient memory to create a new anonymous file.
191 .TP
192 .B EPERM
193 The
194 .B MFD_HUGETLB
195 flag was specified, but the caller was not privileged (did not have the
196 .B CAP_IPC_LOCK
197 capability)
198 and is not a member of the
199 .I sysctl_hugetlb_shm_group
200 group; see the description of
201 .I /proc/sys/vm/sysctl_hugetlb_shm_group
202 in
203 .BR proc (5).
204 .SH STANDARDS
205 Linux.
206 .SH HISTORY
207 Linux 3.17,
208 glibc 2.27.
209 .SH NOTES
210 .\" See also http://lwn.net/Articles/593918/
211 .\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/
212 The
213 .BR memfd_create ()
214 system call provides a simple alternative to manually mounting a
215 .BR tmpfs (5)
216 filesystem and creating and opening a file in that filesystem.
217 The primary purpose of
218 .BR memfd_create ()
219 is to create files and associated file descriptors that are
220 used with the file-sealing APIs provided by
221 .BR fcntl (2).
222 .P
223 The
224 .BR memfd_create ()
225 system call also has uses without file sealing
226 (which is why file-sealing is disabled, unless explicitly requested with the
227 .B MFD_ALLOW_SEALING
228 flag).
229 In particular, it can be used as an alternative to creating files in
230 .I tmp
231 or as an alternative to using the
232 .BR open (2)
233 .B O_TMPFILE
234 in cases where there is no intention to actually link the
235 resulting file into the filesystem.
236 .SS File sealing
237 In the absence of file sealing,
238 processes that communicate via shared memory must either trust each other,
239 or take measures to deal with the possibility that an untrusted peer
240 may manipulate the shared memory region in problematic ways.
241 For example, an untrusted peer might modify the contents of the
242 shared memory at any time, or shrink the shared memory region.
243 The former possibility leaves the local process vulnerable to
244 time-of-check-to-time-of-use race conditions
245 (typically dealt with by copying data from
246 the shared memory region before checking and using it).
247 The latter possibility leaves the local process vulnerable to
248 .B SIGBUS
249 signals when an attempt is made to access a now-nonexistent
250 location in the shared memory region.
251 (Dealing with this possibility necessitates the use of a handler for the
252 .B SIGBUS
253 signal.)
254 .P
255 Dealing with untrusted peers imposes extra complexity on
256 code that employs shared memory.
257 Memory sealing enables that extra complexity to be eliminated,
258 by allowing a process to operate secure in the knowledge that
259 its peer can't modify the shared memory in an undesired fashion.
260 .P
261 An example of the usage of the sealing mechanism is as follows:
262 .IP (1) 5
263 The first process creates a
264 .BR tmpfs (5)
265 file using
266 .BR memfd_create ().
267 The call yields a file descriptor used in subsequent steps.
268 .IP (2)
269 The first process
270 sizes the file created in the previous step using
271 .BR ftruncate (2),
272 maps it using
273 .BR mmap (2),
274 and populates the shared memory with the desired data.
275 .IP (3)
276 The first process uses the
277 .BR fcntl (2)
278 .B F_ADD_SEALS
279 operation to place one or more seals on the file,
280 in order to restrict further modifications on the file.
281 (If placing the seal
282 .BR F_SEAL_WRITE ,
283 then it will be necessary to first unmap the shared writable mapping
284 created in the previous step.
285 Otherwise, behavior similar to
286 .B F_SEAL_WRITE
287 can be achieved by using
288 .BR F_SEAL_FUTURE_WRITE ,
289 which will prevent future writes via
290 .BR mmap (2)
291 and
292 .BR write (2)
293 from succeeding while keeping existing shared writable mappings).
294 .IP (4)
295 A second process obtains a file descriptor for the
296 .BR tmpfs (5)
297 file and maps it.
298 Among the possible ways in which this could happen are the following:
299 .RS
300 .IP \[bu] 3
301 The process that called
302 .BR memfd_create ()
303 could transfer the resulting file descriptor to the second process
304 via a UNIX domain socket (see
305 .BR unix (7)
306 and
307 .BR cmsg (3)).
308 The second process then maps the file using
309 .BR mmap (2).
310 .IP \[bu]
311 The second process is created via
312 .BR fork (2)
313 and thus automatically inherits the file descriptor and mapping.
314 (Note that in this case and the next,
315 there is a natural trust relationship between the two processes,
316 since they are running under the same user ID.
317 Therefore, file sealing would not normally be necessary.)
318 .IP \[bu]
319 The second process opens the file
320 .IR /proc/ pid /fd/ fd,
321 where
322 .I <pid>
323 is the PID of the first process (the one that called
324 .BR memfd_create ()),
325 and
326 .I <fd>
327 is the number of the file descriptor returned by the call to
328 .BR memfd_create ()
329 in that process.
330 The second process then maps the file using
331 .BR mmap (2).
332 .RE
333 .IP (5)
334 The second process uses the
335 .BR fcntl (2)
336 .B F_GET_SEALS
337 operation to retrieve the bit mask of seals
338 that has been applied to the file.
339 This bit mask can be inspected in order to determine
340 what kinds of restrictions have been placed on file modifications.
341 If desired, the second process can apply further seals
342 to impose additional restrictions (so long as the
343 .B F_SEAL_SEAL
344 seal has not yet been applied).
345 .SH EXAMPLES
346 Below are shown two example programs that demonstrate the use of
347 .BR memfd_create ()
348 and the file sealing API.
349 .P
350 The first program,
351 .IR t_memfd_create.c ,
352 creates a
353 .BR tmpfs (5)
354 file using
355 .BR memfd_create (),
356 sets a size for the file, maps it into memory,
357 and optionally places some seals on the file.
358 The program accepts up to three command-line arguments,
359 of which the first two are required.
360 The first argument is the name to associate with the file,
361 the second argument is the size to be set for the file,
362 and the optional third argument is a string of characters that specify
363 seals to be set on the file.
364 .P
365 The second program,
366 .IR t_get_seals.c ,
367 can be used to open an existing file that was created via
368 .BR memfd_create ()
369 and inspect the set of seals that have been applied to that file.
370 .P
371 The following shell session demonstrates the use of these programs.
372 First we create a
373 .BR tmpfs (5)
374 file and set some seals on it:
375 .P
376 .in +4n
377 .EX
378 $ \fB./t_memfd_create my_memfd_file 4096 sw &\fP
379 [1] 11775
380 PID: 11775; fd: 3; /proc/11775/fd/3
381 .EE
382 .in
383 .P
384 At this point, the
385 .I t_memfd_create
386 program continues to run in the background.
387 From another program, we can obtain a file descriptor for the
388 file created by
389 .BR memfd_create ()
390 by opening the
391 .IR /proc/ pid /fd
392 file that corresponds to the file descriptor opened by
393 .BR memfd_create ().
394 Using that pathname, we inspect the content of the
395 .IR /proc/ pid /fd
396 symbolic link, and use our
397 .I t_get_seals
398 program to view the seals that have been placed on the file:
399 .P
400 .in +4n
401 .EX
402 $ \fBreadlink /proc/11775/fd/3\fP
403 /memfd:my_memfd_file (deleted)
404 $ \fB./t_get_seals /proc/11775/fd/3\fP
405 Existing seals: WRITE SHRINK
406 .EE
407 .in
408 .SS Program source: t_memfd_create.c
409 \&
410 .\" SRC BEGIN (t_memfd_create.c)
411 .EX
412 #define _GNU_SOURCE
413 #include <err.h>
414 #include <fcntl.h>
415 #include <stdint.h>
416 #include <stdio.h>
417 #include <stdlib.h>
418 #include <string.h>
419 #include <sys/mman.h>
420 #include <sys/types.h>
421 #include <unistd.h>
422 \&
423 int
424 main(int argc, char *argv[])
425 {
426 int fd;
427 char *name, *seals_arg;
428 ssize_t len;
429 unsigned int seals;
430 \&
431 if (argc < 3) {
432 fprintf(stderr, "%s name size [seals]\[rs]n", argv[0]);
433 fprintf(stderr, "\[rs]t\[aq]seals\[aq] can contain any of the "
434 "following characters:\[rs]n");
435 fprintf(stderr, "\[rs]t\[rs]tg \- F_SEAL_GROW\[rs]n");
436 fprintf(stderr, "\[rs]t\[rs]ts \- F_SEAL_SHRINK\[rs]n");
437 fprintf(stderr, "\[rs]t\[rs]tw \- F_SEAL_WRITE\[rs]n");
438 fprintf(stderr, "\[rs]t\[rs]tW \- F_SEAL_FUTURE_WRITE\[rs]n");
439 fprintf(stderr, "\[rs]t\[rs]tS \- F_SEAL_SEAL\[rs]n");
440 exit(EXIT_FAILURE);
441 }
442 \&
443 name = argv[1];
444 len = atoi(argv[2]);
445 seals_arg = argv[3];
446 \&
447 /* Create an anonymous file in tmpfs; allow seals to be
448 placed on the file. */
449 \&
450 fd = memfd_create(name, MFD_ALLOW_SEALING);
451 if (fd == \-1)
452 err(EXIT_FAILURE, "memfd_create");
453 \&
454 /* Size the file as specified on the command line. */
455 \&
456 if (ftruncate(fd, len) == \-1)
457 err(EXIT_FAILURE, "truncate");
458 \&
459 printf("PID: %jd; fd: %d; /proc/%jd/fd/%d\[rs]n",
460 (intmax_t) getpid(), fd, (intmax_t) getpid(), fd);
461 \&
462 /* Code to map the file and populate the mapping with data
463 omitted. */
464 \&
465 /* If a \[aq]seals\[aq] command\-line argument was supplied, set some
466 seals on the file. */
467 \&
468 if (seals_arg != NULL) {
469 seals = 0;
470 \&
471 if (strchr(seals_arg, \[aq]g\[aq]) != NULL)
472 seals |= F_SEAL_GROW;
473 if (strchr(seals_arg, \[aq]s\[aq]) != NULL)
474 seals |= F_SEAL_SHRINK;
475 if (strchr(seals_arg, \[aq]w\[aq]) != NULL)
476 seals |= F_SEAL_WRITE;
477 if (strchr(seals_arg, \[aq]W\[aq]) != NULL)
478 seals |= F_SEAL_FUTURE_WRITE;
479 if (strchr(seals_arg, \[aq]S\[aq]) != NULL)
480 seals |= F_SEAL_SEAL;
481 \&
482 if (fcntl(fd, F_ADD_SEALS, seals) == \-1)
483 err(EXIT_FAILURE, "fcntl");
484 }
485 \&
486 /* Keep running, so that the file created by memfd_create()
487 continues to exist. */
488 \&
489 pause();
490 \&
491 exit(EXIT_SUCCESS);
492 }
493 .EE
494 .\" SRC END
495 .SS Program source: t_get_seals.c
496 \&
497 .\" SRC BEGIN (t_get_seals.c)
498 .EX
499 #define _GNU_SOURCE
500 #include <err.h>
501 #include <fcntl.h>
502 #include <stdio.h>
503 #include <stdlib.h>
504 \&
505 int
506 main(int argc, char *argv[])
507 {
508 int fd;
509 unsigned int seals;
510 \&
511 if (argc != 2) {
512 fprintf(stderr, "%s /proc/PID/fd/FD\[rs]n", argv[0]);
513 exit(EXIT_FAILURE);
514 }
515 \&
516 fd = open(argv[1], O_RDWR);
517 if (fd == \-1)
518 err(EXIT_FAILURE, "open");
519 \&
520 seals = fcntl(fd, F_GET_SEALS);
521 if (seals == \-1)
522 err(EXIT_FAILURE, "fcntl");
523 \&
524 printf("Existing seals:");
525 if (seals & F_SEAL_SEAL)
526 printf(" SEAL");
527 if (seals & F_SEAL_GROW)
528 printf(" GROW");
529 if (seals & F_SEAL_WRITE)
530 printf(" WRITE");
531 if (seals & F_SEAL_FUTURE_WRITE)
532 printf(" FUTURE_WRITE");
533 if (seals & F_SEAL_SHRINK)
534 printf(" SHRINK");
535 printf("\[rs]n");
536 \&
537 /* Code to map the file and access the contents of the
538 resulting mapping omitted. */
539 \&
540 exit(EXIT_SUCCESS);
541 }
542 .EE
543 .\" SRC END
544 .SH SEE ALSO
545 .BR fcntl (2),
546 .BR ftruncate (2),
547 .BR memfd_secret (2),
548 .BR mmap (2),
549 .BR shmget (2),
550 .BR shm_open (3)