usemsg
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