dd(1) wording and style

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

dd(1) wording and style

Jan Stary
This diff changes the dd(1) manpage in the following ways:

* Replace "It Cm if= Ns Ar file" with "It Cm if Ns = Ns Ar file"
  and similarly for others. The operand is "if", not "if=";
  the "Ns = Ns" might be a slightly excessive markup,
  but common: grep -Fr 'Ns = Ns' /usr/share/man | wc -l
  and is symmetric around the =

* Fix a factual error in the description of bs: it does not
  supersede ibs/obs, dd will error out when both are specified.
 
* "On non-tape devices ... Otherwise ..." is a convoluted way
  to say "tape"; describe tape first and remove the double negative.

* Say "It Cm status Ns = Ns Ar value" instead of

        .It Xo
        .Sm off
        .Cm status= Ar value
        .Sm on
        .Xc

* "Where every value" is not a beginning of a sentence.

* Tweak the wording of osync: regular-sized output block
  is enforced in every case, drop the "if not a multiple".

        Jan


Index: dd.1
===================================================================
RCS file: /cvs/src/bin/dd/dd.1,v
retrieving revision 1.35
diff -u -p -r1.35 dd.1
--- dd.1 16 Feb 2019 17:01:24 -0000 1.35
+++ dd.1 13 Feb 2020 21:45:56 -0000
@@ -57,11 +57,11 @@ and truncated input records to the stand
 .Pp
 The following operands are available:
 .Bl -tag -width of=file
-.It Cm if= Ns Ar file
+.It Cm if Ns = Ns Ar file
 Read input from
 .Ar file
 instead of the standard input.
-.It Cm of= Ns Ar file
+.It Cm of Ns = Ns Ar file
 Write output to
 .Ar file
 instead of the standard output.
@@ -72,22 +72,24 @@ If an initial portion of the output file
 .Cm seek
 operand),
 the output file is truncated at that point.
-.It Cm ibs= Ns Ar n
+.It Cm ibs Ns = Ns Ar n
 Set the input block size to
 .Ar n
 bytes instead of the default 512.
-.It Cm obs= Ns Ar n
+.It Cm obs Ns = Ns Ar n
 Set the output block size to
 .Ar n
 bytes instead of the default 512.
-.It Cm bs= Ns Ar n
+.It Cm bs Ns = Ns Ar n
 Set both the input and output block size to
 .Ar n
-bytes, superseding the
+bytes.
+It is an error to specify both
+.Cm bs
+and either of
 .Cm ibs
-and
-.Cm obs
-operands.
+or
+.Cm obs .
 If no conversion values other than
 .Cm noerror ,
 .Cm notrunc ,
@@ -95,36 +97,36 @@ or
 .Cm sync
 are specified, then each input block is copied to the output as a
 single block without any aggregation of short blocks.
-.It Cm cbs= Ns Ar n
+.It Cm cbs Ns = Ns Ar n
 Set the conversion record size to
 .Ar n
 bytes.
 The conversion record size is required by the record oriented conversion
 values.
-.It Cm count= Ns Ar n
+.It Cm count Ns = Ns Ar n
 Copy only
 .Ar n
 input blocks.
-.It Cm files= Ns Ar n
+.It Cm files Ns = Ns Ar n
 Copy
 .Ar n
 input files before terminating.
 This operand is only applicable when the input device is a tape.
-.It Cm seek= Ns Ar n
+.It Cm seek Ns = Ns Ar n
 Seek
 .Ar n
 blocks from the beginning of the output before copying.
-On non-tape devices, an
-.Xr lseek 2
-operation is used.
-Otherwise, existing blocks are read and the data discarded.
-If the user does not have read permission for the tape, it is positioned
-using the tape
+On a tape device, existing blocks are read and the data discarded;
+if the user does not have read permission for the tape,
+it is positioned using the tape
 .Xr ioctl 2
 function calls.
+On all other devices devices, an
+.Xr lseek 2
+operation is used.
 If the seek operation is past the end of file, space from the current
 end of file to the specified offset is filled with blocks of NUL bytes.
-.It Cm skip= Ns Ar n
+.It Cm skip Ns = Ns Ar n
 Skip
 .Ar n
 blocks from the beginning of the input before copying.
@@ -135,14 +137,10 @@ Otherwise, input data is read and discar
 For pipes, the correct number of bytes is read.
 For all other devices, the correct number of blocks is read without
 distinguishing between a partial or complete block being read.
-.It Xo
-.Sm off
-.Cm status= Ar value
-.Sm on
-.Xc
-Where
+.It Cm status Ns = Ns Ar value
+where
 .Ar value
-is one of the symbols from the following list.
+is one of following.
 .Bl -tag -width unblock
 .It Cm noxfer
 Do not print the transfer statistics as the last line of status output.
@@ -150,15 +148,10 @@ Do not print the transfer statistics as
 Do not print the status output.
 Error messages are shown; informational messages are not.
 .El
-.It Xo
-.Sm off
-.Cm conv= Ar value Oo ,
-.Sm on
-.Ar value ... Oc
-.Xc
-Where
+.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value , Ns ...
+where every
 .Ar value
-is one of the symbols from the following list.
+is one of the following.
 .Bl -tag -width unblock
 .It Cm ascii
 The same as the
@@ -235,13 +228,11 @@ The
 value is not supported for tapes.
 .It Cm osync
 Pad the final output block to the full output block size.
-If the input file is not a multiple of the output block size
-after conversion, this conversion forces the final output block
-to be the same size as preceding blocks for use on devices that require
+This forces the final output block to be the same size
+as preceding blocks for use on devices that require
 regularly sized blocks to be written.
-This option is incompatible with use of the
-.Cm bs= Ns Ar n
-block size specification.
+This option is incompatible with
+.Cm bs .
 .It Cm swab
 Swap every pair of input bytes.
 If an input buffer has an odd number of bytes, the last byte will be

Reply | Threaded
Open this post in threaded view
|

Re: dd(1) wording and style

Jan Stary
On Feb 13 23:25:07, [hidden email] wrote:

> This diff changes the dd(1) manpage in the following ways:
>
> * Replace "It Cm if= Ns Ar file" with "It Cm if Ns = Ns Ar file"
>   and similarly for others. The operand is "if", not "if=";
>   the "Ns = Ns" might be a slightly excessive markup,
>   but common: grep -Fr 'Ns = Ns' /usr/share/man | wc -l
>   and is symmetric around the =
>
> * Fix a factual error in the description of bs: it does not
>   supersede ibs/obs, dd will error out when both are specified.
>  
> * "On non-tape devices ... Otherwise ..." is a convoluted way
>   to say "tape"; describe tape first and remove the double negative.
>
> * Say "It Cm status Ns = Ns Ar value" instead of
>
> .It Xo
> .Sm off
> .Cm status= Ar value
> .Sm on
> .Xc
>
> * "Where every value" is not a beginning of a sentence.
>
> * Tweak the wording of osync: regular-sized output block
>   is enforced in every case, drop the "if not a multiple".
>
> Jan
>
>
> Index: dd.1
> ===================================================================
> RCS file: /cvs/src/bin/dd/dd.1,v
> retrieving revision 1.35
> diff -u -p -r1.35 dd.1
> --- dd.1 16 Feb 2019 17:01:24 -0000 1.35
> +++ dd.1 13 Feb 2020 21:45:56 -0000
> @@ -57,11 +57,11 @@ and truncated input records to the stand
>  .Pp
>  The following operands are available:
>  .Bl -tag -width of=file
> -.It Cm if= Ns Ar file
> +.It Cm if Ns = Ns Ar file
>  Read input from
>  .Ar file
>  instead of the standard input.
> -.It Cm of= Ns Ar file
> +.It Cm of Ns = Ns Ar file
>  Write output to
>  .Ar file
>  instead of the standard output.
> @@ -72,22 +72,24 @@ If an initial portion of the output file
>  .Cm seek
>  operand),
>  the output file is truncated at that point.
> -.It Cm ibs= Ns Ar n
> +.It Cm ibs Ns = Ns Ar n
>  Set the input block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm obs= Ns Ar n
> +.It Cm obs Ns = Ns Ar n
>  Set the output block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm bs= Ns Ar n
> +.It Cm bs Ns = Ns Ar n
>  Set both the input and output block size to
>  .Ar n
> -bytes, superseding the
> +bytes.
> +It is an error to specify both
> +.Cm bs
> +and either of
>  .Cm ibs
> -and
> -.Cm obs
> -operands.
> +or
> +.Cm obs .
>  If no conversion values other than
>  .Cm noerror ,
>  .Cm notrunc ,
> @@ -95,36 +97,36 @@ or
>  .Cm sync
>  are specified, then each input block is copied to the output as a
>  single block without any aggregation of short blocks.
> -.It Cm cbs= Ns Ar n
> +.It Cm cbs Ns = Ns Ar n
>  Set the conversion record size to
>  .Ar n
>  bytes.
>  The conversion record size is required by the record oriented conversion
>  values.
> -.It Cm count= Ns Ar n
> +.It Cm count Ns = Ns Ar n
>  Copy only
>  .Ar n
>  input blocks.
> -.It Cm files= Ns Ar n
> +.It Cm files Ns = Ns Ar n
>  Copy
>  .Ar n
>  input files before terminating.
>  This operand is only applicable when the input device is a tape.
> -.It Cm seek= Ns Ar n
> +.It Cm seek Ns = Ns Ar n
>  Seek
>  .Ar n
>  blocks from the beginning of the output before copying.
> -On non-tape devices, an
> -.Xr lseek 2
> -operation is used.
> -Otherwise, existing blocks are read and the data discarded.
> -If the user does not have read permission for the tape, it is positioned
> -using the tape
> +On a tape device, existing blocks are read and the data discarded;
> +if the user does not have read permission for the tape,
> +it is positioned using the tape
>  .Xr ioctl 2
>  function calls.
> +On all other devices devices, an

devices devices
sorry

> +.Xr lseek 2
> +operation is used.
>  If the seek operation is past the end of file, space from the current
>  end of file to the specified offset is filled with blocks of NUL bytes.
> -.It Cm skip= Ns Ar n
> +.It Cm skip Ns = Ns Ar n
>  Skip
>  .Ar n
>  blocks from the beginning of the input before copying.
> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
>  For pipes, the correct number of bytes is read.
>  For all other devices, the correct number of blocks is read without
>  distinguishing between a partial or complete block being read.
> -.It Xo
> -.Sm off
> -.Cm status= Ar value
> -.Sm on
> -.Xc
> -Where
> +.It Cm status Ns = Ns Ar value
> +where
>  .Ar value
> -is one of the symbols from the following list.
> +is one of following.
>  .Bl -tag -width unblock
>  .It Cm noxfer
>  Do not print the transfer statistics as the last line of status output.
> @@ -150,15 +148,10 @@ Do not print the transfer statistics as
>  Do not print the status output.
>  Error messages are shown; informational messages are not.
>  .El
> -.It Xo
> -.Sm off
> -.Cm conv= Ar value Oo ,
> -.Sm on
> -.Ar value ... Oc
> -.Xc
> -Where
> +.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value , Ns ...
> +where every
>  .Ar value
> -is one of the symbols from the following list.
> +is one of the following.
>  .Bl -tag -width unblock
>  .It Cm ascii
>  The same as the
> @@ -235,13 +228,11 @@ The
>  value is not supported for tapes.
>  .It Cm osync
>  Pad the final output block to the full output block size.
> -If the input file is not a multiple of the output block size
> -after conversion, this conversion forces the final output block
> -to be the same size as preceding blocks for use on devices that require
> +This forces the final output block to be the same size
> +as preceding blocks for use on devices that require
>  regularly sized blocks to be written.
> -This option is incompatible with use of the
> -.Cm bs= Ns Ar n
> -block size specification.
> +This option is incompatible with
> +.Cm bs .
>  .It Cm swab
>  Swap every pair of input bytes.
>  If an input buffer has an odd number of bytes, the last byte will be
>
>

Reply | Threaded
Open this post in threaded view
|

Re: dd(1) wording and style

Jason McIntyre-2
In reply to this post by Jan Stary
On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:
> This diff changes the dd(1) manpage in the following ways:
>

morning.

> * Replace "It Cm if= Ns Ar file" with "It Cm if Ns = Ns Ar file"
>   and similarly for others. The operand is "if", not "if=";
>   the "Ns = Ns" might be a slightly excessive markup,
>   but common: grep -Fr 'Ns = Ns' /usr/share/man | wc -l
>   and is symmetric around the =
>

yes, it is common. and preferred, i think.

> * Fix a factual error in the description of bs: it does not
>   supersede ibs/obs, dd will error out when both are specified.
>  

i don;t want to comment on this change

i'll make some comments inline though:

> * "On non-tape devices ... Otherwise ..." is a convoluted way
>   to say "tape"; describe tape first and remove the double negative.
>
> * Say "It Cm status Ns = Ns Ar value" instead of
>
> .It Xo
> .Sm off
> .Cm status= Ar value
> .Sm on
> .Xc
>
> * "Where every value" is not a beginning of a sentence.
>
> * Tweak the wording of osync: regular-sized output block
>   is enforced in every case, drop the "if not a multiple".
>
> Jan
>
>
> Index: dd.1
> ===================================================================
> RCS file: /cvs/src/bin/dd/dd.1,v
> retrieving revision 1.35
> diff -u -p -r1.35 dd.1
> --- dd.1 16 Feb 2019 17:01:24 -0000 1.35
> +++ dd.1 13 Feb 2020 21:45:56 -0000
> @@ -57,11 +57,11 @@ and truncated input records to the stand
>  .Pp
>  The following operands are available:
>  .Bl -tag -width of=file
> -.It Cm if= Ns Ar file
> +.It Cm if Ns = Ns Ar file
>  Read input from
>  .Ar file
>  instead of the standard input.
> -.It Cm of= Ns Ar file
> +.It Cm of Ns = Ns Ar file
>  Write output to
>  .Ar file
>  instead of the standard output.
> @@ -72,22 +72,24 @@ If an initial portion of the output file
>  .Cm seek
>  operand),
>  the output file is truncated at that point.
> -.It Cm ibs= Ns Ar n
> +.It Cm ibs Ns = Ns Ar n
>  Set the input block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm obs= Ns Ar n
> +.It Cm obs Ns = Ns Ar n
>  Set the output block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm bs= Ns Ar n
> +.It Cm bs Ns = Ns Ar n
>  Set both the input and output block size to
>  .Ar n
> -bytes, superseding the
> +bytes.
> +It is an error to specify both
> +.Cm bs
> +and either of
>  .Cm ibs
> -and
> -.Cm obs
> -operands.
> +or
> +.Cm obs .
>  If no conversion values other than
>  .Cm noerror ,
>  .Cm notrunc ,
> @@ -95,36 +97,36 @@ or
>  .Cm sync
>  are specified, then each input block is copied to the output as a
>  single block without any aggregation of short blocks.
> -.It Cm cbs= Ns Ar n
> +.It Cm cbs Ns = Ns Ar n
>  Set the conversion record size to
>  .Ar n
>  bytes.
>  The conversion record size is required by the record oriented conversion
>  values.
> -.It Cm count= Ns Ar n
> +.It Cm count Ns = Ns Ar n
>  Copy only
>  .Ar n
>  input blocks.
> -.It Cm files= Ns Ar n
> +.It Cm files Ns = Ns Ar n
>  Copy
>  .Ar n
>  input files before terminating.
>  This operand is only applicable when the input device is a tape.
> -.It Cm seek= Ns Ar n
> +.It Cm seek Ns = Ns Ar n
>  Seek
>  .Ar n
>  blocks from the beginning of the output before copying.
> -On non-tape devices, an
> -.Xr lseek 2
> -operation is used.
> -Otherwise, existing blocks are read and the data discarded.
> -If the user does not have read permission for the tape, it is positioned
> -using the tape
> +On a tape device, existing blocks are read and the data discarded;
> +if the user does not have read permission for the tape,
> +it is positioned using the tape
>  .Xr ioctl 2
>  function calls.
> +On all other devices devices, an
> +.Xr lseek 2
> +operation is used.

i think this change is ok. however i think non-tape is clearer than "on
all other devices". it's not a biggie, but i think the current stress on
non-tape devices is probably intentional.

>  If the seek operation is past the end of file, space from the current
>  end of file to the specified offset is filled with blocks of NUL bytes.
> -.It Cm skip= Ns Ar n
> +.It Cm skip Ns = Ns Ar n
>  Skip
>  .Ar n
>  blocks from the beginning of the input before copying.
> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
>  For pipes, the correct number of bytes is read.
>  For all other devices, the correct number of blocks is read without
>  distinguishing between a partial or complete block being read.
> -.It Xo
> -.Sm off
> -.Cm status= Ar value
> -.Sm on
> -.Xc
> -Where
> +.It Cm status Ns = Ns Ar value
> +where

you're correct that "Where" doesn;t really start a sentence, but this is
sentence start position. using a small letter is also incorrect.

in all honesty i would leave this, because it is not easy to rewrite in
a way that sounds natural. but maybe

        The
        .Ar value
        parameter is one of the symbols from the following list:

>  .Ar value
> -is one of the symbols from the following list.
> +is one of following.
>  .Bl -tag -width unblock
>  .It Cm noxfer
>  Do not print the transfer statistics as the last line of status output.
> @@ -150,15 +148,10 @@ Do not print the transfer statistics as
>  Do not print the status output.
>  Error messages are shown; informational messages are not.
>  .El
> -.It Xo
> -.Sm off
> -.Cm conv= Ar value Oo ,
> -.Sm on
> -.Ar value ... Oc
> -.Xc
> -Where
> +.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value , Ns ...
> +where every
>  .Ar value
> -is one of the symbols from the following list.
> +is one of the following.
>  .Bl -tag -width unblock
>  .It Cm ascii
>  The same as the
> @@ -235,13 +228,11 @@ The
>  value is not supported for tapes.
>  .It Cm osync
>  Pad the final output block to the full output block size.
> -If the input file is not a multiple of the output block size
> -after conversion, this conversion forces the final output block
> -to be the same size as preceding blocks for use on devices that require
> +This forces the final output block to be the same size
> +as preceding blocks for use on devices that require
>  regularly sized blocks to be written.
> -This option is incompatible with use of the
> -.Cm bs= Ns Ar n
> -block size specification.
> +This option is incompatible with
> +.Cm bs .

you might want to say "the bs blocksize specification", to avoid the
reader having to remember what bs is.

jmc

>  .It Cm swab
>  Swap every pair of input bytes.
>  If an input buffer has an odd number of bytes, the last byte will be
>

Reply | Threaded
Open this post in threaded view
|

Re: dd(1) wording and style

Ingo Schwarze
Hi,

Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +0000:
> On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:

>> * Fix a factual error in the description of bs: it does not
>>   supersede ibs/obs, dd will error out when both are specified.

> i don;t want to comment on this change

In fact, that's a bug in the code.  POSIX requires:

  bs=expr
    Set both input and output block sizes to expr bytes,
    superseding ibs= and obs=.

  (see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/dd.html )

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: dd(1) wording and style

Ingo Schwarze
In reply to this post by Jason McIntyre-2
Hi,

Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +0000:
> On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:

>> -.It Cm seek= Ns Ar n
>> +.It Cm seek Ns = Ns Ar n
>>  Seek
>>  .Ar n
>>  blocks from the beginning of the output before copying.
>> -On non-tape devices, an
>> -.Xr lseek 2
>> -operation is used.
>> -Otherwise, existing blocks are read and the data discarded.
>> -If the user does not have read permission for the tape, it is positioned
>> -using the tape
>> +On a tape device, existing blocks are read and the data discarded;
>> +if the user does not have read permission for the tape,
>> +it is positioned using the tape
>>  .Xr ioctl 2
>>  function calls.
>> +On all other devices devices, an
>> +.Xr lseek 2
>> +operation is used.
>>  If the seek operation is past the end of file, space from the current
>>  end of file to the specified offset is filled with blocks of NUL bytes.

> i think this change is ok. however i think non-tape is clearer than "on
> all other devices". it's not a biggie, but i think the current stress on
> non-tape devices is probably intentional.

The patch is misleading.  The sentence "If the seek operation is
past the end of file..." only applies to tape devices, so it must
not follow a sentence about lseek(2).

I'm not convinced the text needs to be changed.

The existing order makes sense because the non-tape case can be
handled quickly, and then all the remaining complicated explanations
apply to tapes only.

Or what would you want to change, and why?


>> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
>>  For pipes, the correct number of bytes is read.
>>  For all other devices, the correct number of blocks is read without
>>  distinguishing between a partial or complete block being read.
>> -.It Xo
>> -.Sm off
>> -.Cm status= Ar value
>> -.Sm on
>> -.Xc
>> -Where
>> +.It Cm status Ns = Ns Ar value
>> +where

> you're correct that "Where" doesn;t really start a sentence, but this is
> sentence start position. using a small letter is also incorrect.
>
> in all honesty i would leave this, because it is not easy to rewrite in
> a way that sounds natural. but maybe
>
> The
> .Ar value
> parameter is one of the symbols from the following list:

That would look ugly by causing the line to wrap, but what about
the patch below?

Yours,
  Ingo


Index: dd.1
===================================================================
RCS file: /cvs/src/bin/dd/dd.1,v
retrieving revision 1.36
diff -u -r1.36 dd.1
--- dd.1 14 Feb 2020 15:55:57 -0000 1.36
+++ dd.1 14 Feb 2020 16:33:23 -0000
@@ -136,9 +136,9 @@
 For all other devices, the correct number of blocks is read without
 distinguishing between a partial or complete block being read.
 .It Cm status Ns = Ns Ar value
-Where
+The
 .Ar value
-is one of the symbols from the following list.
+is one of the symbols from the following list:
 .Bl -tag -width unblock
 .It Cm noxfer
 Do not print the transfer statistics as the last line of status output.
@@ -147,9 +147,9 @@
 Error messages are shown; informational messages are not.
 .El
 .It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value ...
-Where
+Each
 .Ar value
-is one of the symbols from the following list.
+is one of the symbols from the following list:
 .Bl -tag -width unblock
 .It Cm ascii
 The same as the

Reply | Threaded
Open this post in threaded view
|

Re: dd(1) wording and style

Jason McIntyre-2
On Fri, Feb 14, 2020 at 05:37:27PM +0100, Ingo Schwarze wrote:

> Hi,
>
> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +0000:
> > On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:
>
> >> -.It Cm seek= Ns Ar n
> >> +.It Cm seek Ns = Ns Ar n
> >>  Seek
> >>  .Ar n
> >>  blocks from the beginning of the output before copying.
> >> -On non-tape devices, an
> >> -.Xr lseek 2
> >> -operation is used.
> >> -Otherwise, existing blocks are read and the data discarded.
> >> -If the user does not have read permission for the tape, it is positioned
> >> -using the tape
> >> +On a tape device, existing blocks are read and the data discarded;
> >> +if the user does not have read permission for the tape,
> >> +it is positioned using the tape
> >>  .Xr ioctl 2
> >>  function calls.
> >> +On all other devices devices, an
> >> +.Xr lseek 2
> >> +operation is used.
> >>  If the seek operation is past the end of file, space from the current
> >>  end of file to the specified offset is filled with blocks of NUL bytes.
>
> > i think this change is ok. however i think non-tape is clearer than "on
> > all other devices". it's not a biggie, but i think the current stress on
> > non-tape devices is probably intentional.
>
> The patch is misleading.  The sentence "If the seek operation is
> past the end of file..." only applies to tape devices, so it must
> not follow a sentence about lseek(2).
>
> I'm not convinced the text needs to be changed.
>
> The existing order makes sense because the non-tape case can be
> handled quickly, and then all the remaining complicated explanations
> apply to tapes only.
>
> Or what would you want to change, and why?
>

i understand. so i agree with your assessment (i failed to read further
into the text!)

>
> >> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
> >>  For pipes, the correct number of bytes is read.
> >>  For all other devices, the correct number of blocks is read without
> >>  distinguishing between a partial or complete block being read.
> >> -.It Xo
> >> -.Sm off
> >> -.Cm status= Ar value
> >> -.Sm on
> >> -.Xc
> >> -Where
> >> +.It Cm status Ns = Ns Ar value
> >> +where
>
> > you're correct that "Where" doesn;t really start a sentence, but this is
> > sentence start position. using a small letter is also incorrect.
> >
> > in all honesty i would leave this, because it is not easy to rewrite in
> > a way that sounds natural. but maybe
> >
> > The
> > .Ar value
> > parameter is one of the symbols from the following list:
>
> That would look ugly by causing the line to wrap, but what about
> the patch below?
>

line wrap?

anyway, i'm ok with your diff, but in all honesty, i'd just get over the
fact that it isn;t quite lovely, and just start

        .Ar value
        is...

but i'm fine with your approach too.
jmc

> Yours,
>   Ingo
>
>
> Index: dd.1
> ===================================================================
> RCS file: /cvs/src/bin/dd/dd.1,v
> retrieving revision 1.36
> diff -u -r1.36 dd.1
> --- dd.1 14 Feb 2020 15:55:57 -0000 1.36
> +++ dd.1 14 Feb 2020 16:33:23 -0000
> @@ -136,9 +136,9 @@
>  For all other devices, the correct number of blocks is read without
>  distinguishing between a partial or complete block being read.
>  .It Cm status Ns = Ns Ar value
> -Where
> +The
>  .Ar value
> -is one of the symbols from the following list.
> +is one of the symbols from the following list:
>  .Bl -tag -width unblock
>  .It Cm noxfer
>  Do not print the transfer statistics as the last line of status output.
> @@ -147,9 +147,9 @@
>  Error messages are shown; informational messages are not.
>  .El
>  .It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value ...
> -Where
> +Each
>  .Ar value
> -is one of the symbols from the following list.
> +is one of the symbols from the following list:
>  .Bl -tag -width unblock
>  .It Cm ascii
>  The same as the
>

Reply | Threaded
Open this post in threaded view
|

Re: dd(1) wording and style

Jan Stary
In reply to this post by Ingo Schwarze
Hi,

On Feb 14 17:37:27, [hidden email] wrote:

> Hi,
>
> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +0000:
> > On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:
>
> >> -.It Cm seek= Ns Ar n
> >> +.It Cm seek Ns = Ns Ar n
> >>  Seek
> >>  .Ar n
> >>  blocks from the beginning of the output before copying.
> >> -On non-tape devices, an
> >> -.Xr lseek 2
> >> -operation is used.
> >> -Otherwise, existing blocks are read and the data discarded.
> >> -If the user does not have read permission for the tape, it is positioned
> >> -using the tape
> >> +On a tape device, existing blocks are read and the data discarded;
> >> +if the user does not have read permission for the tape,
> >> +it is positioned using the tape
> >>  .Xr ioctl 2
> >>  function calls.
> >> +On all other devices devices, an
> >> +.Xr lseek 2
> >> +operation is used.
> >>  If the seek operation is past the end of file, space from the current
> >>  end of file to the specified offset is filled with blocks of NUL bytes.
>
> > i think this change is ok. however i think non-tape is clearer than "on
> > all other devices". it's not a biggie, but i think the current stress on
> > non-tape devices is probably intentional.
>
> The patch is misleading.  The sentence "If the seek operation is
> past the end of file..." only applies to tape devices, so it must
> not follow a sentence about lseek(2).

Why does it only apply to tape devices?
dd if=/dev/zero of=file bs=1 seek=10 count=1
will seek 10 bytes into the output (filling it with zeros)
and then write the 1 byte from input, as intended.
-rw-r--r--  1 hans  wheel  11 Feb 15 10:50 file

        Jan

Reply | Threaded
Open this post in threaded view
|

dd bs= supercede ibs= and obs=

Jan Stary
In reply to this post by Ingo Schwarze
On Feb 14 17:04:51, [hidden email] wrote:

> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +0000:
> > On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:
> >> * Fix a factual error in the description of bs: it does not
> >>   supersede ibs/obs, dd will error out when both are specified.
>
> In fact, that's a bug in the code.  POSIX requires:
>
>   bs=expr
>     Set both input and output block sizes to expr bytes,
>     superseding ibs= and obs=.
>
>   (see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/dd.html )

This is the line that makes it illegal to specify bs=
if ibs= or obs= (or bs= for that matter) has already been specified.

        Jan


Index: args.c
===================================================================
RCS file: /cvs/src/bin/dd/args.c,v
retrieving revision 1.31
diff -u -p -r1.31 args.c
--- args.c 16 Feb 2019 10:54:00 -0000 1.31
+++ args.c 15 Feb 2020 10:05:25 -0000
@@ -68,7 +68,7 @@ static const struct arg {
  void (*f)(char *);
  u_int set, noset;
 } args[] = {
- { "bs", f_bs, C_BS, C_BS|C_IBS|C_OBS|C_OSYNC },
+ { "bs", f_bs, C_BS, C_BS|C_OSYNC },
  { "cbs", f_cbs, C_CBS, C_CBS },
  { "conv", f_conv, 0, 0 },
  { "count", f_count, C_COUNT, C_COUNT },

Reply | Threaded
Open this post in threaded view
|

Re: dd bs= supercede ibs= and obs=

Ingo Schwarze
Hi,

Jan Stary wrote on Sat, Feb 15, 2020 at 11:07:04AM +0100:
> On Feb 14 17:04:51, [hidden email] wrote:
>> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +0000:
>>> On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:

>>>> * Fix a factual error in the description of bs: it does not
>>>>   supersede ibs/obs, dd will error out when both are specified.

>> In fact, that's a bug in the code.  POSIX requires:
>>   bs=expr
>>     Set both input and output block sizes to expr bytes,
>>     superseding ibs= and obs=.
>> (see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/dd.html )

> This is the line that makes it illegal to specify bs=
> if ibs= or obs= (or bs= for that matter) has already been specified.

That appears to be part of the picture, but that is not complete.
As i read POSIX (and our manual page), bs= has to supersede even
ips= and ops= operands that follow it (rather than precede it).

Inspecting the source code, that is also how dd(1) behaved in
4.3BSD-Reno, which got its dd(1) implementation from AT&T Version 7
UNIX, which already behaved that way.

The buggy code was part of a rewrite checked into SCCS by Keith
Bostic@ on 91/07/26, i.e. after about one third of the working phase
leading from Reno to 4.4BSD.  As our Copyright notice still says,
the code he checked in was written by Keith Muller (UC San Diego).
The authorship is confirmed by an explicit entry in the file
"admin/admin/contrib/contrib".

That means the bug is at least 28.5 years old.

Regarding the fix:  It seems sufficient to just remove the four
flags causing dd(1) to exit.  The argument handling callbacks already
do the right thing: f_bs() already overrides ibs and obs, while
f_ibs() and f_obs() do nothing when bs is already set.

Even though the risk feels low for this particular change, i think
i should test this with a full make build / make release, as a
matter of principle when touching such low-level tools.

Here is the new behaviour, matching v7 and 4.3BSD-Reno:

   $ dd if=/dev/zero of=/dev/null ibs=2048 obs=1024 bs=4096 count=2
  dd: bs supersedes ibs and obs
  2+0 records in
  2+0 records out
  8192 bytes transferred in 0.000 secs (140961886 bytes/sec)
   $ dd if=/dev/zero of=/dev/null bs=4096 ibs=2048 obs=1024 count=2
  dd: bs supersedes ibs and obs
  2+0 records in
  2+0 records out
  8192 bytes transferred in 0.000 secs (127456319 bytes/sec)
   $ dd if=/dev/zero of=/dev/null bs=4096 count=2                  
  2+0 records in
  2+0 records out
  8192 bytes transferred in 0.000 secs (230364725 bytes/sec)
   $ dd if=/dev/zero of=/dev/null ibs=4096 count=2
  2+0 records in
  16+0 records out
  8192 bytes transferred in 0.000 secs (183780146 bytes/sec)
   $ dd if=/dev/zero of=/dev/null obs=256 count=2  
  2+0 records in
  4+0 records out
  1024 bytes transferred in 0.000 secs (35021718 bytes/sec)

This also matches GNU gdd(1) from the coreutils package, fwiw.

Yours,
  Ingo


Index: args.c
===================================================================
RCS file: /cvs/src/bin/dd/args.c,v
retrieving revision 1.31
diff -u -p -r1.31 args.c
--- args.c 16 Feb 2019 10:54:00 -0000 1.31
+++ args.c 15 Feb 2020 13:47:04 -0000
@@ -68,14 +68,14 @@ static const struct arg {
  void (*f)(char *);
  u_int set, noset;
 } args[] = {
- { "bs", f_bs, C_BS, C_BS|C_IBS|C_OBS|C_OSYNC },
+ { "bs", f_bs, C_BS, C_BS|C_OSYNC },
  { "cbs", f_cbs, C_CBS, C_CBS },
  { "conv", f_conv, 0, 0 },
  { "count", f_count, C_COUNT, C_COUNT },
  { "files", f_files, C_FILES, C_FILES },
- { "ibs", f_ibs, C_IBS, C_BS|C_IBS },
+ { "ibs", f_ibs, C_IBS, C_IBS },
  { "if", f_if, C_IF, C_IF },
- { "obs", f_obs, C_OBS, C_BS|C_OBS },
+ { "obs", f_obs, C_OBS, C_OBS },
  { "of", f_of, C_OF, C_OF },
  { "seek", f_seek, C_SEEK, C_SEEK },
  { "skip", f_skip, C_SKIP, C_SKIP },

Reply | Threaded
Open this post in threaded view
|

Re: dd(1) wording and style

Ingo Schwarze
In reply to this post by Jan Stary
Hi Jan,

Jan Stary wrote on Sat, Feb 15, 2020 at 10:51:28AM +0100:
> On Feb 14 17:37:27, [hidden email] wrote:
>> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +0000:
>>> On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:

>>>> -.It Cm seek= Ns Ar n
>>>> +.It Cm seek Ns = Ns Ar n
>>>>  Seek
>>>>  .Ar n
>>>>  blocks from the beginning of the output before copying.
>>>> -On non-tape devices, an
>>>> -.Xr lseek 2
>>>> -operation is used.
>>>> -Otherwise, existing blocks are read and the data discarded.
>>>> -If the user does not have read permission for the tape, it is positioned
>>>> -using the tape
>>>> +On a tape device, existing blocks are read and the data discarded;
>>>> +if the user does not have read permission for the tape,
>>>> +it is positioned using the tape
>>>>  .Xr ioctl 2
>>>>  function calls.
>>>> +On all other devices devices, an
>>>> +.Xr lseek 2
>>>> +operation is used.
>>>>  If the seek operation is past the end of file, space from the current
>>>>  end of file to the specified offset is filled with blocks of NUL bytes.

>>> i think this change is ok. however i think non-tape is clearer than "on
>>> all other devices". it's not a biggie, but i think the current stress on
>>> non-tape devices is probably intentional.

>> The patch is misleading.  The sentence "If the seek operation is
>> past the end of file..." only applies to tape devices, so it must
>> not follow a sentence about lseek(2).

> Why does it only apply to tape devices?
> dd if=/dev/zero of=file bs=1 seek=10 count=1
> will seek 10 bytes into the output (filling it with zeros)
> and then write the 1 byte from input, as intended.
> -rw-r--r--  1 hans  wheel  11 Feb 15 10:50 file

You are right, lseek(2) also behaves that way, as documented:

  The lseek() function allows the file offset to be set beyond the end of
  the existing end-of-file of the file.  If data is later written at this
  point, subsequent reads of the data in the gap return bytes of zeros
  (until data is actually written into the gap).

However, the reordering is still unfortunate because it would no longer
be clear that filling the gap also applies to tape devices.  That's
what the dd(1) manual needs to explain because that's what dd(1)
actually implements.  Documenting lseek(2) in the dd(1) manual page,
on the other hand, isn't really needed.

I'm not convinced that the current text for seek= needs further
changes.

Yours,
  Ingo