Debian Codegraph @

upstream/debian-unstable/man2/mmap.2

raw
1 '\" t
2 .\" Copyright 1996, Andries E. Brouwer <[email protected]>
3 .\" Copyright 2006-2007, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH mmap 2 2026-03-19 "Linux man-pages 6.18"
9 .SH NAME
10 mmap, munmap \- map or unmap files or devices into memory
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/mman.h>
17 .P
18 .BR "void *mmap(" "size_t length;"
19 .BI " void " addr [ length "], size_t " length \
20 ", int " prot ", int " flags ,
21 .BI " int " fd ", off_t " offset );
22 .BR "int munmap(" "size_t length;"
23 .BI " void " addr [ length "], size_t " length );
24 .fi
25 .P
26 See VERSIONS for information on feature test macro requirements.
27 .SH DESCRIPTION
28 .BR mmap ()
29 creates a new mapping in the virtual address space of
30 the calling process.
31 The starting address for the new mapping is specified in
32 .IR addr .
33 The
34 .I length
35 argument specifies the length of the mapping (which must be greater than 0).
36 .P
37 If
38 .I addr
39 is NULL,
40 then the kernel chooses the (page-aligned) address
41 at which to create the mapping;
42 this is the most portable method of creating a new mapping.
43 If
44 .I addr
45 is not NULL,
46 then the kernel takes it as a hint about where to place the mapping;
47 on Linux, the kernel will pick a nearby page boundary (but always above
48 or equal to the value specified by
49 .IR /proc/sys/vm/mmap_min_addr )
50 and attempt to create the mapping there.
51 If another mapping already exists there, the kernel picks a new address that
52 may or may not depend on the hint.
53 .\" Before Linux 2.6.24, the address was rounded up to the next page
54 .\" boundary; since Linux 2.6.24, it is rounded down!
55 The address of the new mapping is returned as the result of the call.
56 .P
57 The contents of a file mapping (as opposed to an anonymous mapping;
58 see
59 .B MAP_ANONYMOUS
60 below), are initialized using
61 .I length
62 bytes starting at offset
63 .I offset
64 in the file (or other object) referred to by the file descriptor
65 .IR fd .
66 .I offset
67 must be a multiple of the page size as returned by
68 .IR sysconf(_SC_PAGE_SIZE) .
69 .P
70 After the
71 .BR mmap ()
72 call has returned, the file descriptor,
73 .IR fd ,
74 can be closed immediately without invalidating the mapping.
75 .P
76 The
77 .I prot
78 argument describes the desired memory protection of the mapping
79 (and must not conflict with the open mode of the file).
80 It is either
81 .B PROT_NONE
82 or the bitwise OR of one or more of the following flags:
83 .TP 1.1i
84 .B PROT_EXEC
85 Pages may be executed.
86 .TP
87 .B PROT_READ
88 Pages may be read.
89 .TP
90 .B PROT_WRITE
91 Pages may be written.
92 .TP
93 .B PROT_NONE
94 Pages may not be accessed.
95 .\"
96 .SS The flags argument
97 The
98 .I flags
99 argument determines whether updates to the mapping
100 are visible to other processes mapping the same region,
101 and whether updates are carried through to the underlying file.
102 This behavior is determined by including exactly one
103 of the following values in
104 .IR flags :
105 .TP
106 .B MAP_SHARED
107 Share this mapping.
108 Updates to the mapping are visible to other processes mapping the same region,
109 and (in the case of file-backed mappings)
110 are carried through to the underlying file.
111 (To precisely control when updates are carried through
112 to the underlying file requires the use of
113 .BR msync (2).)
114 .TP
115 .BR MAP_SHARED_VALIDATE " (since Linux 4.15)"
116 This flag provides the same behavior as
117 .B MAP_SHARED
118 except that
119 .B MAP_SHARED
120 mappings ignore unknown flags in
121 .IR flags .
122 By contrast, when creating a mapping using
123 .BR MAP_SHARED_VALIDATE ,
124 the kernel verifies all passed flags are known and fails the
125 mapping with the error
126 .B EOPNOTSUPP
127 for unknown flags.
128 This mapping type is also required to be able to use some mapping flags
129 (e.g.,
130 .BR MAP_SYNC ).
131 .TP
132 .B MAP_PRIVATE
133 Create a private copy-on-write mapping.
134 Updates to the mapping are not visible to other processes
135 mapping the same file, and are not carried through to
136 the underlying file.
137 It is unspecified whether changes made to the file after the
138 .BR mmap ()
139 call are visible in the mapped region.
140 .P
141 Both
142 .B MAP_SHARED
143 and
144 .B MAP_PRIVATE
145 are described in POSIX.1-2001 and POSIX.1-2008.
146 .B MAP_SHARED_VALIDATE
147 is a Linux extension.
148 .P
149 In addition, zero or more of the following values can be ORed in
150 .IR flags :
151 .TP
152 .BR MAP_32BIT " (since Linux 2.4.20, 2.6)"
153 Put the mapping into the first 2 Gigabytes of the process address space.
154 This flag is supported only on x86-64, for 64-bit programs.
155 It was added to allow thread stacks to be allocated somewhere
156 in the first 2\ GB of memory,
157 so as to improve context-switch performance on some early
158 64-bit processors.
159 .\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
160 Modern x86-64 processors no longer have this performance problem,
161 so use of this flag is not required on those systems.
162 The
163 .B MAP_32BIT
164 flag is ignored when
165 .B MAP_FIXED
166 is set.
167 .TP
168 .B MAP_ANON
169 Synonym for
170 .BR MAP_ANONYMOUS ;
171 provided for compatibility with other implementations.
172 .TP
173 .B MAP_ANONYMOUS
174 The mapping is not backed by any file;
175 its contents are initialized to zero.
176 The
177 .I fd
178 argument is ignored;
179 however, some implementations require
180 .I fd
181 to be \-1 if
182 .B MAP_ANONYMOUS
183 (or
184 .BR MAP_ANON )
185 is specified,
186 and portable applications should ensure this.
187 The
188 .I offset
189 argument should be zero.
190 .\" See the pgoff overflow check in do_mmap().
191 .\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c.
192 Support for
193 .B MAP_ANONYMOUS
194 in conjunction with
195 .B MAP_SHARED
196 was added in Linux 2.4.
197 .TP
198 .B MAP_DENYWRITE
199 This flag is ignored.
200 .\" Introduced in 1.1.36, removed in 1.3.24.
201 (Long ago\[em]Linux 2.0 and earlier\[em]it signaled
202 that attempts to write to the underlying file should fail with
203 .BR ETXTBSY .
204 But this was a source of denial-of-service attacks.)
205 .TP
206 .B MAP_EXECUTABLE
207 This flag is ignored.
208 .\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link.
209 .\" (Long ago, it signaled that the underlying file is an executable.
210 .\" However, that information was not really used anywhere.)
211 .\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of
212 .\" MAP_DENYWRITE?
213 .TP
214 .B MAP_FILE
215 Compatibility flag.
216 Ignored.
217 .\" On some systems, this was required as the opposite of
218 .\" MAP_ANONYMOUS -- mtk, 1 May 2007
219 .TP
220 .B MAP_FIXED
221 Don't interpret
222 .I addr
223 as a hint: place the mapping at exactly that address.
224 .I addr
225 must be suitably aligned:
226 for most architectures a multiple of the page size is sufficient;
227 however,
228 some architectures may impose additional restrictions.
229 If the memory region specified by
230 .I addr
231 and
232 .I length
233 overlaps pages of any existing mapping(s), then the overlapped
234 part of the existing mapping(s) will be discarded.
235 If the specified address cannot be used,
236 .BR mmap ()
237 will fail.
238 .IP
239 Software that aspires to be portable should use the
240 .B MAP_FIXED
241 flag with care,
242 keeping in mind that the exact layout of a process's memory mappings
243 is allowed to change significantly between Linux versions,
244 C library versions, and operating system releases.
245 .I Carefully read the discussion of this flag in NOTES!
246 .TP
247 .BR MAP_FIXED_NOREPLACE " (since Linux 4.17)"
248 .\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843
249 This flag provides behavior that is similar to
250 .B MAP_FIXED
251 with respect to the
252 .I addr
253 enforcement, but differs in that
254 .B MAP_FIXED_NOREPLACE
255 never clobbers a preexisting mapped range.
256 If the requested range would collide with an existing mapping,
257 then this call fails with the error
258 .B EEXIST.
259 This flag can therefore be used as a way to atomically
260 (with respect to other threads)
261 attempt to map an address range:
262 one thread will succeed;
263 all others will report failure.
264 .IP
265 Note that older kernels which do not recognize the
266 .B MAP_FIXED_NOREPLACE
267 flag will typically (upon detecting a collision with a preexisting mapping)
268 fall back to a
269 .RB \[lq]non- MAP_FIXED \[rq]
270 type of behavior:
271 they will return an address that is different from the requested address.
272 Therefore, backward-compatible software
273 should check the returned address against the requested address.
274 .TP
275 .B MAP_GROWSDOWN
276 This flag is used for stacks.
277 It indicates to the kernel virtual memory system that the mapping
278 should extend downward in memory.
279 Touching an address in the "guard" page below the mapping will cause
280 the mapping to grow by a page.
281 This growth can be repeated until the mapping grows to within a
282 page of the high end of the next lower mapping,
283 at which point touching the "guard" page will result in a
284 .B SIGSEGV
285 signal.
286 .TP
287 .BR MAP_HUGETLB " (since Linux 2.6.32)"
288 Allocate the mapping using "huge" pages.
289 See the Linux kernel source file
290 .I Documentation/admin\-guide/mm/hugetlbpage.rst
291 for further information, as well as NOTES, below.
292 .TP
293 .B MAP_HUGE_2MB
294 .TQ
295 .BR MAP_HUGE_1GB " (since Linux 3.8)"
296 .\" See https://lwn.net/Articles/533499/
297 Used in conjunction with
298 .B MAP_HUGETLB
299 to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB)
300 on systems that support multiple hugetlb page sizes.
301 .IP
302 More generally, the desired huge page size can be configured by encoding
303 the base-2 logarithm of the desired page size in the six bits at the offset
304 .BR MAP_HUGE_SHIFT .
305 (A value of zero in this bit field provides the default huge page size;
306 the default huge page size can be discovered via the
307 .I Hugepagesize
308 field exposed by
309 .IR /proc/meminfo .)
310 Thus, the above two constants are defined as:
311 .IP
312 .in +4n
313 .EX
314 #define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT)
315 #define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT)
316 .EE
317 .in
318 .IP
319 The range of huge page sizes that are supported by the system
320 can be discovered by listing the subdirectories in
321 .IR /sys/kernel/mm/hugepages .
322 .TP
323 .BR MAP_LOCKED " (since Linux 2.5.37)"
324 Mark the mapped region to be locked in the same way as
325 .BR mlock (2).
326 This implementation will try to populate (prefault) the whole range but the
327 .BR mmap ()
328 call doesn't fail with
329 .B ENOMEM
330 if this fails.
331 Therefore major faults might happen later on.
332 So the semantic is not as strong as
333 .BR mlock (2).
334 One should use
335 .BR mmap ()
336 plus
337 .BR mlock (2)
338 when major faults are not acceptable after the initialization of the mapping.
339 The
340 .B MAP_LOCKED
341 flag is ignored in older kernels.
342 .\" If set, the mapped pages will not be swapped out.
343 .TP
344 .BR MAP_NONBLOCK " (since Linux 2.5.46)"
345 This flag is meaningful only in conjunction with
346 .BR MAP_POPULATE .
347 Don't perform read-ahead:
348 create page tables entries only for pages
349 that are already present in RAM.
350 Since Linux 2.6.23,
351 .\" commit 54cb8821de07f2ffcd28c380ce9b93d5784b40d7
352 this flag causes
353 .B MAP_POPULATE
354 to do nothing.
355 One day, the combination of
356 .B MAP_POPULATE
357 and
358 .B MAP_NONBLOCK
359 may be reimplemented.
360 .TP
361 .B MAP_NORESERVE
362 Do not reserve swap space for this mapping.
363 When swap space is reserved, one has the guarantee
364 that it is possible to modify the mapping.
365 When swap space is not reserved one might get
366 .B SIGSEGV
367 upon a write
368 if no physical memory is available.
369 See also the discussion of the file
370 .I /proc/sys/vm/overcommit_memory
371 in
372 .BR proc_sys_vm (5).
373 Before Linux 2.6, this flag had effect only for
374 private writable mappings.
375 .TP
376 .BR MAP_POPULATE " (since Linux 2.5.46)"
377 Populate (prefault) page tables for a mapping.
378 For a file mapping, this causes read-ahead on the file.
379 This will help to reduce blocking on page faults later.
380 The
381 .BR mmap ()
382 call doesn't fail if the mapping cannot be populated (for example, due
383 to limitations on the number of mapped huge pages when using
384 .BR MAP_HUGETLB ).
385 Support for
386 .B MAP_POPULATE
387 in conjunction with private mappings was added in Linux 2.6.23.
388 .TP
389 .BR MAP_STACK " (since Linux 2.6.27)"
390 Allocate the mapping at an address suitable for a process
391 or thread stack.
392 .IP
393 This flag is currently a no-op on Linux.
394 However, by employing this flag, applications can ensure that
395 they transparently obtain support if the flag
396 is implemented in the future.
397 Thus, it is used in the glibc threading implementation to allow for
398 the fact that some architectures may (later) require special treatment
399 for stack allocations.
400 .\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
401 .\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7
402 .\" http://thread.gmane.org/gmane.linux.kernel/720412
403 .\" "pthread_create() slow for many threads; also time to revisit 64b
404 .\" context switch optimization?"
405 A further reason to employ this flag is portability:
406 .B MAP_STACK
407 exists (and has an effect) on some other systems (e.g., some of the BSDs).
408 .TP
409 .BR MAP_SYNC " (since Linux 4.15)"
410 This flag is available only with the
411 .B MAP_SHARED_VALIDATE
412 mapping type;
413 mappings of type
414 .B MAP_SHARED
415 will silently ignore this flag.
416 This flag is supported only for files supporting DAX
417 (direct mapping of persistent memory).
418 For other files, creating a mapping with this flag results in an
419 .B EOPNOTSUPP
420 error.
421 .IP
422 Shared file mappings with this flag provide the guarantee that while
423 some memory is mapped writable in the address space of the process,
424 it will be visible in the same file at the same offset even after
425 the system crashes or is rebooted.
426 In conjunction with the use of appropriate CPU instructions,
427 this provides users of such mappings with a more efficient way
428 of making data modifications persistent.
429 .TP
430 .BR MAP_UNINITIALIZED " (since Linux 2.6.33)"
431 Don't clear anonymous pages.
432 This flag is intended to improve performance on embedded devices.
433 This flag is honored only if the kernel was configured with the
434 .B CONFIG_MMAP_ALLOW_UNINITIALIZED
435 option.
436 Because of the security implications,
437 that option is normally enabled only on embedded devices
438 (i.e., devices where one has complete control of the contents of user memory).
439 .P
440 Of the above flags, only
441 .B MAP_FIXED
442 is specified in POSIX.1-2001 and POSIX.1-2008.
443 However, most systems also support
444 .B MAP_ANONYMOUS
445 (or its synonym
446 .BR MAP_ANON ).
447 .\" FIXME . for later review when Issue 8 is one day released...
448 .\" POSIX may add MAP_ANON in the future
449 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
450 .\" http://austingroupbugs.net/view.php?id=850
451 .SS munmap()
452 The
453 .BR munmap ()
454 system call deletes the mappings for the specified address range, and
455 causes further references to addresses within the range to generate
456 invalid memory references.
457 The region is also automatically unmapped
458 when the process is terminated.
459 On the other hand, closing the file
460 descriptor does not unmap the region.
461 .P
462 The address
463 .I addr
464 must be a multiple of the page size (but
465 .I length
466 need not be).
467 All pages containing a part
468 of the indicated range are unmapped, and subsequent references
469 to these pages will generate
470 .BR SIGSEGV .
471 It is not an error if the
472 indicated range does not contain any mapped pages.
473 .SH RETURN VALUE
474 On success,
475 .BR mmap ()
476 returns a pointer to the mapped area.
477 On error, the value
478 .B MAP_FAILED
479 (that is,
480 .IR "(void\ *)\ \-1" )
481 is returned, and
482 .I errno
483 is set to indicate the error.
484 .P
485 On success,
486 .BR munmap ()
487 returns 0.
488 On failure, it returns \-1, and
489 .I errno
490 is set to indicate the error (probably to
491 .BR EINVAL ).
492 .SH ERRORS
493 .TP
494 .B EACCES
495 A file descriptor refers to a non-regular file.
496 Or a file mapping was requested, but
497 .I fd
498 is not open for reading.
499 Or
500 .B MAP_SHARED
501 was requested and
502 .B PROT_WRITE
503 is set, but
504 .I fd
505 is not open in read/write
506 .RB ( O_RDWR )
507 mode.
508 Or
509 .B PROT_WRITE
510 is set, but the file is append-only.
511 .TP
512 .B EAGAIN
513 The file has been locked, or too much memory has been locked (see
514 .BR setrlimit (2)).
515 .TP
516 .B EBADF
517 .I fd
518 is not a valid file descriptor (and
519 .B MAP_ANONYMOUS
520 was not set).
521 .TP
522 .B EEXIST
523 .B MAP_FIXED_NOREPLACE
524 was specified in
525 .IR flags ,
526 and the range covered by
527 .I addr
528 and
529 .I length
530 clashes with an existing mapping.
531 .TP
532 .B EINVAL
533 We don't like
534 .IR addr ,
535 .IR length ,
536 or
537 .I offset
538 (e.g., they are too large, or not aligned on a page boundary).
539 .TP
540 .B EINVAL
541 (since Linux 2.6.12)
542 .I length
543 was 0.
544 .TP
545 .B EINVAL
546 .I flags
547 contained none of
548 .BR MAP_PRIVATE ,
549 .BR MAP_SHARED ,
550 or
551 .BR MAP_SHARED_VALIDATE .
552 .TP
553 .B ENFILE
554 .\" This is for shared anonymous segments
555 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
556 The system-wide limit on the total number of open files has been reached.
557 .\" .TP
558 .\" .B ENOEXEC
559 .\" A file could not be mapped for reading.
560 .TP
561 .B ENODEV
562 The underlying filesystem of the specified file does not support
563 memory mapping.
564 .TP
565 .B ENOMEM
566 No memory is available.
567 .TP
568 .B ENOMEM
569 The process's maximum number of mappings would have been exceeded.
570 This error can also occur for
571 .BR munmap (),
572 when unmapping a region in the middle of an existing mapping,
573 since this results in two smaller mappings on either side of
574 the region being unmapped.
575 .TP
576 .B ENOMEM
577 (since Linux 4.7)
578 The process's
579 .B RLIMIT_DATA
580 limit, described in
581 .BR getrlimit (2),
582 would have been exceeded.
583 .TP
584 .B ENOMEM
585 We don't like
586 .IR addr ,
587 because it exceeds the virtual address space of the CPU.
588 .TP
589 .B EOVERFLOW
590 On 32-bit architecture together with the large file extension
591 (i.e., using 64-bit
592 .IR off_t ):
593 the number of pages used for
594 .I length
595 plus number of pages used for
596 .I offset
597 would overflow
598 .I "unsigned long"
599 (32 bits).
600 .TP
601 .B EPERM
602 The
603 .I prot
604 argument asks for
605 .B PROT_EXEC
606 but the mapped area belongs to a file on a filesystem that
607 was mounted no-exec.
608 .\" (Since Linux 2.4.25 / Linux 2.6.0.)
609 .TP
610 .B EPERM
611 The operation was prevented by a file seal;
612 see
613 .BR fcntl (2).
614 .TP
615 .B EPERM
616 The
617 .B MAP_HUGETLB
618 flag was specified, but the caller was not privileged (did not have the
619 .B CAP_IPC_LOCK
620 capability)
621 and is not a member of the
622 .I hugetlb_shm_group
623 group;
624 see the description of
625 .I /proc/sys/vm/hugetlb_shm_group
626 in
627 .BR proc_sys_vm (5).
628 .TP
629 .B ETXTBSY
630 .B MAP_DENYWRITE
631 was set but the object specified by
632 .I fd
633 is open for writing.
634 .P
635 Use of a mapped region can result in these signals:
636 .TP
637 .B SIGSEGV
638 Attempted write into a region mapped as read-only.
639 .TP
640 .B SIGBUS
641 Attempted access to a page of the buffer that lies beyond the
642 end of the mapped file.
643 For an explanation of the treatment of the bytes in the page that
644 corresponds to the end of a mapped file that is not a multiple
645 of the page size, see NOTES.
646 .SH ATTRIBUTES
647 For an explanation of the terms used in this section, see
648 .BR attributes (7).
649 .TS
650 allbox;
651 lbx lb lb
652 l l l.
653 Interface Attribute Value
654 T{
655 .na
656 .nh
657 .BR mmap (),
658 .BR munmap ()
659 T} Thread safety MT-Safe
660 .TE
661 .SH VERSIONS
662 On some hardware architectures (e.g., i386),
663 .B PROT_WRITE
664 implies
665 .BR PROT_READ .
666 It is architecture dependent whether
667 .B PROT_READ
668 implies
669 .B PROT_EXEC
670 or not.
671 Portable programs should always set
672 .B PROT_EXEC
673 if they intend to execute code in the new mapping.
674 .P
675 The portable way to create a mapping is to specify
676 .I addr
677 as 0 (NULL), and omit
678 .B MAP_FIXED
679 from
680 .IR flags .
681 In this case, the system chooses the address for the mapping;
682 the address is chosen so as not to conflict with any existing mapping,
683 and will not be 0.
684 If the
685 .B MAP_FIXED
686 flag is specified, and
687 .I addr
688 is 0 (NULL), then the mapped address will be 0 (NULL).
689 .P
690 Certain
691 .I flags
692 constants are defined only if suitable feature test macros are defined
693 (possibly by default):
694 .B _DEFAULT_SOURCE
695 with glibc 2.19 or later;
696 or
697 .B _BSD_SOURCE
698 or
699 .B _SVID_SOURCE
700 in glibc 2.19 and earlier.
701 (Employing
702 .B _GNU_SOURCE
703 also suffices,
704 and requiring that macro specifically would have been more logical,
705 since these flags are all Linux-specific.)
706 The relevant flags are:
707 .BR MAP_32BIT ,
708 .B MAP_ANONYMOUS
709 (and the synonym
710 .BR MAP_ANON ),
711 .BR MAP_DENYWRITE ,
712 .BR MAP_EXECUTABLE ,
713 .BR MAP_FILE ,
714 .BR MAP_GROWSDOWN ,
715 .BR MAP_HUGETLB ,
716 .BR MAP_LOCKED ,
717 .BR MAP_NONBLOCK ,
718 .BR MAP_NORESERVE ,
719 .BR MAP_POPULATE ,
720 and
721 .BR MAP_STACK .
722 .SS C library/kernel differences
723 This page describes the interface provided by the glibc
724 .BR mmap ()
725 wrapper function.
726 Originally, this function invoked a system call of the same name.
727 Since Linux 2.4, that system call has been superseded by
728 .BR mmap2 (2),
729 and nowadays
730 .\" Since around glibc 2.1/2.2, depending on the platform.
731 the glibc
732 .BR mmap ()
733 wrapper function invokes
734 .BR mmap2 (2)
735 with a suitably adjusted value for
736 .IR offset .
737 .SH STANDARDS
738 POSIX.1-2024.
739 .SH HISTORY
740 SVr4,
741 4.4BSD,
742 SUSv1,
743 POSIX.1-1996.
744 .\" SVr4 documents additional error codes ENXIO and ENODEV.
745 .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW.
746 .P
747 On POSIX systems on which
748 .BR mmap (),
749 .BR msync (2),
750 and
751 .BR munmap ()
752 are available,
753 .B _POSIX_MAPPED_FILES
754 is defined in
755 .I <unistd.h>
756 to a value greater than 0.
757 (See also
758 .BR sysconf (3).)
759 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
760 .\" -1: unavailable, 0: ask using sysconf().
761 .\" glibc defines it to 1.
762 .SH NOTES
763 Memory mapped by
764 .BR mmap ()
765 is preserved across
766 .BR fork (2),
767 with the same attributes.
768 .P
769 A file is mapped in multiples of the page size.
770 For a file that is not
771 a multiple of the page size,
772 the remaining bytes in the partial page at the end of the mapping
773 are zeroed when mapped,
774 and modifications to that region are not written out to the file.
775 The effect of
776 changing the size of the underlying file of a mapping on the pages that
777 correspond to added or removed regions of the file is unspecified.
778 .P
779 An application can determine which pages of a mapping are
780 currently resident in the buffer/page cache using
781 .BR mincore (2).
782 .\"
783 .SS Using MAP_FIXED safely
784 The only safe use for
785 .B MAP_FIXED
786 is where the address range specified by
787 .I addr
788 and
789 .I length
790 was previously reserved using another mapping;
791 otherwise, the use of
792 .B MAP_FIXED
793 is hazardous because it forcibly removes preexisting mappings,
794 making it easy for a multithreaded process to corrupt its own address space.
795 .P
796 For example, suppose that thread A looks through
797 .IR /proc/ pid /maps
798 in order to locate an unused address range that it can map using
799 .BR MAP_FIXED ,
800 while thread B simultaneously acquires part or all of that same
801 address range.
802 When thread A subsequently employs
803 .BR mmap(MAP_FIXED) ,
804 it will effectively clobber the mapping that thread B created.
805 In this scenario,
806 thread B need not create a mapping directly;
807 simply making a library call that,
808 internally,
809 uses
810 .BR dlopen (3)
811 to load some other shared library, will suffice.
812 The
813 .BR dlopen (3)
814 call will map the library into the process's address space.
815 Furthermore, almost any library call may be implemented in a way that
816 adds memory mappings to the address space, either with this technique,
817 or by simply allocating memory.
818 Examples include
819 .BR brk (2),
820 .BR malloc (3),
821 .BR pthread_create (3),
822 and the PAM libraries
823 .UR http:\://www.linux-pam.org
824 .UE .
825 .P
826 Since Linux 4.17, a multithreaded program can use the
827 .B MAP_FIXED_NOREPLACE
828 flag to avoid the hazard described above
829 when attempting to create a mapping at a fixed address
830 that has not been reserved by a preexisting mapping.
831 .\"
832 .SS Timestamps changes for file-backed mappings
833 For file-backed mappings, the
834 .I st_atime
835 field for the mapped file may be updated at any time between the
836 .BR mmap ()
837 and the corresponding unmapping;
838 the first reference to a mapped page
839 will update the field if it has not been already.
840 .P
841 The
842 .I st_ctime
843 and
844 .I st_mtime
845 field for a file mapped with
846 .B PROT_WRITE
847 and
848 .B MAP_SHARED
849 will be updated after
850 a write to the mapped region, and before a subsequent
851 .BR msync (2)
852 with the
853 .B MS_SYNC
854 or
855 .B MS_ASYNC
856 flag, if one occurs.
857 .\"
858 .SS Huge page (Huge TLB) mappings
859 For mappings that employ huge pages, the requirements for the arguments of
860 .BR mmap ()
861 and
862 .BR munmap ()
863 differ somewhat from the requirements for mappings
864 that use the native system page size.
865 .P
866 For
867 .BR mmap (),
868 .I offset
869 must be a multiple of the underlying huge page size.
870 The system automatically aligns
871 .I length
872 to be a multiple of the underlying huge page size.
873 .P
874 For
875 .BR munmap (),
876 .IR addr ,
877 and
878 .I length
879 must both be a multiple of the underlying huge page size.
880 .\"
881 .SH CAVEATS
882 Unlike typical
883 .BR malloc (3)
884 implementations,
885 .BR mmap ()
886 does not prevent creating objects larger than
887 .BR PTRDIFF_MAX .
888 Objects that are larger than
889 .B PTRDIFF_MAX
890 only work in limited ways in C
891 (in particular,
892 pointer subtraction results in undefined behavior
893 if the result would be bigger than
894 .BR PTRDIFF_MAX ).
895 On top of that,
896 GCC also assumes that no object is bigger than
897 .BR PTRDIFF_MAX .
898 .B PTRDIFF_MAX
899 is usually half of the address space size;
900 so for 32-bit processes,
901 it is usually
902 .B 0x7fffffff
903 (almost 2 GiB).
904 .\"
905 .SH BUGS
906 On Linux, there are no guarantees like those suggested above under
907 .BR MAP_NORESERVE .
908 By default, any process can be killed
909 at any moment when the system runs out of memory.
910 .P
911 Before Linux 2.6.7, the
912 .B MAP_POPULATE
913 flag has effect only if
914 .I prot
915 is specified as
916 .BR PROT_NONE .
917 .P
918 SUSv3 specifies that
919 .BR mmap ()
920 should fail if
921 .I length
922 is 0.
923 However, before Linux 2.6.12,
924 .BR mmap ()
925 succeeded in this case: no mapping was created and the call returned
926 .IR addr .
927 Since Linux 2.6.12,
928 .BR mmap ()
929 fails with the error
930 .B EINVAL
931 for this case.
932 .P
933 POSIX specifies that the system shall always
934 zero fill any partial page at the end
935 of the object and that system will never write any modification of the
936 object beyond its end.
937 On Linux, when you write data to such partial page after the end
938 of the object, the data stays in the page cache even after the file
939 is closed and unmapped
940 and even though the data is never written to the file itself,
941 subsequent mappings may see the modified content.
942 In some cases, this could be fixed by calling
943 .BR msync (2)
944 before the unmap takes place;
945 however, this doesn't work on
946 .BR tmpfs (5)
947 (for example, when using the POSIX shared memory interface documented in
948 .BR shm_overview (7)).
949 .SH EXAMPLES
950 .\" FIXME . Add an example here that uses an anonymous shared region for
951 .\" IPC between parent and child.
952 The following program prints part of the file specified in
953 its first command-line argument to standard output.
954 The range of bytes to be printed is specified via offset and length
955 values in the second and third command-line arguments.
956 The program creates a memory mapping of the required
957 pages of the file and then uses
958 .BR write (2)
959 to output the desired bytes.
960 .SS Program source
961 .\" SRC BEGIN (mmap.c)
962 .EX
963 #include <err.h>
964 #include <fcntl.h>
965 #include <stdio.h>
966 #include <stdlib.h>
967 #include <sys/mman.h>
968 #include <sys/stat.h>
969 #include <sys/types.h>
970 #include <unistd.h>
971 \&
972 int
973 main(int argc, char *argv[])
974 {
975 int fd;
976 char *addr;
977 off_t offset, pa_offset;
978 size_t length;
979 ssize_t s;
980 struct stat sb;
981 \&
982 if (argc < 3 || argc > 4) {
983 fprintf(stderr, "%s file offset [length]\[rs]n", argv[0]);
984 exit(EXIT_FAILURE);
985 }
986 \&
987 fd = open(argv[1], O_RDONLY);
988 if (fd == \-1)
989 err(EXIT_FAILURE, "open");
990 \&
991 if (fstat(fd, &sb) == \-1) /* To obtain file size */
992 err(EXIT_FAILURE, "fstat");
993 \&
994 offset = atoi(argv[2]);
995 pa_offset = offset & \[ti](sysconf(_SC_PAGE_SIZE) \- 1);
996 /* offset for mmap() must be page aligned */
997 \&
998 if (offset >= sb.st_size) {
999 fprintf(stderr, "offset is past end of file\[rs]n");
1000 exit(EXIT_FAILURE);
1001 }
1002 \&
1003 if (argc == 4) {
1004 length = atoi(argv[3]);
1005 if (offset + length > sb.st_size)
1006 length = sb.st_size \- offset;
1007 /* Can\[aq]t display bytes past end of file */
1008 \&
1009 } else { /* No length arg ==> display to end of file */
1010 length = sb.st_size \- offset;
1011 }
1012 \&
1013 addr = mmap(NULL, length + offset \- pa_offset, PROT_READ,
1014 MAP_PRIVATE, fd, pa_offset);
1015 if (addr == MAP_FAILED)
1016 err(EXIT_FAILURE, "mmap");
1017 \&
1018 s = write(STDOUT_FILENO, addr + offset \- pa_offset, length);
1019 if (s != length) {
1020 if (s == \-1)
1021 err(EXIT_FAILURE, "write");
1022 \&
1023 fprintf(stderr, "partial write");
1024 exit(EXIT_FAILURE);
1025 }
1026 \&
1027 munmap(addr, length + offset \- pa_offset);
1028 close(fd);
1029 \&
1030 exit(EXIT_SUCCESS);
1031 }
1032 .EE
1033 .\" SRC END
1034 .SH SEE ALSO
1035 .BR ftruncate (2),
1036 .BR getpagesize (2),
1037 .BR memfd_create (2),
1038 .BR mincore (2),
1039 .BR mlock (2),
1040 .BR mmap2 (2),
1041 .BR mprotect (2),
1042 .BR mremap (2),
1043 .BR msync (2),
1044 .BR remap_file_pages (2),
1045 .BR setrlimit (2),
1046 .BR shmat (2),
1047 .BR userfaultfd (2),
1048 .BR shm_open (3),
1049 .BR shm_overview (7)
1050 .P
1051 The descriptions of the following files in
1052 .BR proc (5):
1053 .IR /proc/ pid /maps ,
1054 .IR /proc/ pid /map_files ,
1055 and
1056 .IR /proc/ pid /smaps .
1057 .P
1058 B.O.\& Gallmeister, POSIX.4, O'Reilly, pp.\& 128\[en]129 and 389\[en]391.
1059 .\"
1060 .\" Repeat after me: private read-only mappings are 100% equivalent to
1061 .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus