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