man2/memfd_create.2

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