Bug 893036

The man page is really confusing when no examples are given using these flags. As someone new to the cli, the lack of information could be disastrous.

I have never seen dd being used with dirs either.
For above example, I would have used cp -a or rsync -a
so I think it probably is a doc issue.

(In reply to comment #1)
> The man page is really confusing when no examples are given using these flags.
> As someone new to the cli, the lack of information could be disastrous.

Pleas read to the end of the man page:

  SEE ALSO
    The full documentation for dd is maintained as a Texinfo manual.
    If the info and dd programs are properly installed at your site,
    the command

              info coreutils 'dd invocation'

    should give you access to the complete manual.

As for many GNU projects, the real documentation goes into
the Texinfo manual, and the man page is basically identical
to the output out --help (actually the man page is generated
from that).

(In reply to comment #2)
> I have never seen dd being used with dirs either.

The Linux kernel doesn't allow reading directories; other UNIX kernels
permit that, but the outcome is the binary representation of the directory
which even may contain file system specific bits.  Therefore, the directory
option really is of limited use, which is documented in the Texinfo manual:

    `directory'
          Fail unless the file is a directory.  Most operating systems
          do not allow I/O to a directory, so this flag has limited
          utility.

(In reply to comment #4)
> The Linux kernel doesn't allow reading directories; other UNIX kernels
> permit that, but the outcome is the binary representation of the directory
> which even may contain file system specific bits.  Therefore, the directory
> option really is of limited use [...]

Here's Padraig's (coreutils maintainer) answer:
http://lists.gnu.org/archive/html/coreutils/2014-08/msg00032.html

The consensus is that the directory option has very limited use cases in other operating systems and doesn't work at all with Linux (opensuse).

The info page notes that it doesn't work with Linux, but the man page doesn't.

I realize the info page is supposed to be the primary documentation but I also know lots of people (like me) rarely read the info page.

I've proposed a slight change in dd's usage message that directly tels the user that the flag doesn't work on Linux. If the change is accepted, the man page would contain that information.
But given that such a documentation bug won't be fixed for 13.1, I've moved the bug to openSUSE Factory.

The fix was rejected upstream:

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.

So the man page will not mention it. If you don't like it, please complain upstream on the coreutils@gnu.org ml.

Thanks for the effort.  I consider myself a dd expert and at least I now know what the flag in theory does.