diff mbox series

[v2] man2: new page describing memfd_secret() system call

Message ID 20210729082900.1581359-1-rppt@kernel.org (mailing list archive)
State New
Headers show
Series [v2] man2: new page describing memfd_secret() system call | expand

Commit Message

Mike Rapoport July 29, 2021, 8:29 a.m. UTC
From: Mike Rapoport <rppt@linux.ibm.com>

Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
---

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

Comments

Alejandro Colomar July 29, 2021, 10:12 a.m. UTC | #1
Hi Mike,

On 7/29/21 10:29 AM, Mike Rapoport wrote:
> From: Mike Rapoport <rppt@linux.ibm.com>
> 
> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
> 
> 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

Please check a small typo introduced in v2 below.

Thanks!

Alex

> 
> 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 <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 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, int " cmd ", unsigned int " flags \
> +", int " cpu_id );

Check the parameter list :)
Mike Rapoport July 29, 2021, 10:30 a.m. UTC | #2
On Thu, Jul 29, 2021 at 12:12:12PM +0200, Alejandro Colomar (man-pages) wrote:
> Hi Mike,
> 
> On 7/29/21 10:29 AM, Mike Rapoport wrote:
> > From: Mike Rapoport <rppt@linux.ibm.com>
> > 
> > Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> > ---
> > 
> > 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
> 
> Please check a small typo introduced in v2 below.
> 
> Thanks!
> 
> Alex
> 
> > 
> > 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 <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 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, int " cmd ", unsigned int " flags \
> > +", int " cpu_id );
> 
> Check the parameter list :)
 
Argh. 

Would you need v3 or this on top would suffice?

diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
index 5a70cb5d2..8263f18d5 100644
--- a/man2/memfd_secret.2
+++ b/man2/memfd_secret.2
@@ -31,8 +31,7 @@ memfd_secret \- create an anonymous file to access secret memory regions
 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-.BI "int syscall(SYS_memfd_secret, int " cmd ", unsigned int " flags \
-", int " cpu_id );
+.BI "int syscall(SYS_memfd_secret, unsigned int " flags ");
 .fi
 .PP
 .IR Note :
Alejandro Colomar July 29, 2021, 11:07 a.m. UTC | #3
Hi Mike,

On 7/29/21 12:30 PM, Mike Rapoport wrote:
> On Thu, Jul 29, 2021 at 12:12:12PM +0200, Alejandro Colomar (man-pages) wrote:
>> Hi Mike,
>>
>> On 7/29/21 10:29 AM, Mike Rapoport wrote:
>>> From: Mike Rapoport <rppt@linux.ibm.com>
>>>
>>> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
>>> ---
[...]

>> Check the parameter list :)
>   
> Argh.
> 
> Would you need v3 or this on top would suffice?

That suffices.  Patch applied.

> 
> diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2
> index 5a70cb5d2..8263f18d5 100644
> --- a/man2/memfd_secret.2
> +++ b/man2/memfd_secret.2
> @@ -31,8 +31,7 @@ memfd_secret \- create an anonymous file to access secret memory regions
>   .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
>   .B #include <unistd.h>
>   .PP
> -.BI "int syscall(SYS_memfd_secret, int " cmd ", unsigned int " flags \
> -", int " cpu_id );
> +.BI "int syscall(SYS_memfd_secret, unsigned int " flags ");

I guess you meant ");", but note that the quotes are not necessary there 
(as there aren't any spaces), so I skipped them.

Cheers,

Alex
diff mbox series

Patch

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 <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 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, 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)