man-pages/man2/memfd_create.2

.\" Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
.\" starting from a version by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
.\"
.\" FIXME What is _SW_3_PARA?
.\" 
.\" 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
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.\"
.TH MEMFD_CREATE 2 2014-07-08 Linux "Linux Programmer's Manual"
.SH NAME
memfd_create \- create an anonymous file
.SH SYNOPSIS
.B #include <sys/memfd.h>
.sp
.BI "int memfd_create(const char *" name ", unsigned int " flags ");"
.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.
.\" FIXME In the following sentence I changed "released" to
.\"       "destroyed". Okay?
Once all references to the file are dropped, it is automatically released.
Anonymous memory is used for all backing pages of the file.
.\" FIXME In the following sentence I changed "they" to
.\"       "files created by memfd_create()". Okay?
Therefore, files created by
.BR memfd_create ()
are subject to the same restrictions as other anonymous
.\" FIXME Can you give some examples on some of the restrictions please.
memory allocations such as those allocated using
.BR mmap (2)
with the
.BR MAP_ANONYMOUS
flag.

The initial size of the file is set to 0.
Following the call, the file size should be set using
.BR ftruncate (2).

The name supplied in
.I name
is used as an internal filename and will appear
.\" FIXME What does "internal" in the previous line mean?
as the target of the corresponding symbolic link in the directory
.\" FIXME I added the previous line. Is it correct?
.IR /proc/self/fd/ .
.\" FIXME In the next line, I added "as displayed in that 
The displayed name is always prefixed with
.IR memfd:
and serves only for debugging purposes.
Names do not affect the behavior of the memfd,
.\" FIXME The term "memfd" appears here without having previously been
.\"       defined. Would the correct definition "the memfd" be
.\"       "the file descriptor created by memfd_create"?
and as such multiple files can have the same name without any side effects.

The following values may be bitwise ORed in
.IR flags
to change the behaviour of
.BR memfd_create ():
.TP
.BR 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
.BR MFD_ALLOW_SEALING
Allow sealing operations (see
.BR fcntl (2)
with
.B F_ADD_SEALS
and
.BR F_GET_SEALS )
on this file.
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?
.PP
Unused bits in
.I flags
must be 0.

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 descriptor.

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
.IR name
points to invalid memory.
.TP
.B EINVAL
An unsupported value was specified in one of the arguments:
.I flags
included unknown bits, or
.I name
was too long.
.TP
.B EMFILE
The per-process limit on 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.
.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.
.SH CONFORMING TO
The
.BR memfd_create ()
system call is Linux-specific.
.\" FIXME Do we have any nice example program that could go in the man page?
.SH SEE ALSO
.BR fcntl (2),
.\" FIXME Why the reference to shmget(2) in particular (and not,
.\"       e.g., shm_open(3), mmap(2))?
.BR shmget (2)