From d10b6e6964e63ef94252550512ce4b72a53db1f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <address@hidden>
Date: Mon, 11 Jan 2016 22:31:45 +0000
Subject: [PATCH] doc: suggest "sync" flag to maximize "nocache" effectiveness

doc/coreutils.texi (dd invocation): Add oflag=sync to the streaming
example.  Also reference the "direct" flag.  Mention this is only
a request to the system.
* src/dd.c (usage): Mention the "sync" flag along with "nocache".
Also mention that it's only a request to drop the cache.
* THANKS.in: Add reporter Francois Rigault.
---
 THANKS.in          |  1 +
 doc/coreutils.texi | 17 ++++++++++++-----
 src/dd.c           |  3 ++-
 3 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/THANKS.in b/THANKS.in
index 5c49006..4593f6c 100644
--- a/THANKS.in
+++ b/THANKS.in
@@ -207,6 +207,7 @@ Florian Schlichting                 address@hidden
 Florin Iucha                        address@hidden
 Francesco Montorsi                  address@hidden
 François Pinard                     address@hidden
+François Rigault                    address@hidden
 Frank Adler                         address@hidden
 Frank T Lofaro                      address@hidden
 Fred Fish                           address@hidden
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 2538062..b0d66e3 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8660,12 +8660,18 @@ Use synchronized I/O for both data and metadata.
 @item nocache
 @opindex nocache
 @cindex discarding file cache
-Discard the data cache for a file.
-When count=0 all cache is discarded,
+Request to discard the system data cache for a file.
+When count=0 all cached data for the file is specified,
 otherwise the cache is dropped for the processed
-portion of the file.  Also when count=0
+portion of the file.  Also when count=0,
 failure to discard the cache is diagnosed
 and reflected in the exit status.
+
+Note data that is not already persisted to storage will not
+be discarded from cache, so note the use of the ``sync'' options
+in the examples below, which are used to maximize the
+effectiveness of the @samp{nocache} flag.
+
 Here are some usage examples:
 
 @example
@@ -8678,8 +8684,9 @@ dd of=ofile oflag=nocache conv=notrunc,fdatasync count=0
 # Drop cache for part of file
 dd if=ifile iflag=nocache skip=10 count=10 of=/dev/null
 
-# Stream data using just the read-ahead cache
-dd if=ifile of=ofile iflag=nocache oflag=nocache
+# Stream data using just the read-ahead cache.
+# See also the @samp{direct} flag.
+dd if=ifile of=ofile iflag=nocache oflag=nocache,sync
 @end example
 
 @item nonblock
diff --git a/src/dd.c b/src/dd.c
index d5d01f3..440950a 100644
--- a/src/dd.c
+++ b/src/dd.c
@@ -632,7 +632,8 @@ Each FLAG symbol may be:\n\
         fputs (_("  noatime   do not update access time\n"), stdout);
 #if HAVE_POSIX_FADVISE
       if (O_NOCACHE)
-        fputs (_("  nocache   discard cached data\n"), stdout);
+        fputs (_("  nocache   Request to drop cache.  See also oflag=sync\n"),
+               stdout);
 #endif
       if (O_NOCTTY)
         fputs (_("  noctty    do not assign controlling terminal from file\n"),
-- 
2.5.0