Expand description of MAP_POPULATE.

Expand description MAP_NONBLOCK.
Various minor formatting fixes.

man2/mmap.2

@@ -84,7 +84,8 @@ The
 .I flags
 parameter specifies the type of the mapped object, mapping options and
 whether modifications made to the mapped copy of the page are private to
-the process or are to be shared with other references.  It has bits
+the process or are to be shared with other references.  
+It has bits
 .TP 1.1i
 .B MAP_FIXED
 Do not select a different address than the one specified.
@@ -97,9 +98,12 @@ part of the existing mapping(s) will be discarded.
 If the specified address cannot be used,
 .BR mmap ()
 will fail.
-If MAP_FIXED is specified,
+If
+.B MAP_FIXED 
+is specified,
 .I start
-must be a multiple of the pagesize.  Use of this option is discouraged.
+must be a multiple of the page size.  
+Use of this option is discouraged.
 .TP
 .B MAP_SHARED
 Share this mapping with all other processes that map this object.
@@ -117,7 +121,10 @@ It is unspecified whether changes made to the file after the
 .BR mmap ()
 call are visible in the mapped region.
 .LP
-You must specify exactly one of MAP_SHARED and MAP_PRIVATE.
+You must specify exactly one of 
+.B MAP_SHARED 
+and 
+.BR MAP_PRIVATE .
 .LP
 The above three flags are described in POSIX.1b (formerly POSIX.4) and SUSv2.
 Linux also knows about the following non-standard flags:
@@ -126,7 +133,9 @@ Linux also knows about the following non-standard flags:
 This flag is ignored.
 .\" Introduced in 1.1.36, removed in 1.3.24.
 (Long ago, it signalled that attempts to write to the underlying file
-should fail with ETXTBUSY. But this was a source of denial-of-service attacks.)
+should fail with 
+.BR ETXTBUSY . 
+But this was a source of denial-of-service attacks.)
 .TP
 .B MAP_EXECUTABLE
 This flag is ignored.
@@ -165,11 +174,14 @@ The mapping is not backed by any file; the
 and
 .I offset
 arguments are ignored.  
-The use of this flag in conjunction with MAP_SHARED
+The use of this flag in conjunction with 
+.B MAP_SHARED
 is only supported on Linux since kernel 2.4.
 .TP
 .B MAP_ANON
-Alias for MAP_ANONYMOUS. Deprecated.
+Alias for 
+.BR MAP_ANONYMOUS . 
+Deprecated.
 .TP
 .B MAP_FILE
 Compatibility flag. Ignored.
@@ -177,26 +189,41 @@ Compatibility flag. Ignored.
 .B MAP_32BIT
 Put the mapping into the first 2GB of the process address space.
 Ignored when
-.I MAP_FIXED
-is set. This flag is currently only supported on x86-64 for 64bit programs.
+.B MAP_FIXED
+is set. 
+This flag is currently only supported on x86-64 for 64bit programs.
 .TP
 .BR MAP_POPULATE " (since Linux 2.5.46)"
-Populate (prefault) pagetables.
+Populate (prefault) page tables for a file mapping, 
+by performing read-ahead on the file.
+Later accesses to the mapping will not be bocked by page faults.
 .TP
 .BR MAP_NONBLOCK " (since Linux 2.5.46)"
-Do not block on I/O.
+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.
 .LP
 Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV,
 MAP_COPY, and MAP_LOCAL.
 .LP
 .I fd
-should be a valid file descriptor, unless MAP_ANONYMOUS is set.
-If MAP_ANONYMOUS is set, then 
+should be a valid file descriptor, unless 
+.B MAP_ANONYMOUS 
+is set.
+If 
+.B MAP_ANONYMOUS 
+is set, then 
 .I fd
 is ignored on Linux.
 However, some implementations require 
 .I fd
-to be \-1 if MAP_ANONYMOUS (or MAP_ANON) is specified,
+to be \-1 if 
+.B MAP_ANONYMOUS 
+(or 
+.BR MAP_ANON ) 
+is specified,
 and portable applications should ensure this.
 .LP
 .I offset
@@ -241,10 +268,18 @@ The
 .I st_ctime
 and
 .I st_mtime
-field for a file mapped with PROT_WRITE and MAP_SHARED will be updated after
+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 ()
-with the MS_SYNC or MS_ASYNC flag, if one occurs.
+with the 
+.B MS_SYNC 
+or 
+.BR MS_ASYNC 
+flag, if one occurs.
 .SH "RETURN VALUE"
 On success,
 .BR mmap ()
@@ -258,26 +293,35 @@ On success,
 .BR munmap ()
 returns 0, on failure \-1, and
 .I errno
-is set (probably to EINVAL).
+is set (probably to 
+.BR EINVAL ).
 .SH NOTES
 It is architecture dependent whether
-.I PROT_READ
+.B PROT_READ
 includes
-.I PROT_EXEC
+.B PROT_EXEC
 or not. Portable programs should always set
-.I PROT_EXEC
+.B PROT_EXEC
 if they intend to execute code in the new mapping.
 .SH ERRORS
 .TP
 .B EACCES
 A file descriptor refers to a non-regular file.
-Or MAP_PRIVATE was requested, but
+Or 
+.B MAP_PRIVATE 
+was requested, but
 .I fd
 is not open for reading.
-Or MAP_SHARED was requested and PROT_WRITE is set, but
+Or 
+.B MAP_SHARED 
+was requested and 
+.B PROT_WRITE 
+is set, but
 .I fd
 is not open in read/write (O_RDWR) mode.
-Or PROT_WRITE is set, but the file is append-only.
+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
@@ -285,7 +329,9 @@ The file has been locked, or too much memory has been locked (see
 .TP
 .B EBADF
 .I fd
-is not a valid file descriptor (and MAP_ANONYMOUS was not set).
+is not a valid file descriptor (and 
+.B MAP_ANONYMOUS
+was not set).
 .TP
 .B EINVAL
 We don't like
@@ -294,7 +340,7 @@ or
 .I length
 or
 .IR offset .
-(E.g., they are too large, or not aligned on a PAGESIZE boundary.)
+(E.g., they are too large, or not aligned on a page boundary.)
 .\" jbl - not sure this actually happens ? see generic_file_mmap
 .\" mtk: Before 2.6.12, a length of 0 was permitted: mmap() did 
 .\" not create mapping, but just returned 'start'; since 2.6.12, 
@@ -326,7 +372,8 @@ was mounted no-exec.
 .\" (Since 2.4.25 / 2.6.0.)
 .TP
 .B ETXTBSY
-MAP_DENYWRITE was set but the object specified by
+.B MAP_DENYWRITE 
+was set but the object specified by
 .I fd
 is open for writing.
 .LP