svn commit: r270771 - head/bin/dd

[Bruce Evans]

On Thu, 28 Aug 2014, Warner Losh wrote:

> Author: imp
> Date: Thu Aug 28 21:30:39 2014
> New Revision: 270771
> URL: http://svnweb.freebsd.org/changeset/base/270771
>
> Log:
>  Add canonical population of a disk / thumb drive from an image
>  example.
>
> Modified:
>  head/bin/dd/dd.1
>
> Modified: head/bin/dd/dd.1
> ==============================================================================
> --- head/bin/dd/dd.1	Thu Aug 28 21:27:37 2014	(r270770)
> +++ head/bin/dd/dd.1	Thu Aug 28 21:30:39 2014	(r270771)
> @@ -408,6 +408,11 @@ To create an image of a Mode-1 CD-ROM, w
> for data CD-ROM disks, use a block size of 2048 bytes:
> .Pp
> .Dl "dd if=/dev/acd0 of=filename.iso bs=2048"
> +.Pp
> +Write a filesystem image to a memory stick, padding the end with zeros,
> +if necessary, to a 1MiB boundary:
> +.Pp
> +.Dl "dd if=memstick.img of=/dev/da0 bs=1m conv=noerror,sync"
> .Sh SEE ALSO
> .Xr cp 1 ,
> .Xr mt 1 ,

dd.1 doesn't use the MiB uglyness anywhere else.  It even defines 1M
correctly:

      Where sizes are specified, a decimal, octal, or hexadecimal number of
      bytes is expected.  If the number ends with a ``b'', ``k'', ``m'', ``g'',
      or ``w'', the number is multiplied by 512, 1024 (1K), 1048576 (1M),
      1073741824 (1G) or the number of bytes in an integer, respectively.  Two
      or more numbers may be separated by an ``x'' to indicate a product.

dd also has the correct amount of support (none) for power of 10 sizes in
args.

However, it is not useful to use 1M in the description of ``m''.  It
basically describes ``m'' by saying that it is ``M''.  1048576 is
sufficient and not mistakable for 1000000.  The technical term 1M is
not used anywhere in the man page.  Similarly for 1K and 1G.

However2, dd also accepts upper case aliases for ``m'', etc.  These are
relatively recent bugs in FreeBSD.  They are too recent for news of them
to have reached the man page.  There aren't enough letters to use 2
aliases every power of 2 size, especially starting some years after the
MiB uglyness.

humanize_number(3) still have much the same bugs, except it supports
power of 10 sizes.  expand_number(3) is a little better.
humanize_number() doesn't humanize numbers.  It converts integers into
a string representation in a special dehumanized (scientific) format.
expand_number() doesn't expand numbers.  It parses string
representations of integers into object representations of integers.
This is rarely an expansion.  Normal English usage is that "12345"
is a decimal expansion of a number, not that the number is an expansion
of "12345".  The string representation is usually also larger in size.

expand_number() documents its wastage of 2 aliases for every power of
2 size and its null support for power of 10 sizes.  It doesn't
explicitly document its null support for suffixes like "MiB".  It still
describes the suffixes as prefixes.  They may be prefixes in some
technical SI sense, but they are always suffixes for the parser.
(Indeed, they are prefixes in the technical sense of being prefixes
for units.  expand_number() only "expands" raw numbers, so the units
are null.)  It doesn't document its support for hex and octal numbers.
dd does document this, if not the complete syntax.  expand_number()
has some extensions like support for 3 suffixes above g, but doesn't
support multpliers like dd.  Otherwise, it parses string representations
of numbers much like dd.

humanize_number() doesn't waste letters for suffixes.  It only prints
upper case suffixes, except k means 1000 and K means 1024 (it has no
support for floating point numbers so it doesn't need lower case
suffixes like m for milli).  It has an option to print power of 2
suffixes in the uglified Mi format.  It has an option to print a suffix
like "B", so that megabytes become "MB" or "MiB" or even

     "MB is the correct spelling of 104876 bytes; MiB is ugly, but not
     as ugly as mebiB; fortunately, this function cannot print mebi,
     since it only prints upper suffixes except for k."

This explains some of the confusing uses of "prefix".  First the digits
representing the number are put in the string.  Then an SI suffix is
appended if necessary.  Then a suffix like "B" is appended if requested.
So the SI suffixes may be in the middle.  expand_number() doesn't
support suffixes like "B".  Oops.  The suffix is documented as always
being printed, with a space between it and the rest, so "MB" is
impossible.  There is an HN_NOSPACE flag for suppressing the space
before the SI suffixes, but I don't see one for the final suffix.
Most callers are like df and space-constrained, so they use HN_NOSPACE
and don't print a "B" suffix.  I think they sometimes get the space
before the empty suffix at the end, and either use this as a separator
or do extra work to remove it.  There is also an HN_B flag which gives
a suffix in the SI position if the SI suffix is null.  Most disk
utilities use this, but only small files end up with a "B" suffix
from this.  When they do, the space before it is controlled by HN_NOSPACE.
Parsing "1 M B" and "1 M" would be harder than parsing "1MB" and "1M".
expand_number() supports the "B" suffix with no space before it, as will
occur for small numbers printed using HN_B | HN_NOSPACE, but news of this
has not reached its man page.  It has a large incompatibily with dd
here -- "b" and "B" mean 512 in dd.

Bruce