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.man.txt
+++ new/usr/src/man/man2/mmap.2.man.txt
1 1 MMAP(2) System Calls MMAP(2)
2 2
3 3
4 4
5 5 NAME
6 6 mmap - map pages of memory
7 7
8 8 SYNOPSIS
9 9 #include <sys/mman.h>
10 10
11 11 void *mmap(void *addr, size_t len, int prot, int flags,
12 12 int fildes, off_t off);
13 13
14 14
15 15 DESCRIPTION
16 16 The mmap() function establishes a mapping between a process's address
17 17 space and a file or shared memory object. The format of the call is as
18 18 follows:
19 19
20 20
21 21 pa = mmap(addr, len, prot, flags, fildes, off);
22 22
23 23
24 24 The mmap() function establishes a mapping between the address space of
25 25 the process at an address pa for len bytes to the memory object
26 26 represented by the file descriptor fildes at offset off for len bytes.
27 27 The value of pa is a function of the addr argument and values of
28 28 flags, further described below. A successful mmap() call returns pa as
29 29 its result. The address range starting at pa and continuing for len
30 30 bytes will be legitimate for the possible (not necessarily current)
31 31 address space of the process. The range of bytes starting at off and
32 32 continuing for len bytes will be legitimate for the possible (not
33 33 necessarily current) offsets in the file or shared memory object
34 34 represented by fildes.
35 35
36 36
37 37 The mmap() function allows [pa, pa + len) to extend beyond the end of
38 38 the object both at the time of the mmap() and while the mapping
39 39 persists, such as when the file is created prior to the mmap() call and
40 40 has no contents, or when the file is truncated. Any reference to
41 41 addresses beyond the end of the object, however, will result in the
42 42 delivery of a SIGBUS or SIGSEGV signal. The mmap() function cannot be
43 43 used to implicitly extend the length of files.
44 44
45 45
46 46 The mapping established by mmap() replaces any previous mappings for
47 47 those whole pages containing any part of the address space of the
48 48 process starting at pa and continuing for len bytes.
49 49
50 50
51 51 If the size of the mapped file changes after the call to mmap() as a
52 52 result of some other operation on the mapped file, the effect of
53 53 references to portions of the mapped region that correspond to added or
54 54 removed portions of the file is unspecified.
55 55
56 56
57 57 The mmap() function is supported for regular files and shared memory
58 58 objects. Support for any other type of file is unspecified.
59 59
60 60
61 61 The prot argument determines whether read, write, execute, or some
62 62 combination of accesses are permitted to the data being mapped. The
63 63 prot argument should be either PROT_NONE or the bitwise inclusive OR of
64 64 one or more of the other flags in the following table, defined in the
65 65 header <sys/mman.h>.
66 66
67 67 PROT_READ
68 68 Data can be read.
69 69
70 70
71 71 PROT_WRITE
72 72 Data can be written.
73 73
74 74
75 75 PROT_EXEC
76 76 Data can be executed.
77 77
78 78
79 79 PROT_NONE
80 80 Data cannot be accessed.
81 81
82 82
83 83
84 84 If an implementation of mmap() for a specific platform cannot support
85 85 the combination of access types specified by prot, the call to mmap()
86 86 fails. An implementation may permit accesses other than those specified
87 87 by prot; however, the implementation will not permit a write to succeed
88 88 where PROT_WRITE has not been set or permit any access where PROT_NONE
89 89 alone has been set. Each platform-specific implementation of mmap()
90 90 supports the following values of prot: PROT_NONE, PROT_READ,
91 91 PROT_WRITE, and the inclusive OR of PROT_READ and PROT_WRITE. On some
92 92 platforms, the PROT_WRITE protection option is implemented as
93 93 PROT_READ|PROT_WRITE and PROT_EXEC as PROT_READ|PROT_EXEC. The file
94 94 descriptor fildes is opened with read permission, regardless of the
95 95 protection options specified. If PROT_WRITE is specified, the
96 96 application must have opened the file descriptor fildes with write
97 97 permission unless MAP_PRIVATE is specified in the flags argument as
98 98 described below.
99 99
100 100
101 101 The flags argument provides other information about the handling of
102 102 the mapped data. The value of flags is the bitwise inclusive OR of
103 103 these options, defined in <sys/mman.h>:
104 104
105 105 MAP_SHARED
106 106 Changes are shared.
107 107
108 108
109 109 MAP_PRIVATE
110 110 Changes are private.
111 111
112 112
113 113 MAP_FIXED
114 114 Interpret addr exactly.
115 115
116 116
117 117 MAP_NORESERVE
118 118 Do not reserve swap space.
119 119
120 120
121 121 MAP_ANON
122 122 Map anonymous memory.
123 123
124 124
125 125 MAP_ALIGN
126 126 Interpret addr as required aligment.
127 127
128 128
129 129 MAP_TEXT
130 130 Map text.
|
↓ open down ↓ |
130 lines elided |
↑ open up ↑ |
131 131
132 132
133 133 MAP_INITDATA
134 134 Map initialized data segment.
135 135
136 136
137 137 MAP_32BIT
138 138 Map to the lower 32 bits of address space.
139 139
140 140
141 + MAP_FILE
142 + Map a regular file. This is the default behavior;
143 + specifying this flag is not required. It is provided
144 + for compatibility with other systems and should not be
145 + included in new code.
141 146
147 +
148 +
142 149 The MAP_SHARED and MAP_PRIVATE options describe the disposition of
143 150 write references to the underlying object. If MAP_SHARED is specified,
144 151 write references will change the memory object. If MAP_PRIVATE is
145 152 specified, the initial write reference will create a private copy of
146 153 the memory object page and redirect the mapping to the copy. The
147 154 private copy is not created until the first write; until then, other
148 155 users who have the object mapped MAP_SHARED can change the object.
149 156 Either MAP_SHARED or MAP_PRIVATE must be specified, but not both. The
150 157 mapping type is retained across fork(2).
151 158
152 159
153 160 When MAP_FIXED is set in the flags argument, the system is informed
154 161 that the value of pa must be addr, exactly. If MAP_FIXED is set, mmap()
155 162 may return (void *)-1 and set errno to EINVAL. If a MAP_FIXED request
156 163 is successful, the mapping established by mmap() replaces any previous
157 164 mappings for the process's pages in the range [pa, pa + len). The use
158 165 of MAP_FIXED is discouraged, since it may prevent a system from making
159 166 the most effective use of its resources.
160 167
161 168
162 169 When MAP_FIXED is set and the requested address is the same as previous
163 170 mapping, the previous address is unmapped and the new mapping is
164 171 created on top of the old one.
165 172
166 173
167 174 When MAP_FIXED is not set, the system uses addr to arrive at pa. The pa
168 175 so chosen will be an area of the address space that the system deems
169 176 suitable for a mapping of len bytes to the file. The mmap() function
170 177 interprets an addr value of 0 as granting the system complete freedom
171 178 in selecting pa, subject to constraints described below. A non-zero
172 179 value of addr is taken to be a suggestion of a process address near
173 180 which the mapping should be placed. When the system selects a value for
174 181 pa, it will never place a mapping at address 0, nor will it replace any
175 182 extant mapping, nor map into areas considered part of the potential
176 183 data or stack "segments".
177 184
178 185
179 186 When MAP_ALIGN is set, the system is informed that the alignment of pa
180 187 must be the same as addr. The alignment value in addr must be 0 or some
181 188 power of two multiple of page size as returned by sysconf(3C). If addr
182 189 is 0, the system will choose a suitable alignment.
183 190
184 191
185 192 The MAP_NORESERVE option specifies that no swap space be reserved for a
186 193 mapping. Without this flag, the creation of a writable MAP_PRIVATE
187 194 mapping reserves swap space equal to the size of the mapping; when the
188 195 mapping is written into, the reserved space is employed to hold private
189 196 copies of the data. A write into a MAP_NORESERVE mapping produces
190 197 results which depend on the current availability of swap space in the
191 198 system. If space is available, the write succeeds and a private copy
192 199 of the written page is created; if space is not available, the write
193 200 fails and a SIGBUS or SIGSEGV signal is delivered to the writing
194 201 process. MAP_NORESERVE mappings are inherited across fork(); at the
195 202 time of the fork(), swap space is reserved in the child for all private
196 203 pages that currently exist in the parent; thereafter the child's
197 204 mapping behaves as described above.
198 205
199 206
200 207 When MAP_ANON is set in flags, and fildes is set to -1, mmap() provides
201 208 a direct path to return anonymous pages to the caller. This operation
202 209 is equivalent to passing mmap() an open file descriptor on /dev/zero
203 210 with MAP_ANON elided from the flags argument.
204 211
205 212
206 213 The MAP_TEXT option informs the system that the mapped region will be
207 214 used primarily for executing instructions. This information can help
208 215 the system better utilize MMU resources on some platforms. This flag is
209 216 always passed by the dynamic linker when it maps text segments of
210 217 shared objects. When the MAP_TEXT option is used for regular file
211 218 mappings on some platforms, the system can choose a mapping size larger
212 219 than the page size returned by sysconf(3C). The specific page sizes
213 220 that are used depend on the platform and the alignment of the addr and
214 221 len arguments. Several different mapping sizes can be used to map the
215 222 region with larger page sizes used in the parts of the region that meet
216 223 alignment and size requirements for those page sizes.
217 224
218 225
219 226 The MAP_INITDATA option informs the system that the mapped region is an
220 227 initialized data segment of an executable or shared object. When the
221 228 MAP_INITDATA option is used for regular file mappings on some
222 229 platforms, the system can choose a mapping size larger than the page
223 230 size returned by sysconf(). The MAP_INITDATA option should be used only
224 231 by the dynamic linker for mapping initialized data of shared objects.
225 232
226 233
227 234 The MAP_32BIT option informs the system that the search space for
228 235 mapping assignment should be limited to the first 32 bits (4 Gbytes) of
229 236 the caller's address space. This flag is accepted in both 32-bit and
230 237 64-bit process models, but does not alter the mapping strategy when
231 238 used in a 32-bit process model.
232 239
233 240
234 241 The off argument is constrained to be aligned and sized according to
235 242 the value returned by sysconf() when passed _SC_PAGESIZE or
236 243 _SC_PAGE_SIZE. When MAP_FIXED is specified, the addr argument must also
237 244 meet these constraints. The system performs mapping operations over
238 245 whole pages. Thus, while the len argument need not meet a size or
239 246 alignment constraint, the system will include, in any mapping
240 247 operation, any partial page specified by the range [pa, pa + len).
241 248
242 249
243 250 The system will always zero-fill any partial page at the end of an
244 251 object. Further, the system will never write out any modified portions
245 252 of the last page of an object which are beyond its end. References to
246 253 whole pages following the end of an object will result in the delivery
247 254 of a SIGBUS or SIGSEGV signal. SIGBUS signals may also be delivered on
248 255 various file system conditions, including quota exceeded errors.
249 256
250 257
251 258 The mmap() function adds an extra reference to the file associated with
252 259 the file descriptor fildes which is not removed by a subsequent
253 260 close(2) on that file descriptor. This reference is removed when there
254 261 are no more mappings to the file by a call to the munmap(2) function.
255 262
256 263
257 264 The st_atime field of the mapped file may be marked for update at any
258 265 time between the mmap() call and the corresponding munmap(2) call. The
259 266 initial read or write reference to a mapped region will cause the
260 267 file's st_atime field to be marked for update if it has not already
261 268 been marked for update.
262 269
263 270
264 271 The st_ctime and st_mtime fields of a file that is mapped with
265 272 MAP_SHARED and PROT_WRITE, will be marked for update at some point in
266 273 the interval between a write reference to the mapped region and the
267 274 next call to msync(3C) with MS_ASYNC or MS_SYNC for that portion of the
268 275 file by any process. If there is no such call, these fields may be
269 276 marked for update at any time after a write reference if the underlying
270 277 file is modified as a result.
271 278
272 279
273 280 If the process calls mlockall(3C) with the MCL_FUTURE flag, the pages
274 281 mapped by all future calls to mmap() will be locked in memory. In this
275 282 case, if not enough memory could be locked, mmap() fails and sets errno
276 283 to EAGAIN.
277 284
278 285
279 286 The mmap() function aligns based on the length of the mapping. When
280 287 determining the amount of space to add to the address space, mmap()
281 288 includes two 8-Kbyte pages, one at each end of the mapping that are not
282 289 mapped and are therefore used as "red-zone" pages. Attempts to
283 290 reference these pages result in access violations.
284 291
285 292
286 293 The size requested is incremented by the 16 Kbytes for these pages and
287 294 is then subject to rounding constraints. The constraints are:
288 295
289 296 o For 32-bit processes:
290 297
291 298 If length > 4 Mbytes
292 299 round to 4-Mbyte multiple
293 300 elseif length > 512 Kbytes
294 301 round to 512-Kbyte multiple
295 302 else
296 303 round to 64-Kbyte multiple
297 304
298 305
299 306 o For 64-bit processes:
300 307
301 308 If length > 4 Mbytes
302 309 round to 4-Mbyte multiple
303 310 else
304 311 round to 1-Mbyte multiple
305 312
306 313
307 314
308 315 The net result is that for a 32-bit process:
309 316
310 317 o If an mmap() request is made for 4 Mbytes, it results in 4
311 318 Mbytes + 16 Kbytes and is rounded up to 8 Mbytes.
312 319
313 320 o If an mmap() request is made for 512 Kbytes, it results in
314 321 512 Kbytes + 16 Kbytes and is rounded up to 1 Mbyte.
315 322
316 323 o If an mmap() request is made for 1 Mbyte, it results in 1
317 324 Mbyte + 16 Kbytes and is rounded up to 1.5 Mbytes.
318 325
319 326 o Each 8-Kbyte mmap request "consumes" 64 Kbytes of virtual
320 327 address space.
321 328
322 329
323 330 To obtain maximal address space usage for a 32-bit process:
324 331
325 332 o Combine 8-Kbyte requests up to a limit of 48 Kbytes.
326 333
327 334 o Combine amounts over 48 Kbytes into 496-Kbyte chunks.
328 335
329 336 o Combine amounts over 496 Kbytes into 4080-Kbyte chunks.
330 337
331 338
332 339 To obtain maximal address space usage for a 64-bit process:
333 340
334 341 o Combine amounts < 1008 Kbytes into chunks <= 1008 Kbytes.
335 342
336 343 o Combine amounts over 1008 Kbytes into 4080-Kbyte chunks.
337 344
338 345
339 346 The following is the output from a 32-bit program demonstrating this:
340 347
341 348 map 8192 bytes: 0xff390000
342 349 map 8192 bytes: 0xff380000
343 350
344 351 64-Kbyte delta between starting addresses.
345 352
346 353
347 354 map 512 Kbytes: 0xff180000
348 355 map 512 Kbytes: 0xff080000
349 356
350 357 1-Mbyte delta between starting addresses.
351 358
352 359
353 360 map 496 Kbytes: 0xff000000
354 361 map 496 Kbytes: 0xfef80000
355 362
356 363 512-Kbyte delta between starting addresses
357 364
358 365
359 366 map 1 Mbyte: 0xfee00000
360 367 map 1 Mbyte: 0xfec80000
361 368
362 369 1536-Kbyte delta between starting addresses
363 370
364 371
365 372 map 1008 Kbytes: 0xfeb80000
366 373 map 1008 Kbytes: 0xfea80000
367 374
368 375 1-Mbyte delta between starting addresses
369 376
370 377
371 378 map 4 Mbytes: 0xfe400000
372 379 map 4 Mbytes: 0xfdc00000
373 380
374 381 8-Mbyte delta between starting addresses
375 382
376 383
377 384 map 4080 Kbytes: 0xfd800000
378 385 map 4080 Kbytes: 0xfd400000
379 386
380 387 4-Mbyte delta between starting addresses
381 388
382 389
383 390
384 391 The following is the output of the same program compiled as a 64-bit
385 392 application:
386 393
387 394 map 8192 bytes: 0xffffffff7f000000
388 395 map 8192 bytes: 0xffffffff7ef00000
389 396
390 397 1-Mbyte delta between starting addresses
391 398
392 399
393 400 map 512 Kbytes: 0xffffffff7ee00000
394 401 map 512 Kbytes: 0xffffffff7ed00000
395 402
396 403 1-Mbyte delta between starting addresses
397 404
398 405
399 406 map 496 Kbytes: 0xffffffff7ec00000
400 407 map 496 Kbytes: 0xffffffff7eb00000
401 408
402 409 1-Mbyte delta between starting addresses
403 410
404 411
405 412 map 1 Mbyte: 0xffffffff7e900000
406 413 map 1 Mbyte: 0xffffffff7e700000
407 414
408 415 2-Mbyte delta between starting addresses
409 416
410 417
411 418 map 1008 Kbytes: 0xffffffff7e600000
412 419 map 1008 Kbytes: 0xffffffff7e500000
413 420
414 421 1-Mbyte delta between starting addresses
415 422
416 423
417 424 map 4 Mbytes: 0xffffffff7e000000
418 425 map 4 Mbytes: 0xffffffff7d800000
419 426
420 427 8-Mbyte delta between starting addresses
421 428
422 429
423 430 map 4080 Kbytes: 0xffffffff7d400000
424 431 map 4080 Kbytes: 0xffffffff7d000000
425 432
426 433 4-Mbyte delta between starting addresses
427 434
428 435
429 436 RETURN VALUES
430 437 Upon successful completion, the mmap() function returns the address at
431 438 which the mapping was placed (pa); otherwise, it returns a value of
432 439 MAP_FAILED and sets errno to indicate the error. The symbol MAP_FAILED
433 440 is defined in the header <sys/mman.h>. No successful return from mmap()
434 441 will return the value MAP_FAILED.
435 442
436 443
437 444 If mmap() fails for reasons other than EBADF, EINVAL or ENOTSUP, some
438 445 of the mappings in the address range starting at addr and continuing
439 446 for len bytes may have been unmapped.
440 447
441 448 ERRORS
442 449 The mmap() function will fail if:
443 450
444 451 EACCES
445 452 The fildes file descriptor is not open for read,
446 453 regardless of the protection specified; or fildes is not
447 454 open for write and PROT_WRITE was specified for a
448 455 MAP_SHARED type mapping.
449 456
450 457
451 458 EAGAIN
452 459 The mapping could not be locked in memory.
453 460
454 461 There was insufficient room to reserve swap space for the
455 462 mapping.
456 463
457 464
458 465 EBADF
459 466 The fildes file descriptor is not open (and MAP_ANON was
460 467 not specified).
461 468
462 469
463 470 EINVAL
464 471 The arguments addr (if MAP_FIXED was specified) or off are
465 472 not multiples of the page size as returned by sysconf().
466 473
467 474 The argument addr (if MAP_ALIGN was specified) is not 0 or
468 475 some power of two multiple of page size as returned by
469 476 sysconf(3C).
470 477
471 478 MAP_FIXED and MAP_ALIGN are both specified.
472 479
473 480 The field in flags is invalid (neither MAP_PRIVATE or
474 481 MAP_SHARED is set).
475 482
476 483 The argument len has a value equal to 0.
477 484
478 485 MAP_ANON was specified, but the file descriptor was not
479 486 -1.
480 487
481 488 MAP_TEXT was specified but PROT_EXEC was not.
482 489
483 490 MAP_TEXT and MAP_INITDATA were both specified.
484 491
485 492
486 493 EMFILE
487 494 The number of mapped regions would exceed an
488 495 implementation-dependent limit (per process or per
489 496 system).
490 497
491 498
492 499 ENODEV
493 500 The fildes argument refers to an object for which mmap()
494 501 is meaningless, such as a terminal.
495 502
496 503
497 504 ENOMEM
498 505 The MAP_FIXED option was specified and the range [addr,
499 506 addr + len) exceeds that allowed for the address space of
500 507 a process.
501 508
502 509 The MAP_FIXED option was not specified and there is
503 510 insufficient room in the address space to effect the
504 511 mapping.
505 512
506 513 The mapping could not be locked in memory, if required by
507 514 mlockall(3C), because it would require more space than the
508 515 system is able to supply.
509 516
510 517 The composite size of len plus the lengths obtained from
511 518 all previous calls to mmap() exceeds RLIMIT_VMEM (see
512 519 getrlimit(2)).
513 520
514 521
515 522 ENOTSUP
516 523 The system does not support the combination of accesses
517 524 requested in the prot argument.
518 525
519 526
520 527 ENXIO
521 528 Addresses in the range [off, off + len) are invalid for
522 529 the object specified by fildes.
523 530
524 531 The MAP_FIXED option was specified in flags and the
525 532 combination of addr, len and off is invalid for the object
526 533 specified by fildes.
527 534
528 535
529 536 EOVERFLOW
530 537 The file is a regular file and the value of off plus len
531 538 exceeds the offset maximum establish in the open file
532 539 description associated with fildes.
533 540
534 541
535 542
536 543 The mmap() function may fail if:
537 544
538 545 EAGAIN
539 546 The file to be mapped is already locked using advisory or
540 547 mandatory record locking. See fcntl(2).
541 548
542 549
543 550 USAGE
544 551 Use of mmap() may reduce the amount of memory available to other memory
545 552 allocation functions.
546 553
547 554
548 555 MAP_ALIGN is useful to assure a properly aligned value of pa for
549 556 subsequent use with memcntl(2) and the MC_HAT_ADVISE command. This is
550 557 best used for large, long-lived, and heavily referenced regions.
551 558 MAP_FIXED and MAP_ALIGN are always mutually-exclusive.
552 559
553 560
554 561 Use of MAP_FIXED may result in unspecified behavior in further use of
555 562 brk(2), sbrk(2), malloc(3C), and shmat(2). The use of MAP_FIXED is
556 563 discouraged, as it may prevent an implementation from making the most
557 564 effective use of resources.
558 565
559 566
560 567 The application must ensure correct synchronization when using mmap()
561 568 in conjunction with any other file access method, such as read(2) and
562 569 write(2), standard input/output, and shmat(2).
563 570
564 571
565 572 The mmap() function has a transitional interface for 64-bit file
566 573 offsets. See lf64(5).
567 574
568 575
569 576 The mmap() function allows access to resources using address space
570 577 manipulations instead of the read()/write() interface. Once a file is
571 578 mapped, all a process has to do to access it is use the data at the
572 579 address to which the object was mapped.
573 580
574 581
575 582 Consider the following pseudo-code:
576 583
577 584 fildes = open(...)
578 585 lseek(fildes, offset, whence)
579 586 read(fildes, buf, len)
580 587 /* use data in buf */
581 588
582 589
583 590
584 591 The following is a rewrite using mmap():
585 592
586 593 fildes = open(...)
587 594 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
588 595 MAP_PRIVATE, fildes, offset)
589 596 /* use data at address */
590 597
591 598
592 599 ATTRIBUTES
593 600 See attributes(5) for descriptions of the following attributes:
594 601
595 602
596 603
597 604
598 605 +--------------------+-------------------+
599 606 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
600 607 +--------------------+-------------------+
601 608 |Interface Stability | Standard |
602 609 +--------------------+-------------------+
603 610 |MT-Level | Async-Signal-Safe |
|
↓ open down ↓ |
452 lines elided |
↑ open up ↑ |
604 611 +--------------------+-------------------+
605 612
606 613 SEE ALSO
607 614 close(2), exec(2), fcntl(2), fork(2), getrlimit(2), memcntl(2),
608 615 mmapobj(2), mprotect(2), munmap(2), shmat(2), lockf(3C), mlockall(3C),
609 616 msync(3C), plock(3C), sysconf(3C), attributes(5), lf64(5),
610 617 standards(5), null(7D), zero(7D)
611 618
612 619
613 620
614 - April 9, 2016 MMAP(2)
621 + August 29, 2016 MMAP(2)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX