Re: [PATCH v3] man2: new page describing memfd_secret() system call

Michael Kerrisk (man-pages)
2021-08-16T06:49:43Z

Hi Mike,

On 8/16/21 7:19 AM, Mike Rapoport wrote:
> On Mon, Aug 16, 2021 at 02:29:33AM +0200, Michael Kerrisk (man-pages) wrote:
>> Hi Mike,
>>
>> Thanks for this update!
>>
>> On 8/15/21 8:46 AM, Mike Rapoport wrote:
>>> From: Mike Rapoport <rppt@linux.ibm.com>
>>>
>>> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
>>> ---
>>> v3:
>>> * Incorporate Michael's feedback except the extensive NOTES section.
>>
>> Hmmmm :-|
>>
>>> v2: https://lore.kernel.org/linux-api/20210729082900.1581359-1-rppt@kernel.org
>>> 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 | 154 ++++++++++++++++++++++++++++++++++++++++++++
>>> 1 file changed, 154 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..188c547bf
>>> --- /dev/null
>>> +++ b/man2/memfd_secret.2
>>> @@ -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.
>>
>> I suggested:
>> s/anonymous/anonymous/ RAM-based/
>>
>> was there a reason not to do that?
>
> It seems I've just missed this one.
> Would you like me to send v4 or you can update while applying?

I've applied the patch, and added this edit. Thank you for
writing the page!

>>> +The file provides a way to create and access memory regions
>>> +with stronger protection than usual RAM-based files and
>>> +anonymous memory mappings.
>
> ...
>
>>> +.SH SEE ALSO
>>> +.BR fcntl (2),
>>> +.BR ftruncate (2),
>>> +.BR mlock (2),
>>> +.BR mmap (2),
>>> +.BR setrlimit (2)
>> Thanks! The page looks much better, but sill, that NOTES section
>> that I proposed [1] would be really useful, I think. What are
>> the chances that you could put that together?
>
> I will, hopefully I'll be able to find the time for this in the next few
> weeks.

I'll be back :-).

Cheers,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/