Where is the `--` (double dash) argument documented?

Question

There are some utilities that accept a -- (double dash) as the signal for "end of options", required when a file name starts with a dash:

$ echo "Hello World!" >-file

$ cat -- -file
Hello World!

$ cat -file                      # cat - -file fails in the same way.
cat: invalid option -- 'f'
Try 'cat --help' for more information.

But some of those utilities don't show such an option in the manual page.

The man page for cat doesn't document the use (or validity) of a -- argument in any of the OS'es. This is not meant to be a Unix - Linux flame war, it is a valid, and, I believe, useful concern.

Neither cat, mv, ed (and I am sure many others) document such an option in their manual page that I can find.

Note that ./-file is a more portable workaround to the use of --. For example, the source (dot) command (and written as .) doesn't (generally) work well with an -- argument:

$ echo 'echo "Hello World!"' >-file

$ . ./-file
Hello World!

$ . -file
ksh: .: -f: unknown option
ksh: .: -i: unknown option
ksh: .: -l: unknown option
ksh: .: -e: unknown option
Usage: . [ options ] name [arg ...]

$ . -- -file         # works in bash. Not in dash, ksh, zsh.
ksh: .: -file: cannot open [No such file or directory]

Solution 1

This is a POSIX requirement for all utilities, see POSIX chapter 12.02, Guideline 10 for more information:

The first -- argument that is not an option-argument should be accepted as a delimiter indicating the end of options. Any following arguments should be treated as operands, even if they begin with the '-' character.

POSIX recommends all utilities to follow these guidelines.

There are a few exceptions like echo (read at OPTIONS). And special builtins that do not follow the guidelines (like break, dot, exec, etc.) :

Some of the special built-ins are described as conforming to XBD Utility Syntax Guidelines. For those that are not, the requirement in Utility Description Defaults that "--" be recognized as a first argument to be discarded does not apply and a conforming application shall not use that argument.

The intent is to document all commands that do not follow the guidelines in their POSIX man page, from POSIX chapter 12.02 third paragraph:

Some of the standard utilities do not conform to all of these guidelines; in those cases, the OPTIONS sections describe the deviations.

As the cat POSIX man page documents no deviations in the OPTIONS section, it is expected that it accept -- as a valid argument.

There still may be (faulty) implementations that fail to follow the guideline.

In particular, most GNU core utilities follow this guideline

Solution 2

For Linux OS that have a GNU userland: Debian, RedHat, Ubuntu, Mint, etc. (not some BSD's) the GNU common practices are important:

The list of utilities in your question have in common that they are GNU, in fact they all are GNU coreutils. The full GNU coreutils list is longer.

Most of the utilities from GNU share a common user interface and a common set of basic command line options like --help, --version and the use of -- as the signal for end of options.

The entry at info common and the GNU web page contain:

Certain options are available in all of these programs. Rather than writing identical descriptions for each of the programs, they are described here. (In fact, every GNU program accepts (or should accept) these options.)

‘--’
Delimit the option list. Later arguments, if any, are treated as operands even if they begin with ‘-’. For example, ‘sort -- -r’ reads from the file named -r.

A more precise (but not that easy to explain and remember) command to get to the -- entry is (please copy exactly) info -- cat --.

Solution 3

It is also documented in getopt(1) and getopt(3).

For example,

Each parameter after a `--' parameter is always interpreted as a non-option parameter.

Comments

[Quasímodo]

New GNU/Linux users would really benefit from this question. The canon is "read the manpage", but here is some valuable info that one just won't find there.

[Stephen Kitt]

No, this is not part of the shell.

[done]

@Quasímodo man bash only documents the options valid when calling bash, like bash -- -file. the other utilities may (and do) process arguments in their own particular way.

[Quasímodo]

@Isaac Yes, the header in the corresponding man bash section lets no doubt: "bash interprets the following options when it is invoked".

[mosvy]

what is exactly POSIX's stance on programs which do not take any arguments, but only operands, like dd. Should they recognize the -- or not? FWIW, FreeBSD's dd does not accept it.

[schily]

Good question. Solaris dd calls getopt() with an empty optstring and this could be seen as a hint that Sun believes dd should support it as they added this call in order to get XPG4 compliance.

[j4nd3r53n]

Debian dd -- if=/dev/zero of=/dev/null count=1 works as expected, by simply ignoring --, it seems

[domen]

Which is useful to a developer, but a user of utility will not know if it uses getopt. It's also unlikely such a technical decision would be documented in a user manual for utility.

[Mathias Begert]

Rest in peace, schily