| blob | 1c10966f7d974160ccbc651c8e13748e8f724172 |
1 .\" $NetBSD: mmap.2,v 1.48 2015/02/27 16:18:00 christos Exp $
2 .\"
3 .\" Copyright (c) 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
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.
17 .\"
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
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)mmap.2 8.4 (Berkeley) 5/11/95
31 .\"
32 .Dd February 27, 2015
33 .Dt MMAP 2
34 .Os
35 .Sh NAME
36 .Nm mmap
37 .Nd map files or devices into memory
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/mman.h
42 .Ft void *
43 .Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
44 .Sh DESCRIPTION
45 The
46 .Nm mmap
47 function causes the pages starting at
48 .Fa addr
49 and continuing for at most
50 .Fa len
51 bytes to be mapped from the object described by
52 .Fa fd ,
53 starting at byte offset
54 .Fa offset .
55 If
56 .Fa len
57 is not a multiple of the pagesize, the mapped region may extend past the
58 specified range.
59 Any such extension beyond the end of the mapped object will be zero-filled.
60 .Pp
61 If
62 .Fa addr
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.)
66 If
67 .Fa addr
68 is zero, an address will be selected by the system.
69 The actual starting address of the region is returned.
70 A successful
71 .Fa mmap
72 deletes any previous mapping in the allocated address range.
73 .Pp
74 The protections (region accessibility) are specified in the
75 .Fa prot
76 argument by
77 .Em OR Ns 'ing
78 the following values:
79 .Pp
80 .Bl -tag -width PROT_WRITEXX -offset indent
81 .It Dv PROT_EXEC
82 Pages may be executed.
83 .It Dv PROT_READ
84 Pages may be read.
85 .It Dv PROT_WRITE
86 Pages may be written.
87 .It Dv PROT_NONE
88 Pages may not be accessed.
89 .El
90 .Pp
91 .Bf -symbolic
92 Note that, due to hardware limitations, on some platforms
93 .Dv PROT_WRITE
94 may imply
95 .Dv PROT_READ ,
96 and
97 .Dv PROT_READ
98 may imply
99 .Dv PROT_EXEC .
100 Portable programs should not rely on these flags being separately
101 enforceable.
102 .Ef
103 .Pp
104 The
105 .Fa flags
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.
109 Note that either
110 .Dv MAP_SHARED
111 or
112 .Dv MAP_PRIVATE
113 must be specified.
114 Sharing, mapping type and options are specified in the
115 .Fa flags
116 argument by
117 .Em OR Ns 'ing
118 the following values:
119 .Pp
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.
123 The parameter
124 .Ar n
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
128 size as returned by
129 .Xr sysconf 3
130 with the
131 .Dv _SC_PAGESIZE
132 request.
133 .It Dv MAP_ANON
134 Map anonymous memory not associated with any specific file.
135 The file descriptor is not used for creating
136 .Dv MAP_ANON
137 regions, and must be specified as \-1.
138 The mapped memory will be zero filled.
139 .It Dv MAP_FILE
140 Mapped from a regular file or character-special device memory.
141 Read accesses beyond the end of of the file or device but less
142 than the current page size will be zero-filled.
143 Write accesses beyond the end of the file or device but less
144 than the current page size will not affect the file or device.
145 References beyond the end of file that are beyond the current
146 page size will result in the delivery of
147 .Dv SIGBUS
148 signal.
149 .It Dv MAP_FIXED
150 Do not permit the system to select a different address than the one
151 specified.
152 If the specified address cannot be used,
153 .Nm mmap
154 will fail.
155 If MAP_FIXED is specified,
156 .Fa addr
157 must be a multiple of the pagesize.
158 Use of this option is discouraged.
159 .It Dv MAP_HASSEMAPHORE
160 Notify the kernel that the region may contain semaphores and that special
161 handling may be necessary.
162 .It Dv MAP_INHERIT
163 Permit regions to be inherited across
164 .Xr execve 2
165 system calls.
166 .It Dv MAP_TRYFIXED
167 Attempt to use the address
168 .Fa addr
169 even if it falls within the normally protected process data or
170 text segment memory regions.
171 If the requested region of memory
172 is actually present in the memory map, a different address will
173 be selected as if
174 .Dv MAP_TRYFIXED
175 had not been specified.
176 If
177 .Fa addr
178 is
179 .Fa NULL ,
180 this flag is ignored and the system will select a mapping address.
181 .It Dv MAP_WIRED
182 Lock the mapped region into memory as with
183 .Xr mlock 2 .
184 .It Dv MAP_PRIVATE
185 Modifications made by this process are private, however modifications made by
186 other processes using
187 .Dv MAP_SHARED
188 will be seen.
189 .It Dv MAP_SHARED
190 Modifications are shared.
191 .El
192 .Pp
193 The
194 .Xr close 2
195 function does not unmap pages, see
196 .Xr munmap 2
197 for further information.
198 .Pp
199 The current design does not allow a process to specify the location of
200 swap space.
201 In the future we may define an additional mapping type,
202 .Dv MAP_SWAP ,
203 in which
204 the file descriptor argument specifies a file or device to which swapping
205 should be done.
206 .Pp
207 If
208 .Dv MAP_FIXED
209 is not specified, the system will attempt to place the mapping in an
210 unused portion of the address space chosen to minimize possible
211 collision between mapped regions and the heap.
212 .Sh RETURN VALUES
213 Upon successful completion,
214 .Nm mmap
215 returns a pointer to the mapped region.
216 Otherwise, a value of
217 .Dv MAP_FAILED
218 is returned and
219 .Va errno
220 is set to indicate the error.
221 The symbol
222 .Dv MAP_FAILED
223 is defined in the header
224 .Ao Pa sys/mman.h Ac .
225 No successful return from
226 .Fn mmap
227 will return the value
228 .Dv MAP_FAILED .
229 .Sh ERRORS
230 .Fn mmap
231 will fail if:
232 .Bl -tag -width Er
233 .It Bq Er EACCES
234 The flag
235 .Dv PROT_READ
236 was specified as part of the
237 .Fa prot
238 parameter and
239 .Fa fd
240 was not open for reading.
241 The flags
242 .Dv MAP_SHARED
243 and
244 .Dv PROT_WRITE
245 were specified as part of the
246 .Fa flags
247 and
248 .Fa prot
249 parameters and
250 .Fa fd
251 was not open for writing.
252 .It Bq Er EBADF
253 .Fa fd
254 is not a valid open file descriptor.
255 .It Bq Er EINVAL
256 .\"One of
257 .\".Dv MAP_ANON
258 .\"or
259 .\".Dv MAP_FILE
260 .\"was not specified as part of the
261 .\".Fa flags
262 .\"parameter.
263 .Dv MAP_FIXED
264 was specified and the
265 .Fa addr
266 parameter was not page aligned or was outside of the
267 valid address range for a process.
268 .Dv MAP_ANON was specified and
269 .Fa fd
270 was not \-1.
271 .It Bq Er ENODEV
272 .Fa fd
273 did not reference a regular or character special file.
274 .It Bq Er ENOMEM
275 .Dv MAP_FIXED
276 was specified and the
277 .Fa addr
278 parameter wasn't available.
279 .Dv MAP_ANON
280 was specified and insufficient memory was available.
281 .It Bq Er EOVERFLOW
282 .Fa fd
283 references a regular file and the value of
284 .Fa offset
285 plus
286 .Fa len
287 would exceed the offset maximum established in its open file description.
288 .El
289 .Sh SEE ALSO
290 .Xr madvise 2 ,
291 .Xr mincore 2 ,
292 .Xr mlock 2 ,
293 .Xr mprotect 2 ,
294 .Xr msync 2 ,
295 .Xr munmap 2 ,
296 .Xr getpagesize 3 ,
297 .Xr sysconf 3
298 .Sh STANDARDS
299 The
300 .Fn mmap
301 function conforms to
302 .St -p1003.1b-93 .
303 .Sh HISTORY
304 The
305 .Fn mmap
306 interface was first designed in
307 .Bx 4.2 .