Embedding help into your binaries
Since QNX Neutrino is designed primarily to be deployed on embedded systems but also maintain many of the self-hosted characteristics that makes development on those platforms efficient (no-reboots, easy access, familiar cmd line tools) its help system is dually organized. There is a rich set of standard documentation (HTML or PDF) for the operating system, its programming environment, various libraries and utility functions.
However, since that documentation is not always at hand when you want to run a quick command* each target binary (ls, find, pidin etc) also contains an embedded text segment that holds a description on how to use the utility. In order to get at this information, you use the imaginatively named use utility.
For example, I never remember all the options to the find utility. If I were on a target then I could type in:
% use find find - find files (POSIX) find ... [operand_expression] Operand expressions: ...
In some ways this information is equivalent to unix style man pages, but since it is embedded directly into the binaries you never have to do any fancy configuration to prune information in (or out). Compared to rooting through and finding the utilities you use and then pruning the man pages appropriately, this is wicked easy.
In addition to the usage type of information, you can also print out build version information that is included with QNX binaries:
% use -i find NAME=find DESCRIPTION=find files DATE=2004/12/16-00:01:41-EST STATE=Stable HOST=uberbuild USER=toolsbuild VERSION=6.3.0SP1 TAGID=329
If you are ever contacting QNX support, this is great stuff to send them so that they can match up your binaries directly with the source for a given release if need be.
Under Neutrino the usage information is stuffed into two different ELF sections of the binary.
% ntox86-objdump -h find /usr/bin/find: file format elf32-i386 Sections: Idx Name Size VMA LMA File off Algn ... 19 QNX_usage 00004fb7 00000000 00000000 0000d304 2**0 CONTENTS, READONLY 20 QNX_info 00000085 00000000 00000000 000122bb 2**0 CONTENTS, READONLY
This approach is a double edged sword. On the one hand it means you don’t pay a memory penalty when loading the process since the QNX loader knows that these sections aren’t executable and basically ignores them. Since they are standard ELF sections, you can use all of the standard binary manipulation tools to work with them. The downside of this is that these sections can be removed by utilities such as strip, although the Neutrino image build process, using mkifs will preserve these sections in the OS filesystem image.
The cool thing is that this information stuffing isn’t something just reserved for QNX utilities and shared objects! It can be added to any Neutrino binary via the usemsg utility. There is no set format for the general usage section (QNX_usage), so you can put whatever you like there. The convention is to put command line parameter explanations and example invocations in this free form text section. The information section (QNX_info) is a structured key=value area and has a date and time field that is automatically updated when information is added. It is easy to use this technique to integrate notes that can be easily retrieved on both host and target systems.
% use -i ./a.out No info available in ./a.out. % usemsg -i qnx=cool ./a.out % use -i ./a.out NAME=a.out DATE=2007-03-25EDT-20:06:24 QNX=cool
Use messages are definitely a handy bit of infrastructure that make things just a bit easier for you to work with and manage your system software.
* For example working remotely connected to a customer site with no development environment at hand.