termios.3: CIBAUD and IBSHIFT are implemented on Linux, just unsupported by glibc

[thirdparty/man-pages.git] / man2 / memfd_secret.2

.\" Copyright (c) 2021, IBM Corporation.
.\" Written by Mike Rapoport <rppt@linux.ibm.com>
.\"
.\" Based on memfd_create(2) man page
.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\" 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
.\" (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_SECRET 2 2020-08-02 Linux "Linux Programmer's Manual"
.SH NAME
memfd_secret \- create an anonymous RAM-based file
to access secret memory regions
.SH SYNOPSIS
.nf
.PP
.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.PP
.BI "int syscall(SYS_memfd_secret, unsigned int " flags );
.fi
.PP
.IR Note :
glibc provides no wrapper for
.BR memfd_secret (),
necessitating the use of
.BR syscall (2).
.SH DESCRIPTION
.BR memfd_secret ()
creates an anonymous RAM-based file and returns a file descriptor
that refers to it.
The file provides a way to create and access memory regions
with stronger protection than usual RAM-based files and
anonymous memory mappings.
Once all open references to the file are closed,
it is automatically released.
The initial size of the file is set to 0.
Following the call, the file size should be set using
.BR ftruncate (2).
.PP
The memory areas backing the file created with
.BR memfd_secret (2)
are visible only to the processes that have access to the file descriptor.
The memory region is removed from the kernel page tables
and only the page tables of the processes holding the file descriptor
map the corresponding physical memory.
(Thus, the pages in the region can't be accessed by the kernel itself,
so that, for example, pointers to the region can't be passed to
system calls.)
.PP
The following values may be bitwise ORed in
.I flags
to control the behavior of
.BR memfd_secret ():
.TP
.B FD_CLOEXEC
Set the close-on-exec flag on the new file descriptor,
which causes the region to be removed from the process on
.BR execve (2).
See the description of the
.B O_CLOEXEC
flag in
.BR open (2)
.PP
As its return value,
.BR memfd_secret ()
returns a new file descriptor that refers to an anonymous file.
This file descriptor is opened for both reading and writing
.RB ( O_RDWR )
and
.B O_LARGEFILE
is set for the file descriptor.
.PP
With respect to
.BR fork (2)
and
.BR execve (2),
the usual semantics apply for the file descriptor created by
.BR memfd_secret ().
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.
.PP
The memory region is locked into memory in the same way as with
.BR mlock (2),
so that it will never be written into swap.
However the implementation of
.BR memfd_secret ()
will not try to populate the whole range during the
.BR mmap (2)
call that attaches the region into the process's address space;
instead, the pages are only actually allocated
as they are faulted in.
The amount of memory allowed for memory mappings
of the file descriptor obeys the same rules as
.BR mlock (2)
and cannot exceed
.BR RLIMIT_MEMLOCK .
.SH RETURN VALUE
On success,
.BR memfd_secret ()
returns a new file descriptor.
On error, \-1 is returned and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EINVAL
.I flags
included unknown bits.
.TP
.B EMFILE
The per-process limit on the number of open file descriptors has been reached.
.TP
.B EMFILE
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 ENOSYS
.BR memfd_secret ()
is not implemented on this architecture.
.SH VERSIONS
The
.BR memfd_secret ()
system call first appeared in Linux 5.14.
.SH CONFORMING TO
The
.BR memfd_secret ()
system call is Linux-specific.
.SH SEE ALSO
.BR fcntl (2),
.BR ftruncate (2),
.BR mlock (2),
.BR memfd_create (2),
.BR mmap (2),
.BR setrlimit (2)