`use`

Print a usage message (QNX)

Syntax:

use [-a] utilityname

Options:

-a: Extract all usage information from the load module in its source form, suitable for piping into usemsg.
utilityname: The utility for which a usage message will be displayed.

Description:

The use utility prints a usage message for the specified executable program or shell script.

The use utility searches for utilityname, using the default command search (PATH), and prints the usage message it finds contained in the load file or shell script.

If the LANG environment variable is set, a usage message of that language will be displayed, if available. Alternate language usage messages aren't available within shell scripts. However, shell script messages can be easily edited. While usage messages shipped with standard versions of QNX are in English only, it is possible to add alternate language usage messages by placing the revised usage message in a separate file and using the usemsg utility to insert the usage message in the executable in question.

Usage messages in shell scripts

Usage messages are implemented in binary executable programs using a special form of resource record in the load modules. Usage messages are implemented in shell scripts using a format similar to that which is used in the C source code and interpreted by the usemsg utility.

In shell scripts, the use utility scans each line from the beginning of the script, looking for a line starting with the # character (i.e. a comment) and containing the string __USAGE. The usage message begins on the next line and consists of all subsequent lines up to, but not including, the first line that either starts with #endif or starts with a character other than #.

The following is a sample usage message in a shell script:

    #ifdef __USAGE
    #%C node_number
    #Where:
    #  node_number   is the node you want to act on
    #endif

If the shell script were called foo and you invoked use foo the following message would be printed:

    foo node_number
    Where:
      node_number    is the node you want to act on

In the above shell script fragment, the message starts with:

    #%C	node_number

and ends with:

    # node_number    is the node you want to act on

Within the body of the usage message, the leading #s are stripped by the use utility and don't form part of the message that will be displayed. As with the C language usage message convention (see usemsg), a %C<tab> at the start of a line will be replaced by the program name (or filename of the shell script) and a tab character at the start of a line will space over the same number of spaces as the last previous occurrence of %C<tab>.

You can place the usage message almost anywhere in most shell scripts. Placing it at the beginning will result in quicker response for extracting the usage message at the expense of a very slight slowdown in execution of the shell script. If you're running a shell that doesn't recognize lines beginning with # as comments, you should place the usage message after an explicit exit.

Examples:

Print a usage message for the ls utility:

    use ls