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.
Here are the main principles at work:
which means that the options -a, -b, -c, and -d are supported.
utility [filename...]If the item is mandatory, the ellipsis indicates it may occur one or more times, e.g.:
There are a number of general guidelines to follow when running utilities:
the number should be a separate command-line argument from the -n. But if the documentation refers to:
then number should appear in the same argument as -n without any intervening blanks. Utilities in QNX and in POSIX-conforming systems permit both forms in all utilities unless otherwise stated, but you'll achieve the greatest portability by using the preferred form. This is particularly important when developing scripts that may be used on multiple (QNX and non-QNX) platforms.
cp -R dir1 dir2but not:
cp dir1 dir2 -R
rm -- -tUtilities that don't accept any options also accept and discard a -- before their operands, unless otherwise indicated.
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 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).
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.
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.