`use`

Print a usage message (QNX Neutrino)

Syntax:

use [-a] [-d directory] [-e] [-f filelist] [-i] files

Options:

-a: Extract all usage information from the load module in its source form, suitable for piping into usemsg.
-d directory: Recursively display information for all files under directory.
-e: Include only ELF files.
-f filelist: Read a list of files, one per line, from the specified filelist file, and display information for each.
-i: Display build properties about a load module.
files: One or more executable load modules or shell scripts that contain usage messages.

Description:

The use utility prints a usage message for the specified executable programs or shell scripts.

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

Under the QNX Windows SDK, use works on Neutrino binaries that reside on the Windows system, not on Windows executables.

If the LANG environment variable is set, a usage message of that language is displayed, if available. Alternate language usage messages aren't available within shell scripts. However, it's easy to edit shell script messages. While usage messages shipped with standard versions of QNX Neutrino are in English only, it's 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 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 #.

Here's a sample usage message in a shell script:

#ifdef __USAGE
#%C thread_id
#Where:
#  thread_id   is the thread ID you want to act on
#endif

If the shell script is called foo and you invoke use foo, the following message is printed:

foo thread_id
Where:
  thread_id    is the thread ID you want to act on

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

#%C thread_id

and ends with:

#  thread_id   is the thread ID 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's displayed. As with the C language usage message convention (see usemsg), a %CTab at the start of a line is replaced by the program name (or filename of the shell script) and a tab character at the start of a line spaces over the same number of spaces as the last previous occurrence of %CTab.

You can place the usage message almost anywhere in most shell scripts. Placing it at the beginning results 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

use