1MMAP(2) Linux Programmer's Manual MMAP(2)
2
6 mmap, munmap - map or unmap files or devices into memory
7
9 #include <sys/mman.h>
10 void *mmap(void *addr, size_t length, int prot, int flags,
12 int fd, off_t offset);
13 int munmap(void *addr, size_t length);
14 See NOTES for information on feature test macro requirements.
16
18 mmap() creates a new mapping in the virtual address space of the call‐
19 ing process. The starting address for the new mapping is specified in
20 addr. The length argument specifies the length of the mapping (which
21 must be greater than 0).
22 If addr is NULL, then the kernel chooses the address at which to create
24 the mapping; this is the most portable method of creating a new map‐
25 ping. If addr is not NULL, then the kernel takes it as a hint about
26 where to place the mapping; on Linux, the mapping will be created at a
27 nearby page boundary. The address of the new mapping is returned as
28 the result of the call.
29 The contents of a file mapping (as opposed to an anonymous mapping; see
31 MAP_ANONYMOUS below), are initialized using length bytes starting at
32 offset offset in the file (or other object) referred to by the file
33 descriptor fd. offset must be a multiple of the page size as returned
34 by sysconf(_SC_PAGE_SIZE).
35 The prot argument describes the desired memory protection of the map‐
37 ping (and must not conflict with the open mode of the file). It is
38 either PROT_NONE or the bitwise OR of one or more of the following
39 flags:
40 PROT_EXEC Pages may be executed.
42 PROT_READ Pages may be read.
44 PROT_WRITE Pages may be written.
46 PROT_NONE Pages may not be accessed.
48 The flags argument determines whether updates to the mapping are visi‐
50 ble to other processes mapping the same region, and whether updates are
51 carried through to the underlying file. This behavior is determined by
52 including exactly one of the following values in flags:
53 MAP_SHARED
55 Share this mapping. Updates to the mapping are visible to other
56 processes mapping the same region, and (in the case of file-
57 backed mappings) are carried through to the underlying file.
58 (To precisely control when updates are carried through to the
59 underlying file requires the use of msync(2).)
60 MAP_PRIVATE
62 Create a private copy-on-write mapping. Updates to the mapping
63 are not visible to other processes mapping the same file, and
64 are not carried through to the underlying file. It is unspeci‐
65 fied whether changes made to the file after the mmap() call are
66 visible in the mapped region.
67 Both of these flags are described in POSIX.1-2001 and POSIX.1-2008.
69 In addition, zero or more of the following values can be ORed in flags:
71 MAP_32BIT (since Linux 2.4.20, 2.6)
73 Put the mapping into the first 2 Gigabytes of the process
74 address space. This flag is supported only on x86-64, for
75 64-bit programs. It was added to allow thread stacks to be
76 allocated somewhere in the first 2 GB of memory, so as to
77 improve context-switch performance on some early 64-bit proces‐
78 sors. Modern x86-64 processors no longer have this performance
79 problem, so use of this flag is not required on those systems.
80 The MAP_32BIT flag is ignored when MAP_FIXED is set.
81 MAP_ANON
83 Synonym for MAP_ANONYMOUS. Deprecated.
84 MAP_ANONYMOUS
86 The mapping is not backed by any file; its contents are initial‐
87 ized to zero. The fd argument is ignored; however, some imple‐
88 mentations require fd to be -1 if MAP_ANONYMOUS (or MAP_ANON) is
89 specified, and portable applications should ensure this. The
90 offset argument should be zero. The use of MAP_ANONYMOUS in
91 conjunction with MAP_SHARED is supported on Linux only since
92 kernel 2.4.
93 MAP_DENYWRITE
95 This flag is ignored. (Long ago, it signaled that attempts to
96 write to the underlying file should fail with ETXTBUSY. But
97 this was a source of denial-of-service attacks.)
98 MAP_EXECUTABLE
100 This flag is ignored.
101 MAP_FILE
103 Compatibility flag. Ignored.
104 MAP_FIXED
106 Don't interpret addr as a hint: place the mapping at exactly
107 that address. addr must be suitably aligned: for most architec‐
108 tures a multiple of the page size is sufficient; however, some
109 architectures may impose additional restrictions. If the memory
110 region specified by addr and len overlaps pages of any existing
111 mapping(s), then the overlapped part of the existing mapping(s)
112 will be discarded. If the specified address cannot be used,
113 mmap() will fail. Software that aspires to be portable should
114 use this option with care, keeping in mind that the exact layout
115 of a process's memory mappings is allowed to change signifi‐
116 cantly between kernel versions, C library versions, and operat‐
117 ing system releases.
118 Furthermore, this option is extremely hazardous (when used on
120 its own), because it forcibly removes preexisting mappings, mak‐
121 ing it easy for a multithreaded process to corrupt its own
122 address space.
123 For example, thread A looks through /proc/<pid>/maps and locates
125 an available address range, while thread B simultaneously
126 acquires part or all of that same address range. Thread A then
127 calls mmap(MAP_FIXED), effectively overwriting the mapping that
128 thread B created.
129 Thread B need not create a mapping directly; simply making a
131 library call that, internally, uses dlopen(3) to load some other
132 shared library, will suffice. The dlopen(3) call will map the
133 library into the process's address space. Furthermore, almost
134 any library call may be implemented in a way that adds memory
135 mappings to the address space, either with this technique, or by
136 simply allocating memory. Examples include brk(2), malloc(3),
137 pthread_create(3), and the PAM libraries ⟨http://www.linux-
138 pam.org⟩.
139 MAP_GROWSDOWN
141 This flag is used for stacks. It indicates to the kernel vir‐
142 tual memory system that the mapping should extend downward in
143 memory. The return address is one page lower than the memory
144 area that is actually created in the process's virtual address
145 space. Touching an address in the "guard" page below the map‐
146 ping will cause the mapping to grow by a page. This growth can
147 be repeated until the mapping grows to within a page of the high
148 end of the next lower mapping, at which point touching the
149 "guard" page will result in a SIGSEGV signal.
150 MAP_HUGETLB (since Linux 2.6.32)
152 Allocate the mapping using "huge pages." See the Linux kernel
153 source file Documentation/vm/hugetlbpage.txt for further infor‐
154 mation, as well as NOTES, below.
155 MAP_HUGE_2MB, MAP_HUGE_1GB (since Linux 3.8)
157 Used in conjunction with MAP_HUGETLB to select alternative
158 hugetlb page sizes (respectively, 2 MB and 1 GB) on systems that
159 support multiple hugetlb page sizes.
160 More generally, the desired huge page size can be configured by
162 encoding the base-2 logarithm of the desired page size in the
163 six bits at the offset MAP_HUGE_SHIFT. (A value of zero in this
164 bit field provides the default huge page size; the default huge
165 page size can be discovered vie the Hugepagesize field exposed
166 by /proc/meminfo.) Thus, the above two constants are defined
167 as:
168 #define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT)
170 #define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT)
171 The range of huge page sizes that are supported by the system
173 can be discovered by listing the subdirectories in /sys/ker‐
174 nel/mm/hugepages.
175 MAP_LOCKED (since Linux 2.5.37)
177 Mark the mapped region to be locked in the same way as mlock(2).
178 This implementation will try to populate (prefault) the whole
179 range but the mmap() call doesn't fail with ENOMEM if this
180 fails. Therefore major faults might happen later on. So the
181 semantic is not as strong as mlock(2). One should use mmap()
182 plus mlock(2) when major faults are not acceptable after the
183 initialization of the mapping. The MAP_LOCKED flag is ignored
184 in older kernels.
185 MAP_NONBLOCK (since Linux 2.5.46)
187 This flag is meaningful only in conjunction with MAP_POPULATE.
188 Don't perform read-ahead: create page tables entries only for
189 pages that are already present in RAM. Since Linux 2.6.23, this
190 flag causes MAP_POPULATE to do nothing. One day, the combina‐
191 tion of MAP_POPULATE and MAP_NONBLOCK may be reimplemented.
192 MAP_NORESERVE
194 Do not reserve swap space for this mapping. When swap space is
195 reserved, one has the guarantee that it is possible to modify
196 the mapping. When swap space is not reserved one might get
197 SIGSEGV upon a write if no physical memory is available. See
198 also the discussion of the file /proc/sys/vm/overcommit_memory
199 in proc(5). In kernels before 2.6, this flag had effect only
200 for private writable mappings.
201 MAP_POPULATE (since Linux 2.5.46)
203 Populate (prefault) page tables for a mapping. For a file map‐
204 ping, this causes read-ahead on the file. This will help to
205 reduce blocking on page faults later. MAP_POPULATE is supported
206 for private mappings only since Linux 2.6.23.
207 MAP_STACK (since Linux 2.6.27)
209 Allocate the mapping at an address suitable for a process or
210 thread stack. This flag is currently a no-op, but is used in
211 the glibc threading implementation so that if some architectures
212 require special treatment for stack allocations, support can
213 later be transparently implemented for glibc.
214 MAP_UNINITIALIZED (since Linux 2.6.33)
216 Don't clear anonymous pages. This flag is intended to improve
217 performance on embedded devices. This flag is honored only if
218 the kernel was configured with the CONFIG_MMAP_ALLOW_UNINITIAL‐
219 IZED option. Because of the security implications, that option
220 is normally enabled only on embedded devices (i.e., devices
221 where one has complete control of the contents of user memory).
222 Of the above flags, only MAP_FIXED is specified in POSIX.1-2001 and
224 POSIX.1-2008. However, most systems also support MAP_ANONYMOUS (or its
225 synonym MAP_ANON).
226 Memory mapped by mmap() is preserved across fork(2), with the same
228 attributes.
229 A file is mapped in multiples of the page size. For a file that is not
231 a multiple of the page size, the remaining memory is zeroed when
232 mapped, and writes to that region are not written out to the file. The
233 effect of changing the size of the underlying file of a mapping on the
234 pages that correspond to added or removed regions of the file is
235 unspecified.
236 munmap()
238 The munmap() system call deletes the mappings for the specified address
239 range, and causes further references to addresses within the range to
240 generate invalid memory references. The region is also automatically
241 unmapped when the process is terminated. On the other hand, closing
242 the file descriptor does not unmap the region.
243 The address addr must be a multiple of the page size (but length need
245 not be). All pages containing a part of the indicated range are
246 unmapped, and subsequent references to these pages will generate
247 SIGSEGV. It is not an error if the indicated range does not contain
248 any mapped pages.
249
251 On success, mmap() returns a pointer to the mapped area. On error, the
252 value MAP_FAILED (that is, (void *) -1) is returned, and errno is set
253 to indicate the cause of the error.
254 On success, munmap() returns 0. On failure, it returns -1, and errno
256 is set to indicate the cause of the error (probably to EINVAL).
257
259 EACCES A file descriptor refers to a non-regular file. Or a file map‐
260 ping was requested, but fd is not open for reading. Or
261 MAP_SHARED was requested and PROT_WRITE is set, but fd is not
262 open in read/write (O_RDWR) mode. Or PROT_WRITE is set, but the
263 file is append-only.
264 EAGAIN The file has been locked, or too much memory has been locked
266 (see setrlimit(2)).
267 EBADF fd is not a valid file descriptor (and MAP_ANONYMOUS was not
269 set).
270 EINVAL We don't like addr, length, or offset (e.g., they are too large,
272 or not aligned on a page boundary).
273 EINVAL (since Linux 2.6.12) length was 0.
275 EINVAL flags contained neither MAP_PRIVATE or MAP_SHARED, or contained
277 both of these values.
278 ENFILE The system-wide limit on the total number of open files has been
280 reached.
281 ENODEV The underlying filesystem of the specified file does not support
283 memory mapping.
284 ENOMEM No memory is available.
286 ENOMEM The process's maximum number of mappings would have been
288 exceeded. This error can also occur for munmap(), when unmap‐
289 ping a region in the middle of an existing mapping, since this
290 results in two smaller mappings on either side of the region
291 being unmapped.
292 ENOMEM (since Linux 4.7) The process's RLIMIT_DATA limit, described in
294 getrlimit(2), would have been exceeded.
295 EOVERFLOW
297 On 32-bit architecture together with the large file extension
298 (i.e., using 64-bit off_t): the number of pages used for length
299 plus number of pages used for offset would overflow unsigned
300 long (32 bits).
301 EPERM The prot argument asks for PROT_EXEC but the mapped area belongs
303 to a file on a filesystem that was mounted no-exec.
304 EPERM The operation was prevented by a file seal; see fcntl(2).
306 ETXTBSY
308 MAP_DENYWRITE was set but the object specified by fd is open for
309 writing.
310 Use of a mapped region can result in these signals:
312 SIGSEGV
314 Attempted write into a region mapped as read-only.
315 SIGBUS Attempted access to a portion of the buffer that does not corre‐
317 spond to the file (for example, beyond the end of the file,
318 including the case where another process has truncated the
319 file).
320
322 For an explanation of the terms used in this section, see
323 attributes(7).
324 ┌───────────────────┬───────────────┬─────────┐
326 │Interface │ Attribute │ Value │
327 ├───────────────────┼───────────────┼─────────┤
328 │mmap(), munmap() │ Thread safety │ MT-Safe │
329 └───────────────────┴───────────────┴─────────┘
331 POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD.
332
334 On POSIX systems on which mmap(), msync(2), and munmap() are available,
335 _POSIX_MAPPED_FILES is defined in <unistd.h> to a value greater than 0.
336 (See also sysconf(3).)
337
339 On some hardware architectures (e.g., i386), PROT_WRITE implies
340 PROT_READ. It is architecture dependent whether PROT_READ implies
341 PROT_EXEC or not. Portable programs should always set PROT_EXEC if
342 they intend to execute code in the new mapping.
343 The portable way to create a mapping is to specify addr as 0 (NULL),
345 and omit MAP_FIXED from flags. In this case, the system chooses the
346 address for the mapping; the address is chosen so as not to conflict
347 with any existing mapping, and will not be 0. If the MAP_FIXED flag is
348 specified, and addr is 0 (NULL), then the mapped address will be 0
349 (NULL).
350 Certain flags constants are defined only if suitable feature test
352 macros are defined (possibly by default): _DEFAULT_SOURCE with glibc
353 2.19 or later; or _BSD_SOURCE or _SVID_SOURCE in glibc 2.19 and ear‐
354 lier. (Employing _GNU_SOURCE also suffices, and requiring that macro
355 specifically would have been more logical, since these flags are all
356 Linux-specific.) The relevant flags are: MAP_32BIT, MAP_ANONYMOUS (and
357 the synonym MAP_ANON), MAP_DENYWRITE, MAP_EXECUTABLE, MAP_FILE,
358 MAP_GROWSDOWN, MAP_HUGETLB, MAP_LOCKED, MAP_NONBLOCK, MAP_NORESERVE,
359 MAP_POPULATE, and MAP_STACK.
360 An application can determine which pages of a mapping are currently
362 resident in the buffer/page cache using mincore(2).
363 Timestamps changes for file-backed mappings
365 For file-backed mappings, the st_atime field for the mapped file may be
366 updated at any time between the mmap() and the corresponding unmapping;
367 the first reference to a mapped page will update the field if it has
368 not been already.
369 The st_ctime and st_mtime field for a file mapped with PROT_WRITE and
371 MAP_SHARED will be updated after a write to the mapped region, and
372 before a subsequent msync(2) with the MS_SYNC or MS_ASYNC flag, if one
373 occurs.
374 Huge page (Huge TLB) mappings
376 For mappings that employ huge pages, the requirements for the arguments
377 of mmap() and munmap() differ somewhat from the requirements for map‐
378 pings that use the native system page size.
379 For mmap(), offset must be a multiple of the underlying huge page size.
381 The system automatically aligns length to be a multiple of the underly‐
382 ing huge page size.
383 For munmap(), addr and length must both be a multiple of the underlying
385 huge page size.
386 C library/kernel differences
388 This page describes the interface provided by the glibc mmap() wrapper
389 function. Originally, this function invoked a system call of the same
390 name. Since kernel 2.4, that system call has been superseded by
391 mmap2(2), and nowadays the glibc mmap() wrapper function invokes
392 mmap2(2) with a suitably adjusted value for offset.
393
395 On Linux, there are no guarantees like those suggested above under
396 MAP_NORESERVE. By default, any process can be killed at any moment
397 when the system runs out of memory.
398 In kernels before 2.6.7, the MAP_POPULATE flag has effect only if prot
400 is specified as PROT_NONE.
401 SUSv3 specifies that mmap() should fail if length is 0. However, in
403 kernels before 2.6.12, mmap() succeeded in this case: no mapping was
404 created and the call returned addr. Since kernel 2.6.12, mmap() fails
405 with the error EINVAL for this case.
406 POSIX specifies that the system shall always zero fill any partial page
408 at the end of the object and that system will never write any modifica‐
409 tion of the object beyond its end. On Linux, when you write data to
410 such partial page after the end of the object, the data stays in the
411 page cache even after the file is closed and unmapped and even though
412 the data is never written to the file itself, subsequent mappings may
413 see the modified content. In some cases, this could be fixed by call‐
414 ing msync(2) before the unmap takes place; however, this doesn't work
415 on tmpfs(5) (for example, when using the POSIX shared memory interface
416 documented in shm_overview(7)).
417
419 The following program prints part of the file specified in its first
420 command-line argument to standard output. The range of bytes to be
421 printed is specified via offset and length values in the second and
422 third command-line arguments. The program creates a memory mapping of
423 the required pages of the file and then uses write(2) to output the
424 desired bytes.
425 Program source
427 #include <sys/mman.h>
428 #include <sys/stat.h>
429 #include <fcntl.h>
430 #include <stdio.h>
431 #include <stdlib.h>
432 #include <unistd.h>
433 #define handle_error(msg) \
435 do { perror(msg); exit(EXIT_FAILURE); } while (0)
436 int
438 main(int argc, char *argv[])
439 {
440 char *addr;
441 int fd;
442 struct stat sb;
443 off_t offset, pa_offset;
444 size_t length;
445 ssize_t s;
446 if (argc < 3 || argc > 4) {
448 fprintf(stderr, "%s file offset [length]\n", argv[0]);
449 exit(EXIT_FAILURE);
450 }
451 fd = open(argv[1], O_RDONLY);
453 if (fd == -1)
454 handle_error("open");
455 if (fstat(fd, &sb) == -1) /* To obtain file size */
457 handle_error("fstat");
458 offset = atoi(argv[2]);
460 pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) - 1);
461 /* offset for mmap() must be page aligned */
462 if (offset >= sb.st_size) {
464 fprintf(stderr, "offset is past end of file\n");
465 exit(EXIT_FAILURE);
466 }
467 if (argc == 4) {
469 length = atoi(argv[3]);
470 if (offset + length > sb.st_size)
471 length = sb.st_size - offset;
472 /* Can't display bytes past end of file */
473 } else { /* No length arg ==> display to end of file */
475 length = sb.st_size - offset;
476 }
477 addr = mmap(NULL, length + offset - pa_offset, PROT_READ,
479 MAP_PRIVATE, fd, pa_offset);
480 if (addr == MAP_FAILED)
481 handle_error("mmap");
482 s = write(STDOUT_FILENO, addr + offset - pa_offset, length);
484 if (s != length) {
485 if (s == -1)
486 handle_error("write");
487 fprintf(stderr, "partial write");
489 exit(EXIT_FAILURE);
490 }
491 munmap(addr, length + offset - pa_offset);
493 close(fd);
494 exit(EXIT_SUCCESS);
496 }
497
499 ftruncate(2), getpagesize(2), memfd_create(2), mincore(2), mlock(2),
500 mmap2(2), mprotect(2), mremap(2), msync(2), remap_file_pages(2), setr‐
501 limit(2), shmat(2), userfaultfd(2), shm_open(3), shm_overview(7)
502 The descriptions of the following files in proc(5): /proc/[pid]/maps,
504 /proc/[pid]/map_files, and /proc/[pid]/smaps.
505 B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128–129 and 389–391.
507
509 This page is part of release 4.15 of the Linux man-pages project. A
510 description of the project, information about reporting bugs, and the
511 latest version of this page, can be found at
512 https://www.kernel.org/doc/man-pages/.
513Linux 2017-12-18 MMAP(2)