Tell me more ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.
up vote 17 down vote favorite
4

Should the usage message which is printed with e.g. 

 command -?

of a Unix command go to stderr or stdout, and why? Should it go to the same place if the user makes a mistake with an option?

share|improve this question
4  
Additional note: don't use -? use --help and -h Because --help and -h are standard and because -? will can be interpreted by the shell. – richard Mar 8 '11 at 9:53
1  
@richard This is an excellent point. Fun trick (in bash): touch -- -l; ls -? — you actually get a long listing as if you'd passed -l to ls. – mattdm♦ Mar 8 '11 at 12:56
@richard. When you don't know whether the command accept GNU-style long options or may support a -h option for other thing than a help message, then '-?' (with the quotes) or -: give you a good chance to get an error (and usage) message since : and ? can't be valid options for anything using getopt(3). – Stephane Chazelas Feb 8 at 22:40
@Stephane Chazelas. If I understand your comment correctly, you are writing from the perspective of a user of a program, this question I think is from the perspective of someone writing a program. – richard Feb 9 at 11:55

1 Answer

up vote 30 down vote accepted

It should go to stdout, so you can type:

command --help | less

This is also recommended by the Gnu Coding Standards on --help.

On the other hand, the usage message that you get when you use an invalid option or omit a required argument should go to stderr, because it's an error message, and you don't want it to feed into the next command in a pipeline.

When you use --help, the usage message is the normal and expected output of the command. Therefore, it goes to stdout, so it can be piped to another command, like less or grep.

When you say command --bogus-option | other-command, you don't want the usage message going to stdout, because it's now unexpected output that should not be processed by other-command. Also, if the output of --help is more than a handful of lines, then the usage error message should only contain a summary of the --help output, and refer the user to --help for additional details.

share|improve this answer
1  
It's a bit confusing to have two different output streams for the same message depending on something isn't it? – delete Mar 8 '11 at 8:05
6  
Perhaps, but they're not necessarily the same message. If the output of --help is more than a few lines, then the usage message produced by an invalid option should be just a short summary saying to use --help to see the complete information. – cjm Mar 8 '11 at 8:38
3  
+1 - this is 100% correct, and I don't see any room for disagreement here. – simon Mar 8 '11 at 10:04

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.