Supriya Ghosh (Editor)

Usage message

Updated on
Edit
Like
Comment
Share on FacebookTweet on TwitterShare on LinkedInShare on Reddit

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.

Contents

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 detailed documentation, such as a man page.

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.
  • 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.
  • Examples

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

    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:

    Explanation of the code:

    1. $# is number of parameter passed on the command line to the script
    2. `basename $0` is the output of basename, to strip any path away from the script's filename
    3. 1>&2 is used to redirect the output of echo to stderr

    References

    Usage message Wikipedia