X-Git-Url: http://git.osdn.net/view?p=linuxjm%2FLDP_man-pages.git;a=blobdiff_plain;f=original%2Fman2%2Fmmap.2;h=dbda22b930f0abc469421dc4a4c1b9c8a2ebc91e;hp=fad8a5d2f6d2078c1922ed715d9d2d1c8f241110;hb=4ea6bb24817f6f049d6bbc90ecd77a869876f9b0;hpb=c03a7a882c608ebf399d1b044ce7a6daa922351a diff --git a/original/man2/mmap.2 b/original/man2/mmap.2 index fad8a5d2..dbda22b9 100644 --- a/original/man2/mmap.2 +++ b/original/man2/mmap.2 @@ -1,8 +1,7 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" .\" Copyright (C) 1996 Andries Brouwer .\" and Copyright (C) 2006, 2007 Michael Kerrisk .\" +.\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. @@ -22,6 +21,7 @@ .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END .\" .\" Modified 1997-01-31 by Eric S. Raymond .\" Modified 2000-03-25 by Jim Van Zandt @@ -37,7 +37,7 @@ .\" 2007-07-10, mtk, Added an example program. .\" 2008-11-18, mtk, document MAP_STACK .\" -.TH MMAP 2 2010-06-20 "Linux" "Linux Programmer's Manual" +.TH MMAP 2 2015-01-22 "Linux" "Linux Programmer's Manual" .SH NAME mmap, munmap \- map or unmap files or devices into memory .SH SYNOPSIS @@ -49,6 +49,8 @@ mmap, munmap \- map or unmap files or devices into memory .BI " int " fd ", off_t " offset ); .BI "int munmap(void *" addr ", size_t " length ); .fi + +See NOTES for information on feature test macro requirements. .SH DESCRIPTION .BR mmap () creates a new mapping in the virtual address space of @@ -140,7 +142,7 @@ In addition, zero or more of the following values can be ORed in .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 only supported on x86-64, for 64-bit programs. +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 2GB of memory, so as to improve context-switch performance on some early @@ -179,7 +181,7 @@ The use of .B MAP_ANONYMOUS in conjunction with .B MAP_SHARED -is only supported on Linux since kernel 2.4. +is supported on Linux only since kernel 2.4. .TP .B MAP_DENYWRITE This flag is ignored. @@ -228,7 +230,7 @@ should extend downward in memory. .TP .BR MAP_HUGETLB " (since Linux 2.6.32)" Allocate the mapping using "huge pages." -See the kernel source file +See the Linux kernel source file .I Documentation/vm/hugetlbpage.txt for further information. .TP @@ -242,7 +244,7 @@ This flag is ignored in older kernels. Only meaningful in conjunction with .BR MAP_POPULATE . Don't perform read-ahead: -only create page tables entries for pages +create page tables entries only for pages that are already present in RAM. Since Linux 2.6.23, this flag causes .BR MAP_POPULATE @@ -265,7 +267,7 @@ See also the discussion of the file .I /proc/sys/vm/overcommit_memory in .BR proc (5). -In kernels before 2.6, this flag only had effect for +In kernels before 2.6, this flag had effect only for private writable mappings. .TP .BR MAP_POPULATE " (since Linux 2.5.46)" @@ -273,7 +275,7 @@ Populate (prefault) page tables for a mapping. For a file mapping, this causes read-ahead on the file. Later accesses to the mapping will not be blocked by page faults. .BR MAP_POPULATE -is only supported for private mappings since Linux 2.6.23. +is supported for private mappings only since Linux 2.6.23. .TP .BR MAP_STACK " (since Linux 2.6.27)" Allocate the mapping at an address suitable for a process @@ -291,7 +293,7 @@ support can later be transparently implemented for glibc. .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 only honored if the kernel was configured with the +This flag is honored only if the kernel was configured with the .B CONFIG_MMAP_ALLOW_UNINITIALIZED option. Because of the security implications, @@ -370,7 +372,7 @@ with the or .B MS_ASYNC flag, if one occurs. -.SH "RETURN VALUE" +.SH RETURN VALUE On success, .BR mmap () returns a pointer to the mapped area. @@ -391,9 +393,7 @@ is set (probably to .TP .B EACCES A file descriptor refers to a non-regular file. -Or -.B MAP_PRIVATE -was requested, but +Or a file mapping was requested, but .I fd is not open for reading. Or @@ -449,7 +449,7 @@ The system limit on the total number of open files has been reached. .\" A file could not be mapped for reading. .TP .B ENODEV -The underlying file system of the specified file does not support +The underlying filesystem of the specified file does not support memory mapping. .TP .B ENOMEM @@ -461,15 +461,31 @@ The .I prot argument asks for .B PROT_EXEC -but the mapped area belongs to a file on a file system that +but the mapped area belongs to a file on a filesystem that was mounted no-exec. .\" (Since 2.4.25 / 2.6.0.) .TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP .B ETXTBSY .B MAP_DENYWRITE was set but the object specified by .I fd is open for writing. +.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). .LP Use of a mapped region can result in these signals: .TP @@ -480,14 +496,14 @@ Attempted write into a region mapped as read-only. Attempted access to a portion of the buffer that does not correspond to the file (for example, beyond the end of the file, including the case where another process has truncated the file). -.SH "CONFORMING TO" +.SH CONFORMING TO SVr4, 4.4BSD, POSIX.1-2001. .\" SVr4 documents additional error codes ENXIO and ENODEV. .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. .SH AVAILABILITY On POSIX systems on which .BR mmap (), -.BR msync (2) +.BR msync (2), and .BR munmap () are available, @@ -499,17 +515,6 @@ is defined in \fI\fP to a value greater than 0. .\" -1: unavailable, 0: ask using sysconf(). .\" glibc defines it to 1. .SH NOTES -Since kernel 2.4, this system call has been superseded by -.BR mmap2 (2). -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 . - On some hardware architectures (e.g., i386), .B PROT_WRITE implies @@ -537,6 +542,51 @@ If the flag is specified, and .I addr is 0 (NULL), then the mapped address will be 0 (NULL). + +Certain +.I flags +constants are defined only if either +.BR _BSD_SOURCE +or +.BR _SVID_SOURCE +is defined. +(Requiring +.BR _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 , +.BR 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 ABI 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 kernel 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 BUGS On Linux there are no guarantees like those suggested above under .BR MAP_NORESERVE . @@ -545,7 +595,7 @@ at any moment when the system runs out of memory. In kernels before 2.6.7, the .B MAP_POPULATE -flag only has effect if +flag has effect only if .I prot is specified as .BR PROT_NONE . @@ -564,6 +614,22 @@ Since kernel 2.6.12, fails with the error .B EINVAL for this case. + +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 tmpfs +(for example, when using POSIX shared memory interface documented in +.BR shm_overview (7)). .SH EXAMPLE .\" FIXME . Add an example here that uses an anonymous shared region for .\" IPC between parent and child. @@ -576,8 +642,8 @@ 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 .nf - #include #include #include @@ -646,8 +712,9 @@ main(int argc, char *argv[]) exit(EXIT_SUCCESS); } .fi -.SH "SEE ALSO" +.SH SEE ALSO .BR getpagesize (2), +.BR memfd_create (2), .BR mincore (2), .BR mlock (2), .BR mmap2 (2), @@ -659,8 +726,24 @@ main(int argc, char *argv[]) .BR shmat (2), .BR shm_open (3), .BR shm_overview (7) -.br + +The descriptions of the following files in +.BR proc (5): +.IR /proc/[pid]/maps , +.IR /proc/[pid]/map_files , +and +.IR /proc/[pid]/smaps . + B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391. .\" .\" Repeat after me: private read-only mappings are 100% equivalent to .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus +.SH COLOPHON +This page is part of release 3.79 of the Linux +.I man-pages +project. +A description of the project, +information about reporting bugs, +and the latest version of this page, +can be found at +\%http://www.kernel.org/doc/man\-pages/.