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_GUARD | |||||
Instead of the mapping, create a guard of the specified size. | |||||
markj: "a mapping" | |||||
The guard prevents any other mappings at its address range, | |||||
emasteUnsubmitted Not Done Inline Actions"within its address range" or "overapping its address range" or something like that? The guard prevents mappings without the MAP_FIXED flag from overlapping its address range. emaste: "within its address range" or "overapping its address range" or something like that?
and in… | |||||
markjUnsubmitted Done Inline ActionsI 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 ActionsSounds good. emaste: Sounds good. | |||||
until it is unmapped or another mapping is created there with | |||||
the | |||||
.Dv MAP_FIXED | |||||
flag. | |||||
Any memory access to the guarded range results in the | |||||
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 Actionsresults in the SIGSEGV signal being delivered to the thread. emaste: results in the SIGSEGV signal being delivered to the thread. | |||||
.Dv SIGSEGV | |||||
signal delivered to the thread. | |||||
.Pp | |||||
Not Done Inline ActionsI 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… | |||||
Not Done Inline ActionsI 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… | |||||
Guards allow to create reservations in the address space, which | |||||
emasteUnsubmitted Done Inline ActionsGuards 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..." | |||||
can be replaced by the actual mappings later. | |||||
For instance, system uses guards to prevent inadvertent use of grow | |||||
markjUnsubmitted Done Inline Actions"the system" markj: "the system" | |||||
Done Inline Actionswhich can later be replaced by actual mappings. emaste: which can later be replaced by actual mappings. | |||||
areas for auto-expanded stacks created with | |||||
.Dv MAP_STACK . | |||||
.It Dv MAP_HASSEMAPHORE | .It Dv MAP_HASSEMAPHORE | ||||
Notify the kernel that the region may contain semaphores and that special | Notify the kernel that the region may contain semaphores and that special | ||||
Not Done Inline ActionsI 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. | |||||
handling may be necessary. | handling may be necessary. | ||||
.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 | ||||
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 | ||||
▲ Show 20 Lines • Show All 102 Lines • ▼ Show 20 Lines | |||||
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. | ||||
.El | .El | ||||
.Pp | .Pp | ||||
The | The | ||||
.Xr close 2 | .Xr close 2 | ||||
Not Done Inline ActionsThis 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… | |||||
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 | ||||
Although this implementation does not impose any alignment restrictions on | Although this implementation does not impose any alignment restrictions on | ||||
the | the | ||||
.Fa offset | .Fa offset | ||||
argument, a portable program must only use page-aligned values. | argument, a portable program must only use page-aligned values. | ||||
▲ Show 20 Lines • Show All 124 Lines • ▼ Show 20 Lines | |||||
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 ENODEV | .It Bq Er ENODEV | ||||
.Dv MAP_ANON | .Dv MAP_ANON | ||||
has not been specified and | has not been specified and | ||||
Not Done Inline ActionsI 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 fd | .Fa fd | ||||
did not reference a regular or character special file. | did not reference a regular or character special file. | ||||
Not Done Inline ActionsDrop this "or". The final "or" suffices. alc: Drop this "or". The final "or" suffices. | |||||
.It Bq Er ENOMEM | .It Bq Er ENOMEM | ||||
.Dv MAP_FIXED | .Dv MAP_FIXED | ||||
was specified and the | was specified and the | ||||
.Fa addr | .Fa addr | ||||
argument was not available. | argument was not available. | ||||
.Dv MAP_ANON | .Dv MAP_ANON | ||||
was specified and insufficient memory was available. | was specified and insufficient memory was available. | ||||
.El | .El | ||||
Show All 11 Lines |
"a mapping"