Debian Codegraph @

upstream/debian-unstable/man2/memfd_create.2

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