]>
Commit | Line | Data |
---|---|---|
a62f5121 | 1 | .\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl> |
c11b1abf | 2 | .\" and Copyright (C) 2006, 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
c13182ef | 13 | .\" |
fea681da MK |
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. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
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> | |
c11b1abf | 30 | .\" Modified 2003-05-21 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 31 | .\" MAP_LOCKED works from 2.5.37 |
c11b1abf | 32 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 33 | .\" Modified 2004-09-11 by aeb |
1a956089 MK |
34 | .\" Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr> |
35 | .\" Modified 2004-12-08, mtk, formatting tidy-ups | |
a62f5121 | 36 | .\" Modified 2006-12-04, mtk, various parts rewritten |
74fa61b7 | 37 | .\" 2007-07-10, mtk, Added an example program. |
e6205b0c | 38 | .\" 2008-11-18, mtk, document MAP_STACK |
fea681da | 39 | .\" |
4b8c67d9 | 40 | .TH MMAP 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da MK |
41 | .SH NAME |
42 | mmap, munmap \- map or unmap files or devices into memory | |
43 | .SH SYNOPSIS | |
e0037472 | 44 | .nf |
fea681da | 45 | .B #include <sys/mman.h> |
68e4db0a | 46 | .PP |
14f5ae6d | 47 | .BI "void *mmap(void *" addr ", size_t " length \ |
a62f5121 | 48 | ", int " prot ", int " flags , |
e0037472 | 49 | .BI " int " fd ", off_t " offset ); |
14f5ae6d | 50 | .BI "int munmap(void *" addr ", size_t " length ); |
e0037472 | 51 | .fi |
dbfe9c70 | 52 | .PP |
45e97e2a | 53 | See NOTES for information on feature test macro requirements. |
fea681da | 54 | .SH DESCRIPTION |
1a956089 | 55 | .BR mmap () |
c13182ef | 56 | creates a new mapping in the virtual address space of |
5e8cde2f MK |
57 | the calling process. |
58 | The starting address for the new mapping is specified in | |
14f5ae6d | 59 | .IR addr . |
5e8cde2f MK |
60 | The |
61 | .I length | |
c19250ad | 62 | argument specifies the length of the mapping (which must be greater than 0). |
efeece04 | 63 | .PP |
5e8cde2f | 64 | If |
14f5ae6d | 65 | .I addr |
5e8cde2f MK |
66 | is NULL, |
67 | then the kernel chooses the address at which to create the mapping; | |
68 | this is the most portable method of creating a new mapping. | |
c13182ef | 69 | If |
14f5ae6d | 70 | .I addr |
5e8cde2f MK |
71 | is not NULL, |
72 | then the kernel takes it as a hint about where to place the mapping; | |
6aa7db0a MK |
73 | on Linux, the mapping will be created at a nearby page boundary. |
74 | .\" Before Linux 2.6.24, the address was rounded up to the next page | |
29328361 | 75 | .\" boundary; since 2.6.24, it is rounded down! |
5e8cde2f | 76 | The address of the new mapping is returned as the result of the call. |
efeece04 | 77 | .PP |
5e8cde2f MK |
78 | The contents of a file mapping (as opposed to an anonymous mapping; see |
79 | .B MAP_ANONYMOUS | |
d9bfdb9c | 80 | below), are initialized using |
fea681da MK |
81 | .I length |
82 | bytes starting at offset | |
83 | .I offset | |
5e8cde2f MK |
84 | in the file (or other object) referred to by the file descriptor |
85 | .IR fd . | |
a62f5121 MK |
86 | .I offset |
87 | must be a multiple of the page size as returned by | |
88 | .IR sysconf(_SC_PAGE_SIZE) . | |
dd3568a1 | 89 | .PP |
fea681da MK |
90 | The |
91 | .I prot | |
c13182ef | 92 | argument describes the desired memory protection of the mapping |
5e8cde2f MK |
93 | (and must not conflict with the open mode of the file). |
94 | It is either | |
fea681da | 95 | .B PROT_NONE |
a62f5121 | 96 | or the bitwise OR of one or more of the following flags: |
fea681da MK |
97 | .TP 1.1i |
98 | .B PROT_EXEC | |
99 | Pages may be executed. | |
100 | .TP | |
101 | .B PROT_READ | |
102 | Pages may be read. | |
103 | .TP | |
104 | .B PROT_WRITE | |
105 | Pages may be written. | |
106 | .TP | |
107 | .B PROT_NONE | |
108 | Pages may not be accessed. | |
dd3568a1 | 109 | .PP |
fea681da MK |
110 | The |
111 | .I flags | |
a62f5121 MK |
112 | argument determines whether updates to the mapping |
113 | are visible to other processes mapping the same region, | |
ba7cb080 | 114 | and whether updates are carried through to the underlying file. |
d9bfdb9c | 115 | This behavior is determined by including exactly one |
a62f5121 | 116 | of the following values in |
5e8cde2f | 117 | .IR flags : |
ca90e95a | 118 | .TP |
fea681da | 119 | .B MAP_SHARED |
c13182ef | 120 | Share this mapping. |
bf525e90 MK |
121 | Updates to the mapping are visible to other processes mapping the same region, |
122 | and (in the case of file-backed mappings) | |
123 | are carried through to the underlying file. | |
72e8bdae MK |
124 | (To precisely control when updates are carried through |
125 | to the underlying file requires the use of | |
126 | .BR msync (2).) | |
fea681da MK |
127 | .TP |
128 | .B MAP_PRIVATE | |
129 | Create a private copy-on-write mapping. | |
a62f5121 MK |
130 | Updates to the mapping are not visible to other processes |
131 | mapping the same file, and are not carried through to | |
132 | the underlying file. | |
fea681da | 133 | It is unspecified whether changes made to the file after the |
1a956089 | 134 | .BR mmap () |
fea681da | 135 | call are visible in the mapped region. |
dd3568a1 | 136 | .PP |
78cdbef7 | 137 | Both of these flags are described in POSIX.1-2001 and POSIX.1-2008. |
efeece04 | 138 | .PP |
a62f5121 MK |
139 | In addition, zero or more of the following values can be ORed in |
140 | .IR flags : | |
fea681da | 141 | .TP |
c368e7ca MK |
142 | .BR MAP_32BIT " (since Linux 2.4.20, 2.6)" |
143 | Put the mapping into the first 2 Gigabytes of the process address space. | |
33a0ccb2 | 144 | This flag is supported only on x86-64, for 64-bit programs. |
c368e7ca | 145 | It was added to allow thread stacks to be allocated somewhere |
ee8655b5 | 146 | in the first 2\ GB of memory, |
c368e7ca MK |
147 | so as to improve context-switch performance on some early |
148 | 64-bit processors. | |
149 | .\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 | |
150 | Modern x86-64 processors no longer have this performance problem, | |
151 | so use of this flag is not required on those systems. | |
152 | The | |
83314009 | 153 | .B MAP_32BIT |
c368e7ca | 154 | flag is ignored when |
a62f5121 | 155 | .B MAP_FIXED |
83314009 | 156 | is set. |
fea681da | 157 | .TP |
a62f5121 | 158 | .B MAP_ANON |
c13182ef MK |
159 | Synonym for |
160 | .BR MAP_ANONYMOUS . | |
a62f5121 MK |
161 | Deprecated. |
162 | .TP | |
fea681da | 163 | .B MAP_ANONYMOUS |
5e8cde2f | 164 | The mapping is not backed by any file; |
d9bfdb9c | 165 | its contents are initialized to zero. |
5e8cde2f | 166 | The |
fea681da | 167 | .I fd |
423cb9f7 | 168 | argument is ignored; |
c13182ef | 169 | however, some implementations require |
a62f5121 | 170 | .I fd |
c13182ef MK |
171 | to be \-1 if |
172 | .B MAP_ANONYMOUS | |
173 | (or | |
174 | .BR MAP_ANON ) | |
a62f5121 MK |
175 | is specified, |
176 | and portable applications should ensure this. | |
423cb9f7 JH |
177 | The |
178 | .I offset | |
179 | argument should be zero. | |
180 | .\" See the pgoff overflow check in do_mmap(). | |
181 | .\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c. | |
c13182ef | 182 | The use of |
a62f5121 | 183 | .B MAP_ANONYMOUS |
c13182ef | 184 | in conjunction with |
51ffcca0 | 185 | .B MAP_SHARED |
33a0ccb2 | 186 | is supported on Linux only since kernel 2.4. |
fea681da | 187 | .TP |
83314009 MK |
188 | .B MAP_DENYWRITE |
189 | This flag is ignored. | |
190 | .\" Introduced in 1.1.36, removed in 1.3.24. | |
d9bfdb9c | 191 | (Long ago, it signaled that attempts to write to the underlying file |
83314009 MK |
192 | should fail with |
193 | .BR ETXTBUSY . | |
194 | But this was a source of denial-of-service attacks.) | |
195 | .TP | |
196 | .B MAP_EXECUTABLE | |
197 | This flag is ignored. | |
198 | .\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. | |
d9bfdb9c | 199 | .\" (Long ago, it signaled that the underlying file is an executable. |
83314009 MK |
200 | .\" However, that information was not really used anywhere.) |
201 | .\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of | |
202 | .\" MAP_DENYWRITE? | |
203 | .TP | |
fea681da | 204 | .B MAP_FILE |
c13182ef MK |
205 | Compatibility flag. |
206 | Ignored. | |
988db661 | 207 | .\" On some systems, this was required as the opposite of |
83314009 | 208 | .\" MAP_ANONYMOUS -- mtk, 1 May 2007 |
fea681da | 209 | .TP |
51ffcca0 | 210 | .B MAP_FIXED |
83314009 | 211 | Don't interpret |
14f5ae6d | 212 | .I addr |
83314009 | 213 | as a hint: place the mapping at exactly that address. |
14f5ae6d | 214 | .I addr |
04bb0b99 JH |
215 | must be suitably aligned: for most architectures a multiple of page |
216 | size is sufficient; however, some architectures may impose additional | |
e2da344f MK |
217 | restrictions. |
218 | If the memory region specified by | |
14f5ae6d | 219 | .I addr |
83314009 MK |
220 | and |
221 | .I len | |
222 | overlaps pages of any existing mapping(s), then the overlapped | |
223 | part of the existing mapping(s) will be discarded. | |
224 | If the specified address cannot be used, | |
225 | .BR mmap () | |
226 | will fail. | |
e2da344f MK |
227 | Software that aspires to be portable should use this option with care, |
228 | keeping in mind that the exact layout of a process' memory map | |
229 | is allowed to change significantly between kernel versions, | |
230 | C library versions, and operating system releases. | |
04bb0b99 | 231 | .IP |
e2da344f MK |
232 | Furthermore, this option is extremely hazardous (when used on its own), |
233 | because it forcibly removes pre-existing mappings, | |
234 | making it easy for a multi-threaded process to corrupt its own address space. | |
04bb0b99 JH |
235 | .IP |
236 | For example, thread A looks through | |
237 | .I /proc/<pid>/maps | |
e2da344f MK |
238 | and locates an available address range, |
239 | while thread B simultaneously acquires part or all of that same | |
240 | address range. | |
b9f34840 MK |
241 | A then calls |
242 | .BR mmap(MAP_FIXED) , | |
243 | effectively overwriting the mapping that thread B created. | |
04bb0b99 JH |
244 | .IP |
245 | Thread B need not create a mapping directly; simply making a library call | |
246 | that, internally, uses | |
b9f34840 | 247 | .BR dlopen (3) |
04bb0b99 | 248 | to load some other shared library, will |
e2da344f | 249 | suffice. |
b9f34840 MK |
250 | The |
251 | .BR dlopen (3) | |
252 | call will map the library into the process's address space. | |
e2da344f | 253 | Furthermore, almost any library call may be implemented using this technique. |
b9f34840 MK |
254 | Examples include |
255 | .BR brk (2), | |
256 | .BR malloc (3), | |
257 | .BR pthread_create (3), | |
258 | and the PAM libraries | |
259 | .UR http://www.linux-pam.org | |
260 | .UE . | |
04bb0b99 JH |
261 | .IP |
262 | Newer kernels | |
263 | (Linux 4.16 and later) have a | |
264 | .B MAP_FIXED_SAFE | |
265 | option that avoids the corruption problem; if available, MAP_FIXED_SAFE | |
266 | should be preferred over MAP_FIXED. | |
fea681da | 267 | .TP |
83314009 | 268 | .B MAP_GROWSDOWN |
86f12eb0 MK |
269 | This flag is used for stacks. |
270 | It indicates to the kernel virtual memory system that the mapping | |
5fab2e7c | 271 | should extend downward in memory. |
176b1a76 MK |
272 | The return address is one page lower than the memory area that is |
273 | actually created in the process's virtual address space. | |
274 | Touching an address in the "guard" page below the mapping will cause | |
275 | the mapping to grow by a page. | |
276 | This growth can be repeated until the mapping grows to within a | |
277 | page of the high end of the next lower mapping, | |
278 | at which point touching the "guard" page will result in a | |
279 | .B SIGSEGV | |
280 | signal. | |
83314009 | 281 | .TP |
76a34baa MK |
282 | .BR MAP_HUGETLB " (since Linux 2.6.32)" |
283 | Allocate the mapping using "huge pages." | |
66a9882e | 284 | See the Linux kernel source file |
76a34baa | 285 | .I Documentation/vm/hugetlbpage.txt |
f1461fe1 | 286 | for further information, as well as NOTES, below. |
76a34baa | 287 | .TP |
5d2038b6 MK |
288 | .BR MAP_HUGE_2MB ", " MAP_HUGE_1GB " (since Linux 3.8)" |
289 | .\" See https://lwn.net/Articles/533499/ | |
290 | Used in conjunction with | |
291 | .B MAP_HUGETLB | |
c4b7e5ac | 292 | to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) |
5d2038b6 | 293 | on systems that support multiple hugetlb page sizes. |
efeece04 | 294 | .IP |
5d2038b6 MK |
295 | More generally, the desired huge page size can be configured by encoding |
296 | the base-2 logarithm of the desired page size in the six bits at the offset | |
297 | .BR MAP_HUGE_SHIFT . | |
298 | (A value of zero in this bit field provides the default huge page size; | |
299 | the default huge page size can be discovered vie the | |
300 | .I Hugepagesize | |
301 | field exposed by | |
302 | .IR /proc/meminfo .) | |
303 | Thus, the above two constants are defined as: | |
efeece04 | 304 | .IP |
5d2038b6 | 305 | .in +4n |
b8302363 | 306 | .EX |
5d2038b6 MK |
307 | #define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT) |
308 | #define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT) | |
b8302363 | 309 | .EE |
e646a1ba | 310 | .in |
efeece04 | 311 | .IP |
5d2038b6 MK |
312 | The range of huge page sizes that are supported by the system |
313 | can be discovered by listing the subdirectories in | |
314 | .IR /sys/kernel/mm/hugepages . | |
315 | .TP | |
83314009 | 316 | .BR MAP_LOCKED " (since Linux 2.5.37)" |
7e3786bc | 317 | Mark the mmaped region to be locked in the same way as |
74d32233 | 318 | .BR mlock (2). |
7e3786bc MH |
319 | This implementation will try to populate (prefault) the whole range but |
320 | the mmap call doesn't fail with | |
321 | .B ENOMEM | |
911f1c7a MK |
322 | if this fails. |
323 | Therefore major faults might happen later on. | |
324 | So the semantic is not as strong as | |
7e3786bc | 325 | .BR mlock (2). |
911f1c7a | 326 | One should use |
bf7bc8b8 | 327 | .BR mmap () |
911f1c7a | 328 | plus |
7e3786bc | 329 | .BR mlock (2) |
911f1c7a MK |
330 | when major faults are not acceptable after the initialization of the mapping. |
331 | The | |
332 | .BR MAP_LOCKED | |
333 | flag is ignored in older kernels. | |
83314009 | 334 | .\" If set, the mapped pages will not be swapped out. |
fea681da MK |
335 | .TP |
336 | .BR MAP_NONBLOCK " (since Linux 2.5.46)" | |
3f06ade3 | 337 | This flag is meaningful only in conjunction with |
51ffcca0 | 338 | .BR MAP_POPULATE . |
c13182ef | 339 | Don't perform read-ahead: |
33a0ccb2 | 340 | create page tables entries only for pages |
51ffcca0 | 341 | that are already present in RAM. |
7c40de08 | 342 | Since Linux 2.6.23, this flag causes |
f38fa944 MK |
343 | .BR MAP_POPULATE |
344 | to do nothing. | |
487c2f05 | 345 | One day, the combination of |
f38fa944 MK |
346 | .BR MAP_POPULATE |
347 | and | |
348 | .BR MAP_NONBLOCK | |
3b777aff | 349 | may be reimplemented. |
83314009 MK |
350 | .TP |
351 | .B MAP_NORESERVE | |
352 | Do not reserve swap space for this mapping. | |
353 | When swap space is reserved, one has the guarantee | |
354 | that it is possible to modify the mapping. | |
8bd58774 MK |
355 | When swap space is not reserved one might get |
356 | .B SIGSEGV | |
357 | upon a write | |
83314009 MK |
358 | if no physical memory is available. |
359 | See also the discussion of the file | |
360 | .I /proc/sys/vm/overcommit_memory | |
361 | in | |
362 | .BR proc (5). | |
33a0ccb2 | 363 | In kernels before 2.6, this flag had effect only for |
83314009 MK |
364 | private writable mappings. |
365 | .TP | |
366 | .BR MAP_POPULATE " (since Linux 2.5.46)" | |
f38fa944 MK |
367 | Populate (prefault) page tables for a mapping. |
368 | For a file mapping, this causes read-ahead on the file. | |
bbebbb6d | 369 | This will help to reduce blocking on page faults later. |
f38fa944 | 370 | .BR MAP_POPULATE |
33a0ccb2 | 371 | is supported for private mappings only since Linux 2.6.23. |
e6205b0c MK |
372 | .TP |
373 | .BR MAP_STACK " (since Linux 2.6.27)" | |
374 | Allocate the mapping at an address suitable for a process | |
375 | or thread stack. | |
376 | This flag is currently a no-op, | |
377 | but is used in the glibc threading implementation so that | |
378 | if some architectures require special treatment for stack allocations, | |
379 | support can later be transparently implemented for glibc. | |
67b59ff5 | 380 | .\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 |
e6205b0c MK |
381 | .\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7 |
382 | .\" http://thread.gmane.org/gmane.linux.kernel/720412 | |
383 | .\" "pthread_create() slow for many threads; also time to revisit 64b | |
384 | .\" context switch optimization?" | |
12062404 MK |
385 | .TP |
386 | .BR MAP_UNINITIALIZED " (since Linux 2.6.33)" | |
387 | Don't clear anonymous pages. | |
388 | This flag is intended to improve performance on embedded devices. | |
33a0ccb2 | 389 | This flag is honored only if the kernel was configured with the |
12062404 MK |
390 | .B CONFIG_MMAP_ALLOW_UNINITIALIZED |
391 | option. | |
392 | Because of the security implications, | |
393 | that option is normally enabled only on embedded devices | |
394 | (i.e., devices where one has complete control of the contents of user memory). | |
dd3568a1 | 395 | .PP |
7c7adcbe MK |
396 | Of the above flags, only |
397 | .B MAP_FIXED | |
78cdbef7 | 398 | is specified in POSIX.1-2001 and POSIX.1-2008. |
7c7adcbe MK |
399 | However, most systems also support |
400 | .B MAP_ANONYMOUS | |
401 | (or its synonym | |
402 | .BR MAP_ANON ). | |
f5f41651 MK |
403 | .\" FIXME . for later review when Issue 8 is one day released... |
404 | .\" POSIX may add MAP_ANON in the future | |
405 | .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 | |
406 | .\" http://austingroupbugs.net/view.php?id=850 | |
dd3568a1 | 407 | .PP |
fea681da | 408 | Memory mapped by |
1a956089 | 409 | .BR mmap () |
fea681da MK |
410 | is preserved across |
411 | .BR fork (2), | |
412 | with the same attributes. | |
dd3568a1 | 413 | .PP |
c13182ef MK |
414 | A file is mapped in multiples of the page size. |
415 | For a file that is not | |
fea681da | 416 | a multiple of the page size, the remaining memory is zeroed when mapped, |
c13182ef MK |
417 | and writes to that region are not written out to the file. |
418 | The effect of | |
fea681da MK |
419 | changing the size of the underlying file of a mapping on the pages that |
420 | correspond to added or removed regions of the file is unspecified. | |
de5f7e28 | 421 | .SS munmap() |
fea681da | 422 | The |
1a956089 | 423 | .BR munmap () |
fea681da MK |
424 | system call deletes the mappings for the specified address range, and |
425 | causes further references to addresses within the range to generate | |
c13182ef MK |
426 | invalid memory references. |
427 | The region is also automatically unmapped | |
428 | when the process is terminated. | |
429 | On the other hand, closing the file | |
fea681da | 430 | descriptor does not unmap the region. |
dd3568a1 | 431 | .PP |
fea681da | 432 | The address |
14f5ae6d | 433 | .I addr |
0e824bcb MK |
434 | must be a multiple of the page size (but |
435 | .I length | |
436 | need not be). | |
c13182ef | 437 | All pages containing a part |
fea681da | 438 | of the indicated range are unmapped, and subsequent references |
8bd58774 MK |
439 | to these pages will generate |
440 | .BR SIGSEGV . | |
c13182ef | 441 | It is not an error if the |
fea681da | 442 | indicated range does not contain any mapped pages. |
47297adb | 443 | .SH RETURN VALUE |
fea681da | 444 | On success, |
1a956089 | 445 | .BR mmap () |
fea681da MK |
446 | returns a pointer to the mapped area. |
447 | On error, the value | |
448 | .B MAP_FAILED | |
c13182ef | 449 | (that is, |
009df872 | 450 | .IR "(void\ *)\ \-1" ) |
5e8cde2f | 451 | is returned, and |
fea681da | 452 | .I errno |
80691a91 | 453 | is set to indicate the cause of the error. |
efeece04 | 454 | .PP |
fea681da | 455 | On success, |
1a956089 | 456 | .BR munmap () |
80691a91 MK |
457 | returns 0. |
458 | On failure, it returns \-1, and | |
fea681da | 459 | .I errno |
80691a91 | 460 | is set to indicate the cause of the error (probably to |
51ffcca0 | 461 | .BR EINVAL ). |
fea681da MK |
462 | .SH ERRORS |
463 | .TP | |
464 | .B EACCES | |
465 | A file descriptor refers to a non-regular file. | |
5e7c71f6 | 466 | Or a file mapping was requested, but |
fea681da MK |
467 | .I fd |
468 | is not open for reading. | |
c13182ef MK |
469 | Or |
470 | .B MAP_SHARED | |
471 | was requested and | |
472 | .B PROT_WRITE | |
51ffcca0 | 473 | is set, but |
fea681da | 474 | .I fd |
682edefb MK |
475 | is not open in read/write |
476 | .RB ( O_RDWR ) | |
477 | mode. | |
c13182ef MK |
478 | Or |
479 | .B PROT_WRITE | |
51ffcca0 | 480 | is set, but the file is append-only. |
fea681da MK |
481 | .TP |
482 | .B EAGAIN | |
83cd3686 MK |
483 | The file has been locked, or too much memory has been locked (see |
484 | .BR setrlimit (2)). | |
fea681da MK |
485 | .TP |
486 | .B EBADF | |
487 | .I fd | |
c13182ef | 488 | is not a valid file descriptor (and |
51ffcca0 MK |
489 | .B MAP_ANONYMOUS |
490 | was not set). | |
fea681da MK |
491 | .TP |
492 | .B EINVAL | |
493 | We don't like | |
14f5ae6d | 494 | .IR addr , |
62a04c81 | 495 | .IR length , |
fea681da | 496 | or |
0daa9e92 | 497 | .I offset |
62a04c81 MK |
498 | (e.g., they are too large, or not aligned on a page boundary). |
499 | .TP | |
500 | .B EINVAL | |
f99fc197 | 501 | (since Linux 2.6.12) |
fea681da | 502 | .I length |
62a04c81 MK |
503 | was 0. |
504 | .TP | |
505 | .B EINVAL | |
506 | .I flags | |
507 | contained neither | |
508 | .B MAP_PRIVATE | |
fea681da | 509 | or |
62a04c81 MK |
510 | .BR MAP_SHARED , |
511 | or contained both of these values. | |
fea681da MK |
512 | .TP |
513 | .B ENFILE | |
514 | .\" This is for shared anonymous segments | |
515 | .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() | |
e258766b | 516 | The system-wide limit on the total number of open files has been reached. |
fea681da MK |
517 | .\" .TP |
518 | .\" .B ENOEXEC | |
519 | .\" A file could not be mapped for reading. | |
520 | .TP | |
521 | .B ENODEV | |
9ee4a2b6 | 522 | The underlying filesystem of the specified file does not support |
fea681da MK |
523 | memory mapping. |
524 | .TP | |
525 | .B ENOMEM | |
74309bed MK |
526 | No memory is available. |
527 | .TP | |
528 | .B ENOMEM | |
529 | The process's maximum number of mappings would have been exceeded. | |
c0b89788 | 530 | This error can also occur for |
3804d39d | 531 | .BR munmap (), |
c0b89788 MK |
532 | when unmapping a region in the middle of an existing mapping, |
533 | since this results in two smaller mappings on either side of | |
534 | the region being unmapped. | |
fea681da | 535 | .TP |
c87d084b JG |
536 | .B ENOMEM |
537 | (since Linux 4.7) | |
538 | The process's | |
539 | .B RLIMIT_DATA | |
540 | limit, described in | |
541 | .BR getrlimit (2), | |
542 | would have been exceeded. | |
543 | .TP | |
038f5175 MK |
544 | .B EOVERFLOW |
545 | On 32-bit architecture together with the large file extension | |
546 | (i.e., using 64-bit | |
547 | .IR off_t ): | |
548 | the number of pages used for | |
549 | .I length | |
550 | plus number of pages used for | |
551 | .I offset | |
552 | would overflow | |
553 | .I "unsigned long" | |
554 | (32 bits). | |
555 | .TP | |
fea681da MK |
556 | .B EPERM |
557 | The | |
558 | .I prot | |
559 | argument asks for | |
560 | .B PROT_EXEC | |
9ee4a2b6 | 561 | but the mapped area belongs to a file on a filesystem that |
fea681da MK |
562 | was mounted no-exec. |
563 | .\" (Since 2.4.25 / 2.6.0.) | |
564 | .TP | |
fbab10e5 MK |
565 | .B EPERM |
566 | The operation was prevented by a file seal; see | |
567 | .BR fcntl (2). | |
568 | .TP | |
fea681da | 569 | .B ETXTBSY |
c13182ef | 570 | .B MAP_DENYWRITE |
51ffcca0 | 571 | was set but the object specified by |
fea681da MK |
572 | .I fd |
573 | is open for writing. | |
dd3568a1 | 574 | .PP |
fea681da MK |
575 | Use of a mapped region can result in these signals: |
576 | .TP | |
577 | .B SIGSEGV | |
1e321034 | 578 | Attempted write into a region mapped as read-only. |
fea681da MK |
579 | .TP |
580 | .B SIGBUS | |
581 | Attempted access to a portion of the buffer that does not correspond | |
582 | to the file (for example, beyond the end of the file, including the | |
583 | case where another process has truncated the file). | |
8fddf95a MS |
584 | .SH ATTRIBUTES |
585 | For an explanation of the terms used in this section, see | |
586 | .BR attributes (7). | |
587 | .TS | |
588 | allbox; | |
589 | lbw18 lb lb | |
590 | l l l. | |
591 | Interface Attribute Value | |
592 | T{ | |
593 | .BR mmap (), | |
594 | .BR munmap () | |
595 | T} Thread safety MT-Safe | |
596 | .TE | |
47297adb | 597 | .SH CONFORMING TO |
78cdbef7 | 598 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD. |
2b2581ee MK |
599 | .\" SVr4 documents additional error codes ENXIO and ENODEV. |
600 | .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. | |
fea681da MK |
601 | .SH AVAILABILITY |
602 | On POSIX systems on which | |
1a956089 | 603 | .BR mmap (), |
9af134cd | 604 | .BR msync (2), |
fea681da | 605 | and |
1a956089 | 606 | .BR munmap () |
fea681da MK |
607 | are available, |
608 | .B _POSIX_MAPPED_FILES | |
6387216b MK |
609 | is defined in \fI<unistd.h>\fP to a value greater than 0. |
610 | (See also | |
fea681da | 611 | .BR sysconf (3).) |
97c1eac8 | 612 | .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. |
fea681da MK |
613 | .\" -1: unavailable, 0: ask using sysconf(). |
614 | .\" glibc defines it to 1. | |
a1d5f77c | 615 | .SH NOTES |
34ccb744 | 616 | On some hardware architectures (e.g., i386), |
0daa9e92 | 617 | .B PROT_WRITE |
f3edaabb MK |
618 | implies |
619 | .BR PROT_READ . | |
a1d5f77c MK |
620 | It is architecture dependent whether |
621 | .B PROT_READ | |
622 | implies | |
623 | .B PROT_EXEC | |
624 | or not. | |
625 | Portable programs should always set | |
626 | .B PROT_EXEC | |
627 | if they intend to execute code in the new mapping. | |
efeece04 | 628 | .PP |
80d17cfa MK |
629 | The portable way to create a mapping is to specify |
630 | .I addr | |
631 | as 0 (NULL), and omit | |
632 | .B MAP_FIXED | |
633 | from | |
634 | .IR flags . | |
635 | In this case, the system chooses the address for the mapping; | |
46cdb997 | 636 | the address is chosen so as not to conflict with any existing mapping, |
80d17cfa MK |
637 | and will not be 0. |
638 | If the | |
639 | .B MAP_FIXED | |
640 | flag is specified, and | |
641 | .I addr | |
491cd2f0 | 642 | is 0 (NULL), then the mapped address will be 0 (NULL). |
efeece04 | 643 | .PP |
45e97e2a MK |
644 | Certain |
645 | .I flags | |
f8619b6a MK |
646 | constants are defined only if suitable feature test macros are defined |
647 | (possibly by default): | |
648 | .BR _DEFAULT_SOURCE | |
649 | with glibc 2.19 or later; | |
650 | or | |
45e97e2a MK |
651 | .BR _BSD_SOURCE |
652 | or | |
653 | .BR _SVID_SOURCE | |
f8619b6a | 654 | in glibc 2.19 and earlier. |
50efeef8 | 655 | (Employing |
45e97e2a MK |
656 | .BR _GNU_SOURCE |
657 | also suffices, | |
658 | and requiring that macro specifically would have been more logical, | |
76c637e1 | 659 | since these flags are all Linux-specific.) |
45e97e2a MK |
660 | The relevant flags are: |
661 | .BR MAP_32BIT , | |
662 | .BR MAP_ANONYMOUS | |
663 | (and the synonym | |
664 | .BR MAP_ANON ), | |
665 | .BR MAP_DENYWRITE , | |
666 | .BR MAP_EXECUTABLE , | |
667 | .BR MAP_FILE , | |
668 | .BR MAP_GROWSDOWN , | |
669 | .BR MAP_HUGETLB , | |
670 | .BR MAP_LOCKED , | |
671 | .BR MAP_NONBLOCK , | |
672 | .BR MAP_NORESERVE , | |
673 | .BR MAP_POPULATE , | |
674 | and | |
675 | .BR MAP_STACK . | |
efeece04 | 676 | .PP |
3bd859bf MK |
677 | An application can determine which pages of a mapping are |
678 | currently resident in the buffer/page cache using | |
679 | .BR mincore (2). | |
35c189fb | 680 | .\" |
0f319769 MK |
681 | .SS Timestamps changes for file-backed mappings |
682 | For file-backed mappings, the | |
683 | .I st_atime | |
684 | field for the mapped file may be updated at any time between the | |
685 | .BR mmap () | |
686 | and the corresponding unmapping; the first reference to a mapped | |
687 | page will update the field if it has not been already. | |
dd3568a1 | 688 | .PP |
0f319769 MK |
689 | The |
690 | .I st_ctime | |
691 | and | |
692 | .I st_mtime | |
693 | field for a file mapped with | |
694 | .B PROT_WRITE | |
695 | and | |
696 | .B MAP_SHARED | |
697 | will be updated after | |
698 | a write to the mapped region, and before a subsequent | |
699 | .BR msync (2) | |
700 | with the | |
701 | .B MS_SYNC | |
702 | or | |
703 | .B MS_ASYNC | |
704 | flag, if one occurs. | |
705 | .\" | |
f1461fe1 MK |
706 | .SS Huge page (Huge TLB) mappings |
707 | For mappings that employ huge pages, the requirements for the arguments of | |
708 | .BR mmap () | |
709 | and | |
710 | .BR munmap () | |
711 | differ somewhat from the requirements for mappings | |
712 | that use the native system page size. | |
efeece04 | 713 | .PP |
f1461fe1 MK |
714 | For |
715 | .BR mmap (), | |
716 | .I offset | |
717 | must be a multiple of the underlying huge page size. | |
718 | The system automatically aligns | |
719 | .I length | |
720 | to be a multiple of the underlying huge page size. | |
efeece04 | 721 | .PP |
f1461fe1 MK |
722 | For |
723 | .BR munmap (), | |
724 | .I addr | |
725 | and | |
726 | .I length | |
727 | must both be a multiple of the underlying huge page size. | |
728 | .\" | |
0722a578 | 729 | .SS C library/kernel differences |
35c189fb MK |
730 | This page describes the interface provided by the glibc |
731 | .BR mmap () | |
732 | wrapper function. | |
733 | Originally, this function invoked a system call of the same name. | |
734 | Since kernel 2.4, that system call has been superseded by | |
735 | .BR mmap2 (2), | |
736 | and nowadays | |
737 | .\" Since around glibc 2.1/2.2, depending on the platform. | |
738 | the glibc | |
739 | .BR mmap () | |
740 | wrapper function invokes | |
741 | .BR mmap2 (2) | |
742 | with a suitably adjusted value for | |
743 | .IR offset . | |
fea681da | 744 | .SH BUGS |
329ad271 | 745 | On Linux, there are no guarantees like those suggested above under |
c13182ef | 746 | .BR MAP_NORESERVE . |
dbc53ca8 | 747 | By default, any process can be killed |
fea681da | 748 | at any moment when the system runs out of memory. |
efeece04 | 749 | .PP |
dbc53ca8 MK |
750 | In kernels before 2.6.7, the |
751 | .B MAP_POPULATE | |
33a0ccb2 | 752 | flag has effect only if |
dbc53ca8 MK |
753 | .I prot |
754 | is specified as | |
755 | .BR PROT_NONE . | |
efeece04 | 756 | .PP |
c13182ef | 757 | SUSv3 specifies that |
c8f3e580 MK |
758 | .BR mmap () |
759 | should fail if | |
760 | .I length | |
761 | is 0. | |
762 | However, in kernels before 2.6.12, | |
763 | .BR mmap () | |
764 | succeeded in this case: no mapping was created and the call returned | |
14f5ae6d | 765 | .IR addr . |
c8f3e580 MK |
766 | Since kernel 2.6.12, |
767 | .BR mmap () | |
768 | fails with the error | |
769 | .B EINVAL | |
770 | for this case. | |
efeece04 | 771 | .PP |
a780f17b MK |
772 | POSIX specifies that the system shall always |
773 | zero fill any partial page at the end | |
b072a788 | 774 | of the object and that system will never write any modification of the |
a780f17b MK |
775 | object beyond its end. |
776 | On Linux, when you write data to such partial page after the end | |
b072a788 | 777 | of the object, the data stays in the page cache even after the file |
a780f17b MK |
778 | is closed and unmapped |
779 | and even though the data is never written to the file itself, | |
780 | subsequent mappings may see the modified content. | |
781 | In some cases, this could be fixed by calling | |
782 | .BR msync (2) | |
783 | before the unmap takes place; | |
4e07c70f MK |
784 | however, this doesn't work on |
785 | .BR tmpfs (5) | |
b758a50a | 786 | (for example, when using the POSIX shared memory interface documented in |
a780f17b | 787 | .BR shm_overview (7)). |
74fa61b7 | 788 | .SH EXAMPLE |
2e001ad4 MK |
789 | .\" FIXME . Add an example here that uses an anonymous shared region for |
790 | .\" IPC between parent and child. | |
74fa61b7 MK |
791 | .PP |
792 | The following program prints part of the file specified in | |
793 | its first command-line argument to standard output. | |
794 | The range of bytes to be printed is specified via offset and length | |
795 | values in the second and third command-line arguments. | |
796 | The program creates a memory mapping of the required | |
797 | pages of the file and then uses | |
798 | .BR write (2) | |
799 | to output the desired bytes. | |
f30b7415 | 800 | .SS Program source |
e7d0bb47 | 801 | .EX |
74fa61b7 MK |
802 | #include <sys/mman.h> |
803 | #include <sys/stat.h> | |
804 | #include <fcntl.h> | |
805 | #include <stdio.h> | |
806 | #include <stdlib.h> | |
807 | #include <unistd.h> | |
808 | ||
4407d3d8 MK |
809 | #define handle_error(msg) \\ |
810 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
811 | ||
74fa61b7 MK |
812 | int |
813 | main(int argc, char *argv[]) | |
814 | { | |
815 | char *addr; | |
816 | int fd; | |
817 | struct stat sb; | |
818 | off_t offset, pa_offset; | |
819 | size_t length; | |
820 | ssize_t s; | |
821 | ||
fbbfa7ce | 822 | if (argc < 3 || argc > 4) { |
74fa61b7 MK |
823 | fprintf(stderr, "%s file offset [length]\\n", argv[0]); |
824 | exit(EXIT_FAILURE); | |
825 | } | |
826 | ||
827 | fd = open(argv[1], O_RDONLY); | |
4407d3d8 | 828 | if (fd == \-1) |
8568021d | 829 | handle_error("open"); |
74fa61b7 | 830 | |
4407d3d8 MK |
831 | if (fstat(fd, &sb) == \-1) /* To obtain file size */ |
832 | handle_error("fstat"); | |
74fa61b7 MK |
833 | |
834 | offset = atoi(argv[2]); | |
835 | pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) \- 1); | |
836 | /* offset for mmap() must be page aligned */ | |
837 | ||
838 | if (offset >= sb.st_size) { | |
839 | fprintf(stderr, "offset is past end of file\\n"); | |
840 | exit(EXIT_FAILURE); | |
841 | } | |
842 | ||
843 | if (argc == 4) { | |
844 | length = atoi(argv[3]); | |
845 | if (offset + length > sb.st_size) | |
846 | length = sb.st_size \- offset; | |
f81fb444 | 847 | /* Can\(aqt display bytes past end of file */ |
5b6adad1 | 848 | |
74fa61b7 MK |
849 | } else { /* No length arg ==> display to end of file */ |
850 | length = sb.st_size \- offset; | |
851 | } | |
852 | ||
853 | addr = mmap(NULL, length + offset \- pa_offset, PROT_READ, | |
854 | MAP_PRIVATE, fd, pa_offset); | |
4407d3d8 MK |
855 | if (addr == MAP_FAILED) |
856 | handle_error("mmap"); | |
74fa61b7 MK |
857 | |
858 | s = write(STDOUT_FILENO, addr + offset \- pa_offset, length); | |
859 | if (s != length) { | |
860 | if (s == \-1) | |
4407d3d8 MK |
861 | handle_error("write"); |
862 | ||
863 | fprintf(stderr, "partial write"); | |
74fa61b7 MK |
864 | exit(EXIT_FAILURE); |
865 | } | |
866 | ||
40142309 MK |
867 | munmap(addr, length + offset \- pa_offset); |
868 | close(fd); | |
869 | ||
74fa61b7 | 870 | exit(EXIT_SUCCESS); |
c54ed37e | 871 | } |
e7d0bb47 | 872 | .EE |
47297adb | 873 | .SH SEE ALSO |
74f25490 | 874 | .BR ftruncate (2), |
fea681da | 875 | .BR getpagesize (2), |
c4d76cd9 | 876 | .BR memfd_create (2), |
f75c3a3b | 877 | .BR mincore (2), |
fea681da MK |
878 | .BR mlock (2), |
879 | .BR mmap2 (2), | |
54504ac3 | 880 | .BR mprotect (2), |
fea681da MK |
881 | .BR mremap (2), |
882 | .BR msync (2), | |
931e4e25 | 883 | .BR remap_file_pages (2), |
83cd3686 | 884 | .BR setrlimit (2), |
7921f13b | 885 | .BR shmat (2), |
13acca70 | 886 | .BR userfaultfd (2), |
f93af9c6 MK |
887 | .BR shm_open (3), |
888 | .BR shm_overview (7) | |
efeece04 | 889 | .PP |
0bf14b87 MK |
890 | The descriptions of the following files in |
891 | .BR proc (5): | |
892 | .IR /proc/[pid]/maps , | |
893 | .IR /proc/[pid]/map_files , | |
894 | and | |
895 | .IR /proc/[pid]/smaps . | |
efeece04 | 896 | .PP |
d2fdb1e3 | 897 | B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391. |
fea681da MK |
898 | .\" |
899 | .\" Repeat after me: private read-only mappings are 100% equivalent to | |
900 | .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus |