From: Pádraig Brady <P@draigBrady.com>
Date: Sat, 15 Dec 2012 03:15:38 +0000 (+0000)
Subject: doc: clarify when dd iflag=fullblock is useful
X-Git-Tag: v8.21~50
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f9bf96bfa7c282394792270c2ed6451b370a5bcd;p=thirdparty%2Fcoreutils.git

doc: clarify when dd iflag=fullblock is useful

* doc/coreutils.texi (dd invocation): Explain that iflag=fullblock
ensures that count= will count blocks rather than reads, and
reference that in both the count= and iflag=fullblock descriptions.
Suggested by John Reiser.
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 174a8c386a..bed3553643 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8117,6 +8117,11 @@ Copy @var{n} @samp{ibs}-byte blocks from the input file, instead
 of everything until the end of the file.
 if @samp{iflag=count_bytes} is specified, @var{n} is interpreted
 as a byte count rather than a block count.
+Note if the input may return short reads as could be the case
+when reading from a pipe for example, @samp{iflag=fullblock}
+will ensure that @samp{count=} corresponds to complete input blocks
+rather than the traditional POSIX specified behavior of counting
+input read operations.
 
 @item status=@var{which}
 @opindex status
@@ -8397,6 +8402,10 @@ may return early if a full block is not available.
 When that happens, continue calling @code{read} to fill the remainder
 of the block.
 This flag can be used only with @code{iflag}.
+This flag is useful with pipes for example
+as they may return short reads. In that case,
+this flag is needed to ensure that a @samp{count=} argument is
+interpreted as a block count rather than a count of read operations.
 
 @item count_bytes
 @opindex count_bytes