Utility Conventions

Syntax conventions

Most QNX Neutrino utilities follow standard conventions for argument syntax and behavior. These conventions are based on the utility conventions outlined in POSIX 1003.2-1992.

The syntax synopsis for each utility appears at the top of the page of its manual entry. The utility name appears first, followed by other allowed command-line arguments, which include options, option arguments (e.g., "number" in -n number), and operands (e.g., the names of files to act on).

The syntax synopsis is the only reliable source for information about mutual exclusivity of options and about whether a command-line element is optional or required. This information isn't usually contained in the detailed option listings that appear after the syntax section.

A typical utility syntax line looks like this:

utilityname [-abcd] [-o arg | -p arg] infile... outfile

The example above shows a utility called utilityname that accepts the options -a, -b, -c, and -d; you can use these options by themselves or in any combination.

The utility also accepts the options -o and -p, both of which require an option argument, and which may not be used together (but may be used with the other options -abcd). The utility requires two or more operands: one or more infile and exactly one outfile.

Interpreting utility syntax

Here are the main principles at work:

Invoking utilities

There are a number of general guidelines to follow when running utilities:

File conventions

File pathnames specified on the command line are restricted to 255 characters. Some input files are specifically identified as "text files." Text files are expected to contain ASCII text in newline-terminated lines that don't exceed 2048 characters, unless otherwise indicated.

Signal conventions

Signal actions are inherited from the process that invokes the utility. Most utilities don't do any special processing upon receipt of a signal, but behave instead according to the system defaults. When a utility performs some action on receipt of a signal other than the default, it's documented as doing so.

Note that temporary files aren't left in place after a utility is terminated due to a signal, unless otherwise specified.

Servers and resident processes typically run only as root and ignore most signals (such as SIGPWR).

Exit status conventions

Utilities normally return zero for successful completion and values greater than zero when unsuccessful. Some utilities return different nonzero numbers according to the reason they failed. Beware of testing for a specific nonzero number to indicate failure. (In most cases utilities that may return different nonzero numbers are explicitly documented as doing so. However, you should not rely on this.)

For some utilities, the exit status may reflect only the success or failure of the last action taken (of many). In these cases, this behavior is explicitly documented in the "Exit status" section.

In the ksh, you can use $? to get the exit status of the last command. For more information, see "Parameters" in the documentation for ksh.

Error conventions

Utilities may fail for many reasons, ranging from incorrect usage to underlying system failure. The documentation for the utilities doesn't attempt to outline the exact behavior for all possible modes of failure.

In all cases, unless otherwise specified, every error results in a diagnostic message printed to standard error.

When an error occurs, the utility stops the processing of the current operand and proceeds to process the next operand in the sequence. If a utility fails to process one operand but succeeds on others, the exit status still reflects failure. For utilities that recurse through a filesystem (e.g., find), if an action cannot be performed on one file within a hierarchy, the utility stops processing that file and goes on to the subsequent files in the hierarchy.

When an unrecoverable error occurs (e.g., insufficient memory), the utility prints a diagnostic message to standard error and exits immediately.