Differential D11306 Diff 30012 lib/libc/sys/mmap.2

Changeset View

Standalone View

lib/libc/sys/mmap.2

	Show All 22 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" 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			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95			.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd February 4, 2017			.Dd June 22, 2017
	.Dt MMAP 2			.Dt MMAP 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm mmap			.Nm mmap
	.Nd allocate memory, or map files or devices into memory			.Nd allocate memory, or map files or devices into memory
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	▲ Show 20 Lines • Show All 154 Lines • ▼ Show 20 Lines
	to			to
	.Fa addr			.Fa addr
	+			+
	.Fa len .			.Fa len .
	In contrast, if			In contrast, if
	.Dv MAP_EXCL			.Dv MAP_EXCL
	is specified, the request will fail if a mapping			is specified, the request will fail if a mapping
	already exists within the range.			already exists within the range.
	.It Dv MAP_HASSEMAPHORE			.It Dv MAP_GUARD
	Notify the kernel that the region may contain semaphores and that special			Instead of a mapping, create a guard of the specified size.
				markjUnsubmitted Done Inline Actions "a mapping" markj: "a mapping"
	handling may be necessary.			Guards allow a process to create reservations in its address space,
				emasteUnsubmitted Not Done Inline Actions "within its address range" or "overapping its address range" or something like that? and in light of the below (MAP_FIXED), what about: The guard prevents mappings without the MAP_FIXED flag from overlapping its address range. The range may become part of a mapping after the guard is unmapped, or another mapping is created with the MAP_FIXED flag. emaste: "within its address range" or "overapping its address range" or something like that? and in…
				markjUnsubmitted Done Inline Actions I would write this sentence as "mmap(2) will not create mappings in the address range of a guard unless the request specifies MAP_FIXED. Guards can be destroyed with munmap(2)." In particular, since we're being careful to distinguish between guards and mappings, it seems strange to state that a guard can be unmapped. markj: I would write this sentence as "mmap(2) will not create mappings in the address range of a…
				emasteUnsubmitted Not Done Inline Actions Sounds good. emaste: Sounds good.
				which can later be replaced by actual mappings.
				.Pp
				.Fa mmap
				will not create mappings in the address range of a guard unless
				the request specifies
				markjUnsubmitted Done Inline Actions "results in the delivery of a SIGSEGV signal to the thread" markj: "results in the delivery of a SIGSEGV signal to the thread"
				emasteUnsubmitted Not Done Inline Actions results in the SIGSEGV signal being delivered to the thread. emaste: results in the SIGSEGV signal being delivered to the thread.
				.Dv MAP_FIXED .
				Guards can be destroyed with
				.Xr munmap 2 .
				bjkUnsubmitted Not Done Inline Actions I mayyyybe could see "the thread" being ambiguous to some hypothetical reader (as opposed to "the thread performing the access"), but it's very hard to imagine this causing confusion. bjk: I mayyyybe could see "the thread" being ambiguous to some hypothetical reader (as opposed to…
				alcUnsubmitted Not Done Inline Actions I don't see the harm in tweaking the sentence to avoid any possible confusion: "Any memory access by a thread to the guarded range results in the delivery of a SIGSEGV to that thread." alc: I don't see the harm in tweaking the sentence to avoid any possible confusion: "Any memory…
				Any memory access by a thread to the guarded range results
				emasteUnsubmitted Done Inline Actions Guards allow the reservations to be created in the address space, which can be replaced by actual mappings later on. For instance, the system uses guards to prevent the inadvertent use of regions into which stacks created with MAP_STACK will automatically grow. emaste: Guards allow the reservations to be created in the address space, which can be replaced by…
				markjUnsubmitted Done Inline Actions "Guards allow a process to create reservations in its address space, which..." markj: "Guards allow a process to create reservations in its address space, which..."
				in the delivery of a
				.Dv SIGSEGV
				markjUnsubmitted Done Inline Actions "the system" markj: "the system"
				emasteUnsubmitted Done Inline Actions which can later be replaced by actual mappings. emaste: which can later be replaced by actual mappings.
				signal to that thread.
	.It Dv MAP_NOCORE			.It Dv MAP_NOCORE
	Region is not included in a core file.			Region is not included in a core file.
	.It Dv MAP_NOSYNC			.It Dv MAP_NOSYNC
				alcUnsubmitted Not Done Inline Actions I would suggest moving this (minus the "For instance,") to the description of MAP_STACK. alc: I would suggest moving this (minus the "For instance,") to the description of MAP_STACK.
	Causes data dirtied via this VM map to be flushed to physical media			Causes data dirtied via this VM map to be flushed to physical media
	only when necessary (usually by the pager) rather than gratuitously.			only when necessary (usually by the pager) rather than gratuitously.
	Typically this prevents the update daemons from flushing pages dirtied			Typically this prevents the update daemons from flushing pages dirtied
	through such maps and thus allows efficient sharing of memory across			through such maps and thus allows efficient sharing of memory across
	unassociated processes using a file-backed shared memory map.			unassociated processes using a file-backed shared memory map.
	Without			Without
	this option any VM pages you dirty may be flushed to disk every so often			this option any VM pages you dirty may be flushed to disk every so often
	(every 30-60 seconds usually) which can create performance problems if you			(every 30-60 seconds usually) which can create performance problems if you
	▲ Show 20 Lines • Show All 85 Lines • ▼ Show 20 Lines
	.Fa fd			.Fa fd
	argument			argument
	must be -1 and			must be -1 and
	.Fa prot			.Fa prot
	must include at least			must include at least
	.Dv PROT_READ			.Dv PROT_READ
	and			and
	.Dv PROT_WRITE .			.Dv PROT_WRITE .
				.Pp
	This option creates			This option creates
	a memory region that grows to at most			a memory region that grows to at most
	.Fa len			.Fa len
	bytes in size, starting from the stack top and growing down.			bytes in size, starting from the stack top and growing down.
	The			The
	stack top is the starting address returned by the call, plus			stack top is the starting address returned by the call, plus
	.Fa len			.Fa len
	bytes.			bytes.
	The bottom of the stack at maximum growth is the starting			The bottom of the stack at maximum growth is the starting
	address returned by the call.			address returned by the call.
				The system uses guards to prevent the inadvertent use of
				regions into which stacks created with
				.Dv MAP_STACK
				will automatically grow, without mapping the whole stack in advance.
				wblockUnsubmitted Not Done Inline Actions This is complex. Suggested: Stacks created with .Dv MAP_STACK automatically grow. Guards prevent inadvertent use of the regions into which those stacks can grow without requiring mapping the whole stack in advance. wblock: This is complex. Suggested: ```Stacks created with .Dv MAP_STACK automatically grow. Guards…
	.El			.El
	.Pp			.Pp
	The			The
	.Xr close 2			.Xr close 2
	system call does not unmap pages, see			system call does not unmap pages, see
	.Xr munmap 2			.Xr munmap 2
	for further information.			for further information.
	.Sh NOTES			.Sh NOTES
	▲ Show 20 Lines • Show All 126 Lines • ▼ Show 20 Lines
	and			and
	.Dv MAP_EXCL			.Dv MAP_EXCL
	were specified, but the requested region is already used by a mapping.			were specified, but the requested region is already used by a mapping.
	.It Bq Er EINVAL			.It Bq Er EINVAL
	.Dv MAP_EXCL			.Dv MAP_EXCL
	was specified, but			was specified, but
	.Dv MAP_FIXED			.Dv MAP_FIXED
	was not.			was not.
				.It Bq Er EINVAL
				.Dv MAP_GUARD
				was specified, but the
				alcUnsubmitted Not Done Inline Actions I would drop the "either". It's generally accepted to mean exclusivity, and you want an inclusive "or" here. alc: I would drop the "either". It's generally accepted to mean exclusivity, and you want an…
				.Fa offset
				argument was not zero, the
				alcUnsubmitted Not Done Inline Actions Drop this "or". The final "or" suffices. alc: Drop this "or". The final "or" suffices.
				.Fa fd
				argument was not -1, or the
				.Fa prot
				argument was not
				.Dv PROT_NONE .
	.It Bq Er ENODEV			.It Bq Er ENODEV
	.Dv MAP_ANON			.Dv MAP_ANON
	has not been specified and			has not been specified and
	.Fa fd			.Fa fd
	did not reference a regular or character special file.			did not reference a regular or character special file.
	.It Bq Er ENOMEM			.It Bq Er ENOMEM
	.Dv MAP_FIXED			.Dv MAP_FIXED
	was specified and the			was specified and the
	Show All 16 Lines