[Previous] [Contents] [Next]

Utility Conventions

This chapter includes:

Syntax conventions

Most QNX 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 -- these options may be used alone 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 will be documented as doing so.

Note that temporary files will not be left in place after a utility is terminated due to a signal, unless otherwise specified.

Utilities that begin with a capital letter are used to denote servers and resident processes. All other utility names are entirely in lowercase. Servers and resident processes will typically run only as root, and will 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 will return different non-zero numbers according to the reason they failed. Beware of testing for a specific non-zero number to indicate failure. (In most cases utilities that may return different non-zero 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 will be explicitly documented in the "Exit status" section.

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 will result in a diagnostic message printed to standard error.

When an error occurs, the utility will stop the processing of the current operand and proceed to process the next operand in the sequence. If a utility fails to process one operand but succeeds on others, the exit status will still reflect 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 will stop processing that file and go on to the subsequent files in the hierarchy.

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

[Previous] [Contents] [Next]