usemsg

QNX SDP8.0Utilities ReferenceUtilities

Change the usage message for a command (QNX OS)

Syntax:

usemsg [-ctv] [-f filename]* [-i id[=value]]* [-s string]* loadfile [msgfile]

Runs on:

Linux, Microsoft Windows

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.

-f filename
Read filename for lines containing id=value pairs to import into loadfile.

You can specify multiple -f options. The information tags from all files specified by -f options are written into loadfile.

-i id[=value]
Add the information tag id to loadfile with the specified value. This information is displayed if you run use -i on the executable.

You can specify multiple -i options. The information tags from all -i options are written into loadfile.

You don't have to specify a value for the DATE and NAME ids.

The DATE, NAME, and QNX_BUILDID keys are added automatically when any other key is added.

The id is translated into uppercase.

-s string
Import the usage message from the #ifdef string section in a C source file. If string is omitted, __USAGE is used.

If you specify multiple -s options, usemsg searches for them in order, and uses the first string section found.

-t
Print the DATE as a UTC value instead of using the machine-dependent time zone.
-v
Be verbose. Use for debugging.
loadfile
The name of an executable program to extract a usage message from or insert a usage message into. The section with information tags is rewritten with each usemsg command that specifies any -f or -i options. So, any information tags already in loadfile but not indicated by -f or -i options in the latest command would be removed. 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 OS executable program. All utilities supplied with the QNX OS 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, it doesn't affect the size of your program at runtime. The maximum size of a usage message is 400 lines of 1024 characters, which is likely beyond your wildest dreams of verbosity.

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're 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 1 (stdout) or 2 (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:

%1> some_gnu_tool --help

or:

%1> %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:

%2> 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 in 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 pidin > my_pinitmsg
vi my_pinitmsg
usemsg pidin my_pinitmsg
Page updated: