use

Runs on:

QNX OS, 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.

The QNX_BUILDID in these properties is a string that the debugger uses to ensure that the symbols match the executable. It changes whenever the source code is changed and compiled.

You may specify only one of the -i or -s options.

-r

Display the usage message for all running processes on the system.

-s

Display the version numbers of the source code used to create the executable. When you're building a target image, mkifs by default strips this information. For instructions on including it, see the mkifs raw attribute.

You will be likely working with executables in your target image that don't have version information, so running use -s on them won't be useful. If, however, you have the .sym variants on your host, you can run the host-side use utility on these executable variants to see the version numbers.

On Windows, this utility is found at ${QNX_HOST}\usr\bin\use.exe; you would use this syntax in scripts. On the command line, you would invoke this utility with %QNX_HOST%\usr\bin\use.exe. On Linux, the utility is found at ${QNX_HOST}/usr/bin/use; you would use this syntax in both scripts and on the command line.

You may specify only one of the -s or -i options.

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.

Some host utilities, like mkifs, dumpifs support the -? option to print a usage message, because the use utility would not work for Windows executable files.

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 is displayed, 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 the QNX OS 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.

License checking

The use utility checks for a valid QNX license key before performing any operation. If the license check fails, the utility stops running and displays a diagnostic message. A license check may fail if the license key is expired, missing, or not currently activated, or if the key doesn’t contain the permissions needed to run the utility.

Examples:

Display a usage message for the ls utility:

use ls