svn commit: r270771 - head/bin/dd

[Glen Barber]

On Fri, Aug 29, 2014 at 03:37:12PM +1000, Bruce Evans wrote:
> 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.
> 

This might be a bad time to mention it, but the .Dd wasn't bumped for
this change.

Glen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/svn-src-head/attachments/20140829/cfd89cc8/attachment.sig>