use

Print a usage message (QNX Neutrino)

Syntax:

use [-aeis] [-d directory] [-f filelist] files

Runs on:

QNX Neutrino, Linux, Microsoft Windows

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.

-s

Display the version numbers of the source used in the executable.

files

One or more executable load modules or shell scripts that contain usage messages.

Description:

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

---

Regardless of your current terminal settings specified, the use utility automatically includes a line break after 80 characters.

---

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

If the LANG environment variable is set, a usage message of that language displays, if available. Alternate language usage messages are not available within shell scripts. However, it's easy to edit shell script messages. While usage messages included 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 displayed:

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:

Display a usage message for the ls utility:

use ls

See also:

ksh, usemsg