]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) | |
4 | .\" | |
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 | .\" | |
25 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
26 | .\" Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com> | |
27 | .\" Modified 2001-10-04 by John Levon <moz@compsoc.man.ac.uk> | |
28 | .\" Modified 2003-02-02 by Andi Kleen <ak@muc.de> | |
305a0578 | 29 | .\" Modified 2003-05-21 by Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 30 | .\" MAP_LOCKED works from 2.5.37 |
305a0578 | 31 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 32 | .\" Modified 2004-09-11 by aeb |
1a956089 MK |
33 | .\" Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr> |
34 | .\" Modified 2004-12-08, mtk, formatting tidy-ups | |
fea681da | 35 | .\" |
1a956089 | 36 | .TH MMAP 2 2004-12-08 "Linux 2.6.9" "Linux Programmer's Manual" |
fea681da MK |
37 | .SH NAME |
38 | mmap, munmap \- map or unmap files or devices into memory | |
39 | .SH SYNOPSIS | |
e0037472 | 40 | .nf |
fea681da MK |
41 | .B #include <sys/mman.h> |
42 | .sp | |
e0037472 MK |
43 | .BI "void *mmap(void *" start ", size_t " length ", int " prot ", int " flags , |
44 | .BI " int " fd ", off_t " offset ); | |
fea681da MK |
45 | .sp |
46 | .BI "int munmap(void *" start ", size_t " length ); | |
e0037472 | 47 | .fi |
fea681da MK |
48 | .SH DESCRIPTION |
49 | The | |
1a956089 | 50 | .BR mmap () |
fea681da MK |
51 | function asks to map |
52 | .I length | |
53 | bytes starting at offset | |
54 | .I offset | |
55 | from the file (or other object) specified by the file descriptor | |
56 | .I fd | |
57 | into memory, preferably at address | |
58 | .IR start . | |
59 | This latter address is a hint only, and is usually specified as 0. | |
60 | The actual place where the object is mapped is returned by | |
1a956089 | 61 | .BR mmap (), |
fea681da MK |
62 | and is never 0. |
63 | .LP | |
64 | The | |
65 | .I prot | |
66 | argument describes the desired memory protection (and must not | |
67 | conflict with the open mode of the file). It is either | |
68 | .B PROT_NONE | |
69 | or is the bitwise OR of one or more of the other PROT_* flags. | |
70 | .TP 1.1i | |
71 | .B PROT_EXEC | |
72 | Pages may be executed. | |
73 | .TP | |
74 | .B PROT_READ | |
75 | Pages may be read. | |
76 | .TP | |
77 | .B PROT_WRITE | |
78 | Pages may be written. | |
79 | .TP | |
80 | .B PROT_NONE | |
81 | Pages may not be accessed. | |
82 | .LP | |
83 | The | |
84 | .I flags | |
85 | parameter specifies the type of the mapped object, mapping options and | |
86 | whether modifications made to the mapped copy of the page are private to | |
87 | the process or are to be shared with other references. It has bits | |
88 | .TP 1.1i | |
89 | .B MAP_FIXED | |
90 | Do not select a different address than the one specified. | |
1a956089 | 91 | If the memory region specified by |
8478ee02 | 92 | .I start |
1a956089 | 93 | and |
8478ee02 | 94 | .I len |
1a956089 MK |
95 | overlaps pages of any existing mapping(s), then the overlapped |
96 | part of the existing mapping(s) will be discarded. | |
fea681da | 97 | If the specified address cannot be used, |
1a956089 MK |
98 | .BR mmap () |
99 | will fail. | |
100 | If MAP_FIXED is specified, | |
fea681da MK |
101 | .I start |
102 | must be a multiple of the pagesize. Use of this option is discouraged. | |
103 | .TP | |
104 | .B MAP_SHARED | |
105 | Share this mapping with all other processes that map this object. | |
106 | Storing to the region is equivalent to writing to the file. | |
107 | The file may not actually be updated until | |
108 | .BR msync (2) | |
109 | or | |
110 | .BR munmap (2) | |
111 | are called. | |
112 | .TP | |
113 | .B MAP_PRIVATE | |
114 | Create a private copy-on-write mapping. | |
115 | Stores to the region do not affect the original file. | |
116 | It is unspecified whether changes made to the file after the | |
1a956089 | 117 | .BR mmap () |
fea681da MK |
118 | call are visible in the mapped region. |
119 | .LP | |
120 | You must specify exactly one of MAP_SHARED and MAP_PRIVATE. | |
121 | .LP | |
122 | The above three flags are described in POSIX.1b (formerly POSIX.4) and SUSv2. | |
123 | Linux also knows about the following non-standard flags: | |
124 | .TP | |
125 | .B MAP_DENYWRITE | |
126 | This flag is ignored. | |
127 | .\" Introduced in 1.1.36, removed in 1.3.24. | |
128 | (Long ago, it signalled that attempts to write to the underlying file | |
129 | should fail with ETXTBUSY. But this was a source of denial-of-service attacks.) | |
130 | .TP | |
131 | .B MAP_EXECUTABLE | |
132 | This flag is ignored. | |
133 | .\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. | |
134 | .\" (Long ago, it signalled that the underlying file is an executable. | |
135 | .\" However, that information was not really used anywhere.) | |
136 | .\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of | |
137 | .\" MAP_DENYWRITE? | |
138 | .TP | |
139 | .B MAP_NORESERVE | |
4006dcac MK |
140 | Do not reserve swap space for this mapping. |
141 | When swap space is reserved, one has the guarantee | |
142 | that it is possible to modify the mapping. | |
143 | When swap space is not reserved one might get SIGSEGV upon a write | |
144 | if no physical memory is available. | |
145 | See also the discussion of the file | |
146 | .I /proc/sys/vm/overcommit_memory | |
147 | in | |
148 | .BR proc (5). | |
149 | In kernels before 2.6, this flag only had effect for | |
150 | private writable mappings. | |
fea681da MK |
151 | .TP |
152 | .BR MAP_LOCKED " (since Linux 2.5.37)" | |
153 | Lock the pages of the mapped region into memory in the manner of | |
1a956089 | 154 | .BR mlock () . |
fea681da MK |
155 | This flag is ignored in older kernels. |
156 | .\" If set, the mapped pages will not be swapped out. | |
157 | .TP | |
158 | .B MAP_GROWSDOWN | |
159 | Used for stacks. Indicates to the kernel VM system that the mapping | |
160 | should extend downwards in memory. | |
161 | .TP | |
162 | .B MAP_ANONYMOUS | |
163 | The mapping is not backed by any file; the | |
164 | .I fd | |
165 | and | |
166 | .I offset | |
74f3f90b MK |
167 | arguments are ignored. |
168 | The use of this flag in conjunction with MAP_SHARED | |
169 | is only supported on Linux since kernel 2.4. | |
fea681da MK |
170 | .TP |
171 | .B MAP_ANON | |
172 | Alias for MAP_ANONYMOUS. Deprecated. | |
173 | .TP | |
174 | .B MAP_FILE | |
175 | Compatibility flag. Ignored. | |
176 | .TP | |
177 | .B MAP_32BIT | |
178 | Put the mapping into the first 2GB of the process address space. | |
179 | Ignored when | |
180 | .I MAP_FIXED | |
181 | is set. This flag is currently only supported on x86-64 for 64bit programs. | |
182 | .TP | |
183 | .BR MAP_POPULATE " (since Linux 2.5.46)" | |
184 | Populate (prefault) pagetables. | |
185 | .TP | |
186 | .BR MAP_NONBLOCK " (since Linux 2.5.46)" | |
187 | Do not block on IO. | |
188 | .LP | |
189 | Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV, | |
190 | MAP_COPY, and MAP_LOCAL. | |
191 | .LP | |
192 | .I fd | |
74f3f90b MK |
193 | should be a valid file descriptor, unless MAP_ANONYMOUS is set. |
194 | If MAP_ANONYMOUS is set, then | |
195 | .I fd | |
196 | is ignored on Linux. | |
197 | However, some implementations require | |
198 | .I fd | |
199 | to be \-1 if MAP_ANONYMOUS (or MAP_ANON) is specified, | |
200 | and portable applications should ensure this. | |
fea681da MK |
201 | .LP |
202 | .I offset | |
203 | should be a multiple of the page size as returned by | |
204 | .BR getpagesize (2). | |
205 | .LP | |
206 | Memory mapped by | |
1a956089 | 207 | .BR mmap () |
fea681da MK |
208 | is preserved across |
209 | .BR fork (2), | |
210 | with the same attributes. | |
211 | .LP | |
212 | A file is mapped in multiples of the page size. For a file that is not | |
213 | a multiple of the page size, the remaining memory is zeroed when mapped, | |
214 | and writes to that region are not written out to the file. The effect of | |
215 | changing the size of the underlying file of a mapping on the pages that | |
216 | correspond to added or removed regions of the file is unspecified. | |
217 | ||
218 | The | |
1a956089 | 219 | .BR munmap () |
fea681da MK |
220 | system call deletes the mappings for the specified address range, and |
221 | causes further references to addresses within the range to generate | |
222 | invalid memory references. The region is also automatically unmapped | |
223 | when the process is terminated. On the other hand, closing the file | |
224 | descriptor does not unmap the region. | |
225 | .LP | |
226 | The address | |
227 | .I start | |
228 | must be a multiple of the page size. All pages containing a part | |
229 | of the indicated range are unmapped, and subsequent references | |
230 | to these pages will generate SIGSEGV. It is not an error if the | |
231 | indicated range does not contain any mapped pages. | |
232 | ||
233 | For file-backed mappings, the | |
8478ee02 | 234 | .I st_atime |
fea681da | 235 | field for the mapped file may be updated at any time between the |
1a956089 | 236 | .BR mmap () |
fea681da MK |
237 | and the corresponding unmapping; the first reference to a mapped |
238 | page will update the field if it has not been already. | |
239 | .LP | |
240 | The | |
8478ee02 | 241 | .I st_ctime |
fea681da | 242 | and |
8478ee02 | 243 | .I st_mtime |
fea681da MK |
244 | field for a file mapped with PROT_WRITE and MAP_SHARED will be updated after |
245 | a write to the mapped region, and before a subsequent | |
1a956089 | 246 | .BR msync () |
fea681da MK |
247 | with the MS_SYNC or MS_ASYNC flag, if one occurs. |
248 | .SH "RETURN VALUE" | |
249 | On success, | |
1a956089 | 250 | .BR mmap () |
fea681da MK |
251 | returns a pointer to the mapped area. |
252 | On error, the value | |
253 | .B MAP_FAILED | |
254 | (that is, (void *) \-1) is returned, and | |
255 | .I errno | |
256 | is set appropriately. | |
257 | On success, | |
1a956089 | 258 | .BR munmap () |
fea681da MK |
259 | returns 0, on failure \-1, and |
260 | .I errno | |
261 | is set (probably to EINVAL). | |
262 | .SH NOTES | |
263 | It is architecture dependent whether | |
264 | .I PROT_READ | |
265 | includes | |
266 | .I PROT_EXEC | |
267 | or not. Portable programs should always set | |
268 | .I PROT_EXEC | |
269 | if they intend to execute code in the new mapping. | |
270 | .SH ERRORS | |
271 | .TP | |
272 | .B EACCES | |
273 | A file descriptor refers to a non-regular file. | |
274 | Or MAP_PRIVATE was requested, but | |
275 | .I fd | |
276 | is not open for reading. | |
277 | Or MAP_SHARED was requested and PROT_WRITE is set, but | |
278 | .I fd | |
279 | is not open in read/write (O_RDWR) mode. | |
280 | Or PROT_WRITE is set, but the file is append-only. | |
281 | .TP | |
282 | .B EAGAIN | |
83cd3686 MK |
283 | The file has been locked, or too much memory has been locked (see |
284 | .BR setrlimit (2)). | |
fea681da MK |
285 | .TP |
286 | .B EBADF | |
287 | .I fd | |
288 | is not a valid file descriptor (and MAP_ANONYMOUS was not set). | |
289 | .TP | |
290 | .B EINVAL | |
291 | We don't like | |
292 | .I start | |
293 | or | |
294 | .I length | |
295 | or | |
296 | .IR offset . | |
297 | (E.g., they are too large, or not aligned on a PAGESIZE boundary.) | |
298 | .\" jbl - not sure this actually happens ? see generic_file_mmap | |
24b1a012 MK |
299 | .\" mtk: Before 2.6.12, a length of 0 was permitted: mmap() did |
300 | .\" not create mapping, but just returned 'start'; since 2.6.12, | |
301 | .\" a length of 0 yields EINVAL (as required by SUSv3). | |
fea681da MK |
302 | .TP |
303 | .B ENFILE | |
304 | .\" This is for shared anonymous segments | |
305 | .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() | |
306 | The system limit on the total number of open files has been reached. | |
307 | .\" .TP | |
308 | .\" .B ENOEXEC | |
309 | .\" A file could not be mapped for reading. | |
310 | .TP | |
311 | .B ENODEV | |
312 | The underlying filesystem of the specified file does not support | |
313 | memory mapping. | |
314 | .TP | |
315 | .B ENOMEM | |
316 | No memory is available, or the process's maximum number of mappings would | |
317 | have been exceeded. | |
318 | .TP | |
319 | .B EPERM | |
320 | The | |
321 | .I prot | |
322 | argument asks for | |
323 | .B PROT_EXEC | |
324 | but the mapped area belongs to a file on a filesystem that | |
325 | was mounted no-exec. | |
326 | .\" (Since 2.4.25 / 2.6.0.) | |
327 | .TP | |
328 | .B ETXTBSY | |
329 | MAP_DENYWRITE was set but the object specified by | |
330 | .I fd | |
331 | is open for writing. | |
332 | .LP | |
333 | Use of a mapped region can result in these signals: | |
334 | .TP | |
335 | .B SIGSEGV | |
1e321034 | 336 | Attempted write into a region mapped as read-only. |
fea681da MK |
337 | .TP |
338 | .B SIGBUS | |
339 | Attempted access to a portion of the buffer that does not correspond | |
340 | to the file (for example, beyond the end of the file, including the | |
341 | case where another process has truncated the file). | |
342 | .SH AVAILABILITY | |
343 | On POSIX systems on which | |
1a956089 MK |
344 | .BR mmap (), |
345 | .BR msync () | |
fea681da | 346 | and |
1a956089 | 347 | .BR munmap () |
fea681da MK |
348 | are available, |
349 | .B _POSIX_MAPPED_FILES | |
350 | is defined in <unistd.h> to a value greater than 0. (See also | |
351 | .BR sysconf (3).) | |
352 | .\" POSIX 1003.1-2001: It shall be defined to -1 or 0 or 200112L. | |
353 | .\" -1: unavailable, 0: ask using sysconf(). | |
354 | .\" glibc defines it to 1. | |
355 | .SH "CONFORMING TO" | |
356 | SVr4, POSIX.1b (formerly POSIX.4), 4.4BSD, SUSv2. | |
357 | SVr4 documents additional error codes ENXIO and ENODEV. | |
358 | SUSv2 documents additional error codes EMFILE and EOVERFLOW. | |
359 | .SH BUGS | |
dbc53ca8 MK |
360 | On Linux there are no guarantees like those suggested above under |
361 | .BR MAP_NORESERVE . | |
362 | By default, any process can be killed | |
fea681da | 363 | at any moment when the system runs out of memory. |
dbc53ca8 MK |
364 | |
365 | In kernels before 2.6.7, the | |
366 | .B MAP_POPULATE | |
367 | flag only has effect if | |
368 | .I prot | |
369 | is specified as | |
370 | .BR PROT_NONE . | |
fea681da MK |
371 | .SH "SEE ALSO" |
372 | .BR getpagesize (2), | |
f75c3a3b | 373 | .BR mincore (2), |
fea681da MK |
374 | .BR mlock (2), |
375 | .BR mmap2 (2), | |
376 | .BR mremap (2), | |
377 | .BR msync (2), | |
83cd3686 | 378 | .BR setrlimit (2), |
424a8950 | 379 | .BR shm_open (3) |
fea681da MK |
380 | .br |
381 | B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391. | |
382 | .\" | |
383 | .\" Repeat after me: private read-only mappings are 100% equivalent to | |
384 | .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus |