usemsg

Change usage message for a command (QNX)

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, then a C source is assumed. If present, this argument will be used as the name of the message file to insert into the load file. If the msgfile argument is not 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 executable program. All utilities supplied with QNX 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 is not 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.

Users will use the use utility to print usage messages. For example:

    use ls
    use more
    use sin

Developers may use the usemsg utility to add usage messages to their programs. 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 will be scanned and all text between an #ifdef __USAGE and the next #endif will be 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 were links to the same load file they could 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

%=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, you name the loadfile and don't specify a msgfile.

The %-command and %=language are both optional. If both are specified then the %-command would be followed by one or more %=languages followed by another %-command and another set of %=languages. 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 usage message from C source into myprog:

    usemsg myprog myprog.c

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

    usemsg sinit >sinitmsg
    vedit sinitmsg
    usemsg sinit sinitmsg

See also:

use