mirror of https://github.com/mkerrisk/man-pages
memfd_secret.2: New page describing memfd_secret() system call
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
824b408b7d
commit
ac5edfeb1d
|
@ -0,0 +1,154 @@
|
|||
.\" 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 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_create(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 (2):
|
||||
.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 (2)
|
||||
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 (2)
|
||||
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 (2)
|
||||
system call first appeared in Linux 5.14.
|
||||
.SH CONFORMING TO
|
||||
The
|
||||
.BR memfd_secret (2)
|
||||
system call is Linux-specific.
|
||||
.SH SEE ALSO
|
||||
.BR fcntl (2),
|
||||
.BR ftruncate (2),
|
||||
.BR mlock (2),
|
||||
.BR mmap (2),
|
||||
.BR setrlimit (2)
|
Loading…
Reference in New Issue