From: Mike Rapoport <email@example.com> To: Michael Kerrisk <firstname.lastname@example.org> Cc: Alejandro Colomar <email@example.com>, Mike Rapoport <firstname.lastname@example.org>, Mike Rapoport <email@example.com>, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org Subject: [PATCH] man2: new page describing memfd_secret() system call Date: Tue, 27 Jul 2021 15:41:40 +0300 [thread overview] Message-ID: <email@example.com> (raw) From: Mike Rapoport <firstname.lastname@example.org> Signed-off-by: Mike Rapoport <email@example.com> --- Hi, There were a lot of changes to memfd_secret implementation since the previous posting of this man page, so its contents also changed significantly and there is not much sense to call it v2. man2/memfd_secret.2 | 143 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 man2/memfd_secret.2 diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2 new file mode 100644 index 000000000..e6eee7018 --- /dev/null +++ b/man2/memfd_secret.2 @@ -0,0 +1,143 @@ +.\" Copyright (c) 2021, IBM Corporation. +.\" Written by Mike Rapoport <firstname.lastname@example.org> +.\" +.\" Based on memfd_create(2) man page +.\" Copyright (C) 2014 Michael Kerrisk <email@example.com> +.\" and Copyright (C) 2014 David Herrmann <firstname.lastname@example.org> +.\" +.\" %%%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 file to access secret memory regions +.SH SYNOPSIS +.nf +.BI "int memfd_secret(unsigned int " flags ");" +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.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 references to the file are dropped, 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 contexts that have access to the file descriptor. +These areas are removed from the kernel page tables +and only the page tables of the processes holding the file descriptor +map the corresponding physical memory. +.PP +The following values may be bitwise ORed in +.IR flags +to control the behavior of +.BR memfd_secret (2): +.TP +.BR FD_CLOEXEC +Set the close-on-exec 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. +.PP +As its return value, +.BR memfd_secret () +returns a new file descriptor that can be used to refer 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 regions backed with +.BR memfd_secret () +are locked in the same way as +.BR mlock (2), +however the implementation will not try to +populate the whole range during the +.BR mmap (2) +call. +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 (2) +system call first appeared in Linux 5.14. +.SH CONFORMING TO +The +.BR memfd_secret (2) +system call is Linux-specific. +.SH NOTES +.PP +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.SH SEE ALSO +.BR fcntl (2), +.BR ftruncate (2), +.BR mlock (2), +.BR mmap (2), +.BR setrlimit (2) -- 2.31.1
next reply other threads:[~2021-07-27 12:41 UTC|newest] Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-07-27 12:41 Mike Rapoport [this message] 2021-07-28 20:44 ` Alejandro Colomar (man-pages) -- strict thread matches above, loose matches on Subject: below -- 2020-09-24 13:28 [PATCH v6 0/6] mm: introduce memfd_secret system call to create "secret" memory areas Mike Rapoport 2020-09-24 13:35 ` [PATCH] man2: new page describing memfd_secret() system call Mike Rapoport 2020-09-24 14:55 ` Alejandro Colomar 2020-10-03 9:32 ` Alejandro Colomar 2020-10-05 7:32 ` Mike Rapoport
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [PATCH] man2: new page describing memfd_secret() system call' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).