| 1 |
'\" t |
| 2 |
.\" Copyright 1996, Andries E. Brouwer <[email protected]> |
| 3 |
.\" Copyright 2006-2007, Michael Kerrisk <[email protected]> |
| 4 |
.\" Copyright, the authors of the Linux man-pages project |
| 5 |
.\" |
| 6 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 7 |
.\" |
| 8 |
.TH mmap 2 2026-03-19 "Linux man-pages 6.18" |
| 9 |
.SH NAME |
| 10 |
mmap, munmap \- map or unmap files or devices into memory |
| 11 |
.SH LIBRARY |
| 12 |
Standard C library |
| 13 |
.RI ( libc ,\~ \-lc ) |
| 14 |
.SH SYNOPSIS |
| 15 |
.nf |
| 16 |
.B #include <sys/mman.h> |
| 17 |
.P |
| 18 |
.BR "void *mmap(" "size_t length;" |
| 19 |
.BI " void " addr [ length "], size_t " length \ |
| 20 |
", int " prot ", int " flags , |
| 21 |
.BI " int " fd ", off_t " offset ); |
| 22 |
.BR "int munmap(" "size_t length;" |
| 23 |
.BI " void " addr [ length "], size_t " length ); |
| 24 |
.fi |
| 25 |
.P |
| 26 |
See VERSIONS for information on feature test macro requirements. |
| 27 |
.SH DESCRIPTION |
| 28 |
.BR mmap () |
| 29 |
creates a new mapping in the virtual address space of |
| 30 |
the calling process. |
| 31 |
The starting address for the new mapping is specified in |
| 32 |
.IR addr . |
| 33 |
The |
| 34 |
.I length |
| 35 |
argument specifies the length of the mapping (which must be greater than 0). |
| 36 |
.P |
| 37 |
If |
| 38 |
.I addr |
| 39 |
is NULL, |
| 40 |
then the kernel chooses the (page-aligned) address |
| 41 |
at which to create the mapping; |
| 42 |
this is the most portable method of creating a new mapping. |
| 43 |
If |
| 44 |
.I addr |
| 45 |
is not NULL, |
| 46 |
then the kernel takes it as a hint about where to place the mapping; |
| 47 |
on Linux, the kernel will pick a nearby page boundary (but always above |
| 48 |
or equal to the value specified by |
| 49 |
.IR /proc/sys/vm/mmap_min_addr ) |
| 50 |
and attempt to create the mapping there. |
| 51 |
If another mapping already exists there, the kernel picks a new address that |
| 52 |
may or may not depend on the hint. |
| 53 |
.\" Before Linux 2.6.24, the address was rounded up to the next page |
| 54 |
.\" boundary; since Linux 2.6.24, it is rounded down! |
| 55 |
The address of the new mapping is returned as the result of the call. |
| 56 |
.P |
| 57 |
The contents of a file mapping (as opposed to an anonymous mapping; |
| 58 |
see |
| 59 |
.B MAP_ANONYMOUS |
| 60 |
below), are initialized using |
| 61 |
.I length |
| 62 |
bytes starting at offset |
| 63 |
.I offset |
| 64 |
in the file (or other object) referred to by the file descriptor |
| 65 |
.IR fd . |
| 66 |
.I offset |
| 67 |
must be a multiple of the page size as returned by |
| 68 |
.IR sysconf(_SC_PAGE_SIZE) . |
| 69 |
.P |
| 70 |
After the |
| 71 |
.BR mmap () |
| 72 |
call has returned, the file descriptor, |
| 73 |
.IR fd , |
| 74 |
can be closed immediately without invalidating the mapping. |
| 75 |
.P |
| 76 |
The |
| 77 |
.I prot |
| 78 |
argument describes the desired memory protection of the mapping |
| 79 |
(and must not conflict with the open mode of the file). |
| 80 |
It is either |
| 81 |
.B PROT_NONE |
| 82 |
or the bitwise OR of one or more of the following flags: |
| 83 |
.TP 1.1i |
| 84 |
.B PROT_EXEC |
| 85 |
Pages may be executed. |
| 86 |
.TP |
| 87 |
.B PROT_READ |
| 88 |
Pages may be read. |
| 89 |
.TP |
| 90 |
.B PROT_WRITE |
| 91 |
Pages may be written. |
| 92 |
.TP |
| 93 |
.B PROT_NONE |
| 94 |
Pages may not be accessed. |
| 95 |
.\" |
| 96 |
.SS The flags argument |
| 97 |
The |
| 98 |
.I flags |
| 99 |
argument determines whether updates to the mapping |
| 100 |
are visible to other processes mapping the same region, |
| 101 |
and whether updates are carried through to the underlying file. |
| 102 |
This behavior is determined by including exactly one |
| 103 |
of the following values in |
| 104 |
.IR flags : |
| 105 |
.TP |
| 106 |
.B MAP_SHARED |
| 107 |
Share this mapping. |
| 108 |
Updates to the mapping are visible to other processes mapping the same region, |
| 109 |
and (in the case of file-backed mappings) |
| 110 |
are carried through to the underlying file. |
| 111 |
(To precisely control when updates are carried through |
| 112 |
to the underlying file requires the use of |
| 113 |
.BR msync (2).) |
| 114 |
.TP |
| 115 |
.BR MAP_SHARED_VALIDATE " (since Linux 4.15)" |
| 116 |
This flag provides the same behavior as |
| 117 |
.B MAP_SHARED |
| 118 |
except that |
| 119 |
.B MAP_SHARED |
| 120 |
mappings ignore unknown flags in |
| 121 |
.IR flags . |
| 122 |
By contrast, when creating a mapping using |
| 123 |
.BR MAP_SHARED_VALIDATE , |
| 124 |
the kernel verifies all passed flags are known and fails the |
| 125 |
mapping with the error |
| 126 |
.B EOPNOTSUPP |
| 127 |
for unknown flags. |
| 128 |
This mapping type is also required to be able to use some mapping flags |
| 129 |
(e.g., |
| 130 |
.BR MAP_SYNC ). |
| 131 |
.TP |
| 132 |
.B MAP_PRIVATE |
| 133 |
Create a private copy-on-write mapping. |
| 134 |
Updates to the mapping are not visible to other processes |
| 135 |
mapping the same file, and are not carried through to |
| 136 |
the underlying file. |
| 137 |
It is unspecified whether changes made to the file after the |
| 138 |
.BR mmap () |
| 139 |
call are visible in the mapped region. |
| 140 |
.P |
| 141 |
Both |
| 142 |
.B MAP_SHARED |
| 143 |
and |
| 144 |
.B MAP_PRIVATE |
| 145 |
are described in POSIX.1-2001 and POSIX.1-2008. |
| 146 |
.B MAP_SHARED_VALIDATE |
| 147 |
is a Linux extension. |
| 148 |
.P |
| 149 |
In addition, zero or more of the following values can be ORed in |
| 150 |
.IR flags : |
| 151 |
.TP |
| 152 |
.BR MAP_32BIT " (since Linux 2.4.20, 2.6)" |
| 153 |
Put the mapping into the first 2 Gigabytes of the process address space. |
| 154 |
This flag is supported only on x86-64, for 64-bit programs. |
| 155 |
It was added to allow thread stacks to be allocated somewhere |
| 156 |
in the first 2\ GB of memory, |
| 157 |
so as to improve context-switch performance on some early |
| 158 |
64-bit processors. |
| 159 |
.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 |
| 160 |
Modern x86-64 processors no longer have this performance problem, |
| 161 |
so use of this flag is not required on those systems. |
| 162 |
The |
| 163 |
.B MAP_32BIT |
| 164 |
flag is ignored when |
| 165 |
.B MAP_FIXED |
| 166 |
is set. |
| 167 |
.TP |
| 168 |
.B MAP_ANON |
| 169 |
Synonym for |
| 170 |
.BR MAP_ANONYMOUS ; |
| 171 |
provided for compatibility with other implementations. |
| 172 |
.TP |
| 173 |
.B MAP_ANONYMOUS |
| 174 |
The mapping is not backed by any file; |
| 175 |
its contents are initialized to zero. |
| 176 |
The |
| 177 |
.I fd |
| 178 |
argument is ignored; |
| 179 |
however, some implementations require |
| 180 |
.I fd |
| 181 |
to be \-1 if |
| 182 |
.B MAP_ANONYMOUS |
| 183 |
(or |
| 184 |
.BR MAP_ANON ) |
| 185 |
is specified, |
| 186 |
and portable applications should ensure this. |
| 187 |
The |
| 188 |
.I offset |
| 189 |
argument should be zero. |
| 190 |
.\" See the pgoff overflow check in do_mmap(). |
| 191 |
.\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c. |
| 192 |
Support for |
| 193 |
.B MAP_ANONYMOUS |
| 194 |
in conjunction with |
| 195 |
.B MAP_SHARED |
| 196 |
was added in Linux 2.4. |
| 197 |
.TP |
| 198 |
.B MAP_DENYWRITE |
| 199 |
This flag is ignored. |
| 200 |
.\" Introduced in 1.1.36, removed in 1.3.24. |
| 201 |
(Long ago\[em]Linux 2.0 and earlier\[em]it signaled |
| 202 |
that attempts to write to the underlying file should fail with |
| 203 |
.BR ETXTBSY . |
| 204 |
But this was a source of denial-of-service attacks.) |
| 205 |
.TP |
| 206 |
.B MAP_EXECUTABLE |
| 207 |
This flag is ignored. |
| 208 |
.\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. |
| 209 |
.\" (Long ago, it signaled that the underlying file is an executable. |
| 210 |
.\" However, that information was not really used anywhere.) |
| 211 |
.\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of |
| 212 |
.\" MAP_DENYWRITE? |
| 213 |
.TP |
| 214 |
.B MAP_FILE |
| 215 |
Compatibility flag. |
| 216 |
Ignored. |
| 217 |
.\" On some systems, this was required as the opposite of |
| 218 |
.\" MAP_ANONYMOUS -- mtk, 1 May 2007 |
| 219 |
.TP |
| 220 |
.B MAP_FIXED |
| 221 |
Don't interpret |
| 222 |
.I addr |
| 223 |
as a hint: place the mapping at exactly that address. |
| 224 |
.I addr |
| 225 |
must be suitably aligned: |
| 226 |
for most architectures a multiple of the page size is sufficient; |
| 227 |
however, |
| 228 |
some architectures may impose additional restrictions. |
| 229 |
If the memory region specified by |
| 230 |
.I addr |
| 231 |
and |
| 232 |
.I length |
| 233 |
overlaps pages of any existing mapping(s), then the overlapped |
| 234 |
part of the existing mapping(s) will be discarded. |
| 235 |
If the specified address cannot be used, |
| 236 |
.BR mmap () |
| 237 |
will fail. |
| 238 |
.IP |
| 239 |
Software that aspires to be portable should use the |
| 240 |
.B MAP_FIXED |
| 241 |
flag with care, |
| 242 |
keeping in mind that the exact layout of a process's memory mappings |
| 243 |
is allowed to change significantly between Linux versions, |
| 244 |
C library versions, and operating system releases. |
| 245 |
.I Carefully read the discussion of this flag in NOTES! |
| 246 |
.TP |
| 247 |
.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" |
| 248 |
.\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843 |
| 249 |
This flag provides behavior that is similar to |
| 250 |
.B MAP_FIXED |
| 251 |
with respect to the |
| 252 |
.I addr |
| 253 |
enforcement, but differs in that |
| 254 |
.B MAP_FIXED_NOREPLACE |
| 255 |
never clobbers a preexisting mapped range. |
| 256 |
If the requested range would collide with an existing mapping, |
| 257 |
then this call fails with the error |
| 258 |
.B EEXIST. |
| 259 |
This flag can therefore be used as a way to atomically |
| 260 |
(with respect to other threads) |
| 261 |
attempt to map an address range: |
| 262 |
one thread will succeed; |
| 263 |
all others will report failure. |
| 264 |
.IP |
| 265 |
Note that older kernels which do not recognize the |
| 266 |
.B MAP_FIXED_NOREPLACE |
| 267 |
flag will typically (upon detecting a collision with a preexisting mapping) |
| 268 |
fall back to a |
| 269 |
.RB \[lq]non- MAP_FIXED \[rq] |
| 270 |
type of behavior: |
| 271 |
they will return an address that is different from the requested address. |
| 272 |
Therefore, backward-compatible software |
| 273 |
should check the returned address against the requested address. |
| 274 |
.TP |
| 275 |
.B MAP_GROWSDOWN |
| 276 |
This flag is used for stacks. |
| 277 |
It indicates to the kernel virtual memory system that the mapping |
| 278 |
should extend downward in memory. |
| 279 |
Touching an address in the "guard" page below the mapping will cause |
| 280 |
the mapping to grow by a page. |
| 281 |
This growth can be repeated until the mapping grows to within a |
| 282 |
page of the high end of the next lower mapping, |
| 283 |
at which point touching the "guard" page will result in a |
| 284 |
.B SIGSEGV |
| 285 |
signal. |
| 286 |
.TP |
| 287 |
.BR MAP_HUGETLB " (since Linux 2.6.32)" |
| 288 |
Allocate the mapping using "huge" pages. |
| 289 |
See the Linux kernel source file |
| 290 |
.I Documentation/admin\-guide/mm/hugetlbpage.rst |
| 291 |
for further information, as well as NOTES, below. |
| 292 |
.TP |
| 293 |
.B MAP_HUGE_2MB |
| 294 |
.TQ |
| 295 |
.BR MAP_HUGE_1GB " (since Linux 3.8)" |
| 296 |
.\" See https://lwn.net/Articles/533499/ |
| 297 |
Used in conjunction with |
| 298 |
.B MAP_HUGETLB |
| 299 |
to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) |
| 300 |
on systems that support multiple hugetlb page sizes. |
| 301 |
.IP |
| 302 |
More generally, the desired huge page size can be configured by encoding |
| 303 |
the base-2 logarithm of the desired page size in the six bits at the offset |
| 304 |
.BR MAP_HUGE_SHIFT . |
| 305 |
(A value of zero in this bit field provides the default huge page size; |
| 306 |
the default huge page size can be discovered via the |
| 307 |
.I Hugepagesize |
| 308 |
field exposed by |
| 309 |
.IR /proc/meminfo .) |
| 310 |
Thus, the above two constants are defined as: |
| 311 |
.IP |
| 312 |
.in +4n |
| 313 |
.EX |
| 314 |
#define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT) |
| 315 |
#define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT) |
| 316 |
.EE |
| 317 |
.in |
| 318 |
.IP |
| 319 |
The range of huge page sizes that are supported by the system |
| 320 |
can be discovered by listing the subdirectories in |
| 321 |
.IR /sys/kernel/mm/hugepages . |
| 322 |
.TP |
| 323 |
.BR MAP_LOCKED " (since Linux 2.5.37)" |
| 324 |
Mark the mapped region to be locked in the same way as |
| 325 |
.BR mlock (2). |
| 326 |
This implementation will try to populate (prefault) the whole range but the |
| 327 |
.BR mmap () |
| 328 |
call doesn't fail with |
| 329 |
.B ENOMEM |
| 330 |
if this fails. |
| 331 |
Therefore major faults might happen later on. |
| 332 |
So the semantic is not as strong as |
| 333 |
.BR mlock (2). |
| 334 |
One should use |
| 335 |
.BR mmap () |
| 336 |
plus |
| 337 |
.BR mlock (2) |
| 338 |
when major faults are not acceptable after the initialization of the mapping. |
| 339 |
The |
| 340 |
.B MAP_LOCKED |
| 341 |
flag is ignored in older kernels. |
| 342 |
.\" If set, the mapped pages will not be swapped out. |
| 343 |
.TP |
| 344 |
.BR MAP_NONBLOCK " (since Linux 2.5.46)" |
| 345 |
This flag is meaningful only in conjunction with |
| 346 |
.BR MAP_POPULATE . |
| 347 |
Don't perform read-ahead: |
| 348 |
create page tables entries only for pages |
| 349 |
that are already present in RAM. |
| 350 |
Since Linux 2.6.23, |
| 351 |
.\" commit 54cb8821de07f2ffcd28c380ce9b93d5784b40d7 |
| 352 |
this flag causes |
| 353 |
.B MAP_POPULATE |
| 354 |
to do nothing. |
| 355 |
One day, the combination of |
| 356 |
.B MAP_POPULATE |
| 357 |
and |
| 358 |
.B MAP_NONBLOCK |
| 359 |
may be reimplemented. |
| 360 |
.TP |
| 361 |
.B MAP_NORESERVE |
| 362 |
Do not reserve swap space for this mapping. |
| 363 |
When swap space is reserved, one has the guarantee |
| 364 |
that it is possible to modify the mapping. |
| 365 |
When swap space is not reserved one might get |
| 366 |
.B SIGSEGV |
| 367 |
upon a write |
| 368 |
if no physical memory is available. |
| 369 |
See also the discussion of the file |
| 370 |
.I /proc/sys/vm/overcommit_memory |
| 371 |
in |
| 372 |
.BR proc_sys_vm (5). |
| 373 |
Before Linux 2.6, this flag had effect only for |
| 374 |
private writable mappings. |
| 375 |
.TP |
| 376 |
.BR MAP_POPULATE " (since Linux 2.5.46)" |
| 377 |
Populate (prefault) page tables for a mapping. |
| 378 |
For a file mapping, this causes read-ahead on the file. |
| 379 |
This will help to reduce blocking on page faults later. |
| 380 |
The |
| 381 |
.BR mmap () |
| 382 |
call doesn't fail if the mapping cannot be populated (for example, due |
| 383 |
to limitations on the number of mapped huge pages when using |
| 384 |
.BR MAP_HUGETLB ). |
| 385 |
Support for |
| 386 |
.B MAP_POPULATE |
| 387 |
in conjunction with private mappings was added in Linux 2.6.23. |
| 388 |
.TP |
| 389 |
.BR MAP_STACK " (since Linux 2.6.27)" |
| 390 |
Allocate the mapping at an address suitable for a process |
| 391 |
or thread stack. |
| 392 |
.IP |
| 393 |
This flag is currently a no-op on Linux. |
| 394 |
However, by employing this flag, applications can ensure that |
| 395 |
they transparently obtain support if the flag |
| 396 |
is implemented in the future. |
| 397 |
Thus, it is used in the glibc threading implementation to allow for |
| 398 |
the fact that some architectures may (later) require special treatment |
| 399 |
for stack allocations. |
| 400 |
.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 |
| 401 |
.\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7 |
| 402 |
.\" http://thread.gmane.org/gmane.linux.kernel/720412 |
| 403 |
.\" "pthread_create() slow for many threads; also time to revisit 64b |
| 404 |
.\" context switch optimization?" |
| 405 |
A further reason to employ this flag is portability: |
| 406 |
.B MAP_STACK |
| 407 |
exists (and has an effect) on some other systems (e.g., some of the BSDs). |
| 408 |
.TP |
| 409 |
.BR MAP_SYNC " (since Linux 4.15)" |
| 410 |
This flag is available only with the |
| 411 |
.B MAP_SHARED_VALIDATE |
| 412 |
mapping type; |
| 413 |
mappings of type |
| 414 |
.B MAP_SHARED |
| 415 |
will silently ignore this flag. |
| 416 |
This flag is supported only for files supporting DAX |
| 417 |
(direct mapping of persistent memory). |
| 418 |
For other files, creating a mapping with this flag results in an |
| 419 |
.B EOPNOTSUPP |
| 420 |
error. |
| 421 |
.IP |
| 422 |
Shared file mappings with this flag provide the guarantee that while |
| 423 |
some memory is mapped writable in the address space of the process, |
| 424 |
it will be visible in the same file at the same offset even after |
| 425 |
the system crashes or is rebooted. |
| 426 |
In conjunction with the use of appropriate CPU instructions, |
| 427 |
this provides users of such mappings with a more efficient way |
| 428 |
of making data modifications persistent. |
| 429 |
.TP |
| 430 |
.BR MAP_UNINITIALIZED " (since Linux 2.6.33)" |
| 431 |
Don't clear anonymous pages. |
| 432 |
This flag is intended to improve performance on embedded devices. |
| 433 |
This flag is honored only if the kernel was configured with the |
| 434 |
.B CONFIG_MMAP_ALLOW_UNINITIALIZED |
| 435 |
option. |
| 436 |
Because of the security implications, |
| 437 |
that option is normally enabled only on embedded devices |
| 438 |
(i.e., devices where one has complete control of the contents of user memory). |
| 439 |
.P |
| 440 |
Of the above flags, only |
| 441 |
.B MAP_FIXED |
| 442 |
is specified in POSIX.1-2001 and POSIX.1-2008. |
| 443 |
However, most systems also support |
| 444 |
.B MAP_ANONYMOUS |
| 445 |
(or its synonym |
| 446 |
.BR MAP_ANON ). |
| 447 |
.\" FIXME . for later review when Issue 8 is one day released... |
| 448 |
.\" POSIX may add MAP_ANON in the future |
| 449 |
.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 |
| 450 |
.\" http://austingroupbugs.net/view.php?id=850 |
| 451 |
.SS munmap() |
| 452 |
The |
| 453 |
.BR munmap () |
| 454 |
system call deletes the mappings for the specified address range, and |
| 455 |
causes further references to addresses within the range to generate |
| 456 |
invalid memory references. |
| 457 |
The region is also automatically unmapped |
| 458 |
when the process is terminated. |
| 459 |
On the other hand, closing the file |
| 460 |
descriptor does not unmap the region. |
| 461 |
.P |
| 462 |
The address |
| 463 |
.I addr |
| 464 |
must be a multiple of the page size (but |
| 465 |
.I length |
| 466 |
need not be). |
| 467 |
All pages containing a part |
| 468 |
of the indicated range are unmapped, and subsequent references |
| 469 |
to these pages will generate |
| 470 |
.BR SIGSEGV . |
| 471 |
It is not an error if the |
| 472 |
indicated range does not contain any mapped pages. |
| 473 |
.SH RETURN VALUE |
| 474 |
On success, |
| 475 |
.BR mmap () |
| 476 |
returns a pointer to the mapped area. |
| 477 |
On error, the value |
| 478 |
.B MAP_FAILED |
| 479 |
(that is, |
| 480 |
.IR "(void\ *)\ \-1" ) |
| 481 |
is returned, and |
| 482 |
.I errno |
| 483 |
is set to indicate the error. |
| 484 |
.P |
| 485 |
On success, |
| 486 |
.BR munmap () |
| 487 |
returns 0. |
| 488 |
On failure, it returns \-1, and |
| 489 |
.I errno |
| 490 |
is set to indicate the error (probably to |
| 491 |
.BR EINVAL ). |
| 492 |
.SH ERRORS |
| 493 |
.TP |
| 494 |
.B EACCES |
| 495 |
A file descriptor refers to a non-regular file. |
| 496 |
Or a file mapping was requested, but |
| 497 |
.I fd |
| 498 |
is not open for reading. |
| 499 |
Or |
| 500 |
.B MAP_SHARED |
| 501 |
was requested and |
| 502 |
.B PROT_WRITE |
| 503 |
is set, but |
| 504 |
.I fd |
| 505 |
is not open in read/write |
| 506 |
.RB ( O_RDWR ) |
| 507 |
mode. |
| 508 |
Or |
| 509 |
.B PROT_WRITE |
| 510 |
is set, but the file is append-only. |
| 511 |
.TP |
| 512 |
.B EAGAIN |
| 513 |
The file has been locked, or too much memory has been locked (see |
| 514 |
.BR setrlimit (2)). |
| 515 |
.TP |
| 516 |
.B EBADF |
| 517 |
.I fd |
| 518 |
is not a valid file descriptor (and |
| 519 |
.B MAP_ANONYMOUS |
| 520 |
was not set). |
| 521 |
.TP |
| 522 |
.B EEXIST |
| 523 |
.B MAP_FIXED_NOREPLACE |
| 524 |
was specified in |
| 525 |
.IR flags , |
| 526 |
and the range covered by |
| 527 |
.I addr |
| 528 |
and |
| 529 |
.I length |
| 530 |
clashes with an existing mapping. |
| 531 |
.TP |
| 532 |
.B EINVAL |
| 533 |
We don't like |
| 534 |
.IR addr , |
| 535 |
.IR length , |
| 536 |
or |
| 537 |
.I offset |
| 538 |
(e.g., they are too large, or not aligned on a page boundary). |
| 539 |
.TP |
| 540 |
.B EINVAL |
| 541 |
(since Linux 2.6.12) |
| 542 |
.I length |
| 543 |
was 0. |
| 544 |
.TP |
| 545 |
.B EINVAL |
| 546 |
.I flags |
| 547 |
contained none of |
| 548 |
.BR MAP_PRIVATE , |
| 549 |
.BR MAP_SHARED , |
| 550 |
or |
| 551 |
.BR MAP_SHARED_VALIDATE . |
| 552 |
.TP |
| 553 |
.B ENFILE |
| 554 |
.\" This is for shared anonymous segments |
| 555 |
.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() |
| 556 |
The system-wide limit on the total number of open files has been reached. |
| 557 |
.\" .TP |
| 558 |
.\" .B ENOEXEC |
| 559 |
.\" A file could not be mapped for reading. |
| 560 |
.TP |
| 561 |
.B ENODEV |
| 562 |
The underlying filesystem of the specified file does not support |
| 563 |
memory mapping. |
| 564 |
.TP |
| 565 |
.B ENOMEM |
| 566 |
No memory is available. |
| 567 |
.TP |
| 568 |
.B ENOMEM |
| 569 |
The process's maximum number of mappings would have been exceeded. |
| 570 |
This error can also occur for |
| 571 |
.BR munmap (), |
| 572 |
when unmapping a region in the middle of an existing mapping, |
| 573 |
since this results in two smaller mappings on either side of |
| 574 |
the region being unmapped. |
| 575 |
.TP |
| 576 |
.B ENOMEM |
| 577 |
(since Linux 4.7) |
| 578 |
The process's |
| 579 |
.B RLIMIT_DATA |
| 580 |
limit, described in |
| 581 |
.BR getrlimit (2), |
| 582 |
would have been exceeded. |
| 583 |
.TP |
| 584 |
.B ENOMEM |
| 585 |
We don't like |
| 586 |
.IR addr , |
| 587 |
because it exceeds the virtual address space of the CPU. |
| 588 |
.TP |
| 589 |
.B EOVERFLOW |
| 590 |
On 32-bit architecture together with the large file extension |
| 591 |
(i.e., using 64-bit |
| 592 |
.IR off_t ): |
| 593 |
the number of pages used for |
| 594 |
.I length |
| 595 |
plus number of pages used for |
| 596 |
.I offset |
| 597 |
would overflow |
| 598 |
.I "unsigned long" |
| 599 |
(32 bits). |
| 600 |
.TP |
| 601 |
.B EPERM |
| 602 |
The |
| 603 |
.I prot |
| 604 |
argument asks for |
| 605 |
.B PROT_EXEC |
| 606 |
but the mapped area belongs to a file on a filesystem that |
| 607 |
was mounted no-exec. |
| 608 |
.\" (Since Linux 2.4.25 / Linux 2.6.0.) |
| 609 |
.TP |
| 610 |
.B EPERM |
| 611 |
The operation was prevented by a file seal; |
| 612 |
see |
| 613 |
.BR fcntl (2). |
| 614 |
.TP |
| 615 |
.B EPERM |
| 616 |
The |
| 617 |
.B MAP_HUGETLB |
| 618 |
flag was specified, but the caller was not privileged (did not have the |
| 619 |
.B CAP_IPC_LOCK |
| 620 |
capability) |
| 621 |
and is not a member of the |
| 622 |
.I hugetlb_shm_group |
| 623 |
group; |
| 624 |
see the description of |
| 625 |
.I /proc/sys/vm/hugetlb_shm_group |
| 626 |
in |
| 627 |
.BR proc_sys_vm (5). |
| 628 |
.TP |
| 629 |
.B ETXTBSY |
| 630 |
.B MAP_DENYWRITE |
| 631 |
was set but the object specified by |
| 632 |
.I fd |
| 633 |
is open for writing. |
| 634 |
.P |
| 635 |
Use of a mapped region can result in these signals: |
| 636 |
.TP |
| 637 |
.B SIGSEGV |
| 638 |
Attempted write into a region mapped as read-only. |
| 639 |
.TP |
| 640 |
.B SIGBUS |
| 641 |
Attempted access to a page of the buffer that lies beyond the |
| 642 |
end of the mapped file. |
| 643 |
For an explanation of the treatment of the bytes in the page that |
| 644 |
corresponds to the end of a mapped file that is not a multiple |
| 645 |
of the page size, see NOTES. |
| 646 |
.SH ATTRIBUTES |
| 647 |
For an explanation of the terms used in this section, see |
| 648 |
.BR attributes (7). |
| 649 |
.TS |
| 650 |
allbox; |
| 651 |
lbx lb lb |
| 652 |
l l l. |
| 653 |
Interface Attribute Value |
| 654 |
T{ |
| 655 |
.na |
| 656 |
.nh |
| 657 |
.BR mmap (), |
| 658 |
.BR munmap () |
| 659 |
T} Thread safety MT-Safe |
| 660 |
.TE |
| 661 |
.SH VERSIONS |
| 662 |
On some hardware architectures (e.g., i386), |
| 663 |
.B PROT_WRITE |
| 664 |
implies |
| 665 |
.BR PROT_READ . |
| 666 |
It is architecture dependent whether |
| 667 |
.B PROT_READ |
| 668 |
implies |
| 669 |
.B PROT_EXEC |
| 670 |
or not. |
| 671 |
Portable programs should always set |
| 672 |
.B PROT_EXEC |
| 673 |
if they intend to execute code in the new mapping. |
| 674 |
.P |
| 675 |
The portable way to create a mapping is to specify |
| 676 |
.I addr |
| 677 |
as 0 (NULL), and omit |
| 678 |
.B MAP_FIXED |
| 679 |
from |
| 680 |
.IR flags . |
| 681 |
In this case, the system chooses the address for the mapping; |
| 682 |
the address is chosen so as not to conflict with any existing mapping, |
| 683 |
and will not be 0. |
| 684 |
If the |
| 685 |
.B MAP_FIXED |
| 686 |
flag is specified, and |
| 687 |
.I addr |
| 688 |
is 0 (NULL), then the mapped address will be 0 (NULL). |
| 689 |
.P |
| 690 |
Certain |
| 691 |
.I flags |
| 692 |
constants are defined only if suitable feature test macros are defined |
| 693 |
(possibly by default): |
| 694 |
.B _DEFAULT_SOURCE |
| 695 |
with glibc 2.19 or later; |
| 696 |
or |
| 697 |
.B _BSD_SOURCE |
| 698 |
or |
| 699 |
.B _SVID_SOURCE |
| 700 |
in glibc 2.19 and earlier. |
| 701 |
(Employing |
| 702 |
.B _GNU_SOURCE |
| 703 |
also suffices, |
| 704 |
and requiring that macro specifically would have been more logical, |
| 705 |
since these flags are all Linux-specific.) |
| 706 |
The relevant flags are: |
| 707 |
.BR MAP_32BIT , |
| 708 |
.B MAP_ANONYMOUS |
| 709 |
(and the synonym |
| 710 |
.BR MAP_ANON ), |
| 711 |
.BR MAP_DENYWRITE , |
| 712 |
.BR MAP_EXECUTABLE , |
| 713 |
.BR MAP_FILE , |
| 714 |
.BR MAP_GROWSDOWN , |
| 715 |
.BR MAP_HUGETLB , |
| 716 |
.BR MAP_LOCKED , |
| 717 |
.BR MAP_NONBLOCK , |
| 718 |
.BR MAP_NORESERVE , |
| 719 |
.BR MAP_POPULATE , |
| 720 |
and |
| 721 |
.BR MAP_STACK . |
| 722 |
.SS C library/kernel differences |
| 723 |
This page describes the interface provided by the glibc |
| 724 |
.BR mmap () |
| 725 |
wrapper function. |
| 726 |
Originally, this function invoked a system call of the same name. |
| 727 |
Since Linux 2.4, that system call has been superseded by |
| 728 |
.BR mmap2 (2), |
| 729 |
and nowadays |
| 730 |
.\" Since around glibc 2.1/2.2, depending on the platform. |
| 731 |
the glibc |
| 732 |
.BR mmap () |
| 733 |
wrapper function invokes |
| 734 |
.BR mmap2 (2) |
| 735 |
with a suitably adjusted value for |
| 736 |
.IR offset . |
| 737 |
.SH STANDARDS |
| 738 |
POSIX.1-2024. |
| 739 |
.SH HISTORY |
| 740 |
SVr4, |
| 741 |
4.4BSD, |
| 742 |
SUSv1, |
| 743 |
POSIX.1-1996. |
| 744 |
.\" SVr4 documents additional error codes ENXIO and ENODEV. |
| 745 |
.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. |
| 746 |
.P |
| 747 |
On POSIX systems on which |
| 748 |
.BR mmap (), |
| 749 |
.BR msync (2), |
| 750 |
and |
| 751 |
.BR munmap () |
| 752 |
are available, |
| 753 |
.B _POSIX_MAPPED_FILES |
| 754 |
is defined in |
| 755 |
.I <unistd.h> |
| 756 |
to a value greater than 0. |
| 757 |
(See also |
| 758 |
.BR sysconf (3).) |
| 759 |
.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. |
| 760 |
.\" -1: unavailable, 0: ask using sysconf(). |
| 761 |
.\" glibc defines it to 1. |
| 762 |
.SH NOTES |
| 763 |
Memory mapped by |
| 764 |
.BR mmap () |
| 765 |
is preserved across |
| 766 |
.BR fork (2), |
| 767 |
with the same attributes. |
| 768 |
.P |
| 769 |
A file is mapped in multiples of the page size. |
| 770 |
For a file that is not |
| 771 |
a multiple of the page size, |
| 772 |
the remaining bytes in the partial page at the end of the mapping |
| 773 |
are zeroed when mapped, |
| 774 |
and modifications to that region are not written out to the file. |
| 775 |
The effect of |
| 776 |
changing the size of the underlying file of a mapping on the pages that |
| 777 |
correspond to added or removed regions of the file is unspecified. |
| 778 |
.P |
| 779 |
An application can determine which pages of a mapping are |
| 780 |
currently resident in the buffer/page cache using |
| 781 |
.BR mincore (2). |
| 782 |
.\" |
| 783 |
.SS Using MAP_FIXED safely |
| 784 |
The only safe use for |
| 785 |
.B MAP_FIXED |
| 786 |
is where the address range specified by |
| 787 |
.I addr |
| 788 |
and |
| 789 |
.I length |
| 790 |
was previously reserved using another mapping; |
| 791 |
otherwise, the use of |
| 792 |
.B MAP_FIXED |
| 793 |
is hazardous because it forcibly removes preexisting mappings, |
| 794 |
making it easy for a multithreaded process to corrupt its own address space. |
| 795 |
.P |
| 796 |
For example, suppose that thread A looks through |
| 797 |
.IR /proc/ pid /maps |
| 798 |
in order to locate an unused address range that it can map using |
| 799 |
.BR MAP_FIXED , |
| 800 |
while thread B simultaneously acquires part or all of that same |
| 801 |
address range. |
| 802 |
When thread A subsequently employs |
| 803 |
.BR mmap(MAP_FIXED) , |
| 804 |
it will effectively clobber the mapping that thread B created. |
| 805 |
In this scenario, |
| 806 |
thread B need not create a mapping directly; |
| 807 |
simply making a library call that, |
| 808 |
internally, |
| 809 |
uses |
| 810 |
.BR dlopen (3) |
| 811 |
to load some other shared library, will suffice. |
| 812 |
The |
| 813 |
.BR dlopen (3) |
| 814 |
call will map the library into the process's address space. |
| 815 |
Furthermore, almost any library call may be implemented in a way that |
| 816 |
adds memory mappings to the address space, either with this technique, |
| 817 |
or by simply allocating memory. |
| 818 |
Examples include |
| 819 |
.BR brk (2), |
| 820 |
.BR malloc (3), |
| 821 |
.BR pthread_create (3), |
| 822 |
and the PAM libraries |
| 823 |
.UR http:\://www.linux-pam.org |
| 824 |
.UE . |
| 825 |
.P |
| 826 |
Since Linux 4.17, a multithreaded program can use the |
| 827 |
.B MAP_FIXED_NOREPLACE |
| 828 |
flag to avoid the hazard described above |
| 829 |
when attempting to create a mapping at a fixed address |
| 830 |
that has not been reserved by a preexisting mapping. |
| 831 |
.\" |
| 832 |
.SS Timestamps changes for file-backed mappings |
| 833 |
For file-backed mappings, the |
| 834 |
.I st_atime |
| 835 |
field for the mapped file may be updated at any time between the |
| 836 |
.BR mmap () |
| 837 |
and the corresponding unmapping; |
| 838 |
the first reference to a mapped page |
| 839 |
will update the field if it has not been already. |
| 840 |
.P |
| 841 |
The |
| 842 |
.I st_ctime |
| 843 |
and |
| 844 |
.I st_mtime |
| 845 |
field for a file mapped with |
| 846 |
.B PROT_WRITE |
| 847 |
and |
| 848 |
.B MAP_SHARED |
| 849 |
will be updated after |
| 850 |
a write to the mapped region, and before a subsequent |
| 851 |
.BR msync (2) |
| 852 |
with the |
| 853 |
.B MS_SYNC |
| 854 |
or |
| 855 |
.B MS_ASYNC |
| 856 |
flag, if one occurs. |
| 857 |
.\" |
| 858 |
.SS Huge page (Huge TLB) mappings |
| 859 |
For mappings that employ huge pages, the requirements for the arguments of |
| 860 |
.BR mmap () |
| 861 |
and |
| 862 |
.BR munmap () |
| 863 |
differ somewhat from the requirements for mappings |
| 864 |
that use the native system page size. |
| 865 |
.P |
| 866 |
For |
| 867 |
.BR mmap (), |
| 868 |
.I offset |
| 869 |
must be a multiple of the underlying huge page size. |
| 870 |
The system automatically aligns |
| 871 |
.I length |
| 872 |
to be a multiple of the underlying huge page size. |
| 873 |
.P |
| 874 |
For |
| 875 |
.BR munmap (), |
| 876 |
.IR addr , |
| 877 |
and |
| 878 |
.I length |
| 879 |
must both be a multiple of the underlying huge page size. |
| 880 |
.\" |
| 881 |
.SH CAVEATS |
| 882 |
Unlike typical |
| 883 |
.BR malloc (3) |
| 884 |
implementations, |
| 885 |
.BR mmap () |
| 886 |
does not prevent creating objects larger than |
| 887 |
.BR PTRDIFF_MAX . |
| 888 |
Objects that are larger than |
| 889 |
.B PTRDIFF_MAX |
| 890 |
only work in limited ways in C |
| 891 |
(in particular, |
| 892 |
pointer subtraction results in undefined behavior |
| 893 |
if the result would be bigger than |
| 894 |
.BR PTRDIFF_MAX ). |
| 895 |
On top of that, |
| 896 |
GCC also assumes that no object is bigger than |
| 897 |
.BR PTRDIFF_MAX . |
| 898 |
.B PTRDIFF_MAX |
| 899 |
is usually half of the address space size; |
| 900 |
so for 32-bit processes, |
| 901 |
it is usually |
| 902 |
.B 0x7fffffff |
| 903 |
(almost 2 GiB). |
| 904 |
.\" |
| 905 |
.SH BUGS |
| 906 |
On Linux, there are no guarantees like those suggested above under |
| 907 |
.BR MAP_NORESERVE . |
| 908 |
By default, any process can be killed |
| 909 |
at any moment when the system runs out of memory. |
| 910 |
.P |
| 911 |
Before Linux 2.6.7, the |
| 912 |
.B MAP_POPULATE |
| 913 |
flag has effect only if |
| 914 |
.I prot |
| 915 |
is specified as |
| 916 |
.BR PROT_NONE . |
| 917 |
.P |
| 918 |
SUSv3 specifies that |
| 919 |
.BR mmap () |
| 920 |
should fail if |
| 921 |
.I length |
| 922 |
is 0. |
| 923 |
However, before Linux 2.6.12, |
| 924 |
.BR mmap () |
| 925 |
succeeded in this case: no mapping was created and the call returned |
| 926 |
.IR addr . |
| 927 |
Since Linux 2.6.12, |
| 928 |
.BR mmap () |
| 929 |
fails with the error |
| 930 |
.B EINVAL |
| 931 |
for this case. |
| 932 |
.P |
| 933 |
POSIX specifies that the system shall always |
| 934 |
zero fill any partial page at the end |
| 935 |
of the object and that system will never write any modification of the |
| 936 |
object beyond its end. |
| 937 |
On Linux, when you write data to such partial page after the end |
| 938 |
of the object, the data stays in the page cache even after the file |
| 939 |
is closed and unmapped |
| 940 |
and even though the data is never written to the file itself, |
| 941 |
subsequent mappings may see the modified content. |
| 942 |
In some cases, this could be fixed by calling |
| 943 |
.BR msync (2) |
| 944 |
before the unmap takes place; |
| 945 |
however, this doesn't work on |
| 946 |
.BR tmpfs (5) |
| 947 |
(for example, when using the POSIX shared memory interface documented in |
| 948 |
.BR shm_overview (7)). |
| 949 |
.SH EXAMPLES |
| 950 |
.\" FIXME . Add an example here that uses an anonymous shared region for |
| 951 |
.\" IPC between parent and child. |
| 952 |
The following program prints part of the file specified in |
| 953 |
its first command-line argument to standard output. |
| 954 |
The range of bytes to be printed is specified via offset and length |
| 955 |
values in the second and third command-line arguments. |
| 956 |
The program creates a memory mapping of the required |
| 957 |
pages of the file and then uses |
| 958 |
.BR write (2) |
| 959 |
to output the desired bytes. |
| 960 |
.SS Program source |
| 961 |
.\" SRC BEGIN (mmap.c) |
| 962 |
.EX |
| 963 |
#include <err.h> |
| 964 |
#include <fcntl.h> |
| 965 |
#include <stdio.h> |
| 966 |
#include <stdlib.h> |
| 967 |
#include <sys/mman.h> |
| 968 |
#include <sys/stat.h> |
| 969 |
#include <sys/types.h> |
| 970 |
#include <unistd.h> |
| 971 |
\& |
| 972 |
int |
| 973 |
main(int argc, char *argv[]) |
| 974 |
{ |
| 975 |
int fd; |
| 976 |
char *addr; |
| 977 |
off_t offset, pa_offset; |
| 978 |
size_t length; |
| 979 |
ssize_t s; |
| 980 |
struct stat sb; |
| 981 |
\& |
| 982 |
if (argc < 3 || argc > 4) { |
| 983 |
fprintf(stderr, "%s file offset [length]\[rs]n", argv[0]); |
| 984 |
exit(EXIT_FAILURE); |
| 985 |
} |
| 986 |
\& |
| 987 |
fd = open(argv[1], O_RDONLY); |
| 988 |
if (fd == \-1) |
| 989 |
err(EXIT_FAILURE, "open"); |
| 990 |
\& |
| 991 |
if (fstat(fd, &sb) == \-1) /* To obtain file size */ |
| 992 |
err(EXIT_FAILURE, "fstat"); |
| 993 |
\& |
| 994 |
offset = atoi(argv[2]); |
| 995 |
pa_offset = offset & \[ti](sysconf(_SC_PAGE_SIZE) \- 1); |
| 996 |
/* offset for mmap() must be page aligned */ |
| 997 |
\& |
| 998 |
if (offset >= sb.st_size) { |
| 999 |
fprintf(stderr, "offset is past end of file\[rs]n"); |
| 1000 |
exit(EXIT_FAILURE); |
| 1001 |
} |
| 1002 |
\& |
| 1003 |
if (argc == 4) { |
| 1004 |
length = atoi(argv[3]); |
| 1005 |
if (offset + length > sb.st_size) |
| 1006 |
length = sb.st_size \- offset; |
| 1007 |
/* Can\[aq]t display bytes past end of file */ |
| 1008 |
\& |
| 1009 |
} else { /* No length arg ==> display to end of file */ |
| 1010 |
length = sb.st_size \- offset; |
| 1011 |
} |
| 1012 |
\& |
| 1013 |
addr = mmap(NULL, length + offset \- pa_offset, PROT_READ, |
| 1014 |
MAP_PRIVATE, fd, pa_offset); |
| 1015 |
if (addr == MAP_FAILED) |
| 1016 |
err(EXIT_FAILURE, "mmap"); |
| 1017 |
\& |
| 1018 |
s = write(STDOUT_FILENO, addr + offset \- pa_offset, length); |
| 1019 |
if (s != length) { |
| 1020 |
if (s == \-1) |
| 1021 |
err(EXIT_FAILURE, "write"); |
| 1022 |
\& |
| 1023 |
fprintf(stderr, "partial write"); |
| 1024 |
exit(EXIT_FAILURE); |
| 1025 |
} |
| 1026 |
\& |
| 1027 |
munmap(addr, length + offset \- pa_offset); |
| 1028 |
close(fd); |
| 1029 |
\& |
| 1030 |
exit(EXIT_SUCCESS); |
| 1031 |
} |
| 1032 |
.EE |
| 1033 |
.\" SRC END |
| 1034 |
.SH SEE ALSO |
| 1035 |
.BR ftruncate (2), |
| 1036 |
.BR getpagesize (2), |
| 1037 |
.BR memfd_create (2), |
| 1038 |
.BR mincore (2), |
| 1039 |
.BR mlock (2), |
| 1040 |
.BR mmap2 (2), |
| 1041 |
.BR mprotect (2), |
| 1042 |
.BR mremap (2), |
| 1043 |
.BR msync (2), |
| 1044 |
.BR remap_file_pages (2), |
| 1045 |
.BR setrlimit (2), |
| 1046 |
.BR shmat (2), |
| 1047 |
.BR userfaultfd (2), |
| 1048 |
.BR shm_open (3), |
| 1049 |
.BR shm_overview (7) |
| 1050 |
.P |
| 1051 |
The descriptions of the following files in |
| 1052 |
.BR proc (5): |
| 1053 |
.IR /proc/ pid /maps , |
| 1054 |
.IR /proc/ pid /map_files , |
| 1055 |
and |
| 1056 |
.IR /proc/ pid /smaps . |
| 1057 |
.P |
| 1058 |
B.O.\& Gallmeister, POSIX.4, O'Reilly, pp.\& 128\[en]129 and 389\[en]391. |
| 1059 |
.\" |
| 1060 |
.\" Repeat after me: private read-only mappings are 100% equivalent to |
| 1061 |
.\" shared read-only mappings. No ifs, buts, or maybes. -- Linus |