posix_fadvise.2: Reorganize some text

Details for various flags were hidden under NOTES.
Move them to DESCRIPTION, to make the details more
obvious.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2
index 981ca2886c9369457e0b7b2b2c05cb86f2967881..e741073ef8b62c85088f6f2f975e9c628dae7c32 100644 (file)
--- a/man2/posix_fadvise.2
+++ b/man2/posix_fadvise.2
@@ -78,12 +78,47 @@ The specified data will be accessed in random order.
 .TP
 .B POSIX_FADV_NOREUSE
 The specified data will be accessed only once.
+
+In kernels before 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the
+same semantics as \fBPOSIX_FADV_WILLNEED\fP.
+This was probably a bug; since kernel 2.6.18, this flag is a no-op.
 .TP
 .B POSIX_FADV_WILLNEED
 The specified data will be accessed in the near future.
+
+\fBPOSIX_FADV_WILLNEED\fP initiates a
+nonblocking read of the specified region into the page cache.
+The amount of data read may be decreased by the kernel depending
+on virtual memory load.
+(A few megabytes will usually be fully satisfied,
+and more is rarely useful.)
 .TP
 .B POSIX_FADV_DONTNEED
 The specified data will not be accessed in the near future.
+
+\fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with
+the specified region.
+This is useful, for example, while streaming large
+files.
+A program may periodically request the kernel to free cached data
+that has already been used, so that more useful cached pages are not
+discarded instead.
+
+Requests to discard partial pages are ignored.
+It is preferable to preserve needed data than discard unneeded data.
+If the application requires that data be considered for discarding, then
+.I offset
+and
+.I len
+must be page-aligned.
+
+Pages that have not yet been written out will be unaffected, so if the
+application wishes to guarantee that pages will be released, it should
+call
+.BR fsync (2)
+or
+.BR fdatasync (2)
+first.
 .SH RETURN VALUE
 On success, zero is returned.
 On error, an error number is returned.
@@ -134,41 +169,6 @@ default size for the backing device; \fBPOSIX_FADV_SEQUENTIAL\fP doubles
 this size, and \fBPOSIX_FADV_RANDOM\fP disables file readahead entirely.
 These changes affect the entire file, not just the specified region
 (but other open file handles to the same file are unaffected).
-
-\fBPOSIX_FADV_WILLNEED\fP initiates a
-nonblocking read of the specified region into the page cache.
-The amount of data read may be decreased by the kernel depending
-on virtual memory load.
-(A few megabytes will usually be fully satisfied,
-and more is rarely useful.)
-
-In kernels before 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the
-same semantics as \fBPOSIX_FADV_WILLNEED\fP.
-This was probably a bug; since kernel 2.6.18, this flag is a no-op.
-
-\fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with
-the specified region.
-This is useful, for example, while streaming large
-files.
-A program may periodically request the kernel to free cached data
-that has already been used, so that more useful cached pages are not
-discarded instead.
-
-Requests to discard partial pages are ignored.
-It is preferable to preserve needed data than discard unneeded data.
-If the application requires that data be considered for discarding, then
-.I offset
-and
-.I len
-must be page-aligned.
-
-Pages that have not yet been written out will be unaffected, so if the
-application wishes to guarantee that pages will be released, it should
-call
-.BR fsync (2)
-or
-.BR fdatasync (2)
-first.
 .SS C library/kernel differences
 The name of the wrapper function in the C library is
 .BR posix_fadvise ().