]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
a62f5121 MK |
3 | .\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl> |
4 | .\" and Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net> | |
fea681da MK |
5 | .\" |
6 | .\" Permission is granted to make and distribute verbatim copies of this | |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
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> | |
305a0578 | 30 | .\" Modified 2003-05-21 by Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 31 | .\" MAP_LOCKED works from 2.5.37 |
305a0578 | 32 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk-manpages@gmx.net> |
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 |
fea681da | 37 | .\" |
d9343c5c | 38 | .TH MMAP 2 2006-12-04 "Linux" "Linux Programmer's Manual" |
fea681da MK |
39 | .SH NAME |
40 | mmap, munmap \- map or unmap files or devices into memory | |
41 | .SH SYNOPSIS | |
e0037472 | 42 | .nf |
fea681da MK |
43 | .B #include <sys/mman.h> |
44 | .sp | |
a62f5121 MK |
45 | .BI "void *mmap(void *" start ", size_t " length \ |
46 | ", int " prot ", int " flags , | |
e0037472 | 47 | .BI " int " fd ", off_t " offset ); |
fea681da MK |
48 | .sp |
49 | .BI "int munmap(void *" start ", size_t " length ); | |
e0037472 | 50 | .fi |
fea681da | 51 | .SH DESCRIPTION |
1a956089 | 52 | .BR mmap () |
c13182ef | 53 | creates a new mapping in the virtual address space of |
5e8cde2f MK |
54 | the calling process. |
55 | The starting address for the new mapping is specified in | |
56 | .IR start . | |
57 | The | |
58 | .I length | |
59 | argument specifies the length of the mapping. | |
60 | ||
61 | If | |
62 | .I start | |
63 | is NULL, | |
64 | then the kernel chooses the address at which to create the mapping; | |
65 | this is the most portable method of creating a new mapping. | |
c13182ef MK |
66 | If |
67 | .I start | |
5e8cde2f MK |
68 | is not NULL, |
69 | then the kernel takes it as a hint about where to place the mapping; | |
70 | on Linux, the mapping will be created at the next higher page boundary. | |
71 | The address of the new mapping is returned as the result of the call. | |
72 | ||
73 | The contents of a file mapping (as opposed to an anonymous mapping; see | |
74 | .B MAP_ANONYMOUS | |
c13182ef | 75 | below), are initialised using |
fea681da MK |
76 | .I length |
77 | bytes starting at offset | |
78 | .I offset | |
5e8cde2f MK |
79 | in the file (or other object) referred to by the file descriptor |
80 | .IR fd . | |
a62f5121 MK |
81 | .I offset |
82 | must be a multiple of the page size as returned by | |
83 | .IR sysconf(_SC_PAGE_SIZE) . | |
fea681da MK |
84 | .LP |
85 | The | |
86 | .I prot | |
c13182ef | 87 | argument describes the desired memory protection of the mapping |
5e8cde2f MK |
88 | (and must not conflict with the open mode of the file). |
89 | It is either | |
fea681da | 90 | .B PROT_NONE |
a62f5121 | 91 | or the bitwise OR of one or more of the following flags: |
fea681da MK |
92 | .TP 1.1i |
93 | .B PROT_EXEC | |
94 | Pages may be executed. | |
95 | .TP | |
96 | .B PROT_READ | |
97 | Pages may be read. | |
98 | .TP | |
99 | .B PROT_WRITE | |
100 | Pages may be written. | |
101 | .TP | |
102 | .B PROT_NONE | |
103 | Pages may not be accessed. | |
104 | .LP | |
105 | The | |
106 | .I flags | |
a62f5121 MK |
107 | argument determines whether updates to the mapping |
108 | are visible to other processes mapping the same region, | |
109 | and whether updates are caried through to the underlying file. | |
c13182ef | 110 | This behaviour is determined by including exactly one |
a62f5121 | 111 | of the following values in |
5e8cde2f | 112 | .IR flags : |
fea681da | 113 | .TP 1.1i |
fea681da | 114 | .B MAP_SHARED |
c13182ef | 115 | Share this mapping. |
a62f5121 MK |
116 | Updates to the mapping are visible to other processes that map this file, |
117 | and are carried through to the underlying file. | |
fea681da MK |
118 | The file may not actually be updated until |
119 | .BR msync (2) | |
120 | or | |
121 | .BR munmap (2) | |
a62f5121 | 122 | is called. |
fea681da MK |
123 | .TP |
124 | .B MAP_PRIVATE | |
125 | Create a private copy-on-write mapping. | |
a62f5121 MK |
126 | Updates to the mapping are not visible to other processes |
127 | mapping the same file, and are not carried through to | |
128 | the underlying file. | |
fea681da | 129 | It is unspecified whether changes made to the file after the |
1a956089 | 130 | .BR mmap () |
fea681da MK |
131 | call are visible in the mapped region. |
132 | .LP | |
a62f5121 MK |
133 | Both of these flags are described in POSIX.1-2001. |
134 | ||
135 | In addition, zero or more of the following values can be ORed in | |
136 | .IR flags : | |
fea681da | 137 | .TP |
83314009 MK |
138 | .B MAP_32BIT |
139 | Put the mapping into the first 2GB of the process address space. | |
140 | Ignored when | |
a62f5121 | 141 | .B MAP_FIXED |
83314009 MK |
142 | is set. |
143 | This flag is currently only supported on x86-64 for 64bit programs. | |
fea681da | 144 | .TP |
a62f5121 | 145 | .B MAP_ANON |
c13182ef MK |
146 | Synonym for |
147 | .BR MAP_ANONYMOUS . | |
a62f5121 MK |
148 | Deprecated. |
149 | .TP | |
fea681da | 150 | .B MAP_ANONYMOUS |
5e8cde2f MK |
151 | The mapping is not backed by any file; |
152 | its contents are initialised to zero. | |
153 | The | |
fea681da MK |
154 | .I fd |
155 | and | |
156 | .I offset | |
a62f5121 | 157 | arguments are ignored; |
c13182ef | 158 | however, some implementations require |
a62f5121 | 159 | .I fd |
c13182ef MK |
160 | to be \-1 if |
161 | .B MAP_ANONYMOUS | |
162 | (or | |
163 | .BR MAP_ANON ) | |
a62f5121 MK |
164 | is specified, |
165 | and portable applications should ensure this. | |
c13182ef | 166 | The use of |
a62f5121 | 167 | .B MAP_ANONYMOUS |
c13182ef | 168 | in conjunction with |
51ffcca0 | 169 | .B MAP_SHARED |
74f3f90b | 170 | is only supported on Linux since kernel 2.4. |
fea681da | 171 | .TP |
83314009 MK |
172 | .B MAP_DENYWRITE |
173 | This flag is ignored. | |
174 | .\" Introduced in 1.1.36, removed in 1.3.24. | |
175 | (Long ago, it signalled that attempts to write to the underlying file | |
176 | should fail with | |
177 | .BR ETXTBUSY . | |
178 | But this was a source of denial-of-service attacks.) | |
179 | .TP | |
180 | .B MAP_EXECUTABLE | |
181 | This flag is ignored. | |
182 | .\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. | |
183 | .\" (Long ago, it signalled that the underlying file is an executable. | |
184 | .\" However, that information was not really used anywhere.) | |
185 | .\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of | |
186 | .\" MAP_DENYWRITE? | |
187 | .TP | |
fea681da | 188 | .B MAP_FILE |
c13182ef MK |
189 | Compatibility flag. |
190 | Ignored. | |
83314009 MK |
191 | .\" On some systems, this was required as the opposite of |
192 | .\" MAP_ANONYMOUS -- mtk, 1 May 2007 | |
fea681da | 193 | .TP |
51ffcca0 | 194 | .B MAP_FIXED |
83314009 MK |
195 | Don't interpret |
196 | .I start | |
197 | as a hint: place the mapping at exactly that address. | |
198 | .I start | |
199 | must be a multiple of the page size. | |
200 | If the memory region specified by | |
201 | .I start | |
202 | and | |
203 | .I len | |
204 | overlaps pages of any existing mapping(s), then the overlapped | |
205 | part of the existing mapping(s) will be discarded. | |
206 | If the specified address cannot be used, | |
207 | .BR mmap () | |
208 | will fail. | |
209 | Because requiring a fixed address for a mapping is less portable, | |
210 | the use of this option is discouraged. | |
fea681da | 211 | .TP |
83314009 MK |
212 | .B MAP_GROWSDOWN |
213 | Used for stacks. | |
214 | Indicates to the kernel virtual memory system that the mapping | |
215 | should extend downwards in memory. | |
216 | .TP | |
217 | .BR MAP_LOCKED " (since Linux 2.5.37)" | |
218 | Lock the pages of the mapped region into memory in the manner of | |
0bfa087b | 219 | .BR mlock (2) . |
83314009 MK |
220 | This flag is ignored in older kernels. |
221 | .\" If set, the mapped pages will not be swapped out. | |
fea681da MK |
222 | .TP |
223 | .BR MAP_NONBLOCK " (since Linux 2.5.46)" | |
51ffcca0 MK |
224 | Only meaningful in conjunction with |
225 | .BR MAP_POPULATE . | |
c13182ef MK |
226 | Don't perform read-ahead: |
227 | only create page tables entries for pages | |
51ffcca0 | 228 | that are already present in RAM. |
83314009 MK |
229 | .TP |
230 | .B MAP_NORESERVE | |
231 | Do not reserve swap space for this mapping. | |
232 | When swap space is reserved, one has the guarantee | |
233 | that it is possible to modify the mapping. | |
234 | When swap space is not reserved one might get SIGSEGV upon a write | |
235 | if no physical memory is available. | |
236 | See also the discussion of the file | |
237 | .I /proc/sys/vm/overcommit_memory | |
238 | in | |
239 | .BR proc (5). | |
240 | In kernels before 2.6, this flag only had effect for | |
241 | private writable mappings. | |
242 | .TP | |
243 | .BR MAP_POPULATE " (since Linux 2.5.46)" | |
244 | Populate (prefault) page tables for a file mapping, | |
245 | by performing read-ahead on the file. | |
246 | Later accesses to the mapping will not be blocked by page faults. | |
fea681da | 247 | .LP |
a62f5121 MK |
248 | Of the above flags, only |
249 | .B MAP_FIXED | |
250 | is specified in POSIX.1-2001. | |
251 | However, most systems also support | |
252 | .B MAP_ANONYMOUS | |
c13182ef | 253 | (or its synonym |
a62f5121 MK |
254 | .BR MAP_ANON ). |
255 | .LP | |
fea681da MK |
256 | Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV, |
257 | MAP_COPY, and MAP_LOCAL. | |
258 | .LP | |
fea681da | 259 | Memory mapped by |
1a956089 | 260 | .BR mmap () |
fea681da MK |
261 | is preserved across |
262 | .BR fork (2), | |
263 | with the same attributes. | |
264 | .LP | |
c13182ef MK |
265 | A file is mapped in multiples of the page size. |
266 | For a file that is not | |
fea681da | 267 | a multiple of the page size, the remaining memory is zeroed when mapped, |
c13182ef MK |
268 | and writes to that region are not written out to the file. |
269 | The effect of | |
fea681da MK |
270 | changing the size of the underlying file of a mapping on the pages that |
271 | correspond to added or removed regions of the file is unspecified. | |
272 | ||
273 | The | |
1a956089 | 274 | .BR munmap () |
fea681da MK |
275 | system call deletes the mappings for the specified address range, and |
276 | causes further references to addresses within the range to generate | |
c13182ef MK |
277 | invalid memory references. |
278 | The region is also automatically unmapped | |
279 | when the process is terminated. | |
280 | On the other hand, closing the file | |
fea681da MK |
281 | descriptor does not unmap the region. |
282 | .LP | |
283 | The address | |
284 | .I start | |
c13182ef MK |
285 | must be a multiple of the page size. |
286 | All pages containing a part | |
fea681da | 287 | of the indicated range are unmapped, and subsequent references |
c13182ef MK |
288 | to these pages will generate SIGSEGV. |
289 | It is not an error if the | |
fea681da MK |
290 | indicated range does not contain any mapped pages. |
291 | ||
292 | For file-backed mappings, the | |
8478ee02 | 293 | .I st_atime |
fea681da | 294 | field for the mapped file may be updated at any time between the |
1a956089 | 295 | .BR mmap () |
fea681da MK |
296 | and the corresponding unmapping; the first reference to a mapped |
297 | page will update the field if it has not been already. | |
298 | .LP | |
299 | The | |
8478ee02 | 300 | .I st_ctime |
fea681da | 301 | and |
8478ee02 | 302 | .I st_mtime |
c13182ef MK |
303 | field for a file mapped with |
304 | .B PROT_WRITE | |
305 | and | |
306 | .B MAP_SHARED | |
51ffcca0 | 307 | will be updated after |
fea681da | 308 | a write to the mapped region, and before a subsequent |
0bfa087b | 309 | .BR msync (2) |
c13182ef MK |
310 | with the |
311 | .B MS_SYNC | |
312 | or | |
313 | .BR MS_ASYNC | |
51ffcca0 | 314 | flag, if one occurs. |
fea681da MK |
315 | .SH "RETURN VALUE" |
316 | On success, | |
1a956089 | 317 | .BR mmap () |
fea681da MK |
318 | returns a pointer to the mapped area. |
319 | On error, the value | |
320 | .B MAP_FAILED | |
c13182ef | 321 | (that is, |
5e8cde2f MK |
322 | .I "(void *) \-1)" |
323 | is returned, and | |
fea681da MK |
324 | .I errno |
325 | is set appropriately. | |
326 | On success, | |
1a956089 | 327 | .BR munmap () |
fea681da MK |
328 | returns 0, on failure \-1, and |
329 | .I errno | |
c13182ef | 330 | is set (probably to |
51ffcca0 | 331 | .BR EINVAL ). |
fea681da MK |
332 | .SH ERRORS |
333 | .TP | |
334 | .B EACCES | |
335 | A file descriptor refers to a non-regular file. | |
c13182ef MK |
336 | Or |
337 | .B MAP_PRIVATE | |
51ffcca0 | 338 | was requested, but |
fea681da MK |
339 | .I fd |
340 | is not open for reading. | |
c13182ef MK |
341 | Or |
342 | .B MAP_SHARED | |
343 | was requested and | |
344 | .B PROT_WRITE | |
51ffcca0 | 345 | is set, but |
fea681da MK |
346 | .I fd |
347 | is not open in read/write (O_RDWR) mode. | |
c13182ef MK |
348 | Or |
349 | .B PROT_WRITE | |
51ffcca0 | 350 | is set, but the file is append-only. |
fea681da MK |
351 | .TP |
352 | .B EAGAIN | |
83cd3686 MK |
353 | The file has been locked, or too much memory has been locked (see |
354 | .BR setrlimit (2)). | |
fea681da MK |
355 | .TP |
356 | .B EBADF | |
357 | .I fd | |
c13182ef | 358 | is not a valid file descriptor (and |
51ffcca0 MK |
359 | .B MAP_ANONYMOUS |
360 | was not set). | |
fea681da MK |
361 | .TP |
362 | .B EINVAL | |
363 | We don't like | |
62a04c81 MK |
364 | .IR start , |
365 | .IR length , | |
fea681da | 366 | or |
62a04c81 MK |
367 | .IR offset |
368 | (e.g., they are too large, or not aligned on a page boundary). | |
369 | .TP | |
370 | .B EINVAL | |
371 | (since Linux 2.6.12), | |
fea681da | 372 | .I length |
62a04c81 MK |
373 | was 0. |
374 | .TP | |
375 | .B EINVAL | |
376 | .I flags | |
377 | contained neither | |
378 | .B MAP_PRIVATE | |
fea681da | 379 | or |
62a04c81 MK |
380 | .BR MAP_SHARED , |
381 | or contained both of these values. | |
fea681da MK |
382 | .TP |
383 | .B ENFILE | |
384 | .\" This is for shared anonymous segments | |
385 | .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() | |
386 | The system limit on the total number of open files has been reached. | |
387 | .\" .TP | |
388 | .\" .B ENOEXEC | |
389 | .\" A file could not be mapped for reading. | |
390 | .TP | |
391 | .B ENODEV | |
392 | The underlying filesystem of the specified file does not support | |
393 | memory mapping. | |
394 | .TP | |
395 | .B ENOMEM | |
396 | No memory is available, or the process's maximum number of mappings would | |
397 | have been exceeded. | |
398 | .TP | |
399 | .B EPERM | |
400 | The | |
401 | .I prot | |
402 | argument asks for | |
403 | .B PROT_EXEC | |
404 | but the mapped area belongs to a file on a filesystem that | |
405 | was mounted no-exec. | |
406 | .\" (Since 2.4.25 / 2.6.0.) | |
407 | .TP | |
408 | .B ETXTBSY | |
c13182ef | 409 | .B MAP_DENYWRITE |
51ffcca0 | 410 | was set but the object specified by |
fea681da MK |
411 | .I fd |
412 | is open for writing. | |
413 | .LP | |
414 | Use of a mapped region can result in these signals: | |
415 | .TP | |
416 | .B SIGSEGV | |
1e321034 | 417 | Attempted write into a region mapped as read-only. |
fea681da MK |
418 | .TP |
419 | .B SIGBUS | |
420 | Attempted access to a portion of the buffer that does not correspond | |
421 | to the file (for example, beyond the end of the file, including the | |
422 | case where another process has truncated the file). | |
2b2581ee MK |
423 | .SH "CONFORMING TO" |
424 | SVr4, 4.4BSD, POSIX.1-2001. | |
425 | .\" SVr4 documents additional error codes ENXIO and ENODEV. | |
426 | .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. | |
fea681da MK |
427 | .SH AVAILABILITY |
428 | On POSIX systems on which | |
1a956089 | 429 | .BR mmap (), |
0bfa087b | 430 | .BR msync (2) |
fea681da | 431 | and |
1a956089 | 432 | .BR munmap () |
fea681da MK |
433 | are available, |
434 | .B _POSIX_MAPPED_FILES | |
435 | is defined in <unistd.h> to a value greater than 0. (See also | |
436 | .BR sysconf (3).) | |
97c1eac8 | 437 | .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. |
fea681da MK |
438 | .\" -1: unavailable, 0: ask using sysconf(). |
439 | .\" glibc defines it to 1. | |
a1d5f77c MK |
440 | .SH NOTES |
441 | It is architecture dependent whether | |
442 | .B PROT_READ | |
443 | implies | |
444 | .B PROT_EXEC | |
445 | or not. | |
446 | Portable programs should always set | |
447 | .B PROT_EXEC | |
448 | if they intend to execute code in the new mapping. | |
fea681da | 449 | .SH BUGS |
c13182ef MK |
450 | On Linux there are no guarantees like those suggested above under |
451 | .BR MAP_NORESERVE . | |
dbc53ca8 | 452 | By default, any process can be killed |
fea681da | 453 | at any moment when the system runs out of memory. |
dbc53ca8 MK |
454 | |
455 | In kernels before 2.6.7, the | |
456 | .B MAP_POPULATE | |
457 | flag only has effect if | |
458 | .I prot | |
459 | is specified as | |
460 | .BR PROT_NONE . | |
c8f3e580 | 461 | |
c13182ef | 462 | SUSv3 specifies that |
c8f3e580 MK |
463 | .BR mmap () |
464 | should fail if | |
465 | .I length | |
466 | is 0. | |
467 | However, in kernels before 2.6.12, | |
468 | .BR mmap () | |
469 | succeeded in this case: no mapping was created and the call returned | |
470 | .IR start . | |
471 | Since kernel 2.6.12, | |
472 | .BR mmap () | |
473 | fails with the error | |
474 | .B EINVAL | |
475 | for this case. | |
fea681da MK |
476 | .SH "SEE ALSO" |
477 | .BR getpagesize (2), | |
f75c3a3b | 478 | .BR mincore (2), |
fea681da MK |
479 | .BR mlock (2), |
480 | .BR mmap2 (2), | |
481 | .BR mremap (2), | |
482 | .BR msync (2), | |
931e4e25 | 483 | .BR remap_file_pages (2), |
83cd3686 | 484 | .BR setrlimit (2), |
424a8950 | 485 | .BR shm_open (3) |
fea681da MK |
486 | .br |
487 | B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391. | |
488 | .\" | |
489 | .\" Repeat after me: private read-only mappings are 100% equivalent to | |
490 | .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus |