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 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH MEMFD_CREATE 2 2021-03-22 "Linux man-pages (unreleased)"
   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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .BR MFD_HUGE_2MB ", " MFD_HUGE_1GB ", " "..."
 109 Used in conjunction with
 110 .B MFD_HUGETLB
 111 to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...)
 112 on systems that support multiple hugetlb page sizes.
 113 Definitions for known
 114 huge page sizes are included in the header file
 115 .I <linux/memfd.h>.
 116 .IP
 117 For details on encoding huge page sizes not included in the header file,
 118 see the discussion of the similarly named constants in
 119 .BR mmap (2).
 120 .PP
 121 Unused bits in
 122 .I flags
 123 must be 0.
 124 .PP
 125 As its return value,
 126 .BR memfd_create ()
 127 returns a new file descriptor that can be used to refer to the file.
 128 This file descriptor is opened for both reading and writing
 129 .RB ( O_RDWR )
 130 and
 131 .B O_LARGEFILE
 132 is set for the file descriptor.
 133 .PP
 134 With respect to
 135 .BR fork (2)
 136 and
 137 .BR execve (2),
 138 the usual semantics apply for the file descriptor created by
 139 .BR memfd_create ().
 140 A copy of the file descriptor is inherited by the child produced by
 141 .BR fork (2)
 142 and refers to the same file.
 143 The file descriptor is preserved across
 144 .BR execve (2),
 145 unless the close-on-exec flag has been set.
 146 .SH RETURN VALUE
 147 On success,
 148 .BR memfd_create ()
 149 returns a new file descriptor.
 150 On error, \-1 is returned and
 151 .I errno
 152 is set to indicate the error.
 153 .SH ERRORS
 154 .TP
 155 .B EFAULT
 156 The address in
 157 .I name
 158 points to invalid memory.
 159 .TP
 160 .B EINVAL
 161 .I flags
 162 included unknown bits.
 163 .TP
 164 .B EINVAL
 165 .I name
 166 was too long.
 167 (The limit is
 168 .\" NAME_MAX - strlen("memfd:")
 169 249 bytes, excluding the terminating null byte.)
 170 .TP
 171 .B EINVAL
 172 Both
 173 .B MFD_HUGETLB
 174 and
 175 .B MFD_ALLOW_SEALING
 176 were specified in
 177 .IR flags .
 178 .TP
 179 .B EMFILE
 180 The per-process limit on the number of open file descriptors has been reached.
 181 .TP
 182 .B ENFILE
 183 The system-wide limit on the total number of open files has been reached.
 184 .TP
 185 .B ENOMEM
 186 There was insufficient memory to create a new anonymous file.
 187 .SH VERSIONS
 188 The
 189 .BR memfd_create ()
 190 system call first appeared in Linux 3.17;
 191 glibc support was added in version 2.27.
 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 sysctl_hugetlb_shm_group
 201 group; see the description of
 202 .I /proc/sys/vm/sysctl_hugetlb_shm_group
 203 in
 204 .BR proc (5).
 205 .SH STANDARDS
 206 The
 207 .BR memfd_create ()
 208 system call is Linux-specific.
 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 .PP
 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 .PP
 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 .PP
 261 An example of the usage of the sealing mechanism is as follows:
 262 .IP 1. 3
 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 * 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 *
 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 *
 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 .PP
 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 file.
 364 .PP
 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 .PP
 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 .PP
 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 .PP
 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 .PP
 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 <fcntl.h>
 414 #include <stdint.h>
 415 #include <stdio.h>
 416 #include <stdlib.h>
 417 #include <string.h>
 418 #include <sys/mman.h>
 419 #include <unistd.h>
 420
 421 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 422                         } while (0)
 423
 424 int
 425 main(int argc, char *argv[])
 426 {
 427     int fd;
 428     unsigned int seals;
 429     char *name, *seals_arg;
 430     ssize_t len;
 431
 432     if (argc < 3) {
 433         fprintf(stderr, "%s name size [seals]\en", argv[0]);
 434         fprintf(stderr, "\et\(aqseals\(aq can contain any of the "
 435                 "following characters:\en");
 436         fprintf(stderr, "\et\etg \- F_SEAL_GROW\en");
 437         fprintf(stderr, "\et\ets \- F_SEAL_SHRINK\en");
 438         fprintf(stderr, "\et\etw \- F_SEAL_WRITE\en");
 439         fprintf(stderr, "\et\etW \- F_SEAL_FUTURE_WRITE\en");
 440         fprintf(stderr, "\et\etS \- F_SEAL_SEAL\en");
 441         exit(EXIT_FAILURE);
 442     }
 443
 444     name = argv[1];
 445     len = atoi(argv[2]);
 446     seals_arg = argv[3];
 447
 448     /* Create an anonymous file in tmpfs; allow seals to be
 449        placed on the file. */
 450
 451     fd = memfd_create(name, MFD_ALLOW_SEALING);
 452     if (fd == \-1)
 453         errExit("memfd_create");
 454
 455     /* Size the file as specified on the command line. */
 456
 457     if (ftruncate(fd, len) == \-1)
 458         errExit("truncate");
 459
 460     printf("PID: %jd; fd: %d; /proc/%jd/fd/%d\en",
 461            (intmax_t) getpid(), fd, (intmax_t) getpid(), fd);
 462
 463     /* Code to map the file and populate the mapping with data
 464        omitted. */
 465
 466     /* If a \(aqseals\(aq command\-line argument was supplied, set some
 467        seals on the file. */
 468
 469     if (seals_arg != NULL) {
 470         seals = 0;
 471
 472         if (strchr(seals_arg, \(aqg\(aq) != NULL)
 473             seals |= F_SEAL_GROW;
 474         if (strchr(seals_arg, \(aqs\(aq) != NULL)
 475             seals |= F_SEAL_SHRINK;
 476         if (strchr(seals_arg, \(aqw\(aq) != NULL)
 477             seals |= F_SEAL_WRITE;
 478         if (strchr(seals_arg, \(aqW\(aq) != NULL)
 479             seals |= F_SEAL_FUTURE_WRITE;
 480         if (strchr(seals_arg, \(aqS\(aq) != NULL)
 481             seals |= F_SEAL_SEAL;
 482
 483         if (fcntl(fd, F_ADD_SEALS, seals) == \-1)
 484             errExit("fcntl");
 485     }
 486
 487     /* Keep running, so that the file created by memfd_create()
 488        continues to exist. */
 489
 490     pause();
 491
 492     exit(EXIT_SUCCESS);
 493 }
 494 .EE
 495 .\" SRC END
 496 .SS Program source: t_get_seals.c
 497 \&
 498 .\" SRC BEGIN (t_get_seals.c)
 499 .EX
 500 #define _GNU_SOURCE
 501 #include <fcntl.h>
 502 #include <stdio.h>
 503 #include <stdlib.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 .\" SRC END
 547 .SH SEE ALSO
 548 .BR fcntl (2),
 549 .BR ftruncate (2),
 550 .BR memfd_secret (2),
 551 .BR mmap (2),
 552 .BR shmget (2),
 553 .BR shm_open (3)