Utility Conventions

This chapter includes:

Syntax conventions
File conventions
Signal conventions
Exit status conventions
Error conventions

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:

When utilities have many options, the options may appear grouped together in the syntax like this:
```
utilname [-abcd]
```
which means that the options -a, -b, -c, and -d are supported.
Options, option arguments, and operands enclosed in brackets ([ and ]) are optional and can be omitted. Note that the [ and ] symbols should never be included in the actual command.
Arguments separated by | are mutually exclusive. Sometimes mutually exclusive arguments that relate to modes of operation will be indicated with multiple syntax lines representing the different forms of the command.
A trailing ellipsis mark (...) after options or operands indicates that the preceding item may be repeated. If the preceding item is optional, the ellipsis indicates that the item may occur zero or more times, e.g.:
```
 
         utility [filename...]
```
If the item is mandatory, the ellipsis indicates it may occur one or more times, e.g.:
```
  
         utility filename...
```

Invoking utilities

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

An option may be followed by another option after a single dash (-) on the command line as long as each preceding option doesn't have an option argument. For example, the option string -abc is equivalent to -a -b -c. However, if -a accepts an option argument, then -abc would be equivalent to -a bc instead.
Options and their option arguments should be specified with spacing as shown in their documentation. If the documentation says:
```
-n number
```
the number should be a separate command-line argument from the -n. But if the documentation refers to:
```
-nnumber
```
then number should appear in the same argument as -n without any intervening blanks. Utilities in QNX and in POSIX-conforming systems will permit both forms in all utilities unless otherwise stated, but greatest portability is achieved by using the preferred form. This is particularly important when developing scripts that may be used on multiple (QNX and non-QNX) platforms.
Options are usually listed in alphabetical order, but there's no restriction on the order that they may appear in the command line when used, unless otherwise indicated in the documentation for the utility. Note that in some utilities, mutually exclusive options will override each other in a "last one wins" manner.
All options and associated option arguments must precede any operands on the command line. For example, if you want to run the cp utility with the -R option, you may enter:
```
     cp -R dir1 dir2
```
but not:
```
     cp dir1 dir2 -R
```
Decimal integers will be accepted when numeric values are required in operands and option arguments, unless otherwise specified. Some utilities may support 0octal and 0xhex numbers as well without being documented as doing so. For this reason, don't precede decimal numbers with leading zeros.
Integer numerical operands and option arguments must be in the range 0 to 2147483647 unless otherwise specified. If negative numbers are accepted, the acceptable range is -2147483647 to 2147483647.
The argument -- ("dash dash") may be placed on the command line as a delimiter indicating the end of options and the start of operands. This is particularly useful when the operands themselves might start with a dash. For example, to remove a file named "-t", you would use:
```
     rm -- -t
```
Utilities that don't accept any options will also accept and discard a -- before their operands, unless otherwise indicated.
Most utilities that accept filenames as operands (and sometimes as option arguments) will accept the filename "-" to mean standard input, or, when unambiguous from its context, standard output.

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.