Shell – Where is the `–` (double dash) argument documented

documentationoptionsshell

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]

Best Answer

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

Related Solutions

shell – Difference Between $* and $@

When they are not quoted, $* and $@ are the same. You shouldn't use either of these, because they can break unexpectedly as soon as you have arguments containing spaces or wildcards.

"$*" expands to a single word "$1c$2c...". Usually c is a space, but it's actually the first character of IFS, so it can be anything you choose.

The only good use I've ever found for it is:

join arguments with comma (simple version)

join1() {
    typeset IFS=,
    echo "$*"
}

join1 a b c   # => a,b,c

join arguments with the specified delimiter (better version)

join2() {
    typeset IFS=$1   # typeset makes a local variable in ksh (see footnote)
    shift
    echo "$*"
}

join2 + a b c   # => a+b+c

"$@" expands to separate words: "$1" "$2" ...

This is almost always what you want. It expands each positional parameter to a separate word, which makes it perfect for taking command line or function arguments in and then passing them on to another command or function. And because it expands using double quotes, it means things don't break if, say, "$1" contains a space or an asterisk (*).

Let's write a script called svim that runs vim with sudo. We'll do three versions to illustrate the difference.

svim1

#!/bin/sh
sudo vim $*

svim2

#!/bin/sh
sudo vim "$*"

svim3

#!/bin/sh
sudo vim "$@"

All of them will be fine for simple cases, e.g. a single file name that doesn't contain spaces:

svim1 foo.txt             # == sudo vim foo.txt
svim2 foo.txt             # == sudo vim "foo.txt"
svim2 foo.txt             # == sudo vim "foo.txt"

But only $* and "$@" work properly if you have multiple arguments.

svim1 foo.txt bar.txt     # == sudo vim foo.txt bar.txt
svim2 foo.txt bar.txt     # == sudo vim "foo.txt bar.txt"   # one file name!
svim3 foo.txt bar.txt     # == sudo vim "foo.txt" "bar.txt"

And only "$*" and "$@" work properly if you have arguments containing spaces.

svim1 "shopping list.txt" # == sudo vim shopping list.txt   # two file names!
svim2 "shopping list.txt" # == sudo vim "shopping list.txt"
svim3 "shopping list.txt" # == sudo vim "shopping list.txt"

So only "$@" will work properly all the time.

typeset is how to make a local variable in ksh (bash and ash use local instead). It means IFS will be restored to its previous value when the function returns. This is important, because the commands you run afterward might not work properly if IFS is set to something non-standard.

LS – Documentation for Showing Output Vertically

The manual is out of date with the program. Try ls --help | grep -- ' -1':

  -1                         list one file per line

It is one of the last options described if you just do ls --help.

Best Answer

Related Solutions

shell – Difference Between $* and $@

LS – Documentation for Showing Output Vertically

Related Question