1 .\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl>
2 .\" and Copyright (C) 2006, 2007 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
27 .\" Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
28 .\" Modified 2001-10-04 by John Levon <moz@compsoc.man.ac.uk>
29 .\" Modified 2003-02-02 by Andi Kleen <ak@muc.de>
30 .\" Modified 2003-05-21 by Michael Kerrisk <mtk.manpages@gmail.com>
31 .\" MAP_LOCKED works from 2.5.37
32 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
33 .\" Modified 2004-09-11 by aeb
34 .\" Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr>
35 .\" Modified 2004-12-08, mtk, formatting tidy-ups
36 .\" Modified 2006-12-04, mtk, various parts rewritten
37 .\" 2007-07-10, mtk, Added an example program.
38 .\" 2008-11-18, mtk, document MAP_STACK
40 .TH MMAP 2 2018-04-30 "Linux" "Linux Programmer's Manual"
42 mmap, munmap \- map or unmap files or devices into memory
45 .B #include <sys/mman.h>
47 .BI "void *mmap(void *" addr ", size_t " length \
48 ", int " prot ", int " flags ,
49 .BI " int " fd ", off_t " offset );
50 .BI "int munmap(void *" addr ", size_t " length );
53 See NOTES for information on feature test macro requirements.
56 creates a new mapping in the virtual address space of
58 The starting address for the new mapping is specified in
62 argument specifies the length of the mapping (which must be greater than 0).
67 then the kernel chooses the (page-aligned) address
68 at which to create the mapping;
69 this is the most portable method of creating a new mapping.
73 then the kernel takes it as a hint about where to place the mapping;
74 on Linux, the mapping will be created at a nearby page boundary.
75 .\" Before Linux 2.6.24, the address was rounded up to the next page
76 .\" boundary; since 2.6.24, it is rounded down!
77 The address of the new mapping is returned as the result of the call.
79 The contents of a file mapping (as opposed to an anonymous mapping; see
81 below), are initialized using
83 bytes starting at offset
85 in the file (or other object) referred to by the file descriptor
88 must be a multiple of the page size as returned by
89 .IR sysconf(_SC_PAGE_SIZE) .
93 call has returned, the file descriptor,
95 can be closed immediately without invalidating the mapping.
99 argument describes the desired memory protection of the mapping
100 (and must not conflict with the open mode of the file).
103 or the bitwise OR of one or more of the following flags:
106 Pages may be executed.
112 Pages may be written.
115 Pages may not be accessed.
119 argument determines whether updates to the mapping
120 are visible to other processes mapping the same region,
121 and whether updates are carried through to the underlying file.
122 This behavior is determined by including exactly one
123 of the following values in
128 Updates to the mapping are visible to other processes mapping the same region,
129 and (in the case of file-backed mappings)
130 are carried through to the underlying file.
131 (To precisely control when updates are carried through
132 to the underlying file requires the use of
135 .BR MAP_SHARED_VALIDATE " (since Linux 4.15)"
136 This flag provides the same behavior as
140 mappings ignore unknown flags in
142 By contrast, when creating a mapping using
143 .BR MAP_SHARED_VALIDATE ,
144 the kernel verifies all passed flags are known and fails the
145 mapping with the error
148 This mapping type is also required to be able to use some mapping flags
153 Create a private copy-on-write mapping.
154 Updates to the mapping are not visible to other processes
155 mapping the same file, and are not carried through to
157 It is unspecified whether changes made to the file after the
159 call are visible in the mapped region.
165 are described in POSIX.1-2001 and POSIX.1-2008.
166 .B MAP_SHARED_VALIDATE
167 is a Linux extension.
169 In addition, zero or more of the following values can be ORed in
172 .BR MAP_32BIT " (since Linux 2.4.20, 2.6)"
173 Put the mapping into the first 2 Gigabytes of the process address space.
174 This flag is supported only on x86-64, for 64-bit programs.
175 It was added to allow thread stacks to be allocated somewhere
176 in the first 2\ GB of memory,
177 so as to improve context-switch performance on some early
179 .\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
180 Modern x86-64 processors no longer have this performance problem,
181 so use of this flag is not required on those systems.
194 The mapping is not backed by any file;
195 its contents are initialized to zero.
199 however, some implementations require
206 and portable applications should ensure this.
209 argument should be zero.
210 .\" See the pgoff overflow check in do_mmap().
211 .\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c.
216 is supported on Linux only since kernel 2.4.
219 This flag is ignored.
220 .\" Introduced in 1.1.36, removed in 1.3.24.
221 (Long ago\(emLinux 2.0 and earlier\(emit signaled
222 that attempts to write to the underlying file should fail with
224 But this was a source of denial-of-service attacks.)
227 This flag is ignored.
228 .\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link.
229 .\" (Long ago, it signaled that the underlying file is an executable.
230 .\" However, that information was not really used anywhere.)
231 .\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of
237 .\" On some systems, this was required as the opposite of
238 .\" MAP_ANONYMOUS -- mtk, 1 May 2007
243 as a hint: place the mapping at exactly that address.
245 must be suitably aligned: for most architectures a multiple of the page
246 size is sufficient; however, some architectures may impose additional
248 If the memory region specified by
252 overlaps pages of any existing mapping(s), then the overlapped
253 part of the existing mapping(s) will be discarded.
254 If the specified address cannot be used,
258 Software that aspires to be portable should use the
261 keeping in mind that the exact layout of a process's memory mappings
262 is allowed to change significantly between kernel versions,
263 C library versions, and operating system releases.
264 .IR "Carefully read the discussion of this flag in NOTES!"
266 .BR MAP_FIXED_NOREPLACE " (since Linux 4.17)"
267 .\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843
268 This flag provides behavior that is similar to
272 enforcement, but differs in that
273 .B MAP_FIXED_NOREPLACE
274 never clobbers a preexisting mapped range.
275 If the requested range would collide with an existing mapping,
276 then this call fails with the error
278 This flag can therefore be used as a way to atomically
279 (with respect to other threads) attempt to map an address range:
280 one thread will succeed; all others will report failure.
282 Note that older kernels which do not recognize the
283 .BR MAP_FIXED_NOREPLACE
284 flag will typically (upon detecting a collision with a preexisting mapping)
285 fall back to a "non-\c
288 they will return an address that is different from the requested address.
289 Therefore, backward-compatible software
290 should check the returned address against the requested address.
293 This flag is used for stacks.
294 It indicates to the kernel virtual memory system that the mapping
295 should extend downward in memory.
296 The return address is one page lower than the memory area that is
297 actually created in the process's virtual address space.
298 Touching an address in the "guard" page below the mapping will cause
299 the mapping to grow by a page.
300 This growth can be repeated until the mapping grows to within a
301 page of the high end of the next lower mapping,
302 at which point touching the "guard" page will result in a
306 .BR MAP_HUGETLB " (since Linux 2.6.32)"
307 Allocate the mapping using "huge pages."
308 See the Linux kernel source file
309 .I Documentation/admin-guide/mm/hugetlbpage.rst
310 for further information, as well as NOTES, below.
312 .BR MAP_HUGE_2MB ", " MAP_HUGE_1GB " (since Linux 3.8)"
313 .\" See https://lwn.net/Articles/533499/
314 Used in conjunction with
316 to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB)
317 on systems that support multiple hugetlb page sizes.
319 More generally, the desired huge page size can be configured by encoding
320 the base-2 logarithm of the desired page size in the six bits at the offset
322 (A value of zero in this bit field provides the default huge page size;
323 the default huge page size can be discovered via the
327 Thus, the above two constants are defined as:
331 #define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT)
332 #define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT)
336 The range of huge page sizes that are supported by the system
337 can be discovered by listing the subdirectories in
338 .IR /sys/kernel/mm/hugepages .
340 .BR MAP_LOCKED " (since Linux 2.5.37)"
341 Mark the mapped region to be locked in the same way as
343 This implementation will try to populate (prefault) the whole range but the
345 call doesn't fail with
348 Therefore major faults might happen later on.
349 So the semantic is not as strong as
355 when major faults are not acceptable after the initialization of the mapping.
358 flag is ignored in older kernels.
359 .\" If set, the mapped pages will not be swapped out.
361 .BR MAP_NONBLOCK " (since Linux 2.5.46)"
362 This flag is meaningful only in conjunction with
364 Don't perform read-ahead:
365 create page tables entries only for pages
366 that are already present in RAM.
367 Since Linux 2.6.23, this flag causes
370 One day, the combination of
374 may be reimplemented.
377 Do not reserve swap space for this mapping.
378 When swap space is reserved, one has the guarantee
379 that it is possible to modify the mapping.
380 When swap space is not reserved one might get
383 if no physical memory is available.
384 See also the discussion of the file
385 .I /proc/sys/vm/overcommit_memory
388 In kernels before 2.6, this flag had effect only for
389 private writable mappings.
391 .BR MAP_POPULATE " (since Linux 2.5.46)"
392 Populate (prefault) page tables for a mapping.
393 For a file mapping, this causes read-ahead on the file.
394 This will help to reduce blocking on page faults later.
396 is supported for private mappings only since Linux 2.6.23.
398 .BR MAP_STACK " (since Linux 2.6.27)"
399 Allocate the mapping at an address suitable for a process
401 This flag is currently a no-op,
402 but is used in the glibc threading implementation so that
403 if some architectures require special treatment for stack allocations,
404 support can later be transparently implemented for glibc.
405 .\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
406 .\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7
407 .\" http://thread.gmane.org/gmane.linux.kernel/720412
408 .\" "pthread_create() slow for many threads; also time to revisit 64b
409 .\" context switch optimization?"
411 .BR MAP_SYNC " (since Linux 4.15)"
412 This flag is available only with the
413 .B MAP_SHARED_VALIDATE
417 will silently ignore this flag.
418 This flag is supported only for files supporting DAX
419 (direct mapping of persistent memory).
420 For other files, creating a mapping with this flag results in an
424 Shared file mappings with this flag provide the guarantee that while
425 some memory is writably mapped in the address space of the process,
426 it will be visible in the same file at the same offset even after
427 the system crashes or is rebooted.
428 In conjunction with the use of appropriate CPU instructions,
429 this provides users of such mappings with a more efficient way
430 of making data modifications persistent.
432 .BR MAP_UNINITIALIZED " (since Linux 2.6.33)"
433 Don't clear anonymous pages.
434 This flag is intended to improve performance on embedded devices.
435 This flag is honored only if the kernel was configured with the
436 .B CONFIG_MMAP_ALLOW_UNINITIALIZED
438 Because of the security implications,
439 that option is normally enabled only on embedded devices
440 (i.e., devices where one has complete control of the contents of user memory).
442 Of the above flags, only
444 is specified in POSIX.1-2001 and POSIX.1-2008.
445 However, most systems also support
449 .\" FIXME . for later review when Issue 8 is one day released...
450 .\" POSIX may add MAP_ANON in the future
451 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
452 .\" http://austingroupbugs.net/view.php?id=850
458 with the same attributes.
460 A file is mapped in multiples of the page size.
461 For a file that is not
462 a multiple of the page size, the remaining memory is zeroed when mapped,
463 and writes to that region are not written out to the file.
465 changing the size of the underlying file of a mapping on the pages that
466 correspond to added or removed regions of the file is unspecified.
470 system call deletes the mappings for the specified address range, and
471 causes further references to addresses within the range to generate
472 invalid memory references.
473 The region is also automatically unmapped
474 when the process is terminated.
475 On the other hand, closing the file
476 descriptor does not unmap the region.
480 must be a multiple of the page size (but
483 All pages containing a part
484 of the indicated range are unmapped, and subsequent references
485 to these pages will generate
487 It is not an error if the
488 indicated range does not contain any mapped pages.
492 returns a pointer to the mapped area.
496 .IR "(void\ *)\ \-1" )
499 is set to indicate the cause of the error.
504 On failure, it returns \-1, and
506 is set to indicate the cause of the error (probably to
511 A file descriptor refers to a non-regular file.
512 Or a file mapping was requested, but
514 is not open for reading.
521 is not open in read/write
526 is set, but the file is append-only.
529 The file has been locked, or too much memory has been locked (see
534 is not a valid file descriptor (and
539 .BR MAP_FIXED_NOREPLACE
542 and the range covered by
546 clashes with an existing mapping.
554 (e.g., they are too large, or not aligned on a page boundary).
567 or contained both of these values.
570 .\" This is for shared anonymous segments
571 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
572 The system-wide limit on the total number of open files has been reached.
575 .\" A file could not be mapped for reading.
578 The underlying filesystem of the specified file does not support
582 No memory is available.
585 The process's maximum number of mappings would have been exceeded.
586 This error can also occur for
588 when unmapping a region in the middle of an existing mapping,
589 since this results in two smaller mappings on either side of
590 the region being unmapped.
598 would have been exceeded.
601 On 32-bit architecture together with the large file extension
604 the number of pages used for
606 plus number of pages used for
617 but the mapped area belongs to a file on a filesystem that
619 .\" (Since 2.4.25 / 2.6.0.)
622 The operation was prevented by a file seal; see
627 was set but the object specified by
631 Use of a mapped region can result in these signals:
634 Attempted write into a region mapped as read-only.
637 Attempted access to a portion of the buffer that does not correspond
638 to the file (for example, beyond the end of the file, including the
639 case where another process has truncated the file).
641 For an explanation of the terms used in this section, see
647 Interface Attribute Value
651 T} Thread safety MT-Safe
654 POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD.
655 .\" SVr4 documents additional error codes ENXIO and ENODEV.
656 .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW.
658 On POSIX systems on which
664 .B _POSIX_MAPPED_FILES
665 is defined in \fI<unistd.h>\fP to a value greater than 0.
668 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
669 .\" -1: unavailable, 0: ask using sysconf().
670 .\" glibc defines it to 1.
672 On some hardware architectures (e.g., i386),
676 It is architecture dependent whether
681 Portable programs should always set
683 if they intend to execute code in the new mapping.
685 The portable way to create a mapping is to specify
687 as 0 (NULL), and omit
691 In this case, the system chooses the address for the mapping;
692 the address is chosen so as not to conflict with any existing mapping,
696 flag is specified, and
698 is 0 (NULL), then the mapped address will be 0 (NULL).
702 constants are defined only if suitable feature test macros are defined
703 (possibly by default):
705 with glibc 2.19 or later;
710 in glibc 2.19 and earlier.
714 and requiring that macro specifically would have been more logical,
715 since these flags are all Linux-specific.)
716 The relevant flags are:
733 An application can determine which pages of a mapping are
734 currently resident in the buffer/page cache using
737 .SS Using MAP_FIXED safely
738 The only safe use for
740 is where the address range specified by
744 was previously reserved using another mapping;
745 otherwise, the use of
747 is hazardous because it forcibly removes preexisting mappings,
748 making it easy for a multithreaded process to corrupt its own address space.
750 For example, suppose that thread A looks through
752 and in order to locate an unused address range that it can map using
754 while thread B simultaneously acquires part or all of that same
756 When thread A subsequently employs
757 .BR mmap(MAP_FIXED) ,
758 it will effectively clobber the mapping that thread B created.
760 thread B need not create a mapping directly; simply making a library call
761 that, internally, uses
763 to load some other shared library, will suffice.
766 call will map the library into the process's address space.
767 Furthermore, almost any library call may be implemented in a way that
768 adds memory mappings to the address space, either with this technique,
769 or by simply allocating memory.
773 .BR pthread_create (3),
774 and the PAM libraries
775 .UR http://www.linux-pam.org
778 Since Linux 4.17, a multithreaded program can use the
779 .BR MAP_FIXED_NOREPLACE
780 flag to avoid the hazard described above
781 when attempting to create a mapping at a fixed address
782 that has not been reserved by a preexisting mapping.
784 .SS Timestamps changes for file-backed mappings
785 For file-backed mappings, the
787 field for the mapped file may be updated at any time between the
789 and the corresponding unmapping; the first reference to a mapped
790 page will update the field if it has not been already.
796 field for a file mapped with
800 will be updated after
801 a write to the mapped region, and before a subsequent
809 .SS Huge page (Huge TLB) mappings
810 For mappings that employ huge pages, the requirements for the arguments of
814 differ somewhat from the requirements for mappings
815 that use the native system page size.
820 must be a multiple of the underlying huge page size.
821 The system automatically aligns
823 to be a multiple of the underlying huge page size.
830 must both be a multiple of the underlying huge page size.
832 .SS C library/kernel differences
833 This page describes the interface provided by the glibc
836 Originally, this function invoked a system call of the same name.
837 Since kernel 2.4, that system call has been superseded by
840 .\" Since around glibc 2.1/2.2, depending on the platform.
843 wrapper function invokes
845 with a suitably adjusted value for
848 On Linux, there are no guarantees like those suggested above under
850 By default, any process can be killed
851 at any moment when the system runs out of memory.
853 In kernels before 2.6.7, the
855 flag has effect only if
865 However, in kernels before 2.6.12,
867 succeeded in this case: no mapping was created and the call returned
875 POSIX specifies that the system shall always
876 zero fill any partial page at the end
877 of the object and that system will never write any modification of the
878 object beyond its end.
879 On Linux, when you write data to such partial page after the end
880 of the object, the data stays in the page cache even after the file
881 is closed and unmapped
882 and even though the data is never written to the file itself,
883 subsequent mappings may see the modified content.
884 In some cases, this could be fixed by calling
886 before the unmap takes place;
887 however, this doesn't work on
889 (for example, when using the POSIX shared memory interface documented in
890 .BR shm_overview (7)).
892 .\" FIXME . Add an example here that uses an anonymous shared region for
893 .\" IPC between parent and child.
895 The following program prints part of the file specified in
896 its first command-line argument to standard output.
897 The range of bytes to be printed is specified via offset and length
898 values in the second and third command-line arguments.
899 The program creates a memory mapping of the required
900 pages of the file and then uses
902 to output the desired bytes.
905 #include <sys/mman.h>
906 #include <sys/stat.h>
912 #define handle_error(msg) \\
913 do { perror(msg); exit(EXIT_FAILURE); } while (0)
916 main(int argc, char *argv[])
921 off_t offset, pa_offset;
925 if (argc < 3 || argc > 4) {
926 fprintf(stderr, "%s file offset [length]\\n", argv[0]);
930 fd = open(argv[1], O_RDONLY);
932 handle_error("open");
934 if (fstat(fd, &sb) == \-1) /* To obtain file size */
935 handle_error("fstat");
937 offset = atoi(argv[2]);
938 pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) \- 1);
939 /* offset for mmap() must be page aligned */
941 if (offset >= sb.st_size) {
942 fprintf(stderr, "offset is past end of file\\n");
947 length = atoi(argv[3]);
948 if (offset + length > sb.st_size)
949 length = sb.st_size \- offset;
950 /* Can\(aqt display bytes past end of file */
952 } else { /* No length arg ==> display to end of file */
953 length = sb.st_size \- offset;
956 addr = mmap(NULL, length + offset \- pa_offset, PROT_READ,
957 MAP_PRIVATE, fd, pa_offset);
958 if (addr == MAP_FAILED)
959 handle_error("mmap");
961 s = write(STDOUT_FILENO, addr + offset \- pa_offset, length);
964 handle_error("write");
966 fprintf(stderr, "partial write");
970 munmap(addr, length + offset \- pa_offset);
979 .BR memfd_create (2),
986 .BR remap_file_pages (2),
993 The descriptions of the following files in
995 .IR /proc/[pid]/maps ,
996 .IR /proc/[pid]/map_files ,
998 .IR /proc/[pid]/smaps .
1000 B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391.
1002 .\" Repeat after me: private read-only mappings are 100% equivalent to
1003 .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus