Re: [PATCH] Linux: Add memfd_create system call wrapper

[Rical Jasan <ricaljasan at pacific dot net>]

On 11/18/2017 09:32 AM, Florian Weimer wrote:
> diff --git a/manual/llio.texi b/manual/llio.texi
> index 8c7c58c216..625fe49ac1 100644
> --- a/manual/llio.texi
> +++ b/manual/llio.texi
> @@ -1808,6 +1808,69 @@ the given @var{name} previously created by @code{shm_open}.
>  On failure @code{errno} is set.
>  @end deftypefn
>  
> +@deftypefn Function int memfd_create (const char *@var{name}, unsigned int flags)

"@var{flags}"

Use @deftypefun, and drop "Function" (shortcut).

> +@standards{Linux, sys/mman.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
> +The @code{memfd_create} function returns a file descriptor which can be
> +used to create memory mappings using the @code{mmap} function.  It is
> +similar to the @code{shm_open} function in the sense that these mappings
> +are not backed by actual files.  However, the descriptor return by

"returned"

> +@code{memfd_create} does not correspond to a named object; the
> +@var{name} argument is used for informative purposes only.  The

I see in mman-linux.h, "NAME is a name for debugging."  Can we say
"debugging purposes" here?  As-is, it sounds ignored, and doesn't really
hint at what type of information one could get from it or how.

> +descriptor can be passed between processes (for example, over local
> +domain sockets), and mappings at the same offset refer to the same
> +memory, or the descriptor can be used to create alias mappings within
> +the same process.

The and/or here is odd.  What about: "...the same memory.  The
descriptor can also be used..."

> +
> +The descriptor initially refers to a zero-length file.  Before mappings
> +can be created which are backed by memory, the file size needs to be
> +increased with the @code{ftruncate} function.  @xref{File Size}.
> +
> +The @var{flags} argument can be a combination of the following flags:
> +
> +@vtable @code
> +@item MFD_CLOEXEC
> +@standards{Linux, sys/mman.h}
> +The descriptor is created with the @code{O_CLOEXEC} flag.
> +
> +@item MFD_ALLOW_SEALING
> +@standards{Linux, sys/mman.h}
> +The descriptor supports the addition of seals using the @code{fcntl}
> +function.
> +
> +@item MFD_HUGETLB
> +@standards{Linux, sys/mman.h}
> +This requests that mappings created using the returned file descriptor
> +use a larger page size.  See @code{MAP_HUGETLB} above for details.
> +
> +This flag is incompatible with @code{MFD_ALLOW_SEALING}.
> +@end vtable
> +
> +@code{memfd_create} returns a file descriptor on success, and @math{-1}

I think @code for return values is more appropriate.

> +on failure.
> +
> +The following @code{errno} error conditions are defined for this
> +function:
> +
> +@table @code
> +@item EINVAL
> +An invalid combination is specified in @var{flags}, or @var{name} is
> +too long.
> +
> +@item EFAULT
> +The @var{name} argument does not point to a string.
> +
> +@item EMFILE
> +The operation would exceed the file descriptor limit for this process.
> +
> +@item ENFILE
> +The operation would exceed the system-wide file descriptor limit.
> +
> +@item ENOMEM
> +There is not enough memory for the operation.
> +@end table
> +@end deftypefn

OK.

> diff --git a/sysdeps/unix/sysv/linux/bits/mman-linux.h b/sysdeps/unix/sysv/linux/bits/mman-linux.h
> index 78c07c890a..1ffa5490af 100644
> --- a/sysdeps/unix/sysv/linux/bits/mman-linux.h
> +++ b/sysdeps/unix/sysv/linux/bits/mman-linux.h
> @@ -111,3 +111,19 @@
>  # define MCL_ONFAULT	4		/* Lock all pages that are
>  					   faulted in.  */
>  #endif
> +
> +#ifdef __USE_GNU
> +/* Flags for memfd_create.  */
> +# define MFD_CLOEXEC 1U
> +# define MFD_ALLOW_SEALING 2U
> +# define MFD_HUGETLB 4U
> +
> +__BEGIN_DECLS
> +
> +/* Create a new memory file descriptor.  NAME is a name for debugging.
> +   FLAGS is a combination of the MFD_* constants.  */
> +int memfd_create (const char *__name, unsigned int __flags) __THROW;
> +
> +__END_DECLS
> +
> +#endif /* __USE_GNU */

Leaving this part for reference.

Thank you,
Rical