Differential D21393 Diff 62227 lib/libc/sys/memfd_create.2

Changeset View

Standalone View

lib/libc/sys/memfd_create.2

This file was added.

				.\" SPDX-License-Identifier: BSD-2-Clause
				.\"
				.\" Copyright (c) 2019 Kyle Evans <kevans@FreeBSD.org>
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
				.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
				.\" SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd September 17, 2019
				.Dt MEMFD_CREATE 2
				.Os
				.Sh NAME
				.Nm memfd_create
				.Nd Create anonymous shared memory object
				.Sh LIBRARY
				.Lb libc
				.Sh SYNOPSIS
				.In sys/mman.h
				.Ft int
				.Fo memfd_create
				.Fa "const char *name"
				.Fa "unsigned int flags"
				.Fc
				.Sh DESCRIPTION
				The
				.Fn memfd_create
				system call
				jillesUnsubmitted Not Done Inline Actions Do we care that this is no longer a direct system call but a function? jilles: Do we care that this is no longer a direct system call but a function?
				kevansAuthorUnsubmitted Done Inline Actions memfd_create(3) would be reasonable - at one point I was tempted to instead merge the content into shm_open(2) and add shm_open.2 -> memfd_create.3 MLINK. 100 lines of additional content is almost nothing, and these are clearly heavily linked. I do not have strong feelings on move to section 3 vs. merge. kevans: memfd_create(3) would be reasonable - at one point I was tempted to instead merge the content…
				creates an anonymous shared memory object, identical to that created by
				.Xr shm_open 2
				when
				.Dv SHM_ANON
				is specified.
				Newly created objects start off with a size of zero.
				The size of the object must be adjusted via
				.Xr ftruncate 2 .
				.Pp
				The
				.Fa name
				argument must not be
				.Dv NULL ,
				but it may be an empty string.
				The length of the
				.Fa name
				argument may not exceed
				.Dv NAME_MAX
				minus six characters for the prefix
				.Dq memfd: ,
				which will be prepended.
				The
				.Fa name
				argument, while currently unused, is intended solely for debugging purposes and
				markjUnsubmitted Not Done Inline Actions I find the "while currently unused" bit confusing since the rest of the sentence goes on to explain that the kernel will never use it. markj: I find the "while currently unused" bit confusing since the rest of the sentence goes on to…
				kevansAuthorUnsubmitted Done Inline Actions What I was trying to capture is that: It's not currently used for anything The kernel itself can never use the name as an identity for this shmfd, so, for example: conflicts mean nothing, as it's just a label The kernel could eventually expose it to userland (but again, can never use it itself) via procfs/fdescfs or some other mechanism, so a sensible name is a good idea anyways I'm unsure how to convey this in a concise manner suitable for a manpage, though. kevans: What I was trying to capture is that: - It's not currently used for anything - The kernel…
				markjUnsubmitted Not Done Inline Actions I think you could just drop "while currently unused." You could perhaps also add, "Names are therefore not required to be unique." markj: I think you could just drop "while currently unused." You could perhaps also add, "Names are…
				will never be used by the kernel to identify a memfd.
				.Pp
				The following
				.Fa flags
				may be specified:
				.Bl -tag -width MFD_ALLOW_SEALING
				.It Dv MFD_CLOEXEC
				Set
				.Dv FD_CLOEXEC
				on the resulting file descriptor.
				.It Dv MFD_ALLOW_SEALING
				Allow adding seals to the resulting file descriptor using the
				.Dv F_ADD_SEALS
				.Xr fcntl 2 .
				markjUnsubmitted Not Done Inline Actions Missing "command" at the end of the sentence? markj: Missing "command" at the end of the sentence?
				.It Dv MFD_HUGETLB
				This flag is currently unsupported.
				.El
				.Sh RETURN VALUES
				If successful,
				.Fn memfd_create
				returns the file descriptor for the opened file; otherwise the value \-1 is
				returned and the global variable
				.Va errno
				is set to indicate the error.
				.Sh ERRORS
				In addition to the errors returned by
				.Xr shm_open 2 ,
				.Fn memfd_create
				will return
				.Bl -tag -width Er
				.It Bq Er EBADF
				The
				.Fa name
				argument was
				.Dv NULL .
				jillesUnsubmitted Not Done Inline Actions Hmm, do we want to document this copied Linux bug? jilles: Hmm, do we want to document this copied Linux bug?
				kevansAuthorUnsubmitted Done Inline Actions I think we have to, unfortunately, or we'll be just as confusing. I contemplated switching it to EINVAL, but EINVAL is already so incredibly overloaded that it's actually somewhat annoying to debug usage. kevans: I think we have to, unfortunately, or we'll be just as confusing. I contemplated switching it…
				.It Bq Er EINVAL
				The
				.Fa name
				argument was too long.
				.It Bq Er EINVAL
				Any flags not listed above were specified.
				.It Bq Er ENOSYS
				.Dv MFD_HUGETLB
				has been specified, and this system does not support forced hugetlb mappings.
				.El
				.Sh SEE ALSO
				.Xr fcntl 2 ,
				.Xr ftruncate 2 ,
				.Xr shm_open 2
				.Sh STANDARDS
				The
				.Fn memfd_create
				system call is expected to be compatible with the Linux system call of
				the same name.
				.Sh HISTORY
				The
				.Fn memfd_create
				function appeared in
				.Fx 13.0 .