.\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
.\"
.\" %%%LICENSE_START(GPLv2+)
-.\"
+.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.\"
-.TH MEMFD_CREATE 2 2015-01-22 Linux "Linux Programmer's Manual"
+.TH MEMFD_CREATE 2 2018-02-02 Linux "Linux Programmer's Manual"
.SH NAME
memfd_create \- create an anonymous file
.SH SYNOPSIS
-.B #include <sys/memfd.h>
-.sp
+.nf
+.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
+.B #include <sys/mman.h>
+.PP
.BI "int memfd_create(const char *" name ", unsigned int " flags ");"
.SH DESCRIPTION
.BR memfd_create ()
with the
.BR MAP_ANONYMOUS
flag.
-
+.PP
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.)
-
+.PP
The name supplied in
.I name
is used as a filename and will be displayed
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.
-
+.PP
The following values may be bitwise ORed in
.IR flags
-to change the behaviour of
+to change the behavior of
.BR memfd_create ():
.TP
.BR MFD_CLOEXEC
.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?
+.\" 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
+.BR MFD_HUGE_2MB ", " MFD_HUGE_1GB ", " "..."
+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).
.PP
Unused bits in
.I flags
must be 0.
-
+.PP
As its return value,
.BR memfd_create ()
returns a new file descriptor that can be used to refer to the file.
.RB ( O_RDWR )
and
.B O_LARGEFILE
-is set for the descriptor.
-
+is set for the file descriptor.
+.PP
With respect to
.BR fork (2)
and
points to invalid memory.
.TP
.B EINVAL
-An unsupported value was specified in one of the arguments:
.I flags
-included unknown bits, or
+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 open file descriptors has been reached.
+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.
.SH VERSIONS
The
.BR memfd_create ()
-system call first appeared in Linux 3.17.
-.\" FIXME . When glibc support appears, update the following sentence:
-Support in the GNU C library is pending.
+system call first appeared in Linux 3.17;
+glibc support was added in version 2.27.
.SH CONFORMING TO
The
.BR memfd_create ()
system call is Linux-specific.
.SH NOTES
+.PP
.\" 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
-.I tmpfs
+.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).
-
+.PP
The
.BR memfd_create ()
system call also has uses without file sealing
(Dealing with this possibility necessitates the use of a handler for the
.BR SIGBUS
signal.)
-
+.PP
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.
-
+.PP
An example of the usage of the sealing mechanism is as follows:
-
.IP 1. 3
The first process creates a
-.I tmpfs
-file using
+.BR tmpfs (5)
+file using
.BR memfd_create ().
The call yields a file descriptor used in subsequent steps.
.IP 2.
created in the previous step.)
.IP 4.
A second process obtains a file descriptor for the
-.I tmpfs
+.BR tmpfs (5)
file and maps it.
Among the possible ways in which this could happen are the following:
.RS
since they are running under the same user ID.
Therefore, file sealing would not normally be necessary.)
.IP *
-The second process opens the file
-.IR /proc/<pd>/fd/<fd> ,
+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
Below are shown two example programs that demonstrate the use of
.BR memfd_create ()
and the file sealing API.
-
+.PP
The first program,
.IR t_memfd_create.c ,
creates a
-.I tmpfs
+.BR tmpfs (5)
file using
.BR memfd_create (),
sets a size for the file, maps it into memory,
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 is a string of characters that specify
+and the optional third argument is a string of characters that specify
seals to be set on file.
-
+.PP
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.
-
+.PP
The following shell session demonstrates the use of these programs.
First we create a
-.I tmpfs
+.BR tmpfs (5)
file and set some seals on it:
-
+.PP
.in +4n
-.nf
+.EX
$ \fB./t_memfd_create my_memfd_file 4096 sw &\fP
[1] 11775
PID: 11775; fd: 3; /proc/11775/fd/3
-.fi
+.EE
.in
-
+.PP
At this point, the
.I t_memfd_create
program continues to run in the background.
file created by
.BR memfd_create ()
by opening the
-.IR /proc/PID/fd
-file that corresponds to the descriptor opened by
+.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
+.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:
-
+.PP
.in +4n
-.nf
+.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
-.fi
+.EE
.in
.SS Program source: t_memfd_create.c
\&
-.nf
-#include <sys/memfd.h>
+.EX
+#define _GNU_SOURCE
+#include <sys/mman.h>
#include <fcntl.h>
#include <stdlib.h>
#include <unistd.h>
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.SS Program source: t_get_seals.c
\&
-.nf
-#include <sys/memfd.h>
+.EX
+#define _GNU_SOURCE
+#include <sys/mman.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdlib.h>
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.SH SEE ALSO
.BR fcntl (2),
.BR ftruncate (2),
projects / thirdparty / man-pages.git / blobdiff