diff --git a/man-pages-3.24-mmap64.patch b/man-pages-3.24-mmap64.patch new file mode 100644 index 0000000..e01e597 --- /dev/null +++ b/man-pages-3.24-mmap64.patch @@ -0,0 +1,6 @@ +diff -up man-pages-3.24/man3/mmap64.3.pom man-pages-3.24/man3/mmap64.3 +--- man-pages-3.24/man3/mmap64.3.pom 2010-02-26 05:46:32.000000000 +0100 ++++ man-pages-3.24/man3/mmap64.3 2010-06-04 08:35:13.000000000 +0200 +@@ -1 +1 @@ +-.so man2/mmap2.2 ++.so man2/mmap.2 diff --git a/man-pages.spec b/man-pages.spec index defe23e..5bae4e9 100644 --- a/man-pages.spec +++ b/man-pages.spec @@ -4,7 +4,7 @@ Summary: Man (manual) pages from the Linux Documentation Project Name: man-pages Version: 3.24 -Release: 5%{?dist} +Release: 6%{?dist} License: GPLv2+ and GPL+ and BSD and MIT and Copyright only and IEEE Group: Documentation URL: http://www.kernel.org/pub/linux/docs/manpages/ @@ -17,6 +17,7 @@ Source3: man-pages-extralocale.tar.bz2 Source4: man-pages_syscalls-03.tar.bz2 # IBM-supplied man pages for suid binaries: Source5: man-suid-bins.tar.bz2 +Source6: mmap.2 Patch1: man-pages-1.51-iconv.patch Patch28: man-pages-2.46-nscd.patch Patch36: man-pages-2.63-unimplemented.patch @@ -37,6 +38,7 @@ Patch63: man-pages-3.24-getnameinfo.patch Patch64: man-pages-3.24-atanh.patch Patch65: man-pages-3.24-sysconf.patch Patch66: man-pages-3.24-recv.patch +Patch67: man-pages-3.24-mmap64.patch Buildroot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) Autoreq: false @@ -51,6 +53,7 @@ Documentation Project (LDP). mv man-pages-posix-%{posix_version}-%{posix_release}/* ./ rmdir man-pages-posix-%{posix_version}-%{posix_release} +cp %{SOURCE6} man2/mmap.2 %patch1 -p1 %patch28 -p1 @@ -72,6 +75,7 @@ rmdir man-pages-posix-%{posix_version}-%{posix_release} %patch64 -p1 %patch65 -p1 %patch66 -p1 +%patch67 -p1 ### And now remove those we are not going to use: @@ -142,6 +146,10 @@ rm -rf $RPM_BUILD_ROOT %lang(en) %{_mandir}/en/man*/* %changelog +* Fri Jun 4 2010 Ivana Hutarova Varekova - 3.24-6 +- Resolves: #596666 + Man page for mmap64 is confusing + * Mon May 31 2010 Ivana Hutarova Varekova - 3.24-5 - Resolves: #597429 remove the duplicate info about error output (recv(2) man page) diff --git a/mmap.2 b/mmap.2 new file mode 100644 index 0000000..605a527 --- /dev/null +++ b/mmap.2 @@ -0,0 +1,675 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (C) 1996 Andries Brouwer +.\" and Copyright (C) 2006, 2007 Michael Kerrisk +.\" +.\" 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. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2000-03-25 by Jim Van Zandt +.\" Modified 2001-10-04 by John Levon +.\" Modified 2003-02-02 by Andi Kleen +.\" Modified 2003-05-21 by Michael Kerrisk +.\" MAP_LOCKED works from 2.5.37 +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2004-09-11 by aeb +.\" Modified 2004-12-08, from Eric Estievenart +.\" 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 2009-09-26 "Linux" "Linux Programmer's Manual" +.SH NAME +mmap, mmap64, munmap \- map or unmap files or devices into memory +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *mmap(void *" addr ", size_t " length \ +", int " prot ", int " flags , +.BI " int " fd ", off_t " offset ); +.BI "void *mmap64(void *" addr ", size_t " length \ +", int " prot ", int " flags , +.BI " int " fd ", off64_t " offset ); +.BI "int munmap(void *" addr ", size_t " length ); +.fi +.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. + +If +.I addr +is NULL, +then the kernel chooses the 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 mapping will be created at a nearby page boundary. +.\" Before Linux 2.6.24, the address was rounded up to the next page +.\" boundary; since 2.6.24, it is rounded down! +The address of the new mapping is returned as the result of the call. + +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) . +.LP +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. +.LP +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 1.1i +.B MAP_SHARED +Share this mapping. +Updates to the mapping are visible to other processes that map this file, +and are carried through to the underlying file. +The file may not actually be updated until +.BR msync (2) +or +.BR munmap () +is called. +.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. +.LP +Both of these flags are described in POSIX.1-2001. + +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 only supported 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 +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 . +Deprecated. +.TP +.B MAP_ANONYMOUS +The mapping is not backed by any file; +its contents are initialized to zero. +The +.I fd +and +.I offset +arguments are 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 use of +.B MAP_ANONYMOUS +in conjunction with +.B MAP_SHARED +is only supported on Linux since kernel 2.4. +.TP +.B MAP_DENYWRITE +This flag is ignored. +.\" Introduced in 1.1.36, removed in 1.3.24. +(Long ago, it signaled that attempts to write to the underlying file +should fail with +.BR ETXTBUSY . +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 a multiple of the page size. +If the memory region specified by +.I addr +and +.I len +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. +Because requiring a fixed address for a mapping is less portable, +the use of this option is discouraged. +.TP +.B MAP_GROWSDOWN +Used for stacks. +Indicates to the kernel virtual memory system that the mapping +should extend downwards in memory. +.TP +.BR MAP_HUGETLB " (since Linux 2.6.32)" +Allocate the mapping using "huge pages." +See the kernel source file +.I Documentation/vm/hugetlbpage.txt +for further information. +.TP +.BR MAP_LOCKED " (since Linux 2.5.37)" +Lock the pages of the mapped region into memory in the manner of +.BR mlock (2). +This 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)" +Only meaningful in conjunction with +.BR MAP_POPULATE . +Don't perform read-ahead: +only create page tables entries for pages +that are already present in RAM. +Since Linux 2.6.23, this flag causes +.BR MAP_POPULATE +to do nothing. +One day the combination of +.BR MAP_POPULATE +and +.BR 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). +In kernels before 2.6, this flag only had effect 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. +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. +.LP +Of the above flags, only +.B MAP_FIXED +is specified in POSIX.1-2001. +However, most systems also support +.B MAP_ANONYMOUS +(or its synonym +.BR MAP_ANON ). +.TP +.BR MAP_STACK " (since Linux 2.6.27)" +Allocate the mapping at an address suitable for a process +or thread stack. +This flag is currently a no-op, +but is used in the glibc threading implementation so that +if some architectures require special treatment for stack allocations, +support can later be transparently implemented for glibc. +.\" 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?" +.LP +Some systems document the additional flags +.BR MAP_AUTOGROW , +.BR MAP_AUTORESRV , +.BR MAP_COPY , +and +.BR MAP_LOCAL . +.LP +Memory mapped by +.BR mmap () +is preserved across +.BR fork (2), +with the same attributes. +.LP +A file is mapped in multiples of the page size. +For a file that is not +a multiple of the page size, the remaining memory is zeroed when mapped, +and writes 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. +.SS mmap64() +The +.BR mmap64 () +system call operates in exactly the same way as +.BR mmap (), +except that the final argument specifies the offset as +a 64-bit off64_t. This enables applications to aceess the large +files. +.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. +.LP +The address +.I addr +must be a multiple of the page size. +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. +.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. +.LP +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. +.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 appropriately. +On success, +.BR munmap () +returns 0, on failure \-1, and +.I errno +is set (probably to +.BR EINVAL ). +.SH ERRORS +.TP +.B EACCES +A file descriptor refers to a non-regular file. +Or +.B MAP_PRIVATE +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 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 neither +.B MAP_PRIVATE +or +.BR MAP_SHARED , +or contained both of these values. +.TP +.B ENFILE +.\" This is for shared anonymous segments +.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() +The system 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 file system of the specified file does not support +memory mapping. +.TP +.B ENOMEM +No memory is available, or the process's maximum number of mappings would +have been exceeded. +.TP +.B EPERM +The +.I prot +argument asks for +.B PROT_EXEC +but the mapped area belongs to a file on a file system that +was mounted no-exec. +.\" (Since 2.4.25 / 2.6.0.) +.TP +.B ETXTBSY +.B MAP_DENYWRITE +was set but the object specified by +.I fd +is open for writing. +.LP +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 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" +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) +and +.BR munmap () +are available, +.B _POSIX_MAPPED_FILES +is defined in \fI\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 +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 +.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. + +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). +.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. + +In kernels before 2.6.7, the +.B MAP_POPULATE +flag only has effect if +.I prot +is specified as +.BR PROT_NONE . + +SUSv3 specifies that +.BR mmap () +should fail if +.I length +is 0. +However, in kernels before 2.6.12, +.BR mmap () +succeeded in this case: no mapping was created and the call returned +.IR addr . +Since kernel 2.6.12, +.BR mmap () +fails with the error +.B EINVAL +for this case. +.SH EXAMPLE +.\" FIXME . Add an example here that uses an anonymous shared region for +.\" IPC between parent and child. +.PP +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. +.nf + +#include +#include +#include +#include +#include +#include + +#define handle_error(msg) \\ + do { perror(msg); exit(EXIT_FAILURE); } while (0) + +int +main(int argc, char *argv[]) +{ + char *addr; + int fd; + struct stat sb; + off_t offset, pa_offset; + size_t length; + ssize_t s; + + if (argc < 3 || argc > 4) { + fprintf(stderr, "%s file offset [length]\\n", 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 & ~(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\\n"); + exit(EXIT_FAILURE); + } + + if (argc == 4) { + length = atoi(argv[3]); + if (offset + length > sb.st_size) + length = sb.st_size \- offset; + /* Can\(aqt 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); + } + + exit(EXIT_SUCCESS); +} /* main */ +.fi +.SH "SEE ALSO" +.BR getpagesize (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 shm_open (3), +.BR shm_overview (7) +.br +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.24 of the Linux +.I man-pages +project. +A description of the project, +and information about reporting bugs, +can be found at +http://www.kernel.org/doc/man-pages/.