In
computer programming
Computer programming is the process of performing a particular computation (or more generally, accomplishing a specific computing result), usually by designing and building an executable computer program. Programming involves tasks such as anal ...
, 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 argument
A command-line interpreter or command-line processor uses a command-line interface (CLI) to receive commands from a user in the form of lines of text. This provides a means of setting parameters for the environment, invoking executables and pro ...
s or
option
Option or Options may refer to:
Computing
*Option key, a key on Apple computer keyboards
*Option type, a polymorphic data type in programming languages
*Command-line option, an optional parameter to a command
*OPTIONS, an HTTP request method
...
s acceptable to said program.
Usage messages are utilized as a quick way for a program to inform the user of proper command
syntax, and should not be substituted for proper error messages or for detailed documentation such as a
man page
A man page (short for manual page) is a form of software documentation usually found on a Unix or Unix-like operating system. Topics covered include computer programs (including library and system calls), formal standards and conventions, and ev ...
.
Pattern
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
An argument is a statement or group of statements called premises intended to determine the degree of truth or acceptability of another statement called conclusion. Arguments can be studied from three main perspectives: the logical, the dialectic ...
.
* To indicate optional arguments,
Square brackets
A bracket is either of two tall fore- or back-facing punctuation marks commonly used to isolate a segment of text or data from its surroundings. Typically deployed in symmetric pairs, an individual bracket may be identified as a 'left' or 'r ...
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 bar
The vertical bar, , is a glyph with various uses in mathematics, computing, and typography. It has many names, often related to particular meanings: Sheffer stroke (in logic), pipe, bar, or (literally the word "or"), vbar, and others.
Usage ...
s within groups.
Examples
Here is an example based on the
NetBSD
NetBSD is a free and open-source Unix operating system based on the Berkeley Software Distribution (BSD). It was the first open-source BSD descendant officially released after 386BSD was forked. It continues to be actively developed and is a ...
br>
source code style guide
Usage: program aDde
The Alliance for Direct Democracy in Europe, abbreviated to ADDE, was a European political party founded in 2014. It was composed of parties belonging to the Europe of Freedom and Direct Democracy (EFDD) group in the European Parliament (EP). T ...
-gn number
N, or n, is the fourteenth letter in the Latin alphabet, used in the modern English alphabet, the alphabets of other western European languages and others worldwide. Its name in English is ''en'' (pronounced ), plural ''ens''.
History
...
-c c_argreq1 req2 pt1 [opt2 PT1 may refer to:
* 486958 Arrokoth (New Horizons PT1), a Kuiper belt object and selected target for a flyby of the New Horizons probe
* Pratt & Whitney PT1, a free-piston gas-turbine engine
* Consolidated PT-1 Trusty, a 1930s USAAS primary trainer ...
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
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
Anti-patterns
A usage statement is not an error message, but is often used as a lazy way to avoid printing a useful error message. 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 the standard output;
if the user has entered an incorrect command line, a properly written command line program will print a succinct error message that describes the exact error made by the user rather than printing the usage statement and requiring the user to figure out what the mistake was. If the 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.
See also
*
Command-line interface
References
{{DEFAULTSORT:Usage Message
Online help