Change the usage message for a command (QNX Neutrino)
usemsg [-c] loadfile [msgfile]
#ifdef __USAGE ... #endif
Note that there are two underscores before USAGE.
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.
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:
The use utility spawns:
and then prints the output.
If the executable sends its output to stderr, add this line instead:
%1> some_gnu_tool --help
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:
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.
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