Print this page
6607 add default MAP_FILE symbol to sys/mman.h
Reviewed by: Andy Stormont <astormont@racktopsystems.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/mmap.2
+++ new/usr/src/man/man2/mmap.2
1 1 '\" te
2 +.\" Copyright 2016 James S Blachly, MD. All Rights Reserved.
2 3 .\" Copyright 2013 OmniTI Computer Consulting, Inc. All Rights Reserved.
3 4 .\" Copyright 1989 AT&T. Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
4 5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
5 6 .\" http://www.opengroup.org/bookstore/.
6 7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
7 8 .\" This notice shall appear on any product containing this material.
8 9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
9 10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
10 11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
11 -.TH MMAP 2 "April 9, 2016"
12 +.TH MMAP 2 "August 29, 2016"
12 13 .SH NAME
13 14 mmap \- map pages of memory
14 15 .SH SYNOPSIS
15 16 .LP
16 17 .nf
17 18 #include <sys/mman.h>
18 19
19 20 \fBvoid *\fR\fBmmap\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIprot\fR, \fBint\fR \fIflags\fR,
20 21 \fBint\fR \fIfildes\fR, \fBoff_t\fR \fIoff\fR);
21 22 .fi
22 23
23 24 .SH DESCRIPTION
24 25 .LP
25 26 The \fBmmap()\fR function establishes a mapping between a process's address
26 27 space and a file or shared memory object. The format of the call is as follows:
27 28 .sp
28 29 .LP
29 30 \fIpa\fR = \fBmmap(\fR\fIaddr\fR\fB, \fR\fIlen\fR\fB, \fR\fIprot\fR\fB,
30 31 \fR\fIflags\fR\fB, \fR\fIfildes\fR\fB, \fR\fIoff\fR\fB);\fR
31 32 .sp
32 33 .LP
33 34 The \fBmmap()\fR function establishes a mapping between the address space of
34 35 the process at an address \fIpa\fR for \fIlen\fR bytes to the memory object
35 36 represented by the file descriptor \fIfildes\fR at offset \fIoff\fR for
36 37 \fIlen\fR bytes. The value of \fIpa\fR is a function of the \fIaddr\fR
37 38 argument and values of \fIflags\fR, further described below. A successful
38 39 \fBmmap()\fR call returns \fIpa\fR as its result. The address range starting at
39 40 \fIpa\fR and continuing for \fIlen\fR bytes will be legitimate for the possible
40 41 (not necessarily current) address space of the process. The range of bytes
41 42 starting at \fIoff\fR and continuing for \fIlen\fR bytes will be legitimate for
42 43 the possible (not necessarily current) offsets in the file or shared memory
43 44 object represented by \fIfildes\fR.
44 45 .sp
45 46 .LP
46 47 The \fBmmap()\fR function allows [\fIpa, pa + len\fR) to extend beyond the end
47 48 of the object both at the time of the \fBmmap()\fR and while the mapping
48 49 persists, such as when the file is created prior to the \fBmmap()\fR call and
49 50 has no contents, or when the file is truncated. Any reference to addresses
50 51 beyond the end of the object, however, will result in the delivery of a
51 52 \fBSIGBUS\fR or \fBSIGSEGV\fR signal. The \fBmmap()\fR function cannot be used
52 53 to implicitly extend the length of files.
53 54 .sp
54 55 .LP
55 56 The mapping established by \fBmmap()\fR replaces any previous mappings for
56 57 those whole pages containing any part of the address space of the process
57 58 starting at \fIpa\fR and continuing for \fIlen\fR bytes.
58 59 .sp
59 60 .LP
60 61 If the size of the mapped file changes after the call to \fBmmap()\fR as a
61 62 result of some other operation on the mapped file, the effect of references to
62 63 portions of the mapped region that correspond to added or removed portions of
63 64 the file is unspecified.
64 65 .sp
65 66 .LP
66 67 The \fBmmap()\fR function is supported for regular files and shared memory
67 68 objects. Support for any other type of file is unspecified.
68 69 .sp
69 70 .LP
70 71 The \fIprot\fR argument determines whether read, write, execute, or some
71 72 combination of accesses are permitted to the data being mapped. The \fIprot\fR
72 73 argument should be either \fBPROT_NONE\fR or the bitwise inclusive \fBOR\fR of
73 74 one or more of the other flags in the following table, defined in the header
74 75 <\fBsys/mman.h\fR>.
75 76 .sp
76 77 .ne 2
77 78 .na
78 79 \fB\fBPROT_READ\fR\fR
79 80 .ad
80 81 .RS 14n
81 82 Data can be read.
82 83 .RE
83 84
84 85 .sp
85 86 .ne 2
86 87 .na
87 88 \fB\fBPROT_WRITE\fR\fR
88 89 .ad
89 90 .RS 14n
90 91 Data can be written.
91 92 .RE
92 93
93 94 .sp
94 95 .ne 2
95 96 .na
96 97 \fB\fBPROT_EXEC\fR\fR
97 98 .ad
98 99 .RS 14n
99 100 Data can be executed.
100 101 .RE
101 102
102 103 .sp
103 104 .ne 2
104 105 .na
105 106 \fB\fBPROT_NONE\fR\fR
106 107 .ad
107 108 .RS 14n
108 109 Data cannot be accessed.
109 110 .RE
110 111
111 112 .sp
112 113 .LP
113 114 If an implementation of \fBmmap()\fR for a specific platform cannot support the
114 115 combination of access types specified by \fIprot\fR, the call to \fBmmap()\fR
115 116 fails. An implementation may permit accesses other than those specified by
116 117 \fIprot\fR; however, the implementation will not permit a write to succeed
117 118 where \fBPROT_WRITE\fR has not been set or permit any access where
118 119 \fBPROT_NONE\fR alone has been set. Each platform-specific implementation of
119 120 \fBmmap()\fR supports the following values of \fIprot\fR: \fBPROT_NONE\fR,
120 121 \fBPROT_READ\fR, \fBPROT_WRITE\fR, and the inclusive \fBOR\fR of
121 122 \fBPROT_READ\fR and \fBPROT_WRITE\fR. On some platforms, the \fBPROT_WRITE\fR
122 123 protection option is implemented as \fBPROT_READ|PROT_WRITE\fR and
123 124 \fBPROT_EXEC\fR as \fBPROT_READ|PROT_EXEC\fR. The file descriptor \fIfildes\fR
124 125 is opened with read permission, regardless of the protection options specified.
125 126 If \fBPROT_WRITE\fR is specified, the application must have opened the file
126 127 descriptor \fIfildes\fR with write permission unless \fBMAP_PRIVATE\fR is
127 128 specified in the \fIflags\fR argument as described below.
128 129 .sp
129 130 .LP
130 131 The \fIflags\fR argument provides other information about the handling of the
131 132 mapped data. The value of \fIflags\fR is the bitwise inclusive \fBOR\fR of
132 133 these options, defined in <\fBsys/mman.h\fR>:
133 134 .sp
134 135 .ne 2
135 136 .na
136 137 \fB\fBMAP_SHARED\fR\fR
137 138 .ad
138 139 .RS 17n
139 140 Changes are shared.
140 141 .RE
141 142
142 143 .sp
143 144 .ne 2
144 145 .na
145 146 \fB\fBMAP_PRIVATE\fR\fR
146 147 .ad
147 148 .RS 17n
148 149 Changes are private.
149 150 .RE
150 151
151 152 .sp
152 153 .ne 2
153 154 .na
154 155 \fB\fBMAP_FIXED\fR\fR
155 156 .ad
156 157 .RS 17n
157 158 Interpret \fIaddr\fR exactly.
158 159 .RE
159 160
160 161 .sp
161 162 .ne 2
162 163 .na
163 164 \fB\fBMAP_NORESERVE\fR\fR
164 165 .ad
165 166 .RS 17n
166 167 Do not reserve swap space.
167 168 .RE
168 169
169 170 .sp
170 171 .ne 2
171 172 .na
172 173 \fB\fBMAP_ANON\fR\fR
173 174 .ad
174 175 .RS 17n
175 176 Map anonymous memory.
176 177 .RE
177 178
178 179 .sp
179 180 .ne 2
180 181 .na
181 182 \fB\fBMAP_ALIGN\fR\fR
182 183 .ad
183 184 .RS 17n
184 185 Interpret \fIaddr\fR as required aligment.
185 186 .RE
186 187
187 188 .sp
188 189 .ne 2
189 190 .na
190 191 \fB\fBMAP_TEXT\fR\fR
191 192 .ad
192 193 .RS 17n
193 194 Map text.
194 195 .RE
195 196
196 197 .sp
197 198 .ne 2
198 199 .na
199 200 \fB\fBMAP_INITDATA\fR\fR
200 201 .ad
201 202 .RS 17n
202 203 Map initialized data segment.
203 204 .RE
|
↓ open down ↓ |
182 lines elided |
↑ open up ↑ |
204 205
205 206 .sp
206 207 .ne 2
207 208 .na
208 209 \fB\fBMAP_32BIT\fR\fR
209 210 .ad
210 211 .RS 17n
211 212 Map to the lower 32 bits of address space.
212 213 .RE
213 214
215 +.sp
216 +.ne 2
217 +.na
218 +\fB\fBMAP_FILE\fR\fR
219 +.ad
220 +.RS 17n
221 +Map a regular file. This is the default behavior;
222 +specifying this flag is not required. It is provided
223 +for compatibility with other systems and should not be
224 +included in new code.
225 +.RE
226 +
214 227 .sp
215 228 .LP
216 229 The \fBMAP_SHARED\fR and \fBMAP_PRIVATE\fR options describe the disposition of
217 230 write references to the underlying object. If \fBMAP_SHARED\fR is specified,
218 231 write references will change the memory object. If \fBMAP_PRIVATE\fR is
219 232 specified, the initial write reference will create a private copy of the memory
220 233 object page and redirect the mapping to the copy. The private copy is not
221 234 created until the first write; until then, other users who have the object
222 235 mapped \fBMAP_SHARED\fR can change the object. Either \fBMAP_SHARED\fR or
223 236 \fBMAP_PRIVATE\fR must be specified, but not both. The mapping type is retained
224 237 across \fBfork\fR(2).
225 238 .sp
226 239 .LP
227 240 When \fBMAP_FIXED\fR is set in the \fIflags\fR argument, the system is informed
228 241 that the value of \fIpa\fR must be \fIaddr\fR, exactly. If \fBMAP_FIXED\fR is
229 242 set, \fBmmap()\fR may return (\fBvoid *\fR)\(mi1 and set \fBerrno\fR to
230 243 \fBEINVAL\fR. If a \fBMAP_FIXED\fR request is successful, the mapping
231 244 established by \fBmmap()\fR replaces any previous mappings for the process's
232 245 pages in the range [\fIpa, pa + len\fR). The use of \fBMAP_FIXED\fR is
233 246 discouraged, since it may prevent a system from making the most effective use
234 247 of its resources.
235 248 .sp
236 249 .LP
237 250 When \fBMAP_FIXED\fR is set and the requested address is the same as previous
238 251 mapping, the previous address is unmapped and the new mapping is created on top
239 252 of the old one.
240 253 .sp
241 254 .LP
242 255 When \fBMAP_FIXED\fR is not set, the system uses \fIaddr\fR to arrive at
243 256 \fIpa\fR. The \fIpa\fR so chosen will be an area of the address space that the
244 257 system deems suitable for a mapping of \fIlen\fR bytes to the file. The
245 258 \fBmmap()\fR function interprets an \fIaddr\fR value of 0 as granting the
246 259 system complete freedom in selecting \fIpa\fR, subject to constraints described
247 260 below. A non-zero value of \fIaddr\fR is taken to be a suggestion of a process
248 261 address near which the mapping should be placed. When the system selects a
249 262 value for \fIpa\fR, it will never place a mapping at address 0, nor will it
250 263 replace any extant mapping, nor map into areas considered part of the potential
251 264 data or stack "segments".
252 265 .sp
253 266 .LP
254 267 When \fBMAP_ALIGN\fR is set, the system is informed that the alignment of
255 268 \fIpa\fR must be the same as \fIaddr\fR. The alignment value in \fIaddr\fR must
256 269 be 0 or some power of two multiple of page size as returned by
257 270 \fBsysconf\fR(3C). If addr is 0, the system will choose a suitable alignment.
258 271 .sp
259 272 .LP
260 273 The \fBMAP_NORESERVE\fR option specifies that no swap space be reserved for a
261 274 mapping. Without this flag, the creation of a writable \fBMAP_PRIVATE\fR
262 275 mapping reserves swap space equal to the size of the mapping; when the mapping
263 276 is written into, the reserved space is employed to hold private copies of the
264 277 data. A write into a \fBMAP_NORESERVE\fR mapping produces results which depend
265 278 on the current availability of swap space in the system. If space is
266 279 available, the write succeeds and a private copy of the written page is
267 280 created; if space is not available, the write fails and a \fBSIGBUS\fR or
268 281 \fBSIGSEGV\fR signal is delivered to the writing process. \fBMAP_NORESERVE\fR
269 282 mappings are inherited across \fBfork()\fR; at the time of the \fBfork()\fR,
270 283 swap space is reserved in the child for all private pages that currently exist
271 284 in the parent; thereafter the child's mapping behaves as described above.
272 285 .sp
273 286 .LP
274 287 When \fBMAP_ANON\fR is set in \fIflags\fR, and \fIfildes\fR is set to -1,
275 288 \fBmmap()\fR provides a direct path to return anonymous pages to the caller.
276 289 This operation is equivalent to passing \fBmmap()\fR an open file descriptor on
277 290 \fB/dev/zero\fR with \fBMAP_ANON\fR elided from the \fIflags\fR argument.
278 291 .sp
279 292 .LP
280 293 The \fBMAP_TEXT\fR option informs the system that the mapped region will be
281 294 used primarily for executing instructions. This information can help the system
282 295 better utilize MMU resources on some platforms. This flag is always passed by
283 296 the dynamic linker when it maps text segments of shared objects. When the
284 297 \fBMAP_TEXT\fR option is used for regular file mappings on some platforms, the
285 298 system can choose a mapping size larger than the page size returned by
286 299 \fBsysconf\fR(3C). The specific page sizes that are used depend on the platform
287 300 and the alignment of the addr and len arguments. Several different mapping sizes
288 301 can be used to map the region with larger page sizes used in the parts of the
289 302 region that meet alignment and size requirements for those page sizes.
290 303 .sp
291 304 .LP
292 305 The \fBMAP_INITDATA\fR option informs the system that the mapped region is an
293 306 initialized data segment of an executable or shared object. When the
294 307 \fBMAP_INITDATA\fR option is used for regular file mappings on some platforms,
295 308 the system can choose a mapping size larger than the page size returned by
296 309 \fBsysconf()\fR. The \fBMAP_INITDATA\fR option should be used only by the
297 310 dynamic linker for mapping initialized data of shared objects.
298 311 .sp
299 312 .LP
300 313 The \fBMAP_32BIT\fR option informs the system that the search space for
301 314 mapping assignment should be limited to the first 32 bits (4 Gbytes) of the
302 315 caller's address space. This flag is accepted in both 32-bit and 64-bit
303 316 process models, but does not alter the mapping strategy when used in a
304 317 32-bit process model.
305 318 .sp
306 319 .LP
307 320 The \fIoff\fR argument is constrained to be aligned and sized according to the
308 321 value returned by \fBsysconf()\fR when passed \fB_SC_PAGESIZE\fR or
309 322 \fB_SC_PAGE_SIZE\fR. When \fBMAP_FIXED\fR is specified, the \fIaddr\fR argument
310 323 must also meet these constraints. The system performs mapping operations over
311 324 whole pages. Thus, while the \fIlen\fR argument need not meet a size or
312 325 alignment constraint, the system will include, in any mapping operation, any
313 326 partial page specified by the range [\fIpa, pa + len\fR).
314 327 .sp
315 328 .LP
316 329 The system will always zero-fill any partial page at the end of an object.
317 330 Further, the system will never write out any modified portions of the last page
318 331 of an object which are beyond its end. References to whole pages following the
319 332 end of an object will result in the delivery of a \fBSIGBUS\fR or \fBSIGSEGV\fR
320 333 signal. \fBSIGBUS\fR signals may also be delivered on various file system
321 334 conditions, including quota exceeded errors.
322 335 .sp
323 336 .LP
324 337 The \fBmmap()\fR function adds an extra reference to the file associated with
325 338 the file descriptor \fIfildes\fR which is not removed by a subsequent
326 339 \fBclose\fR(2) on that file descriptor. This reference is removed when there
327 340 are no more mappings to the file by a call to the \fBmunmap\fR(2) function.
328 341 .sp
329 342 .LP
330 343 The \fBst_atime\fR field of the mapped file may be marked for update at any
331 344 time between the \fBmmap()\fR call and the corresponding \fBmunmap\fR(2) call.
332 345 The initial read or write reference to a mapped region will cause the file's
333 346 \fBst_atime\fR field to be marked for update if it has not already been marked
334 347 for update.
335 348 .sp
336 349 .LP
337 350 The \fBst_ctime\fR and \fBst_mtime\fR fields of a file that is mapped with
338 351 \fBMAP_SHARED\fR and \fBPROT_WRITE\fR, will be marked for update at some point
339 352 in the interval between a write reference to the mapped region and the next
340 353 call to \fBmsync\fR(3C) with \fBMS_ASYNC\fR or \fBMS_SYNC\fR for that portion
341 354 of the file by any process. If there is no such call, these fields may be
342 355 marked for update at any time after a write reference if the underlying file is
343 356 modified as a result.
344 357 .sp
345 358 .LP
346 359 If the process calls \fBmlockall\fR(3C) with the \fBMCL_FUTURE\fR flag, the
347 360 pages mapped by all future calls to \fBmmap()\fR will be locked in memory. In
348 361 this case, if not enough memory could be locked, \fBmmap()\fR fails and sets
349 362 \fBerrno\fR to \fBEAGAIN\fR.
350 363 .sp
351 364 .LP
352 365 The \fBmmap()\fR function aligns based on the length of the mapping. When
353 366 determining the amount of space to add to the address space, \fBmmap()\fR
354 367 includes two 8-Kbyte pages, one at each end of the mapping that are not mapped
355 368 and are therefore used as "red-zone" pages. Attempts to reference these pages
356 369 result in access violations.
357 370 .sp
358 371 .LP
359 372 The size requested is incremented by the 16 Kbytes for these pages and is then
360 373 subject to rounding constraints. The constraints are:
361 374 .RS +4
362 375 .TP
363 376 .ie t \(bu
364 377 .el o
365 378 For 32-bit processes:
366 379 .sp
367 380 .in +2
368 381 .nf
369 382 If length > 4 Mbytes
370 383 round to 4-Mbyte multiple
371 384 elseif length > 512 Kbytes
372 385 round to 512-Kbyte multiple
373 386 else
374 387 round to 64-Kbyte multiple
375 388 .fi
376 389 .in -2
377 390
378 391 .RE
379 392 .RS +4
380 393 .TP
381 394 .ie t \(bu
382 395 .el o
383 396 For 64-bit processes:
384 397 .sp
385 398 .in +2
386 399 .nf
387 400 If length > 4 Mbytes
388 401 round to 4-Mbyte multiple
389 402 else
390 403 round to 1-Mbyte multiple
391 404 .fi
392 405 .in -2
393 406
394 407 .RE
395 408 .sp
396 409 .LP
397 410 The net result is that for a 32-bit process:
398 411 .RS +4
399 412 .TP
400 413 .ie t \(bu
401 414 .el o
402 415 If an \fBmmap()\fR request is made for 4 Mbytes, it results in 4 Mbytes + 16
403 416 Kbytes and is rounded up to 8 Mbytes.
404 417 .RE
405 418 .RS +4
406 419 .TP
407 420 .ie t \(bu
408 421 .el o
409 422 If an \fBmmap()\fR request is made for 512 Kbytes, it results in 512 Kbytes +
410 423 16 Kbytes and is rounded up to 1 Mbyte.
411 424 .RE
412 425 .RS +4
413 426 .TP
414 427 .ie t \(bu
415 428 .el o
416 429 If an \fBmmap()\fR request is made for 1 Mbyte, it results in 1 Mbyte + 16
417 430 Kbytes and is rounded up to 1.5 Mbytes.
418 431 .RE
419 432 .RS +4
420 433 .TP
421 434 .ie t \(bu
422 435 .el o
423 436 Each 8-Kbyte mmap request "consumes" 64 Kbytes of virtual address space.
424 437 .RE
425 438 .sp
426 439 .LP
427 440 To obtain maximal address space usage for a 32-bit process:
428 441 .RS +4
429 442 .TP
430 443 .ie t \(bu
431 444 .el o
432 445 Combine 8-Kbyte requests up to a limit of 48 Kbytes.
433 446 .RE
434 447 .RS +4
435 448 .TP
436 449 .ie t \(bu
437 450 .el o
438 451 Combine amounts over 48 Kbytes into 496-Kbyte chunks.
439 452 .RE
440 453 .RS +4
441 454 .TP
442 455 .ie t \(bu
443 456 .el o
444 457 Combine amounts over 496 Kbytes into 4080-Kbyte chunks.
445 458 .RE
446 459 .sp
447 460 .LP
448 461 To obtain maximal address space usage for a 64-bit process:
449 462 .RS +4
450 463 .TP
451 464 .ie t \(bu
452 465 .el o
453 466 Combine amounts < 1008 Kbytes into chunks <= 1008 Kbytes.
454 467 .RE
455 468 .RS +4
456 469 .TP
457 470 .ie t \(bu
458 471 .el o
459 472 Combine amounts over 1008 Kbytes into 4080-Kbyte chunks.
460 473 .RE
461 474 .sp
462 475 .LP
463 476 The following is the output from a 32-bit program demonstrating this:
464 477 .sp
465 478 .ne 2
466 479 .na
467 480 \fBmap 8192 bytes: \fB0xff390000\fR\fR
468 481 .ad
469 482 .br
470 483 .na
471 484 \fBmap 8192 bytes: \fB0xff380000\fR\fR
472 485 .ad
473 486 .sp .6
474 487 .RS 4n
475 488 64-Kbyte delta between starting addresses.
476 489 .RE
477 490
478 491 .sp
479 492 .ne 2
480 493 .na
481 494 \fBmap 512 Kbytes: \fB0xff180000\fR\fR
482 495 .ad
483 496 .br
484 497 .na
485 498 \fBmap 512 Kbytes: \fB0xff080000\fR\fR
486 499 .ad
487 500 .sp .6
488 501 .RS 4n
489 502 1-Mbyte delta between starting addresses.
490 503 .RE
491 504
492 505 .sp
493 506 .ne 2
494 507 .na
495 508 \fBmap 496 Kbytes: \fB0xff000000\fR\fR
496 509 .ad
497 510 .br
498 511 .na
499 512 \fBmap 496 Kbytes: \fB0xfef80000\fR\fR
500 513 .ad
501 514 .sp .6
502 515 .RS 4n
503 516 512-Kbyte delta between starting addresses
504 517 .RE
505 518
506 519 .sp
507 520 .ne 2
508 521 .na
509 522 \fBmap 1 Mbyte: \fB0xfee00000\fR\fR
510 523 .ad
511 524 .br
512 525 .na
513 526 \fBmap 1 Mbyte: \fB0xfec80000\fR\fR
514 527 .ad
515 528 .sp .6
516 529 .RS 4n
517 530 1536-Kbyte delta between starting addresses
518 531 .RE
519 532
520 533 .sp
521 534 .ne 2
522 535 .na
523 536 \fBmap 1008 Kbytes: \fB0xfeb80000\fR\fR
524 537 .ad
525 538 .br
526 539 .na
527 540 \fBmap 1008 Kbytes: \fB0xfea80000\fR\fR
528 541 .ad
529 542 .sp .6
530 543 .RS 4n
531 544 1-Mbyte delta between starting addresses
532 545 .RE
533 546
534 547 .sp
535 548 .ne 2
536 549 .na
537 550 \fBmap 4 Mbytes: \fB0xfe400000\fR\fR
538 551 .ad
539 552 .br
540 553 .na
541 554 \fBmap 4 Mbytes: \fB0xfdc00000\fR\fR
542 555 .ad
543 556 .sp .6
544 557 .RS 4n
545 558 8-Mbyte delta between starting addresses
546 559 .RE
547 560
548 561 .sp
549 562 .ne 2
550 563 .na
551 564 \fBmap 4080 Kbytes: \fB0xfd800000\fR\fR
552 565 .ad
553 566 .br
554 567 .na
555 568 \fBmap 4080 Kbytes: \fB0xfd400000\fR\fR
556 569 .ad
557 570 .sp .6
558 571 .RS 4n
559 572 4-Mbyte delta between starting addresses
560 573 .RE
561 574
562 575 .sp
563 576 .LP
564 577 The following is the output of the same program compiled as a 64-bit
565 578 application:
566 579 .sp
567 580 .ne 2
568 581 .na
569 582 \fBmap 8192 bytes: \fB0xffffffff7f000000\fR\fR
570 583 .ad
571 584 .br
572 585 .na
573 586 \fBmap 8192 bytes: \fB0xffffffff7ef00000\fR\fR
574 587 .ad
575 588 .sp .6
576 589 .RS 4n
577 590 1-Mbyte delta between starting addresses
578 591 .RE
579 592
580 593 .sp
581 594 .ne 2
582 595 .na
583 596 \fBmap 512 Kbytes: \fB0xffffffff7ee00000\fR\fR
584 597 .ad
585 598 .br
586 599 .na
587 600 \fBmap 512 Kbytes: \fB0xffffffff7ed00000\fR\fR
588 601 .ad
589 602 .sp .6
590 603 .RS 4n
591 604 1-Mbyte delta between starting addresses
592 605 .RE
593 606
594 607 .sp
595 608 .ne 2
596 609 .na
597 610 \fBmap 496 Kbytes: \fB0xffffffff7ec00000\fR\fR
598 611 .ad
599 612 .br
600 613 .na
601 614 \fBmap 496 Kbytes: \fB0xffffffff7eb00000\fR\fR
602 615 .ad
603 616 .sp .6
604 617 .RS 4n
605 618 1-Mbyte delta between starting addresses
606 619 .RE
607 620
608 621 .sp
609 622 .ne 2
610 623 .na
611 624 \fBmap 1 Mbyte: \fB0xffffffff7e900000\fR\fR
612 625 .ad
613 626 .br
614 627 .na
615 628 \fBmap 1 Mbyte: \fB0xffffffff7e700000\fR\fR
616 629 .ad
617 630 .sp .6
618 631 .RS 4n
619 632 2-Mbyte delta between starting addresses
620 633 .RE
621 634
622 635 .sp
623 636 .ne 2
624 637 .na
625 638 \fBmap 1008 Kbytes: \fB0xffffffff7e600000\fR\fR
626 639 .ad
627 640 .br
628 641 .na
629 642 \fBmap 1008 Kbytes: \fB0xffffffff7e500000\fR\fR
630 643 .ad
631 644 .sp .6
632 645 .RS 4n
633 646 1-Mbyte delta between starting addresses
634 647 .RE
635 648
636 649 .sp
637 650 .ne 2
638 651 .na
639 652 \fBmap 4 Mbytes: \fB0xffffffff7e000000\fR\fR
640 653 .ad
641 654 .br
642 655 .na
643 656 \fBmap 4 Mbytes: \fB0xffffffff7d800000\fR\fR
644 657 .ad
645 658 .sp .6
646 659 .RS 4n
647 660 8-Mbyte delta between starting addresses
648 661 .RE
649 662
650 663 .sp
651 664 .ne 2
652 665 .na
653 666 \fBmap 4080 Kbytes: \fB0xffffffff7d400000\fR\fR
654 667 .ad
655 668 .br
656 669 .na
657 670 \fBmap 4080 Kbytes: \fB0xffffffff7d000000\fR\fR
658 671 .ad
659 672 .sp .6
660 673 .RS 4n
661 674 4-Mbyte delta between starting addresses
662 675 .RE
663 676
664 677 .SH RETURN VALUES
665 678 .LP
666 679 Upon successful completion, the \fBmmap()\fR function returns the address at
667 680 which the mapping was placed (\fIpa\fR); otherwise, it returns a value of
668 681 \fBMAP_FAILED\fR and sets \fBerrno\fR to indicate the error. The symbol
669 682 \fBMAP_FAILED\fR is defined in the header <\fBsys/mman.h\fR>. No successful
670 683 return from \fBmmap()\fR will return the value \fBMAP_FAILED\fR.
671 684 .sp
672 685 .LP
673 686 If \fBmmap()\fR fails for reasons other than \fBEBADF\fR, \fBEINVAL\fR or
674 687 \fBENOTSUP\fR, some of the mappings in the address range starting at \fIaddr\fR
675 688 and continuing for \fIlen\fR bytes may have been unmapped.
676 689 .SH ERRORS
677 690 .LP
678 691 The \fBmmap()\fR function will fail if:
679 692 .sp
680 693 .ne 2
681 694 .na
682 695 \fB\fBEACCES\fR\fR
683 696 .ad
684 697 .RS 13n
685 698 The \fIfildes\fR file descriptor is not open for read, regardless of the
686 699 protection specified; or \fIfildes\fR is not open for write and
687 700 \fBPROT_WRITE\fR was specified for a \fBMAP_SHARED\fR type mapping.
688 701 .RE
689 702
690 703 .sp
691 704 .ne 2
692 705 .na
693 706 \fB\fBEAGAIN\fR\fR
694 707 .ad
695 708 .RS 13n
696 709 The mapping could not be locked in memory.
697 710 .sp
698 711 There was insufficient room to reserve swap space for the mapping.
699 712 .RE
700 713
701 714 .sp
702 715 .ne 2
703 716 .na
704 717 \fB\fBEBADF\fR\fR
705 718 .ad
706 719 .RS 13n
707 720 The \fIfildes\fR file descriptor is not open (and \fBMAP_ANON\fR was not
708 721 specified).
709 722 .RE
710 723
711 724 .sp
712 725 .ne 2
713 726 .na
714 727 \fB\fBEINVAL\fR\fR
715 728 .ad
716 729 .RS 13n
717 730 The arguments \fIaddr\fR (if \fBMAP_FIXED\fR was specified) or \fIoff\fR are
718 731 not multiples of the page size as returned by \fBsysconf()\fR.
719 732 .sp
720 733 The argument \fIaddr\fR (if \fBMAP_ALIGN\fR was specified) is not 0 or some
721 734 power of two multiple of page size as returned by \fBsysconf\fR(3C).
722 735 .sp
723 736 \fBMAP_FIXED\fR and \fBMAP_ALIGN\fR are both specified.
724 737 .sp
725 738 The field in \fIflags\fR is invalid (neither \fBMAP_PRIVATE\fR or
726 739 \fBMAP_SHARED\fR is set).
727 740 .sp
728 741 The argument \fIlen\fR has a value equal to 0.
729 742 .sp
730 743 \fBMAP_ANON\fR was specified, but the file descriptor was not \(mi1.
731 744 .sp
732 745 \fBMAP_TEXT\fR was specified but \fBPROT_EXEC\fR was not.
733 746 .sp
734 747 \fBMAP_TEXT\fR and \fBMAP_INITDATA\fR were both specified.
735 748 .RE
736 749
737 750 .sp
738 751 .ne 2
739 752 .na
740 753 \fB\fBEMFILE\fR\fR
741 754 .ad
742 755 .RS 13n
743 756 The number of mapped regions would exceed an implementation-dependent limit
744 757 (per process or per system).
745 758 .RE
746 759
747 760 .sp
748 761 .ne 2
749 762 .na
750 763 \fB\fBENODEV\fR\fR
751 764 .ad
752 765 .RS 13n
753 766 The \fIfildes\fR argument refers to an object for which \fBmmap()\fR is
754 767 meaningless, such as a terminal.
755 768 .RE
756 769
757 770 .sp
758 771 .ne 2
759 772 .na
760 773 \fB\fBENOMEM\fR\fR
761 774 .ad
762 775 .RS 13n
763 776 The \fBMAP_FIXED\fR option was specified and the range [\fIaddr, addr + len\fR)
764 777 exceeds that allowed for the address space of a process.
765 778 .sp
766 779 The \fBMAP_FIXED\fR option was \fInot\fR specified and there is insufficient
767 780 room in the address space to effect the mapping.
768 781 .sp
769 782 The mapping could not be locked in memory, if required by \fBmlockall\fR(3C),
770 783 because it would require more space than the system is able to supply.
771 784 .sp
772 785 The composite size of \fIlen\fR plus the lengths obtained from all previous
773 786 calls to \fBmmap()\fR exceeds \fBRLIMIT_VMEM\fR (see \fBgetrlimit\fR(2)).
774 787 .RE
775 788
776 789 .sp
777 790 .ne 2
778 791 .na
779 792 \fB\fBENOTSUP\fR\fR
780 793 .ad
781 794 .RS 13n
782 795 The system does not support the combination of accesses requested in the
783 796 \fIprot\fR argument.
784 797 .RE
785 798
786 799 .sp
787 800 .ne 2
788 801 .na
789 802 \fB\fBENXIO\fR\fR
790 803 .ad
791 804 .RS 13n
792 805 Addresses in the range [\fIoff, off + len\fR) are invalid for the object
793 806 specified by \fIfildes\fR.
794 807 .sp
795 808 The \fBMAP_FIXED\fR option was specified in \fIflags\fR and the combination of
796 809 \fIaddr\fR, \fIlen\fR and \fIoff\fR is invalid for the object specified by
797 810 \fIfildes\fR.
798 811 .RE
799 812
800 813 .sp
801 814 .ne 2
802 815 .na
803 816 \fB\fBEOVERFLOW\fR\fR
804 817 .ad
805 818 .RS 13n
806 819 The file is a regular file and the value of \fIoff\fR plus \fIlen\fR exceeds
807 820 the offset maximum establish in the open file description associated with
808 821 \fIfildes\fR.
809 822 .RE
810 823
811 824 .sp
812 825 .LP
813 826 The \fBmmap()\fR function may fail if:
814 827 .sp
815 828 .ne 2
816 829 .na
817 830 \fB\fBEAGAIN\fR\fR
818 831 .ad
819 832 .RS 10n
820 833 The file to be mapped is already locked using advisory or mandatory record
821 834 locking. See \fBfcntl\fR(2).
822 835 .RE
823 836
824 837 .SH USAGE
825 838 .LP
826 839 Use of \fBmmap()\fR may reduce the amount of memory available to other memory
827 840 allocation functions.
828 841 .sp
829 842 .LP
830 843 \fBMAP_ALIGN\fR is useful to assure a properly aligned value of \fIpa\fR for
831 844 subsequent use with \fBmemcntl\fR(2) and the \fBMC_HAT_ADVISE\fR command. This
832 845 is best used for large, long-lived, and heavily referenced regions.
833 846 \fBMAP_FIXED\fR and \fBMAP_ALIGN\fR are always mutually-exclusive.
834 847 .sp
835 848 .LP
836 849 Use of \fBMAP_FIXED\fR may result in unspecified behavior in further use of
837 850 \fBbrk\fR(2), \fBsbrk\fR(2), \fBmalloc\fR(3C), and \fBshmat\fR(2). The use of
838 851 \fBMAP_FIXED\fR is discouraged, as it may prevent an implementation from making
839 852 the most effective use of resources.
840 853 .sp
841 854 .LP
842 855 The application must ensure correct synchronization when using \fBmmap()\fR in
843 856 conjunction with any other file access method, such as \fBread\fR(2) and
844 857 \fBwrite\fR(2), standard input/output, and \fBshmat\fR(2).
845 858 .sp
846 859 .LP
847 860 The \fBmmap()\fR function has a transitional interface for 64-bit file offsets.
848 861 See \fBlf64\fR(5).
849 862 .sp
850 863 .LP
851 864 The \fBmmap()\fR function allows access to resources using address space
852 865 manipulations instead of the \fBread()\fR/\fBwrite()\fR interface. Once a file
853 866 is mapped, all a process has to do to access it is use the data at the address
854 867 to which the object was mapped.
855 868 .sp
856 869 .LP
857 870 Consider the following pseudo-code:
858 871 .sp
859 872 .in +2
860 873 .nf
861 874 fildes = open(\|.\|.\|.)
862 875 lseek(fildes, offset, whence)
863 876 read(fildes, buf, len)
864 877 /* use data in buf */
865 878 .fi
866 879 .in -2
867 880
868 881 .sp
869 882 .LP
870 883 The following is a rewrite using \fBmmap()\fR:
871 884 .sp
872 885 .in +2
873 886 .nf
874 887 fildes = open(\|.\|.\|.)
875 888 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
876 889 MAP_PRIVATE, fildes, offset)
877 890 /* use data at address */
878 891 .fi
879 892 .in -2
880 893
881 894 .SH ATTRIBUTES
882 895 .LP
883 896 See \fBattributes\fR(5) for descriptions of the following attributes:
884 897 .sp
885 898
886 899 .sp
887 900 .TS
888 901 box;
889 902 c | c
890 903 l | l .
891 904 ATTRIBUTE TYPE ATTRIBUTE VALUE
892 905 _
893 906 Interface Stability Standard
894 907 _
895 908 MT-Level Async-Signal-Safe
896 909 .TE
897 910
898 911 .SH SEE ALSO
899 912 .LP
900 913 \fBclose\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2),
901 914 \fBgetrlimit\fR(2), \fBmemcntl\fR(2), \fBmmapobj\fR(2), \fBmprotect\fR(2),
902 915 \fBmunmap\fR(2), \fBshmat\fR(2), \fBlockf\fR(3C), \fBmlockall\fR(3C),
903 916 \fBmsync\fR(3C), \fBplock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5),
904 917 \fBlf64\fR(5), \fBstandards\fR(5), \fBnull\fR(7D), \fBzero\fR(7D)
|
↓ open down ↓ |
681 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX