Re: Improving dd's usage message

[Pádraig Brady]

On 09/03/2014 11:32 AM, Philipp Thomas wrote:
> We have a bug where an openSUSE user complains that only the info pages tell
> of the uselesness of the directory flag for dd on Linux. In order help that
> I've come up with this small change to dd's usage output which would then
> also be part of the man page. Oppinions?
> 
> Philipp
> 
> diff --git a/NEWS b/NEWS
> index ba0d3d7..b601061 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -15,6 +15,9 @@ GNU coreutils NEWS                                    -*- 
> outline -*-
>    --skip-chdir option is specified.
>    [bug introduced in coreutils-8.23]
>  
> +** Improvements
> +
> +  dd now states in its help that the directory flag doesn't work on Linux.
>  
>  * Noteworthy changes in release 8.23 (2014-07-18) [stable]
>  
> diff --git a/src/dd.c b/src/dd.c
> index 1e387f3..0030d1b 100644
> --- a/src/dd.c
> +++ b/src/dd.c
> @@ -590,7 +590,10 @@ Each FLAG symbol may be:\n\
>        if (O_DIRECT)
>          fputs (_("  direct    use direct I/O for data\n"), stdout);
>        if (O_DIRECTORY)
> -        fputs (_("  directory  fail unless a directory\n"), stdout);
> +        fputs (_("\
> +  directory  fail unless a directory\n\
> +             NOTE: This does not work on Linux\n\
> +"), stdout);
>        if (O_DSYNC)
>          fputs (_("  dsync     use synchronized I/O for data\n"), stdout);
>        if (O_SYNC)

It's better to avoid mentioning particular implementations in docs
as that can be incomplete and those implementations can change.

Stating that it "does not work" is vague also.
Consider this to directly check a directory is accessible:

  linux$ dd status=none iflag=directory count=0 if=. || return

  linux$ dd status=none iflag=directory count=0 if=/etc/passwd || return
  dd: failed to open ‘/etc/passwd’: Not a directory

  linux$ dd status=none iflag=directory count=0 if=/root || return
  dd: opening `/root': Permission denied

We discussed recently the utility of low level directory I/O and decided
that it's an artefact to when directory representation was more coupled
with user space processing.  I.E. low level directory I/O is of more limited
use than this flag itself per se.

Therefore I think the man page is fine as is.

thanks,
Pádraig.