Usage message

On Unix-like platforms, usage messages usually follow the same common pattern:

• They often begin with "Usage:" , the command, followed by a list of arguments.
• To indicate optional arguments, Square brackets are commonly used, and can also be used to group parameters that must be specified together.
• To indicate required arguments, Angled brackets are commonly used, following the same grouping conventions as square brackets.
• Exclusive parameters can be indicated by separating them with vertical bars within groups.

Here is an example based on the NetBSD source code style guide:

Usage: program [-aDde] [-f | -g] [-n number] [-b b_arg | -c c_arg] req1 req2 [opt1 [opt2]]

This would indicate that "program" should be called with:

• options without operands: a, D, d, e (any of which may be omitted). Note that in this case some parameters are case-sensitive
• exclusive options: f, g (denoted by the vertical bar)
• options with operands: n
• exclusive options with operands: b, c
• required arguments: req1, req2
• optional argument opt1, which may be used with or without opt2 (marked optional within the group by using another set of square brackets)
• optional argument opt2, which requires opt1

To print a usage statement in a shell script, one might write:

case "$arg" in
...
h) printf 'Usage: %s parameter1 parameter2 ...\n' "$(basename "$0")"
   exit 0
   ;;
...
esac

A usage statement is not an error message, but is often used as a lazy way to avoid printing a useful error message. A properly written command line program will print a succinct error message that describes the exact error made by the caller rather than printing the usage statement and requiring the user to figure out what the mistake was. If a user fails to pass the correct number of arguments, for example, a single line stating that an argument is missing is far more useful than several pages of output providing a general usage. As a corollary, a usage statement should only be printed when specifically requested by the user (via --help, or -h, or -?, or some similar flag or argument) and should be written to stdout.[1][2]

• Command-line interface