`usemsg`

Change the usage message for a command (QNX Neutrino)

Syntax:

usemsg [-c] loadfile [msgfile]

Options:

-c

The usage message is contained in a C source program delimited by:

#ifdef __USAGE
...
#endif

Note that there are two underscores before USAGE.

loadfile

The name of an executable program to extract or insert a usage message. The current PATH environment variable is searched to locate loadfile.

msgfile

A text file or a C source file containing a usage message (see -c). If the msgfile name ends in .c, a C source is assumed. If present, this argument is used as the name of the message file to insert into the load file. If the msgfile argument isn't present, the usage message is read from the load file and printed to standard output.

Description:

The usemsg utility lets you examine or change the usage record contained within a QNX Neutrino executable program. All utilities supplied with QNX Neutrino are shipped with a usage message describing their options. This information is kept in a resource record in the load file. Since this usage text isn't loaded into memory when the program is run, you can make it as large as 32K characters without affecting the size of your program at runtime.

The use utility prints usage messages. For example:

use ls
use more
use pidin

Developers may use the usemsg utility to add usage messages to their programs.

Displaying help messages in ported executables

If you are porting or developing an executable that already has a help message invoked by an argument, you can make use display the existing help message by adding one extra line in the executable, like this:

%digit> cmd argument

Where digit is where to read the output from, either 0 (stdout) or 1 (stderr). The use utility itself always prints to stdout but executables may print to stdout or stderr.

For example, if some_gnu_tool has an option --help that sends a help message to stdout, add a line like this:

%0> some_gnu_tool --help

%0> %C --help

In this example, when someone types:

use some_gnu_tool

The use utility spawns:

some_gnu_tool --help

and then prints the output.

If the executable sends its output to stderr, add this line instead:

%1> some_gnu_tool --help

Adding or changing a usage message

There are two forms of adding a usage message to a load file. One form assumes a simple text file while the other assumes that the usage message is contained in a C source program:

usemsg program textfile
usemsg program program.c

In the second form, the C source is scanned and all text between an #ifdef __USAGE and the next #endif is used. In both cases, any existing usage message is replaced by the new message. Note that this utility lets you both change existing usage messages and add usage messages to programs that have none. You don't need the program source.

The usemsg utility provides a simple grammar that allows it to support usage messages in several different languages. It also supports different messages linked to the name used to invoke the usage. For example, if less and more are links to the same load file they can each have their own usage within the same usage record within the file.

The grammar consists of the special symbol % in the first column followed by an action character as follows:

%%: A single %.
%-command: The start of a specific command's usage message.
%=language: The start of a new language.
%C<tab>: Replace with name of command and a space.
<tab>: Insert spaces equal to the length of the command + 1.

To extract the entire usage message, including all languages and the grammar control sequences, name the loadfile and don't specify a msgfile.

The %-command and %=language are both optional. If both are specified, the %-command is followed by one or more %=language sections followed by another %-command and another set of %=language sections. The following examples should clarify the required nesting:

%C   a single language message

%=english
%C   an English language message
%=french
%C   a French language message

%-less
%C   single language message for less
%-more
%C   single language message for more

%-less
%=english
%C   an English language message for less
%=french
%C   a French language message for less
%-more
%=english
%C   an English language message for more
%=french
%C   a French language message for more

If multiple language usage messages are available, use employs the LANG environment variable to select a language. If LANG isn't defined or doesn't match any language present, then the first usage message is printed. Likewise, if multiple command names are present, the command passed as an argument is used to select a command. If no match occurs, the first usage message is printed.

Examples:

Insert a usage message from C source into myprog:

usemsg myprog myprog.c

Extract the entire usage message for pidin, edit the message, then reinsert the changed message:

usemsg sinit >sinitmsg
vi sinitmsg
usemsg sinit sinitmsg