Usage message
In computer programming, the usage message of a program with command-line interface refers to the brief message prompted for the list of command-line arguments or options acceptable to the program.
The usage message is a quick way for the users to learn or remember how to use a program or command before reading the detailed document or seeking help from people.
Pattern
On the Unix-like platforms, usage messages usually follows the same common pattern:
- They often begin with "Usage:" (hence possibly the name), 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.
- Exclusive parameters can be indicated by separating them with vertical bars within groups.
Examples
Here is a thorough 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
Implementation
For example, if a shell script called "myscript" required at least two parameter to be run, a programmer could create a usage message using something similar to the following:
if [$# -lt 2] then echo Usage: `basename $0` parameter1 parameter2 ... 1>&2 fi
Explanation of the code:
- $# is number of parameter passed on the command line to the script
- `basename $0` is the output of basename, to strip any path away from the script's filename
- 1>&2 is used to redirect the output of echo to stderr