Unix – Interactive Command Usage Reference

documentationoptionsposixqnx

The question of why some commands rely on manpages whereas others rely on something like the --help flag for providing command usage reference is not new. There is usually a difference in scope between documentation for a command and a command usage synopsis. The latter is often a subset of the former. But even when most commands and utilities have manpages for instance, there exists differences in their formatting of the synopsis section which have very practical implications when trying to extract such information. In other cases one might find clues with the strings utility when a command has seemingly no documentation.

I was interested with the commands I have on this QNX platform and discovered the use command1 to display usage information. As explained in usemsg, the framework involves setting a standard usage record in the utilities source and once compiled this can be accessed with the use command and you can also wrap the native functionality etc. It is quite convenient as I could simply do

use -d dir >>file

on /base and /proc/boot to extract all the usage for all the commands on the system basically.

So I then briefly looked at the source for GNU coreutils ls and FreeBSD ls to see if they did something like that and the former puts usage information in some usage named function(for --help I guess) while the latter doesn't seem to put it anywhere at all(?).

  • Is this sort of solution(use) typical of what you find with commercial Unix to present command usage reference interactively?
  • Does POSIX/SUS recommend or suggest anything about presenting/implementing command usage reference in commands(as opposed to specifying notation for shell utilities)?

1.use command: 

use
Print a usage message (QNX Neutrino)

Syntax:
use [-aeis] [-d directory] [-f filelist] files

Options:
-a
    Extract all usage information from the load module in its source form, suitable for piping into usemsg. 
-d directory
    Recursively display information for all files under directory. 
-e
    Include only ELF files. 
-f filelist
    Read a list of files, one per line, from the specified filelist file, and display information for each. 
-i
    Display build properties about a load module. 
-s
    Display the version numbers of the source used in the executable. 
files
    One or more executable load modules or shell scripts that contain usage messages.

Best Answer

Commercial unices generally present usage information only in man pages. Having the command itself display usage information is not a traditional Unix feature (except for displaying the list of supported options, but without any explanation, on a usage error). POSIX and its relatives don't talk about anything like this.

Having a --help option that displays a usage summary (typically a list of options, one per line, with a ~60 characters max description for each option) is a GNU standard. As far as I know, this convention was initiated by the GNU project, as part of the double-dash convention for multi-letter option names. There are other utilities, such as X11 utilities, that use multi-letter option names with a single dash and support -help; I don't know which one came first.

The use command is a QNX thing.

Related Question