]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl> | |
2 | .\" and Copyright (C) 2006, 2007 Michael Kerrisk <mtk.manpages@gmail.com> | |
3 | .\" | |
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. | |
8 | .\" | |
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. | |
13 | .\" | |
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 | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
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 | |
39 | .\" | |
40 | .TH MMAP 2 2018-04-30 "Linux" "Linux Programmer's Manual" | |
41 | .SH NAME | |
42 | mmap, munmap \- map or unmap files or devices into memory | |
43 | .SH SYNOPSIS | |
44 | .nf | |
45 | .B #include <sys/mman.h> | |
46 | .PP | |
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 ); | |
51 | .fi | |
52 | .PP | |
53 | See NOTES for information on feature test macro requirements. | |
54 | .SH DESCRIPTION | |
55 | .BR mmap () | |
56 | creates a new mapping in the virtual address space of | |
57 | the calling process. | |
58 | The starting address for the new mapping is specified in | |
59 | .IR addr . | |
60 | The | |
61 | .I length | |
62 | argument specifies the length of the mapping (which must be greater than 0). | |
63 | .PP | |
64 | If | |
65 | .I addr | |
66 | is NULL, | |
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. | |
70 | If | |
71 | .I addr | |
72 | is not NULL, | |
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. | |
78 | .PP | |
79 | The contents of a file mapping (as opposed to an anonymous mapping; see | |
80 | .B MAP_ANONYMOUS | |
81 | below), are initialized using | |
82 | .I length | |
83 | bytes starting at offset | |
84 | .I offset | |
85 | in the file (or other object) referred to by the file descriptor | |
86 | .IR fd . | |
87 | .I offset | |
88 | must be a multiple of the page size as returned by | |
89 | .IR sysconf(_SC_PAGE_SIZE) . | |
90 | .PP | |
91 | After the | |
92 | .BR mmap () | |
93 | call has returned, the file descriptor, | |
94 | .IR fd , | |
95 | can be closed immediately without invalidating the mapping. | |
96 | .PP | |
97 | The | |
98 | .I prot | |
99 | argument describes the desired memory protection of the mapping | |
100 | (and must not conflict with the open mode of the file). | |
101 | It is either | |
102 | .B PROT_NONE | |
103 | or the bitwise OR of one or more of the following flags: | |
104 | .TP 1.1i | |
105 | .B PROT_EXEC | |
106 | Pages may be executed. | |
107 | .TP | |
108 | .B PROT_READ | |
109 | Pages may be read. | |
110 | .TP | |
111 | .B PROT_WRITE | |
112 | Pages may be written. | |
113 | .TP | |
114 | .B PROT_NONE | |
115 | Pages may not be accessed. | |
116 | .PP | |
117 | The | |
118 | .I flags | |
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 | |
124 | .IR flags : | |
125 | .TP | |
126 | .B MAP_SHARED | |
127 | Share this mapping. | |
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 | |
133 | .BR msync (2).) | |
134 | .TP | |
135 | .BR MAP_SHARED_VALIDATE " (since Linux 4.15)" | |
136 | This flag provides the same behavior as | |
137 | .B MAP_SHARED | |
138 | except that | |
139 | .B MAP_SHARED | |
140 | mappings ignore unknown flags in | |
141 | .IR flags . | |
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 | |
146 | .BR EOPNOTSUPP | |
147 | for unknown flags. | |
148 | This mapping type is also required to be able to use some mapping flags | |
149 | (e.g., | |
150 | .BR MAP_SYNC ). | |
151 | .TP | |
152 | .B MAP_PRIVATE | |
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 | |
156 | the underlying file. | |
157 | It is unspecified whether changes made to the file after the | |
158 | .BR mmap () | |
159 | call are visible in the mapped region. | |
160 | .PP | |
161 | Both | |
162 | .B MAP_SHARED | |
163 | and | |
164 | .B MAP_PRIVATE | |
165 | are described in POSIX.1-2001 and POSIX.1-2008. | |
166 | .B MAP_SHARED_VALIDATE | |
167 | is a Linux extension. | |
168 | .PP | |
169 | In addition, zero or more of the following values can be ORed in | |
170 | .IR flags : | |
171 | .TP | |
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 | |
178 | 64-bit processors. | |
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. | |
182 | The | |
183 | .B MAP_32BIT | |
184 | flag is ignored when | |
185 | .B MAP_FIXED | |
186 | is set. | |
187 | .TP | |
188 | .B MAP_ANON | |
189 | Synonym for | |
190 | .BR MAP_ANONYMOUS . | |
191 | Deprecated. | |
192 | .TP | |
193 | .B MAP_ANONYMOUS | |
194 | The mapping is not backed by any file; | |
195 | its contents are initialized to zero. | |
196 | The | |
197 | .I fd | |
198 | argument is ignored; | |
199 | however, some implementations require | |
200 | .I fd | |
201 | to be \-1 if | |
202 | .B MAP_ANONYMOUS | |
203 | (or | |
204 | .BR MAP_ANON ) | |
205 | is specified, | |
206 | and portable applications should ensure this. | |
207 | The | |
208 | .I offset | |
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. | |
212 | The use of | |
213 | .B MAP_ANONYMOUS | |
214 | in conjunction with | |
215 | .B MAP_SHARED | |
216 | is supported on Linux only since kernel 2.4. | |
217 | .TP | |
218 | .B MAP_DENYWRITE | |
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 | |
223 | .BR ETXTBUSY . | |
224 | But this was a source of denial-of-service attacks.) | |
225 | .TP | |
226 | .B MAP_EXECUTABLE | |
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 | |
232 | .\" MAP_DENYWRITE? | |
233 | .TP | |
234 | .B MAP_FILE | |
235 | Compatibility flag. | |
236 | Ignored. | |
237 | .\" On some systems, this was required as the opposite of | |
238 | .\" MAP_ANONYMOUS -- mtk, 1 May 2007 | |
239 | .TP | |
240 | .B MAP_FIXED | |
241 | Don't interpret | |
242 | .I addr | |
243 | as a hint: place the mapping at exactly that address. | |
244 | .I addr | |
245 | must be suitably aligned: for most architectures a multiple of the page | |
246 | size is sufficient; however, some architectures may impose additional | |
247 | restrictions. | |
248 | If the memory region specified by | |
249 | .I addr | |
250 | and | |
251 | .I len | |
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, | |
255 | .BR mmap () | |
256 | will fail. | |
257 | .IP | |
258 | Software that aspires to be portable should use the | |
259 | .BR MAP_FIXED | |
260 | flag with care, | |
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!" | |
265 | .TP | |
266 | .BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" | |
267 | .\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843 | |
268 | This flag provides behavior that is similar to | |
269 | .B MAP_FIXED | |
270 | with respect to the | |
271 | .I addr | |
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 | |
277 | .B EEXIST. | |
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. | |
281 | .IP | |
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 | |
286 | .B MAP_FIXED\c | |
287 | " type of behavior: | |
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. | |
291 | .TP | |
292 | .B MAP_GROWSDOWN | |
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 | |
303 | .B SIGSEGV | |
304 | signal. | |
305 | .TP | |
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. | |
311 | .TP | |
312 | .BR MAP_HUGE_2MB ", " MAP_HUGE_1GB " (since Linux 3.8)" | |
313 | .\" See https://lwn.net/Articles/533499/ | |
314 | Used in conjunction with | |
315 | .B MAP_HUGETLB | |
316 | to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) | |
317 | on systems that support multiple hugetlb page sizes. | |
318 | .IP | |
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 | |
321 | .BR MAP_HUGE_SHIFT . | |
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 | |
324 | .I Hugepagesize | |
325 | field exposed by | |
326 | .IR /proc/meminfo .) | |
327 | Thus, the above two constants are defined as: | |
328 | .IP | |
329 | .in +4n | |
330 | .EX | |
331 | #define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT) | |
332 | #define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT) | |
333 | .EE | |
334 | .in | |
335 | .IP | |
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 . | |
339 | .TP | |
340 | .BR MAP_LOCKED " (since Linux 2.5.37)" | |
341 | Mark the mapped region to be locked in the same way as | |
342 | .BR mlock (2). | |
343 | This implementation will try to populate (prefault) the whole range but the | |
344 | .BR mmap () | |
345 | call doesn't fail with | |
346 | .B ENOMEM | |
347 | if this fails. | |
348 | Therefore major faults might happen later on. | |
349 | So the semantic is not as strong as | |
350 | .BR mlock (2). | |
351 | One should use | |
352 | .BR mmap () | |
353 | plus | |
354 | .BR mlock (2) | |
355 | when major faults are not acceptable after the initialization of the mapping. | |
356 | The | |
357 | .BR MAP_LOCKED | |
358 | flag is ignored in older kernels. | |
359 | .\" If set, the mapped pages will not be swapped out. | |
360 | .TP | |
361 | .BR MAP_NONBLOCK " (since Linux 2.5.46)" | |
362 | This flag is meaningful only in conjunction with | |
363 | .BR MAP_POPULATE . | |
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 | |
368 | .BR MAP_POPULATE | |
369 | to do nothing. | |
370 | One day, the combination of | |
371 | .BR MAP_POPULATE | |
372 | and | |
373 | .BR MAP_NONBLOCK | |
374 | may be reimplemented. | |
375 | .TP | |
376 | .B MAP_NORESERVE | |
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 | |
381 | .B SIGSEGV | |
382 | upon a write | |
383 | if no physical memory is available. | |
384 | See also the discussion of the file | |
385 | .I /proc/sys/vm/overcommit_memory | |
386 | in | |
387 | .BR proc (5). | |
388 | In kernels before 2.6, this flag had effect only for | |
389 | private writable mappings. | |
390 | .TP | |
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. | |
395 | .BR MAP_POPULATE | |
396 | is supported for private mappings only since Linux 2.6.23. | |
397 | .TP | |
398 | .BR MAP_STACK " (since Linux 2.6.27)" | |
399 | Allocate the mapping at an address suitable for a process | |
400 | or thread stack. | |
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?" | |
410 | .TP | |
411 | .BR MAP_SYNC " (since Linux 4.15)" | |
412 | This flag is available only with the | |
413 | .B MAP_SHARED_VALIDATE | |
414 | mapping type; | |
415 | mappings of type | |
416 | .B MAP_SHARED | |
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 | |
421 | .B EOPNOTSUPP | |
422 | error. | |
423 | .IP | |
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. | |
431 | .TP | |
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 | |
437 | option. | |
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). | |
441 | .PP | |
442 | Of the above flags, only | |
443 | .B MAP_FIXED | |
444 | is specified in POSIX.1-2001 and POSIX.1-2008. | |
445 | However, most systems also support | |
446 | .B MAP_ANONYMOUS | |
447 | (or its synonym | |
448 | .BR MAP_ANON ). | |
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 | |
453 | .PP | |
454 | Memory mapped by | |
455 | .BR mmap () | |
456 | is preserved across | |
457 | .BR fork (2), | |
458 | with the same attributes. | |
459 | .PP | |
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. | |
464 | The effect of | |
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. | |
467 | .SS munmap() | |
468 | The | |
469 | .BR munmap () | |
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. | |
477 | .PP | |
478 | The address | |
479 | .I addr | |
480 | must be a multiple of the page size (but | |
481 | .I length | |
482 | need not be). | |
483 | All pages containing a part | |
484 | of the indicated range are unmapped, and subsequent references | |
485 | to these pages will generate | |
486 | .BR SIGSEGV . | |
487 | It is not an error if the | |
488 | indicated range does not contain any mapped pages. | |
489 | .SH RETURN VALUE | |
490 | On success, | |
491 | .BR mmap () | |
492 | returns a pointer to the mapped area. | |
493 | On error, the value | |
494 | .B MAP_FAILED | |
495 | (that is, | |
496 | .IR "(void\ *)\ \-1" ) | |
497 | is returned, and | |
498 | .I errno | |
499 | is set to indicate the cause of the error. | |
500 | .PP | |
501 | On success, | |
502 | .BR munmap () | |
503 | returns 0. | |
504 | On failure, it returns \-1, and | |
505 | .I errno | |
506 | is set to indicate the cause of the error (probably to | |
507 | .BR EINVAL ). | |
508 | .SH ERRORS | |
509 | .TP | |
510 | .B EACCES | |
511 | A file descriptor refers to a non-regular file. | |
512 | Or a file mapping was requested, but | |
513 | .I fd | |
514 | is not open for reading. | |
515 | Or | |
516 | .B MAP_SHARED | |
517 | was requested and | |
518 | .B PROT_WRITE | |
519 | is set, but | |
520 | .I fd | |
521 | is not open in read/write | |
522 | .RB ( O_RDWR ) | |
523 | mode. | |
524 | Or | |
525 | .B PROT_WRITE | |
526 | is set, but the file is append-only. | |
527 | .TP | |
528 | .B EAGAIN | |
529 | The file has been locked, or too much memory has been locked (see | |
530 | .BR setrlimit (2)). | |
531 | .TP | |
532 | .B EBADF | |
533 | .I fd | |
534 | is not a valid file descriptor (and | |
535 | .B MAP_ANONYMOUS | |
536 | was not set). | |
537 | .TP | |
538 | .B EEXIST | |
539 | .BR MAP_FIXED_NOREPLACE | |
540 | was specified in | |
541 | .IR flags , | |
542 | and the range covered by | |
543 | .IR addr | |
544 | and | |
545 | .IR length | |
546 | clashes with an existing mapping. | |
547 | .TP | |
548 | .B EINVAL | |
549 | We don't like | |
550 | .IR addr , | |
551 | .IR length , | |
552 | or | |
553 | .I offset | |
554 | (e.g., they are too large, or not aligned on a page boundary). | |
555 | .TP | |
556 | .B EINVAL | |
557 | (since Linux 2.6.12) | |
558 | .I length | |
559 | was 0. | |
560 | .TP | |
561 | .B EINVAL | |
562 | .I flags | |
563 | contained neither | |
564 | .B MAP_PRIVATE | |
565 | or | |
566 | .BR MAP_SHARED , | |
567 | or contained both of these values. | |
568 | .TP | |
569 | .B ENFILE | |
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. | |
573 | .\" .TP | |
574 | .\" .B ENOEXEC | |
575 | .\" A file could not be mapped for reading. | |
576 | .TP | |
577 | .B ENODEV | |
578 | The underlying filesystem of the specified file does not support | |
579 | memory mapping. | |
580 | .TP | |
581 | .B ENOMEM | |
582 | No memory is available. | |
583 | .TP | |
584 | .B ENOMEM | |
585 | The process's maximum number of mappings would have been exceeded. | |
586 | This error can also occur for | |
587 | .BR munmap (), | |
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. | |
591 | .TP | |
592 | .B ENOMEM | |
593 | (since Linux 4.7) | |
594 | The process's | |
595 | .B RLIMIT_DATA | |
596 | limit, described in | |
597 | .BR getrlimit (2), | |
598 | would have been exceeded. | |
599 | .TP | |
600 | .B EOVERFLOW | |
601 | On 32-bit architecture together with the large file extension | |
602 | (i.e., using 64-bit | |
603 | .IR off_t ): | |
604 | the number of pages used for | |
605 | .I length | |
606 | plus number of pages used for | |
607 | .I offset | |
608 | would overflow | |
609 | .I "unsigned long" | |
610 | (32 bits). | |
611 | .TP | |
612 | .B EPERM | |
613 | The | |
614 | .I prot | |
615 | argument asks for | |
616 | .B PROT_EXEC | |
617 | but the mapped area belongs to a file on a filesystem that | |
618 | was mounted no-exec. | |
619 | .\" (Since 2.4.25 / 2.6.0.) | |
620 | .TP | |
621 | .B EPERM | |
622 | The operation was prevented by a file seal; see | |
623 | .BR fcntl (2). | |
624 | .TP | |
625 | .B ETXTBSY | |
626 | .B MAP_DENYWRITE | |
627 | was set but the object specified by | |
628 | .I fd | |
629 | is open for writing. | |
630 | .PP | |
631 | Use of a mapped region can result in these signals: | |
632 | .TP | |
633 | .B SIGSEGV | |
634 | Attempted write into a region mapped as read-only. | |
635 | .TP | |
636 | .B SIGBUS | |
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). | |
640 | .SH ATTRIBUTES | |
641 | For an explanation of the terms used in this section, see | |
642 | .BR attributes (7). | |
643 | .TS | |
644 | allbox; | |
645 | lbw18 lb lb | |
646 | l l l. | |
647 | Interface Attribute Value | |
648 | T{ | |
649 | .BR mmap (), | |
650 | .BR munmap () | |
651 | T} Thread safety MT-Safe | |
652 | .TE | |
653 | .SH CONFORMING TO | |
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. | |
657 | .SH AVAILABILITY | |
658 | On POSIX systems on which | |
659 | .BR mmap (), | |
660 | .BR msync (2), | |
661 | and | |
662 | .BR munmap () | |
663 | are available, | |
664 | .B _POSIX_MAPPED_FILES | |
665 | is defined in \fI<unistd.h>\fP to a value greater than 0. | |
666 | (See also | |
667 | .BR sysconf (3).) | |
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. | |
671 | .SH NOTES | |
672 | On some hardware architectures (e.g., i386), | |
673 | .B PROT_WRITE | |
674 | implies | |
675 | .BR PROT_READ . | |
676 | It is architecture dependent whether | |
677 | .B PROT_READ | |
678 | implies | |
679 | .B PROT_EXEC | |
680 | or not. | |
681 | Portable programs should always set | |
682 | .B PROT_EXEC | |
683 | if they intend to execute code in the new mapping. | |
684 | .PP | |
685 | The portable way to create a mapping is to specify | |
686 | .I addr | |
687 | as 0 (NULL), and omit | |
688 | .B MAP_FIXED | |
689 | from | |
690 | .IR flags . | |
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, | |
693 | and will not be 0. | |
694 | If the | |
695 | .B MAP_FIXED | |
696 | flag is specified, and | |
697 | .I addr | |
698 | is 0 (NULL), then the mapped address will be 0 (NULL). | |
699 | .PP | |
700 | Certain | |
701 | .I flags | |
702 | constants are defined only if suitable feature test macros are defined | |
703 | (possibly by default): | |
704 | .BR _DEFAULT_SOURCE | |
705 | with glibc 2.19 or later; | |
706 | or | |
707 | .BR _BSD_SOURCE | |
708 | or | |
709 | .BR _SVID_SOURCE | |
710 | in glibc 2.19 and earlier. | |
711 | (Employing | |
712 | .BR _GNU_SOURCE | |
713 | also suffices, | |
714 | and requiring that macro specifically would have been more logical, | |
715 | since these flags are all Linux-specific.) | |
716 | The relevant flags are: | |
717 | .BR MAP_32BIT , | |
718 | .BR MAP_ANONYMOUS | |
719 | (and the synonym | |
720 | .BR MAP_ANON ), | |
721 | .BR MAP_DENYWRITE , | |
722 | .BR MAP_EXECUTABLE , | |
723 | .BR MAP_FILE , | |
724 | .BR MAP_GROWSDOWN , | |
725 | .BR MAP_HUGETLB , | |
726 | .BR MAP_LOCKED , | |
727 | .BR MAP_NONBLOCK , | |
728 | .BR MAP_NORESERVE , | |
729 | .BR MAP_POPULATE , | |
730 | and | |
731 | .BR MAP_STACK . | |
732 | .PP | |
733 | An application can determine which pages of a mapping are | |
734 | currently resident in the buffer/page cache using | |
735 | .BR mincore (2). | |
736 | .\" | |
737 | .SS Using MAP_FIXED safely | |
738 | The only safe use for | |
739 | .BR MAP_FIXED | |
740 | is where the address range specified by | |
741 | .IR addr | |
742 | and | |
743 | .I length | |
744 | was previously reserved using another mapping; | |
745 | otherwise, the use of | |
746 | .BR MAP_FIXED | |
747 | is hazardous because it forcibly removes preexisting mappings, | |
748 | making it easy for a multithreaded process to corrupt its own address space. | |
749 | .PP | |
750 | For example, suppose that thread A looks through | |
751 | .I /proc/<pid>/maps | |
752 | and in order to locate an unused address range that it can map using | |
753 | .BR MAP_FIXED , | |
754 | while thread B simultaneously acquires part or all of that same | |
755 | address range. | |
756 | When thread A subsequently employs | |
757 | .BR mmap(MAP_FIXED) , | |
758 | it will effectively clobber the mapping that thread B created. | |
759 | In this scenario, | |
760 | thread B need not create a mapping directly; simply making a library call | |
761 | that, internally, uses | |
762 | .BR dlopen (3) | |
763 | to load some other shared library, will suffice. | |
764 | The | |
765 | .BR dlopen (3) | |
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. | |
770 | Examples include | |
771 | .BR brk (2), | |
772 | .BR malloc (3), | |
773 | .BR pthread_create (3), | |
774 | and the PAM libraries | |
775 | .UR http://www.linux-pam.org | |
776 | .UE . | |
777 | .PP | |
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. | |
783 | .\" | |
784 | .SS Timestamps changes for file-backed mappings | |
785 | For file-backed mappings, the | |
786 | .I st_atime | |
787 | field for the mapped file may be updated at any time between the | |
788 | .BR mmap () | |
789 | and the corresponding unmapping; the first reference to a mapped | |
790 | page will update the field if it has not been already. | |
791 | .PP | |
792 | The | |
793 | .I st_ctime | |
794 | and | |
795 | .I st_mtime | |
796 | field for a file mapped with | |
797 | .B PROT_WRITE | |
798 | and | |
799 | .B MAP_SHARED | |
800 | will be updated after | |
801 | a write to the mapped region, and before a subsequent | |
802 | .BR msync (2) | |
803 | with the | |
804 | .B MS_SYNC | |
805 | or | |
806 | .B MS_ASYNC | |
807 | flag, if one occurs. | |
808 | .\" | |
809 | .SS Huge page (Huge TLB) mappings | |
810 | For mappings that employ huge pages, the requirements for the arguments of | |
811 | .BR mmap () | |
812 | and | |
813 | .BR munmap () | |
814 | differ somewhat from the requirements for mappings | |
815 | that use the native system page size. | |
816 | .PP | |
817 | For | |
818 | .BR mmap (), | |
819 | .I offset | |
820 | must be a multiple of the underlying huge page size. | |
821 | The system automatically aligns | |
822 | .I length | |
823 | to be a multiple of the underlying huge page size. | |
824 | .PP | |
825 | For | |
826 | .BR munmap (), | |
827 | .I addr | |
828 | and | |
829 | .I length | |
830 | must both be a multiple of the underlying huge page size. | |
831 | .\" | |
832 | .SS C library/kernel differences | |
833 | This page describes the interface provided by the glibc | |
834 | .BR mmap () | |
835 | wrapper function. | |
836 | Originally, this function invoked a system call of the same name. | |
837 | Since kernel 2.4, that system call has been superseded by | |
838 | .BR mmap2 (2), | |
839 | and nowadays | |
840 | .\" Since around glibc 2.1/2.2, depending on the platform. | |
841 | the glibc | |
842 | .BR mmap () | |
843 | wrapper function invokes | |
844 | .BR mmap2 (2) | |
845 | with a suitably adjusted value for | |
846 | .IR offset . | |
847 | .SH BUGS | |
848 | On Linux, there are no guarantees like those suggested above under | |
849 | .BR MAP_NORESERVE . | |
850 | By default, any process can be killed | |
851 | at any moment when the system runs out of memory. | |
852 | .PP | |
853 | In kernels before 2.6.7, the | |
854 | .B MAP_POPULATE | |
855 | flag has effect only if | |
856 | .I prot | |
857 | is specified as | |
858 | .BR PROT_NONE . | |
859 | .PP | |
860 | SUSv3 specifies that | |
861 | .BR mmap () | |
862 | should fail if | |
863 | .I length | |
864 | is 0. | |
865 | However, in kernels before 2.6.12, | |
866 | .BR mmap () | |
867 | succeeded in this case: no mapping was created and the call returned | |
868 | .IR addr . | |
869 | Since kernel 2.6.12, | |
870 | .BR mmap () | |
871 | fails with the error | |
872 | .B EINVAL | |
873 | for this case. | |
874 | .PP | |
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 | |
885 | .BR msync (2) | |
886 | before the unmap takes place; | |
887 | however, this doesn't work on | |
888 | .BR tmpfs (5) | |
889 | (for example, when using the POSIX shared memory interface documented in | |
890 | .BR shm_overview (7)). | |
891 | .SH EXAMPLE | |
892 | .\" FIXME . Add an example here that uses an anonymous shared region for | |
893 | .\" IPC between parent and child. | |
894 | .PP | |
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 | |
901 | .BR write (2) | |
902 | to output the desired bytes. | |
903 | .SS Program source | |
904 | .EX | |
905 | #include <sys/mman.h> | |
906 | #include <sys/stat.h> | |
907 | #include <fcntl.h> | |
908 | #include <stdio.h> | |
909 | #include <stdlib.h> | |
910 | #include <unistd.h> | |
911 | ||
912 | #define handle_error(msg) \\ | |
913 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
914 | ||
915 | int | |
916 | main(int argc, char *argv[]) | |
917 | { | |
918 | char *addr; | |
919 | int fd; | |
920 | struct stat sb; | |
921 | off_t offset, pa_offset; | |
922 | size_t length; | |
923 | ssize_t s; | |
924 | ||
925 | if (argc < 3 || argc > 4) { | |
926 | fprintf(stderr, "%s file offset [length]\\n", argv[0]); | |
927 | exit(EXIT_FAILURE); | |
928 | } | |
929 | ||
930 | fd = open(argv[1], O_RDONLY); | |
931 | if (fd == \-1) | |
932 | handle_error("open"); | |
933 | ||
934 | if (fstat(fd, &sb) == \-1) /* To obtain file size */ | |
935 | handle_error("fstat"); | |
936 | ||
937 | offset = atoi(argv[2]); | |
938 | pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) \- 1); | |
939 | /* offset for mmap() must be page aligned */ | |
940 | ||
941 | if (offset >= sb.st_size) { | |
942 | fprintf(stderr, "offset is past end of file\\n"); | |
943 | exit(EXIT_FAILURE); | |
944 | } | |
945 | ||
946 | if (argc == 4) { | |
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 */ | |
951 | ||
952 | } else { /* No length arg ==> display to end of file */ | |
953 | length = sb.st_size \- offset; | |
954 | } | |
955 | ||
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"); | |
960 | ||
961 | s = write(STDOUT_FILENO, addr + offset \- pa_offset, length); | |
962 | if (s != length) { | |
963 | if (s == \-1) | |
964 | handle_error("write"); | |
965 | ||
966 | fprintf(stderr, "partial write"); | |
967 | exit(EXIT_FAILURE); | |
968 | } | |
969 | ||
970 | munmap(addr, length + offset \- pa_offset); | |
971 | close(fd); | |
972 | ||
973 | exit(EXIT_SUCCESS); | |
974 | } | |
975 | .EE | |
976 | .SH SEE ALSO | |
977 | .BR ftruncate (2), | |
978 | .BR getpagesize (2), | |
979 | .BR memfd_create (2), | |
980 | .BR mincore (2), | |
981 | .BR mlock (2), | |
982 | .BR mmap2 (2), | |
983 | .BR mprotect (2), | |
984 | .BR mremap (2), | |
985 | .BR msync (2), | |
986 | .BR remap_file_pages (2), | |
987 | .BR setrlimit (2), | |
988 | .BR shmat (2), | |
989 | .BR userfaultfd (2), | |
990 | .BR shm_open (3), | |
991 | .BR shm_overview (7) | |
992 | .PP | |
993 | The descriptions of the following files in | |
994 | .BR proc (5): | |
995 | .IR /proc/[pid]/maps , | |
996 | .IR /proc/[pid]/map_files , | |
997 | and | |
998 | .IR /proc/[pid]/smaps . | |
999 | .PP | |
1000 | B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391. | |
1001 | .\" | |
1002 | .\" Repeat after me: private read-only mappings are 100% equivalent to | |
1003 | .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus |