diff options
Diffstat (limited to 'man2/mmap.2')
| -rw-r--r-- | man2/mmap.2 | 1037 |
1 files changed, 0 insertions, 1037 deletions
diff --git a/man2/mmap.2 b/man2/mmap.2 deleted file mode 100644 index 63df5a98a..000000000 --- a/man2/mmap.2 +++ /dev/null @@ -1,1037 +0,0 @@ -'\" t -.\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl> -.\" and Copyright (C) 2006, 2007 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> -.\" Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com> -.\" Modified 2001-10-04 by John Levon <moz@compsoc.man.ac.uk> -.\" Modified 2003-02-02 by Andi Kleen <ak@muc.de> -.\" Modified 2003-05-21 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" MAP_LOCKED works from Linux 2.5.37 -.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" Modified 2004-09-11 by aeb -.\" Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr> -.\" Modified 2004-12-08, mtk, formatting tidy-ups -.\" Modified 2006-12-04, mtk, various parts rewritten -.\" 2007-07-10, mtk, Added an example program. -.\" 2008-11-18, mtk, document MAP_STACK -.\" -.TH mmap 2 (date) "Linux man-pages (unreleased)" -.SH NAME -mmap, munmap \- map or unmap files or devices into memory -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/mman.h> -.P -.BI "void *mmap(void " addr [. length "], size_t " length \ -", int " prot ", int " flags , -.BI " int " fd ", off_t " offset ); -.BI "int munmap(void " addr [. length "], size_t " length ); -.fi -.P -See NOTES for information on feature test macro requirements. -.SH DESCRIPTION -.BR mmap () -creates a new mapping in the virtual address space of -the calling process. -The starting address for the new mapping is specified in -.IR addr . -The -.I length -argument specifies the length of the mapping (which must be greater than 0). -.P -If -.I addr -is NULL, -then the kernel chooses the (page-aligned) address -at which to create the mapping; -this is the most portable method of creating a new mapping. -If -.I addr -is not NULL, -then the kernel takes it as a hint about where to place the mapping; -on Linux, the kernel will pick a nearby page boundary (but always above -or equal to the value specified by -.IR /proc/sys/vm/mmap_min_addr ) -and attempt to create the mapping there. -If another mapping already exists there, the kernel picks a new address that -may or may not depend on the hint. -.\" Before Linux 2.6.24, the address was rounded up to the next page -.\" boundary; since Linux 2.6.24, it is rounded down! -The address of the new mapping is returned as the result of the call. -.P -The contents of a file mapping (as opposed to an anonymous mapping; see -.B MAP_ANONYMOUS -below), are initialized using -.I length -bytes starting at offset -.I offset -in the file (or other object) referred to by the file descriptor -.IR fd . -.I offset -must be a multiple of the page size as returned by -.IR sysconf(_SC_PAGE_SIZE) . -.P -After the -.BR mmap () -call has returned, the file descriptor, -.IR fd , -can be closed immediately without invalidating the mapping. -.P -The -.I prot -argument describes the desired memory protection of the mapping -(and must not conflict with the open mode of the file). -It is either -.B PROT_NONE -or the bitwise OR of one or more of the following flags: -.TP 1.1i -.B PROT_EXEC -Pages may be executed. -.TP -.B PROT_READ -Pages may be read. -.TP -.B PROT_WRITE -Pages may be written. -.TP -.B PROT_NONE -Pages may not be accessed. -.\" -.SS The flags argument -The -.I flags -argument determines whether updates to the mapping -are visible to other processes mapping the same region, -and whether updates are carried through to the underlying file. -This behavior is determined by including exactly one -of the following values in -.IR flags : -.TP -.B MAP_SHARED -Share this mapping. -Updates to the mapping are visible to other processes mapping the same region, -and (in the case of file-backed mappings) -are carried through to the underlying file. -(To precisely control when updates are carried through -to the underlying file requires the use of -.BR msync (2).) -.TP -.BR MAP_SHARED_VALIDATE " (since Linux 4.15)" -This flag provides the same behavior as -.B MAP_SHARED -except that -.B MAP_SHARED -mappings ignore unknown flags in -.IR flags . -By contrast, when creating a mapping using -.BR MAP_SHARED_VALIDATE , -the kernel verifies all passed flags are known and fails the -mapping with the error -.B EOPNOTSUPP -for unknown flags. -This mapping type is also required to be able to use some mapping flags -(e.g., -.BR MAP_SYNC ). -.TP -.B MAP_PRIVATE -Create a private copy-on-write mapping. -Updates to the mapping are not visible to other processes -mapping the same file, and are not carried through to -the underlying file. -It is unspecified whether changes made to the file after the -.BR mmap () -call are visible in the mapped region. -.P -Both -.B MAP_SHARED -and -.B MAP_PRIVATE -are described in POSIX.1-2001 and POSIX.1-2008. -.B MAP_SHARED_VALIDATE -is a Linux extension. -.P -In addition, zero or more of the following values can be ORed in -.IR flags : -.TP -.BR MAP_32BIT " (since Linux 2.4.20, 2.6)" -Put the mapping into the first 2 Gigabytes of the process address space. -This flag is supported only on x86-64, for 64-bit programs. -It was added to allow thread stacks to be allocated somewhere -in the first 2\ GB of memory, -so as to improve context-switch performance on some early -64-bit processors. -.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 -Modern x86-64 processors no longer have this performance problem, -so use of this flag is not required on those systems. -The -.B MAP_32BIT -flag is ignored when -.B MAP_FIXED -is set. -.TP -.B MAP_ANON -Synonym for -.BR MAP_ANONYMOUS ; -provided for compatibility with other implementations. -.TP -.B MAP_ANONYMOUS -The mapping is not backed by any file; -its contents are initialized to zero. -The -.I fd -argument is ignored; -however, some implementations require -.I fd -to be \-1 if -.B MAP_ANONYMOUS -(or -.BR MAP_ANON ) -is specified, -and portable applications should ensure this. -The -.I offset -argument should be zero. -.\" See the pgoff overflow check in do_mmap(). -.\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c. -Support for -.B MAP_ANONYMOUS -in conjunction with -.B MAP_SHARED -was added in Linux 2.4. -.TP -.B MAP_DENYWRITE -This flag is ignored. -.\" Introduced in 1.1.36, removed in 1.3.24. -(Long ago\[em]Linux 2.0 and earlier\[em]it signaled -that attempts to write to the underlying file should fail with -.BR ETXTBSY . -But this was a source of denial-of-service attacks.) -.TP -.B MAP_EXECUTABLE -This flag is ignored. -.\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. -.\" (Long ago, it signaled that the underlying file is an executable. -.\" However, that information was not really used anywhere.) -.\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of -.\" MAP_DENYWRITE? -.TP -.B MAP_FILE -Compatibility flag. -Ignored. -.\" On some systems, this was required as the opposite of -.\" MAP_ANONYMOUS -- mtk, 1 May 2007 -.TP -.B MAP_FIXED -Don't interpret -.I addr -as a hint: place the mapping at exactly that address. -.I addr -must be suitably aligned: for most architectures a multiple of the page -size is sufficient; however, some architectures may impose additional -restrictions. -If the memory region specified by -.I addr -and -.I length -overlaps pages of any existing mapping(s), then the overlapped -part of the existing mapping(s) will be discarded. -If the specified address cannot be used, -.BR mmap () -will fail. -.IP -Software that aspires to be portable should use the -.B MAP_FIXED -flag with care, -keeping in mind that the exact layout of a process's memory mappings -is allowed to change significantly between Linux versions, -C library versions, and operating system releases. -.I Carefully read the discussion of this flag in NOTES! -.TP -.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" -.\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843 -This flag provides behavior that is similar to -.B MAP_FIXED -with respect to the -.I addr -enforcement, but differs in that -.B MAP_FIXED_NOREPLACE -never clobbers a preexisting mapped range. -If the requested range would collide with an existing mapping, -then this call fails with the error -.B EEXIST. -This flag can therefore be used as a way to atomically -(with respect to other threads) attempt to map an address range: -one thread will succeed; all others will report failure. -.IP -Note that older kernels which do not recognize the -.B MAP_FIXED_NOREPLACE -flag will typically (upon detecting a collision with a preexisting mapping) -fall back to a -.RB \[lq]non- MAP_FIXED \[rq] -type of behavior: -they will return an address that is different from the requested address. -Therefore, backward-compatible software -should check the returned address against the requested address. -.TP -.B MAP_GROWSDOWN -This flag is used for stacks. -It indicates to the kernel virtual memory system that the mapping -should extend downward in memory. -The return address is one page lower than the memory area that is -actually created in the process's virtual address space. -Touching an address in the "guard" page below the mapping will cause -the mapping to grow by a page. -This growth can be repeated until the mapping grows to within a -page of the high end of the next lower mapping, -at which point touching the "guard" page will result in a -.B SIGSEGV -signal. -.TP -.BR MAP_HUGETLB " (since Linux 2.6.32)" -Allocate the mapping using "huge" pages. -See the Linux kernel source file -.I Documentation/admin\-guide/mm/hugetlbpage.rst -for further information, as well as NOTES, below. -.TP -.B MAP_HUGE_2MB -.TQ -.BR MAP_HUGE_1GB " (since Linux 3.8)" -.\" See https://lwn.net/Articles/533499/ -Used in conjunction with -.B MAP_HUGETLB -to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) -on systems that support multiple hugetlb page sizes. -.IP -More generally, the desired huge page size can be configured by encoding -the base-2 logarithm of the desired page size in the six bits at the offset -.BR MAP_HUGE_SHIFT . -(A value of zero in this bit field provides the default huge page size; -the default huge page size can be discovered via the -.I Hugepagesize -field exposed by -.IR /proc/meminfo .) -Thus, the above two constants are defined as: -.IP -.in +4n -.EX -#define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT) -#define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT) -.EE -.in -.IP -The range of huge page sizes that are supported by the system -can be discovered by listing the subdirectories in -.IR /sys/kernel/mm/hugepages . -.TP -.BR MAP_LOCKED " (since Linux 2.5.37)" -Mark the mapped region to be locked in the same way as -.BR mlock (2). -This implementation will try to populate (prefault) the whole range but the -.BR mmap () -call doesn't fail with -.B ENOMEM -if this fails. -Therefore major faults might happen later on. -So the semantic is not as strong as -.BR mlock (2). -One should use -.BR mmap () -plus -.BR mlock (2) -when major faults are not acceptable after the initialization of the mapping. -The -.B MAP_LOCKED -flag is ignored in older kernels. -.\" If set, the mapped pages will not be swapped out. -.TP -.BR MAP_NONBLOCK " (since Linux 2.5.46)" -This flag is meaningful only in conjunction with -.BR MAP_POPULATE . -Don't perform read-ahead: -create page tables entries only for pages -that are already present in RAM. -Since Linux 2.6.23, -.\" commit 54cb8821de07f2ffcd28c380ce9b93d5784b40d7 -this flag causes -.B MAP_POPULATE -to do nothing. -One day, the combination of -.B MAP_POPULATE -and -.B MAP_NONBLOCK -may be reimplemented. -.TP -.B MAP_NORESERVE -Do not reserve swap space for this mapping. -When swap space is reserved, one has the guarantee -that it is possible to modify the mapping. -When swap space is not reserved one might get -.B SIGSEGV -upon a write -if no physical memory is available. -See also the discussion of the file -.I /proc/sys/vm/overcommit_memory -in -.BR proc (5). -Before Linux 2.6, this flag had effect only for -private writable mappings. -.TP -.BR MAP_POPULATE " (since Linux 2.5.46)" -Populate (prefault) page tables for a mapping. -For a file mapping, this causes read-ahead on the file. -This will help to reduce blocking on page faults later. -The -.BR mmap () -call doesn't fail if the mapping cannot be populated (for example, due -to limitations on the number of mapped huge pages when using -.BR MAP_HUGETLB ). -Support for -.B MAP_POPULATE -in conjunction with private mappings was added in Linux 2.6.23. -.TP -.BR MAP_STACK " (since Linux 2.6.27)" -Allocate the mapping at an address suitable for a process -or thread stack. -.IP -This flag is currently a no-op on Linux. -However, by employing this flag, applications can ensure that -they transparently obtain support if the flag -is implemented in the future. -Thus, it is used in the glibc threading implementation to allow for -the fact that some architectures may (later) require special treatment -for stack allocations. -.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 -.\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7 -.\" http://thread.gmane.org/gmane.linux.kernel/720412 -.\" "pthread_create() slow for many threads; also time to revisit 64b -.\" context switch optimization?" -A further reason to employ this flag is portability: -.B MAP_STACK -exists (and has an effect) on some other systems (e.g., some of the BSDs). -.TP -.BR MAP_SYNC " (since Linux 4.15)" -This flag is available only with the -.B MAP_SHARED_VALIDATE -mapping type; -mappings of type -.B MAP_SHARED -will silently ignore this flag. -This flag is supported only for files supporting DAX -(direct mapping of persistent memory). -For other files, creating a mapping with this flag results in an -.B EOPNOTSUPP -error. -.IP -Shared file mappings with this flag provide the guarantee that while -some memory is mapped writable in the address space of the process, -it will be visible in the same file at the same offset even after -the system crashes or is rebooted. -In conjunction with the use of appropriate CPU instructions, -this provides users of such mappings with a more efficient way -of making data modifications persistent. -.TP -.BR MAP_UNINITIALIZED " (since Linux 2.6.33)" -Don't clear anonymous pages. -This flag is intended to improve performance on embedded devices. -This flag is honored only if the kernel was configured with the -.B CONFIG_MMAP_ALLOW_UNINITIALIZED -option. -Because of the security implications, -that option is normally enabled only on embedded devices -(i.e., devices where one has complete control of the contents of user memory). -.P -Of the above flags, only -.B MAP_FIXED -is specified in POSIX.1-2001 and POSIX.1-2008. -However, most systems also support -.B MAP_ANONYMOUS -(or its synonym -.BR MAP_ANON ). -.\" FIXME . for later review when Issue 8 is one day released... -.\" POSIX may add MAP_ANON in the future -.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 -.\" http://austingroupbugs.net/view.php?id=850 -.SS munmap() -The -.BR munmap () -system call deletes the mappings for the specified address range, and -causes further references to addresses within the range to generate -invalid memory references. -The region is also automatically unmapped -when the process is terminated. -On the other hand, closing the file -descriptor does not unmap the region. -.P -The address -.I addr -must be a multiple of the page size (but -.I length -need not be). -All pages containing a part -of the indicated range are unmapped, and subsequent references -to these pages will generate -.BR SIGSEGV . -It is not an error if the -indicated range does not contain any mapped pages. -.SH RETURN VALUE -On success, -.BR mmap () -returns a pointer to the mapped area. -On error, the value -.B MAP_FAILED -(that is, -.IR "(void\ *)\ \-1" ) -is returned, and -.I errno -is set to indicate the error. -.P -On success, -.BR munmap () -returns 0. -On failure, it returns \-1, and -.I errno -is set to indicate the error (probably to -.BR EINVAL ). -.SH ERRORS -.TP -.B EACCES -A file descriptor refers to a non-regular file. -Or a file mapping was requested, but -.I fd -is not open for reading. -Or -.B MAP_SHARED -was requested and -.B PROT_WRITE -is set, but -.I fd -is not open in read/write -.RB ( O_RDWR ) -mode. -Or -.B PROT_WRITE -is set, but the file is append-only. -.TP -.B EAGAIN -The file has been locked, or too much memory has been locked (see -.BR setrlimit (2)). -.TP -.B EBADF -.I fd -is not a valid file descriptor (and -.B MAP_ANONYMOUS -was not set). -.TP -.B EEXIST -.B MAP_FIXED_NOREPLACE -was specified in -.IR flags , -and the range covered by -.I addr -and -.I length -clashes with an existing mapping. -.TP -.B EINVAL -We don't like -.IR addr , -.IR length , -or -.I offset -(e.g., they are too large, or not aligned on a page boundary). -.TP -.B EINVAL -(since Linux 2.6.12) -.I length -was 0. -.TP -.B EINVAL -.I flags -contained none of -.BR MAP_PRIVATE , -.BR MAP_SHARED , -or -.BR MAP_SHARED_VALIDATE . -.TP -.B ENFILE -.\" This is for shared anonymous segments -.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() -The system-wide limit on the total number of open files has been reached. -.\" .TP -.\" .B ENOEXEC -.\" A file could not be mapped for reading. -.TP -.B ENODEV -The underlying filesystem of the specified file does not support -memory mapping. -.TP -.B ENOMEM -No memory is available. -.TP -.B ENOMEM -The process's maximum number of mappings would have been exceeded. -This error can also occur for -.BR munmap (), -when unmapping a region in the middle of an existing mapping, -since this results in two smaller mappings on either side of -the region being unmapped. -.TP -.B ENOMEM -(since Linux 4.7) -The process's -.B RLIMIT_DATA -limit, described in -.BR getrlimit (2), -would have been exceeded. -.TP -.B ENOMEM -We don't like -.IR addr , -because it exceeds the virtual address space of the CPU. -.TP -.B EOVERFLOW -On 32-bit architecture together with the large file extension -(i.e., using 64-bit -.IR off_t ): -the number of pages used for -.I length -plus number of pages used for -.I offset -would overflow -.I "unsigned long" -(32 bits). -.TP -.B EPERM -The -.I prot -argument asks for -.B PROT_EXEC -but the mapped area belongs to a file on a filesystem that -was mounted no-exec. -.\" (Since Linux 2.4.25 / Linux 2.6.0.) -.TP -.B EPERM -The operation was prevented by a file seal; see -.BR fcntl (2). -.TP -.B EPERM -The -.B MAP_HUGETLB -flag was specified, but the caller was not privileged (did not have the -.B CAP_IPC_LOCK -capability) -and is not a member of the -.I sysctl_hugetlb_shm_group -group; see the description of -.I /proc/sys/vm/sysctl_hugetlb_shm_group -in -.BR proc_sys (5). -.TP -.B ETXTBSY -.B MAP_DENYWRITE -was set but the object specified by -.I fd -is open for writing. -.P -Use of a mapped region can result in these signals: -.TP -.B SIGSEGV -Attempted write into a region mapped as read-only. -.TP -.B SIGBUS -Attempted access to a page of the buffer that lies beyond the -end of the mapped file. -For an explanation of the treatment of the bytes in the page that -corresponds to the end of a mapped file that is not a multiple -of the page size, see NOTES. -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR mmap (), -.BR munmap () -T} Thread safety MT-Safe -.TE -.SH VERSIONS -On some hardware architectures (e.g., i386), -.B PROT_WRITE -implies -.BR PROT_READ . -It is architecture dependent whether -.B PROT_READ -implies -.B PROT_EXEC -or not. -Portable programs should always set -.B PROT_EXEC -if they intend to execute code in the new mapping. -.P -The portable way to create a mapping is to specify -.I addr -as 0 (NULL), and omit -.B MAP_FIXED -from -.IR flags . -In this case, the system chooses the address for the mapping; -the address is chosen so as not to conflict with any existing mapping, -and will not be 0. -If the -.B MAP_FIXED -flag is specified, and -.I addr -is 0 (NULL), then the mapped address will be 0 (NULL). -.P -Certain -.I flags -constants are defined only if suitable feature test macros are defined -(possibly by default): -.B _DEFAULT_SOURCE -with glibc 2.19 or later; -or -.B _BSD_SOURCE -or -.B _SVID_SOURCE -in glibc 2.19 and earlier. -(Employing -.B _GNU_SOURCE -also suffices, -and requiring that macro specifically would have been more logical, -since these flags are all Linux-specific.) -The relevant flags are: -.BR MAP_32BIT , -.B MAP_ANONYMOUS -(and the synonym -.BR MAP_ANON ), -.BR MAP_DENYWRITE , -.BR MAP_EXECUTABLE , -.BR MAP_FILE , -.BR MAP_GROWSDOWN , -.BR MAP_HUGETLB , -.BR MAP_LOCKED , -.BR MAP_NONBLOCK , -.BR MAP_NORESERVE , -.BR MAP_POPULATE , -and -.BR MAP_STACK . -.SS C library/kernel differences -This page describes the interface provided by the glibc -.BR mmap () -wrapper function. -Originally, this function invoked a system call of the same name. -Since Linux 2.4, that system call has been superseded by -.BR mmap2 (2), -and nowadays -.\" Since around glibc 2.1/2.2, depending on the platform. -the glibc -.BR mmap () -wrapper function invokes -.BR mmap2 (2) -with a suitably adjusted value for -.IR offset . -.SH STANDARDS -POSIX.1-2008. -.SH HISTORY -POSIX.1-2001, SVr4, 4.4BSD. -.\" SVr4 documents additional error codes ENXIO and ENODEV. -.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. -.P -On POSIX systems on which -.BR mmap (), -.BR msync (2), -and -.BR munmap () -are available, -.B _POSIX_MAPPED_FILES -is defined in \fI<unistd.h>\fP to a value greater than 0. -(See also -.BR sysconf (3).) -.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. -.\" -1: unavailable, 0: ask using sysconf(). -.\" glibc defines it to 1. -.SH NOTES -Memory mapped by -.BR mmap () -is preserved across -.BR fork (2), -with the same attributes. -.P -A file is mapped in multiples of the page size. -For a file that is not -a multiple of the page size, -the remaining bytes in the partial page at the end of the mapping -are zeroed when mapped, -and modifications to that region are not written out to the file. -The effect of -changing the size of the underlying file of a mapping on the pages that -correspond to added or removed regions of the file is unspecified. -.P -An application can determine which pages of a mapping are -currently resident in the buffer/page cache using -.BR mincore (2). -.\" -.SS Using MAP_FIXED safely -The only safe use for -.B MAP_FIXED -is where the address range specified by -.I addr -and -.I length -was previously reserved using another mapping; -otherwise, the use of -.B MAP_FIXED -is hazardous because it forcibly removes preexisting mappings, -making it easy for a multithreaded process to corrupt its own address space. -.P -For example, suppose that thread A looks through -.IR /proc/ pid /maps -in order to locate an unused address range that it can map using -.BR MAP_FIXED , -while thread B simultaneously acquires part or all of that same -address range. -When thread A subsequently employs -.BR mmap(MAP_FIXED) , -it will effectively clobber the mapping that thread B created. -In this scenario, -thread B need not create a mapping directly; simply making a library call -that, internally, uses -.BR dlopen (3) -to load some other shared library, will suffice. -The -.BR dlopen (3) -call will map the library into the process's address space. -Furthermore, almost any library call may be implemented in a way that -adds memory mappings to the address space, either with this technique, -or by simply allocating memory. -Examples include -.BR brk (2), -.BR malloc (3), -.BR pthread_create (3), -and the PAM libraries -.UR http://www.linux-pam.org -.UE . -.P -Since Linux 4.17, a multithreaded program can use the -.B MAP_FIXED_NOREPLACE -flag to avoid the hazard described above -when attempting to create a mapping at a fixed address -that has not been reserved by a preexisting mapping. -.\" -.SS Timestamps changes for file-backed mappings -For file-backed mappings, the -.I st_atime -field for the mapped file may be updated at any time between the -.BR mmap () -and the corresponding unmapping; the first reference to a mapped -page will update the field if it has not been already. -.P -The -.I st_ctime -and -.I st_mtime -field for a file mapped with -.B PROT_WRITE -and -.B MAP_SHARED -will be updated after -a write to the mapped region, and before a subsequent -.BR msync (2) -with the -.B MS_SYNC -or -.B MS_ASYNC -flag, if one occurs. -.\" -.SS Huge page (Huge TLB) mappings -For mappings that employ huge pages, the requirements for the arguments of -.BR mmap () -and -.BR munmap () -differ somewhat from the requirements for mappings -that use the native system page size. -.P -For -.BR mmap (), -.I offset -must be a multiple of the underlying huge page size. -The system automatically aligns -.I length -to be a multiple of the underlying huge page size. -.P -For -.BR munmap (), -.IR addr , -and -.I length -must both be a multiple of the underlying huge page size. -.\" -.SH BUGS -On Linux, there are no guarantees like those suggested above under -.BR MAP_NORESERVE . -By default, any process can be killed -at any moment when the system runs out of memory. -.P -Before Linux 2.6.7, the -.B MAP_POPULATE -flag has effect only if -.I prot -is specified as -.BR PROT_NONE . -.P -SUSv3 specifies that -.BR mmap () -should fail if -.I length -is 0. -However, before Linux 2.6.12, -.BR mmap () -succeeded in this case: no mapping was created and the call returned -.IR addr . -Since Linux 2.6.12, -.BR mmap () -fails with the error -.B EINVAL -for this case. -.P -POSIX specifies that the system shall always -zero fill any partial page at the end -of the object and that system will never write any modification of the -object beyond its end. -On Linux, when you write data to such partial page after the end -of the object, the data stays in the page cache even after the file -is closed and unmapped -and even though the data is never written to the file itself, -subsequent mappings may see the modified content. -In some cases, this could be fixed by calling -.BR msync (2) -before the unmap takes place; -however, this doesn't work on -.BR tmpfs (5) -(for example, when using the POSIX shared memory interface documented in -.BR shm_overview (7)). -.SH EXAMPLES -.\" FIXME . Add an example here that uses an anonymous shared region for -.\" IPC between parent and child. -The following program prints part of the file specified in -its first command-line argument to standard output. -The range of bytes to be printed is specified via offset and length -values in the second and third command-line arguments. -The program creates a memory mapping of the required -pages of the file and then uses -.BR write (2) -to output the desired bytes. -.SS Program source -.\" SRC BEGIN (mmap.c) -.EX -#include <fcntl.h> -#include <stdio.h> -#include <stdlib.h> -#include <sys/mman.h> -#include <sys/stat.h> -#include <unistd.h> -\& -#define handle_error(msg) \e - do { perror(msg); exit(EXIT_FAILURE); } while (0) -\& -int -main(int argc, char *argv[]) -{ - int fd; - char *addr; - off_t offset, pa_offset; - size_t length; - ssize_t s; - struct stat sb; -\& - if (argc < 3 || argc > 4) { - fprintf(stderr, "%s file offset [length]\en", argv[0]); - exit(EXIT_FAILURE); - } -\& - fd = open(argv[1], O_RDONLY); - if (fd == \-1) - handle_error("open"); -\& - if (fstat(fd, &sb) == \-1) /* To obtain file size */ - handle_error("fstat"); -\& - offset = atoi(argv[2]); - pa_offset = offset & \[ti](sysconf(_SC_PAGE_SIZE) \- 1); - /* offset for mmap() must be page aligned */ -\& - if (offset >= sb.st_size) { - fprintf(stderr, "offset is past end of file\en"); - exit(EXIT_FAILURE); - } -\& - if (argc == 4) { - length = atoi(argv[3]); - if (offset + length > sb.st_size) - length = sb.st_size \- offset; - /* Can\[aq]t display bytes past end of file */ -\& - } else { /* No length arg ==> display to end of file */ - length = sb.st_size \- offset; - } -\& - addr = mmap(NULL, length + offset \- pa_offset, PROT_READ, - MAP_PRIVATE, fd, pa_offset); - if (addr == MAP_FAILED) - handle_error("mmap"); -\& - s = write(STDOUT_FILENO, addr + offset \- pa_offset, length); - if (s != length) { - if (s == \-1) - handle_error("write"); -\& - fprintf(stderr, "partial write"); - exit(EXIT_FAILURE); - } -\& - munmap(addr, length + offset \- pa_offset); - close(fd); -\& - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR ftruncate (2), -.BR getpagesize (2), -.BR memfd_create (2), -.BR mincore (2), -.BR mlock (2), -.BR mmap2 (2), -.BR mprotect (2), -.BR mremap (2), -.BR msync (2), -.BR remap_file_pages (2), -.BR setrlimit (2), -.BR shmat (2), -.BR userfaultfd (2), -.BR shm_open (3), -.BR shm_overview (7) -.P -The descriptions of the following files in -.BR proc (5): -.IR /proc/ pid /maps , -.IR /proc/ pid /map_files , -and -.IR /proc/ pid /smaps . -.P -B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391. -.\" -.\" Repeat after me: private read-only mappings are 100% equivalent to -.\" shared read-only mappings. No ifs, buts, or maybes. -- Linus |