1 .\" $NetBSD: mmap.2,v 1.47 2012/01/05 15:19:52 reinoud Exp $
3 .\" Copyright (c) 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)mmap.2 8.4 (Berkeley) 5/11/95
37 .Nd map files or devices into memory
43 .Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
47 function causes the pages starting at
49 and continuing for at most
51 bytes to be mapped from the object described by
53 starting at byte offset
57 is not a multiple of the pagesize, the mapped region may extend past the
59 Any such extension beyond the end of the mapped object will be zero-filled.
63 is non-zero, it is used as a hint to the system.
64 (As a convenience to the system, the actual address of the region may differ
65 from the address supplied.)
68 is zero, an address will be selected by the system.
69 The actual starting address of the region is returned.
72 deletes any previous mapping in the allocated address range.
74 The protections (region accessibility) are specified in the
80 .Bl -tag -width PROT_WRITEXX -offset indent
82 Pages may be executed.
88 Pages may not be accessed.
92 Note that, due to hardware limitations, on some platforms
100 Portable programs should not rely on these flags being separately
106 parameter specifies the type of the mapped object, mapping options and
107 whether modifications made to the mapped copy of the page are private
108 to the process or are to be shared with other references.
114 Sharing, mapping type and options are specified in the
118 the following values:
120 .Bl -tag -width MAP_HASSEMAPHOREXX -offset indent
121 .It Dv MAP_ALIGNED(n)
122 Request that the allocation be aligned to the given boundary.
125 should be the base 2 logarithm of the desired alignment (e.g., to
126 request alignment to 16K, use 14 as the value for n).
127 The alignment must be equal to or greater than the platform's page
134 Map anonymous memory not associated with any specific file.
135 The file descriptor is not used for creating
137 regions, and must be specified as \-1.
138 The mapped memory will be zero filled.
140 Mapped from a regular file or character-special device memory.
142 Do not permit the system to select a different address than the one
144 If the specified address cannot be used,
147 If MAP_FIXED is specified,
149 must be a multiple of the pagesize.
150 Use of this option is discouraged.
151 .It Dv MAP_HASSEMAPHORE
152 Notify the kernel that the region may contain semaphores and that special
153 handling may be necessary.
155 Permit regions to be inherited across
159 Attempt to use the address
161 even if it falls within the normally protected process data or
162 text segment memory regions.
163 If the requested region of memory
164 is actually present in the memory map, a different address will
167 had not been specified.
172 this flag is ignored and the system will select a mapping address.
174 Lock the mapped region into memory as with
177 Modifications made by this process are private, however modifications made by
178 other processes using
182 Modifications are shared.
187 function does not unmap pages, see
189 for further information.
191 The current design does not allow a process to specify the location of
193 In the future we may define an additional mapping type,
196 the file descriptor argument specifies a file or device to which swapping
201 is not specified, the system will attempt to place the mapping in an
202 unused portion of the address space chosen to minimize possible
203 collision between mapped regions and the heap.
205 Upon successful completion,
207 returns a pointer to the mapped region.
208 Otherwise, a value of
212 is set to indicate the error.
215 is defined in the header
216 .Ao Pa sys/mman.h Ac .
217 No successful return from
219 will return the value
228 was specified as part of the
232 was not open for reading.
237 were specified as part of the
243 was not open for writing.
246 is not a valid open file descriptor.
252 .\"was not specified as part of the
256 was specified and the
258 parameter was not page aligned or was outside of the
259 valid address range for a process.
260 .Dv MAP_ANON was specified and
265 did not reference a regular or character special file.
268 was specified and the
270 parameter wasn't available.
272 was specified and insufficient memory was available.
275 references a regular file and the value of
279 would exceed the offset maximum established in its open file description.
298 interface was first designed in