From patchwork Thu Jul 29 08:29:00 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Rapoport X-Patchwork-Id: 12408085 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 375ADC432BE for ; Thu, 29 Jul 2021 08:29:09 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id C5AD860D07 for ; Thu, 29 Jul 2021 08:29:08 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org C5AD860D07 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=kvack.org Received: by kanga.kvack.org (Postfix) id 25B6B6B0036; Thu, 29 Jul 2021 04:29:08 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 20B716B005D; Thu, 29 Jul 2021 04:29:08 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 0FACE6B006C; Thu, 29 Jul 2021 04:29:08 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0066.hostedemail.com [216.40.44.66]) by kanga.kvack.org (Postfix) with ESMTP id E88766B0036 for ; Thu, 29 Jul 2021 04:29:07 -0400 (EDT) Received: from smtpin04.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay03.hostedemail.com (Postfix) with ESMTP id 71A8F824999B for ; Thu, 29 Jul 2021 08:29:07 +0000 (UTC) X-FDA: 78414950334.04.2C18E87 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by imf28.hostedemail.com (Postfix) with ESMTP id 137B7900850C for ; Thu, 29 Jul 2021 08:29:06 +0000 (UTC) Received: by mail.kernel.org (Postfix) with ESMTPSA id 1C81960D07; Thu, 29 Jul 2021 08:29:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1627547346; bh=YkYp2gBenrrqFbWlwBkBunts6riSeDwI8+WtP6GKnb8=; h=From:To:Cc:Subject:Date:From; b=AVxzwWiP5kuwoCTjjVux0Fv5frS1TwUEvdi6KSl1Uo5gevqi/mjmbGu/msrdwXe5m RMLbnY/8G/jiJXGzqtKBp8idSMngH8S1aMJw9Xd/FZMNLO5jXiVUUdU7SEmjQm3geW A7wKjoUW61EVafXnyeqeW4jVk2e/B4+rk3vghRzOq3GFyTe5UzBZMXfhyjJabr26y5 VDvC54XXkc+8rrNEf/3L+3sU1bg+6z58Iuldh2WPHDIGHE0r17097QFfWRYuMWIpPP 4vBAUTHBxkIQGUtcXwqrhAr3rD+40+DvUj/U4Cc2/KXNJiOVDWIXJhBrn7Rt/DGeFf cH5ihMUXxHq/g== From: Mike Rapoport To: Michael Kerrisk , Alejandro Colomar Cc: Mike Rapoport , Mike Rapoport , linux-api@vger.kernel.org, linux-man@vger.kernel.org, linux-mm@kvack.org Subject: [PATCH v2] man2: new page describing memfd_secret() system call Date: Thu, 29 Jul 2021 11:29:00 +0300 Message-Id: <20210729082900.1581359-1-rppt@kernel.org> X-Mailer: git-send-email 2.31.1 MIME-Version: 1.0 Authentication-Results: imf28.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=AVxzwWiP; spf=pass (imf28.hostedemail.com: domain of rppt@kernel.org designates 198.145.29.99 as permitted sender) smtp.mailfrom=rppt@kernel.org; dmarc=pass (policy=none) header.from=kernel.org X-Rspamd-Server: rspam05 X-Rspamd-Queue-Id: 137B7900850C X-Stat-Signature: sw33fjot943m7cm8a3yitnyhjt5eukor X-HE-Tag: 1627547346-600932 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: From: Mike Rapoport Signed-off-by: Mike Rapoport --- v2: address Alex's comments: * update synopsis to match new style for syscalls without a wrapper * drop note about absence of glibc wrapper * update formatting v1: https://lore.kernel.org/linux-api/20210727124140.1487079-1-rppt@kernel.org man2/memfd_secret.2 | 147 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 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..5a70cb5d2 --- /dev/null +++ b/man2/memfd_secret.2 @@ -0,0 +1,147 @@ +.\" Copyright (c) 2021, IBM Corporation. +.\" Written by Mike Rapoport +.\" +.\" Based on memfd_create(2) man page +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 David Herrmann +.\" +.\" %%%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 +.\" . +.\" %%%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 +.PP +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.PP +.BI "int syscall(SYS_memfd_secret, int " cmd ", unsigned int " flags \ +", int " cpu_id ); +.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 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 +.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. +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 SEE ALSO +.BR fcntl (2), +.BR ftruncate (2), +.BR mlock (2), +.BR mmap (2), +.BR setrlimit (2)