This article has multiple issues. Please help improve it or discuss these issues on the talk page. (Learn how and when to remove these template messages)(Learn how and when to remove this template message)
In computer programming, a usage message or help message refers to a brief message displayed by a program that utilizes a command-line interface for execution. This message usually consists of the correct command line usage for the program and includes a list of the correct command-line arguments or options acceptable to said program.
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.
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
For example, if a shell script 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 printf 'Usage: %s parameter1 parameter2 ...\n' "$(basename "$0")" >&2 exit 64 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
- >&2 is used to redirect the output of printf to stderr
- /usr/include/sysexits.h defines 64 as the preferable exit code for usage errors.