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