diff options
Diffstat (limited to 'man/man2/memfd_create.2')
| -rw-r--r-- | man/man2/memfd_create.2 | 549 |
1 files changed, 549 insertions, 0 deletions
diff --git a/man/man2/memfd_create.2 b/man/man2/memfd_create.2 new file mode 100644 index 000000000..794aa0e54 --- /dev/null +++ b/man/man2/memfd_create.2 @@ -0,0 +1,549 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH memfd_create 2 (date) "Linux man-pages (unreleased)" +.SH NAME +memfd_create \- create an anonymous file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <sys/mman.h> +.P +.BI "int memfd_create(const char *" name ", unsigned int " flags ");" +.fi +.SH DESCRIPTION +.BR memfd_create () +creates an anonymous file and returns a file descriptor that refers to it. +The file behaves like a regular file, and so can be modified, +truncated, memory-mapped, and so on. +However, unlike a regular file, +it lives in RAM and has a volatile backing storage. +Once all references to the file are dropped, it is automatically released. +Anonymous memory is used for all backing pages of the file. +Therefore, files created by +.BR memfd_create () +have the same semantics as other anonymous +.\" David Herrmann: +.\" memfd uses VM_NORESERVE so each page is accounted on first access. +.\" This means, the overcommit-limits (see __vm_enough_memory()) and the +.\" memory-cgroup limits (mem_cgroup_try_charge()) are applied. Note that +.\" those are accounted on "current" and "current->mm", that is, the +.\" process doing the first page access. +memory allocations such as those allocated using +.BR mmap (2) +with the +.B MAP_ANONYMOUS +flag. +.P +The initial size of the file is set to 0. +Following the call, the file size should be set using +.BR ftruncate (2). +(Alternatively, the file may be populated by calls to +.BR write (2) +or similar.) +.P +The name supplied in +.I name +is used as a filename and will be displayed +as the target of the corresponding symbolic link in the directory +.IR /proc/self/fd/ . +The displayed name is always prefixed with +.I memfd: +and serves only for debugging purposes. +Names do not affect the behavior of the file descriptor, +and as such multiple files can have the same name without any side effects. +.P +The following values may be bitwise ORed in +.I flags +to change the behavior of +.BR memfd_create (): +.TP +.B MFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.TP +.B MFD_ALLOW_SEALING +Allow sealing operations on this file. +See the discussion of the +.B F_ADD_SEALS +and +.B F_GET_SEALS +operations in +.BR fcntl (2), +and also NOTES, below. +The initial set of seals is empty. +If this flag is not set, the initial set of seals will be +.BR F_SEAL_SEAL , +meaning that no other seals can be set on the file. +.\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default? +.\" Is it worth adding some text explaining this? +.TP +.BR MFD_HUGETLB " (since Linux 4.14)" +.\" commit 749df87bd7bee5a79cef073f5d032ddb2b211de8 +The anonymous file will be created in the hugetlbfs filesystem using +huge pages. +See the Linux kernel source file +.I Documentation/admin\-guide/mm/hugetlbpage.rst +for more information about hugetlbfs. +.\" commit 47b9012ecdc747f6936395265e677d41e11a31ff +Specifying both +.B MFD_HUGETLB +and +.B MFD_ALLOW_SEALING +in +.I flags +is supported since Linux 4.16. +.TP +.B MFD_HUGE_2MB +.TQ +.B MFD_HUGE_1GB +.TQ +\&.\|.\|. +Used in conjunction with +.B MFD_HUGETLB +to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...) +on systems that support multiple hugetlb page sizes. +Definitions for known +huge page sizes are included in the header file +.I <linux/memfd.h>. +.IP +For details on encoding huge page sizes not included in the header file, +see the discussion of the similarly named constants in +.BR mmap (2). +.P +Unused bits in +.I flags +must be 0. +.P +As its return value, +.BR memfd_create () +returns a new file descriptor that can be used to refer to the file. +This file descriptor is opened for both reading and writing +.RB ( O_RDWR ) +and +.B O_LARGEFILE +is set for the file descriptor. +.P +With respect to +.BR fork (2) +and +.BR execve (2), +the usual semantics apply for the file descriptor created by +.BR memfd_create (). +A copy of the file descriptor is inherited by the child produced by +.BR fork (2) +and refers to the same file. +The file descriptor is preserved across +.BR execve (2), +unless the close-on-exec flag has been set. +.SH RETURN VALUE +On success, +.BR memfd_create () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The address in +.I name +points to invalid memory. +.TP +.B EINVAL +.I flags +included unknown bits. +.TP +.B EINVAL +.I name +was too long. +(The limit is +.\" NAME_MAX - strlen("memfd:") +249 bytes, excluding the terminating null byte.) +.TP +.B EINVAL +Both +.B MFD_HUGETLB +and +.B MFD_ALLOW_SEALING +were specified in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create a new anonymous file. +.TP +.B EPERM +The +.B MFD_HUGETLB +flag was specified, but the caller was not privileged (did not have the +.B CAP_IPC_LOCK +capability) +and is not a member of the +.I sysctl_hugetlb_shm_group +group; see the description of +.I /proc/sys/vm/sysctl_hugetlb_shm_group +in +.BR proc (5). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.17, +glibc 2.27. +.SH NOTES +.\" See also http://lwn.net/Articles/593918/ +.\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/ +The +.BR memfd_create () +system call provides a simple alternative to manually mounting a +.BR tmpfs (5) +filesystem and creating and opening a file in that filesystem. +The primary purpose of +.BR memfd_create () +is to create files and associated file descriptors that are +used with the file-sealing APIs provided by +.BR fcntl (2). +.P +The +.BR memfd_create () +system call also has uses without file sealing +(which is why file-sealing is disabled, unless explicitly requested with the +.B MFD_ALLOW_SEALING +flag). +In particular, it can be used as an alternative to creating files in +.I tmp +or as an alternative to using the +.BR open (2) +.B O_TMPFILE +in cases where there is no intention to actually link the +resulting file into the filesystem. +.SS File sealing +In the absence of file sealing, +processes that communicate via shared memory must either trust each other, +or take measures to deal with the possibility that an untrusted peer +may manipulate the shared memory region in problematic ways. +For example, an untrusted peer might modify the contents of the +shared memory at any time, or shrink the shared memory region. +The former possibility leaves the local process vulnerable to +time-of-check-to-time-of-use race conditions +(typically dealt with by copying data from +the shared memory region before checking and using it). +The latter possibility leaves the local process vulnerable to +.B SIGBUS +signals when an attempt is made to access a now-nonexistent +location in the shared memory region. +(Dealing with this possibility necessitates the use of a handler for the +.B SIGBUS +signal.) +.P +Dealing with untrusted peers imposes extra complexity on +code that employs shared memory. +Memory sealing enables that extra complexity to be eliminated, +by allowing a process to operate secure in the knowledge that +its peer can't modify the shared memory in an undesired fashion. +.P +An example of the usage of the sealing mechanism is as follows: +.IP (1) 5 +The first process creates a +.BR tmpfs (5) +file using +.BR memfd_create (). +The call yields a file descriptor used in subsequent steps. +.IP (2) +The first process +sizes the file created in the previous step using +.BR ftruncate (2), +maps it using +.BR mmap (2), +and populates the shared memory with the desired data. +.IP (3) +The first process uses the +.BR fcntl (2) +.B F_ADD_SEALS +operation to place one or more seals on the file, +in order to restrict further modifications on the file. +(If placing the seal +.BR F_SEAL_WRITE , +then it will be necessary to first unmap the shared writable mapping +created in the previous step. +Otherwise, behavior similar to +.B F_SEAL_WRITE +can be achieved by using +.BR F_SEAL_FUTURE_WRITE , +which will prevent future writes via +.BR mmap (2) +and +.BR write (2) +from succeeding while keeping existing shared writable mappings). +.IP (4) +A second process obtains a file descriptor for the +.BR tmpfs (5) +file and maps it. +Among the possible ways in which this could happen are the following: +.RS +.IP \[bu] 3 +The process that called +.BR memfd_create () +could transfer the resulting file descriptor to the second process +via a UNIX domain socket (see +.BR unix (7) +and +.BR cmsg (3)). +The second process then maps the file using +.BR mmap (2). +.IP \[bu] +The second process is created via +.BR fork (2) +and thus automatically inherits the file descriptor and mapping. +(Note that in this case and the next, +there is a natural trust relationship between the two processes, +since they are running under the same user ID. +Therefore, file sealing would not normally be necessary.) +.IP \[bu] +The second process opens the file +.IR /proc/ pid /fd/ fd, +where +.I <pid> +is the PID of the first process (the one that called +.BR memfd_create ()), +and +.I <fd> +is the number of the file descriptor returned by the call to +.BR memfd_create () +in that process. +The second process then maps the file using +.BR mmap (2). +.RE +.IP (5) +The second process uses the +.BR fcntl (2) +.B F_GET_SEALS +operation to retrieve the bit mask of seals +that has been applied to the file. +This bit mask can be inspected in order to determine +what kinds of restrictions have been placed on file modifications. +If desired, the second process can apply further seals +to impose additional restrictions (so long as the +.B F_SEAL_SEAL +seal has not yet been applied). +.SH EXAMPLES +Below are shown two example programs that demonstrate the use of +.BR memfd_create () +and the file sealing API. +.P +The first program, +.IR t_memfd_create.c , +creates a +.BR tmpfs (5) +file using +.BR memfd_create (), +sets a size for the file, maps it into memory, +and optionally places some seals on the file. +The program accepts up to three command-line arguments, +of which the first two are required. +The first argument is the name to associate with the file, +the second argument is the size to be set for the file, +and the optional third argument is a string of characters that specify +seals to be set on the file. +.P +The second program, +.IR t_get_seals.c , +can be used to open an existing file that was created via +.BR memfd_create () +and inspect the set of seals that have been applied to that file. +.P +The following shell session demonstrates the use of these programs. +First we create a +.BR tmpfs (5) +file and set some seals on it: +.P +.in +4n +.EX +$ \fB./t_memfd_create my_memfd_file 4096 sw &\fP +[1] 11775 +PID: 11775; fd: 3; /proc/11775/fd/3 +.EE +.in +.P +At this point, the +.I t_memfd_create +program continues to run in the background. +From another program, we can obtain a file descriptor for the +file created by +.BR memfd_create () +by opening the +.IR /proc/ pid /fd +file that corresponds to the file descriptor opened by +.BR memfd_create (). +Using that pathname, we inspect the content of the +.IR /proc/ pid /fd +symbolic link, and use our +.I t_get_seals +program to view the seals that have been placed on the file: +.P +.in +4n +.EX +$ \fBreadlink /proc/11775/fd/3\fP +/memfd:my_memfd_file (deleted) +$ \fB./t_get_seals /proc/11775/fd/3\fP +Existing seals: WRITE SHRINK +.EE +.in +.SS Program source: t_memfd_create.c +\& +.\" SRC BEGIN (t_memfd_create.c) +.EX +#define _GNU_SOURCE +#include <err.h> +#include <fcntl.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/mman.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *name, *seals_arg; + ssize_t len; + unsigned int seals; +\& + if (argc < 3) { + fprintf(stderr, "%s name size [seals]\en", argv[0]); + fprintf(stderr, "\et\[aq]seals\[aq] can contain any of the " + "following characters:\en"); + fprintf(stderr, "\et\etg \- F_SEAL_GROW\en"); + fprintf(stderr, "\et\ets \- F_SEAL_SHRINK\en"); + fprintf(stderr, "\et\etw \- F_SEAL_WRITE\en"); + fprintf(stderr, "\et\etW \- F_SEAL_FUTURE_WRITE\en"); + fprintf(stderr, "\et\etS \- F_SEAL_SEAL\en"); + exit(EXIT_FAILURE); + } +\& + name = argv[1]; + len = atoi(argv[2]); + seals_arg = argv[3]; +\& + /* Create an anonymous file in tmpfs; allow seals to be + placed on the file. */ +\& + fd = memfd_create(name, MFD_ALLOW_SEALING); + if (fd == \-1) + err(EXIT_FAILURE, "memfd_create"); +\& + /* Size the file as specified on the command line. */ +\& + if (ftruncate(fd, len) == \-1) + err(EXIT_FAILURE, "truncate"); +\& + printf("PID: %jd; fd: %d; /proc/%jd/fd/%d\en", + (intmax_t) getpid(), fd, (intmax_t) getpid(), fd); +\& + /* Code to map the file and populate the mapping with data + omitted. */ +\& + /* If a \[aq]seals\[aq] command\-line argument was supplied, set some + seals on the file. */ +\& + if (seals_arg != NULL) { + seals = 0; +\& + if (strchr(seals_arg, \[aq]g\[aq]) != NULL) + seals |= F_SEAL_GROW; + if (strchr(seals_arg, \[aq]s\[aq]) != NULL) + seals |= F_SEAL_SHRINK; + if (strchr(seals_arg, \[aq]w\[aq]) != NULL) + seals |= F_SEAL_WRITE; + if (strchr(seals_arg, \[aq]W\[aq]) != NULL) + seals |= F_SEAL_FUTURE_WRITE; + if (strchr(seals_arg, \[aq]S\[aq]) != NULL) + seals |= F_SEAL_SEAL; +\& + if (fcntl(fd, F_ADD_SEALS, seals) == \-1) + err(EXIT_FAILURE, "fcntl"); + } +\& + /* Keep running, so that the file created by memfd_create() + continues to exist. */ +\& + pause(); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Program source: t_get_seals.c +\& +.\" SRC BEGIN (t_get_seals.c) +.EX +#define _GNU_SOURCE +#include <err.h> +#include <fcntl.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ + int fd; + unsigned int seals; +\& + if (argc != 2) { + fprintf(stderr, "%s /proc/PID/fd/FD\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd = open(argv[1], O_RDWR); + if (fd == \-1) + err(EXIT_FAILURE, "open"); +\& + seals = fcntl(fd, F_GET_SEALS); + if (seals == \-1) + err(EXIT_FAILURE, "fcntl"); +\& + printf("Existing seals:"); + if (seals & F_SEAL_SEAL) + printf(" SEAL"); + if (seals & F_SEAL_GROW) + printf(" GROW"); + if (seals & F_SEAL_WRITE) + printf(" WRITE"); + if (seals & F_SEAL_FUTURE_WRITE) + printf(" FUTURE_WRITE"); + if (seals & F_SEAL_SHRINK) + printf(" SHRINK"); + printf("\en"); +\& + /* Code to map the file and access the contents of the + resulting mapping omitted. */ +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fcntl (2), +.BR ftruncate (2), +.BR memfd_secret (2), +.BR mmap (2), +.BR shmget (2), +.BR shm_open (3) |