1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
4 .\" %%%LICENSE_START(GPLv2+)
6 .\" This program is free software; you can redistribute it and/or modify
7 .\" it under the terms of the GNU General Public License as published by
8 .\" the Free Software Foundation; either version 2 of the License, or
9 .\" (at your option) any later version.
11 .\" This program is distributed in the hope that it will be useful,
12 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
13 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 .\" GNU General Public License for more details.
16 .\" You should have received a copy of the GNU General Public
17 .\" License along with this manual; if not, see
18 .\" <http://www.gnu.org/licenses/>.
21 .TH MEMFD_CREATE 2 2019-03-06 Linux "Linux Programmer's Manual"
23 memfd_create \- create an anonymous file
26 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
27 .B #include <sys/mman.h>
29 .BI "int memfd_create(const char *" name ", unsigned int " flags ");"
32 creates an anonymous file and returns a file descriptor that refers to it.
33 The file behaves like a regular file, and so can be modified,
34 truncated, memory-mapped, and so on.
35 However, unlike a regular file,
36 it lives in RAM and has a volatile backing storage.
37 Once all references to the file are dropped, it is automatically released.
38 Anonymous memory is used for all backing pages of the file.
39 Therefore, files created by
41 have the same semantics as other anonymous
43 .\" memfd uses VM_NORESERVE so each page is accounted on first access.
44 .\" This means, the overcommit-limits (see __vm_enough_memory()) and the
45 .\" memory-cgroup limits (mem_cgroup_try_charge()) are applied. Note that
46 .\" those are accounted on "current" and "current->mm", that is, the
47 .\" process doing the first page access.
48 memory allocations such as those allocated using
54 The initial size of the file is set to 0.
55 Following the call, the file size should be set using
57 (Alternatively, the file may be populated by calls to
63 is used as a filename and will be displayed
64 as the target of the corresponding symbolic link in the directory
66 The displayed name is always prefixed with
68 and serves only for debugging purposes.
69 Names do not affect the behavior of the file descriptor,
70 and as such multiple files can have the same name without any side effects.
72 The following values may be bitwise ORed in
74 to change the behavior of
80 flag on the new file descriptor.
81 See the description of the
85 for reasons why this may be useful.
88 Allow sealing operations on this file.
89 See the discussion of the
95 and also NOTES, below.
96 The initial set of seals is empty.
97 If this flag is not set, the initial set of seals will be
99 meaning that no other seals can be set on the file.
100 .\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default?
101 .\" Is it worth adding some text explaining this?
103 .BR MFD_HUGETLB " (since Linux 4.14)"
104 .\" commit 749df87bd7bee5a79cef073f5d032ddb2b211de8
105 The anonymous file will be created in the hugetlbfs filesystem using
107 See the Linux kernel source file
108 .I Documentation/admin-guide/mm/hugetlbpage.rst
109 for more information about hugetlbfs.
110 .\" commit 47b9012ecdc747f6936395265e677d41e11a31ff
117 is supported since Linux 4.16.
119 .BR MFD_HUGE_2MB ", " MFD_HUGE_1GB ", " "..."
120 Used in conjunction with
122 to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...)
123 on systems that support multiple hugetlb page sizes.
124 Definitions for known
125 huge page sizes are included in the header file
128 For details on encoding huge page sizes not included in the header file,
129 see the discussion of the similarly named constants in
138 returns a new file descriptor that can be used to refer to the file.
139 This file descriptor is opened for both reading and writing
143 is set for the file descriptor.
149 the usual semantics apply for the file descriptor created by
151 A copy of the file descriptor is inherited by the child produced by
153 and refers to the same file.
154 The file descriptor is preserved across
156 unless the close-on-exec flag has been set.
160 returns a new file descriptor.
161 On error, \-1 is returned and
163 is set to indicate the error.
169 points to invalid memory.
173 included unknown bits.
179 .\" NAME_MAX - strlen("memfd:")
180 249 bytes, excluding the terminating null byte.)
191 The per-process limit on the number of open file descriptors has been reached.
194 The system-wide limit on the total number of open files has been reached.
197 There was insufficient memory to create a new anonymous file.
201 system call first appeared in Linux 3.17;
202 glibc support was added in version 2.27.
206 system call is Linux-specific.
209 .\" See also http://lwn.net/Articles/593918/
210 .\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/
213 system call provides a simple alternative to manually mounting a
215 filesystem and creating and opening a file in that filesystem.
216 The primary purpose of
218 is to create files and associated file descriptors that are
219 used with the file-sealing APIs provided by
224 system call also has uses without file sealing
225 (which is why file-sealing is disabled, unless explicitly requested with the
226 .BR MFD_ALLOW_SEALING
228 In particular, it can be used as an alternative to creating files in
230 or as an alternative to using the
233 in cases where there is no intention to actually link the
234 resulting file into the filesystem.
236 In the absence of file sealing,
237 processes that communicate via shared memory must either trust each other,
238 or take measures to deal with the possibility that an untrusted peer
239 may manipulate the shared memory region in problematic ways.
240 For example, an untrusted peer might modify the contents of the
241 shared memory at any time, or shrink the shared memory region.
242 The former possibility leaves the local process vulnerable to
243 time-of-check-to-time-of-use race conditions
244 (typically dealt with by copying data from
245 the shared memory region before checking and using it).
246 The latter possibility leaves the local process vulnerable to
248 signals when an attempt is made to access a now-nonexistent
249 location in the shared memory region.
250 (Dealing with this possibility necessitates the use of a handler for the
254 Dealing with untrusted peers imposes extra complexity on
255 code that employs shared memory.
256 Memory sealing enables that extra complexity to be eliminated,
257 by allowing a process to operate secure in the knowledge that
258 its peer can't modify the shared memory in an undesired fashion.
260 An example of the usage of the sealing mechanism is as follows:
262 The first process creates a
266 The call yields a file descriptor used in subsequent steps.
269 sizes the file created in the previous step using
273 and populates the shared memory with the desired data.
275 The first process uses the
278 operation to place one or more seals on the file,
279 in order to restrict further modifications on the file.
282 then it will be necessary to first unmap the shared writable mapping
283 created in the previous step.)
285 A second process obtains a file descriptor for the
288 Among the possible ways in which this could happen are the following:
291 The process that called
293 could transfer the resulting file descriptor to the second process
294 via a UNIX domain socket (see
298 The second process then maps the file using
301 The second process is created via
303 and thus automatically inherits the file descriptor and mapping.
304 (Note that in this case and the next,
305 there is a natural trust relationship between the two processes,
306 since they are running under the same user ID.
307 Therefore, file sealing would not normally be necessary.)
309 The second process opens the file
310 .IR /proc/<pid>/fd/<fd> ,
313 is the PID of the first process (the one that called
314 .BR memfd_create ()),
317 is the number of the file descriptor returned by the call to
320 The second process then maps the file using
324 The second process uses the
327 operation to retrieve the bit mask of seals
328 that has been applied to the file.
329 This bit mask can be inspected in order to determine
330 what kinds of restrictions have been placed on file modifications.
331 If desired, the second process can apply further seals
332 to impose additional restrictions (so long as the
334 seal has not yet been applied).
336 Below are shown two example programs that demonstrate the use of
338 and the file sealing API.
341 .IR t_memfd_create.c ,
346 sets a size for the file, maps it into memory,
347 and optionally places some seals on the file.
348 The program accepts up to three command-line arguments,
349 of which the first two are required.
350 The first argument is the name to associate with the file,
351 the second argument is the size to be set for the file,
352 and the optional third argument is a string of characters that specify
353 seals to be set on file.
357 can be used to open an existing file that was created via
359 and inspect the set of seals that have been applied to that file.
361 The following shell session demonstrates the use of these programs.
364 file and set some seals on it:
368 $ \fB./t_memfd_create my_memfd_file 4096 sw &\fP
370 PID: 11775; fd: 3; /proc/11775/fd/3
376 program continues to run in the background.
377 From another program, we can obtain a file descriptor for the
382 file that corresponds to the file descriptor opened by
384 Using that pathname, we inspect the content of the
386 symbolic link, and use our
388 program to view the seals that have been placed on the file:
392 $ \fBreadlink /proc/11775/fd/3\fP
393 /memfd:my_memfd_file (deleted)
394 $ \fB./t_get_seals /proc/11775/fd/3\fP
395 Existing seals: WRITE SHRINK
398 .SS Program source: t_memfd_create.c
402 #include <sys/mman.h>
409 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
413 main(int argc, char *argv[])
418 char *name, *seals_arg;
422 fprintf(stderr, "%s name size [seals]\en", argv[0]);
423 fprintf(stderr, "\et\(aqseals\(aq can contain any of the "
424 "following characters:\en");
425 fprintf(stderr, "\et\etg \- F_SEAL_GROW\en");
426 fprintf(stderr, "\et\ets \- F_SEAL_SHRINK\en");
427 fprintf(stderr, "\et\etw \- F_SEAL_WRITE\en");
428 fprintf(stderr, "\et\etS \- F_SEAL_SEAL\en");
436 /* Create an anonymous file in tmpfs; allow seals to be
437 placed on the file */
439 fd = memfd_create(name, MFD_ALLOW_SEALING);
441 errExit("memfd_create");
443 /* Size the file as specified on the command line */
445 if (ftruncate(fd, len) == \-1)
448 printf("PID: %ld; fd: %d; /proc/%ld/fd/%d\en",
449 (long) getpid(), fd, (long) getpid(), fd);
451 /* Code to map the file and populate the mapping with data
454 /* If a \(aqseals\(aq command\-line argument was supplied, set some
457 if (seals_arg != NULL) {
460 if (strchr(seals_arg, \(aqg\(aq) != NULL)
461 seals |= F_SEAL_GROW;
462 if (strchr(seals_arg, \(aqs\(aq) != NULL)
463 seals |= F_SEAL_SHRINK;
464 if (strchr(seals_arg, \(aqw\(aq) != NULL)
465 seals |= F_SEAL_WRITE;
466 if (strchr(seals_arg, \(aqS\(aq) != NULL)
467 seals |= F_SEAL_SEAL;
469 if (fcntl(fd, F_ADD_SEALS, seals) == \-1)
473 /* Keep running, so that the file created by memfd_create()
474 continues to exist */
481 .SS Program source: t_get_seals.c
485 #include <sys/mman.h>
492 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
496 main(int argc, char *argv[])
502 fprintf(stderr, "%s /proc/PID/fd/FD\en", argv[0]);
506 fd = open(argv[1], O_RDWR);
510 seals = fcntl(fd, F_GET_SEALS);
514 printf("Existing seals:");
515 if (seals & F_SEAL_SEAL)
517 if (seals & F_SEAL_GROW)
519 if (seals & F_SEAL_WRITE)
521 if (seals & F_SEAL_SHRINK)
525 /* Code to map the file and access the contents of the
526 resulting mapping omitted */