Utility Conventions

 Utility Argument Syntax

This section describes the argument syntax of the standard utilities and introduces terminology used throughout this specification set for describing the arguments processed by the utilities.

Within this specification set, a special notation is used for describing the syntax of a utility's arguments. Unless otherwise noted, all utility descriptions use this notation, which is illustrated by this example (see the XCU specification, Simple Commands ):

utility_name[-a][-b][-coption_argument][-d|-e][-foption_argument][operand...]

The notation used for the SYNOPSIS sections imposes requirements on the implementors of the standard utilities and provides a simple reference for the application developer or system user.

1. The utility in the example is named utility_name. It is followed by options , option-arguments and operands . The arguments that consist of hyphens and single letters or digits, such as -a, are known as options (or, historically, flags). Certain options are followed by an option-argument, as shown with [-c option_argument]. The arguments following the last options and option-arguments are named operands.

2. Option-arguments are sometimes shown separated from their options by blank characters, sometimes directly adjacent. This reflects the situation that in some cases an option-argument is included within the same argument string as the option; in most cases it is the next argument. The Utility Syntax Guidelines in Utility Syntax Guidelines require that the option be a separate argument from its option-argument, but there are some exceptions in this specification set to ensure continued operation of historical applications:

   1. If the SYNOPSIS of a standard utility shows a space character between an option and option-argument (as with [-c option_argument] in the example), a portable application must use separate arguments for that option and its option-argument.

   2. If a space character is not shown (as with [-foption_argument] in the example), a portable application must place an option and its option-argument directly adjacent in the same argument string, without intervening blank characters.

   3. Notwithstanding the preceding requirements on portable applications, systems permit, but do not require, an application to specify options and option-arguments as separate arguments whether or not a space character is shown on the synopsis line, except in those cases (marked with the EX portability warning) where an option-argument is optional and no separation can be used.

   4. A standard utility may also be implemented to operate correctly when the required separation into multiple arguments is violated by a non-portable application.

   In summary, the following table shows allowable combinations:

   	SYNOPSIS Shows:
   	-a arg	-barg	-c[arg]
   Portable application must use:	-a arg	-barg	n/a
   System will support:	-a arg	-barg	-carg or -c
   System may support:	-aarg	-b arg

3. Options are usually listed in alphabetical order unless this would make the utility description more confusing. There are no implied relationships between the options based upon the order in which they appear, unless otherwise stated in the OPTIONS section, or unless the exception in Utility Syntax Guidelines guideline 11 applies. If an option that does not have option-arguments is repeated, the results are undefined, unless otherwise stated.

4. Frequently, names of parameters that require substitution by actual values are shown with embedded underscores. Alternatively, parameters are shown as follows:

   <parameter name>

   The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and must never be included in data submitted to the utility.

5. When a utility has only a few permissible options, they are sometimes shown individually, as in the example. Utilities with many flags generally show all of the individual flags (that do not take option-arguments) grouped, as in:

   
   
   utility_name [-abcDxyz][-p arg][operand]
   
   

   Utilities with very complex arguments may be shown as follows:

   
   
   utility_name [options][operands]
   
   

6. Unless otherwise specified, whenever an operand or option-argument is, or contains, a numeric value:

   • The number is interpreted as a decimal integer.

   • Numerals in the range 0 to 2147483647 are syntactically recognised as numeric values.

   • When the utility description states that it accepts negative numbers as operands or option-arguments, numerals in the range -2147483647 to 2147483647 are syntactically recognised as numeric values.

   • Ranges greater than those listed here are allowed.

   This does not mean that all numbers within the allowable range are necessarily semantically correct. A standard utility that accepts an option-argument or operand that is to be interpreted as a number, and for which a range of values smaller than that shown above is permitted by the XCU specification, describes that smaller range along with the description of the option-argument or operand. If an error is generated, the utility's diagnostic message will indicate that the value is out of the supported range, not that it is syntactically incorrect.

   For example, the specification of dd obs=3000000000 would yield undefined behaviour for the application and could be a syntax error because the number 3000000000 is outside of the range -2147483647 to +2147483647. On the other hand, dd obs=2000000000 may cause some error, such as "blocksize too large", rather than a syntax error.

7. Arguments or option-arguments enclosed in the [ and ] notation are optional and can be omitted. The [ and ] symbols must never be included in data submitted to the utility.

8. Arguments separated by the | vertical bar notation are mutually exclusive. The | symbols must never be included in data submitted to the utility. Alternatively, mutually exclusive options and operands may be listed with multiple synopsis lines. For example:

   
   
   utility_name -d[-a][-c option_argument][operand...]
   
   utility_name[-a][-b][operand...]
   
   

   When multiple synopsis lines are given for a utility, it is an indication that the utility has mutually exclusive arguments. These mutually exclusive arguments alter the functionality of the utility so that only certain other arguments are valid in combination with one of the mutually exclusive arguments. Only one of the mutually exclusive arguments is allowed for invocation of the utility. Unless otherwise stated in an accompanying OPTIONS section, the relationships between arguments depicted in the SYNOPSIS sections are mandatory requirements placed on portable applications. The use of conflicting mutually exclusive arguments produces undefined results, unless a utility description specifies otherwise. When an option is shown without the [ ] brackets, it means that option is required for that version of the SYNOPSIS. However, it is not required to be the first argument, as shown in the example above, unless otherwise stated.

   The use of undefined for conflicting argument usage and for repeated usage of the same option is meant to prevent portable applications from using conflicting arguments or repeated options, unless specifically allowed, as is the case with ls (which allows simultaneous, repeated use of the -C, -l and -1 options). Many historical implementations will tolerate this usage, choosing either the first or the last applicable argument, and this tolerance may continue, but portable applications cannot rely upon it. (Other implementations may choose to print usage messages instead.)

   The use of undefined for conflicting argument usage also allows an implementation to make reasonable extensions to utilities where the implementor considers mutually exclusive options according to the XCU specification to have a sensible meaning and result.

9. Ellipses (...) are used to denote that one or more occurrences of an option or operand are allowed. When an option or an operand followed by ellipses is enclosed in brackets, zero or more options or operands can be specified. The forms:

   
   
   utility_name -f option_argument...[operand...]
   
   utility_name [-g option_argument]...[operand...]
   
   

   indicate that multiple occurrences of the option and its option-argument preceding the ellipses are valid, with semantics as indicated in the OPTIONS section of the utility. (See also Guideline 11 in Utility Syntax Guidelines .) In the first example, each option-argument requires a preceding -f and at least one -f option_argument must be given.

   The XCU specification does not define the result of a utility when an option-argument or operand is not followed by ellipses and the application specifies more than one of that option-argument or operand. This allows an implementation to define valid (although non-standard) behaviour for the utility when more than one such option or operand are specified.

10. When the synopsis line is too long to be printed on a single line in the XCU specification, the indented lines following the initial line are continuation lines. An actual use of the command would appear on a single logical line.

Utility Syntax Guidelines 

The following guidelines are established for the naming of utilities and for the specification of options, option-arguments and operands. The getopt() function in the XSH specification assists utilities in handling options and operands that conform to these guidelines.

Operands and option-arguments can contain characters not specified in the portable character set.

The guidelines are intended to provide guidance to the authors of future utilities, such as those written specific to a local system or that are to be components of a larger application. Some of the standard utilities do not conform to all of these guidelines; in those cases, the OPTIONS sections describe the deviations.

Guideline  1:

Utility names should be between two and nine characters, inclusive.

Guideline  2:

Utility names should include lower-case letters (the lower character classification) and digits only from the portable character set. Guidelines 1 and 2 are offered as guidance for locales using Latin alphabets. No recommendations are made by this specification set concerning utility naming in other locales. In the XCU specification, Simple Commands , it is further stated that a command used in the XSI Shell Command Language cannot be named with a trailing colon.

Guideline  3:

Each option name should be a single alphanumeric character (the alnum character classification) from the portable character set. Multi-digit options are not allowed. Instances of historical utilities that used them have been marked LEGACY in the XCU specification, with the numbers being changed from option names to option-arguments.

Guideline  4:

All options should be preceded by the "-" delimiter character.

Guideline  5:

Options without option-arguments should be accepted when grouped behind one "-" delimiter.

Guideline  6:

Each option and option-argument should be a separate argument, except as noted in Utility Argument Syntax , item (2).

Guideline  7:

Option-arguments should not be optional.

Guideline  8:

When multiple option-arguments are specified to follow a single option, they should be presented as a single argument, using commas within that argument or blank characters within that argument to separate them. It is up to the utility to parse a comma-separated list itself because getopt() just returns a single string. This situation was retained so that certain historical utilities would not violate the guidelines. Applications preparing for international use should be aware of an occasional problem with comma-separated lists: in some locales, the comma is used as the radix character. Thus, if an application is preparing operands for a utility that expects a comma-separated list, it should avoid generating non-integer values through one of the means that is influenced by setting the LC_NUMERIC variable (such as awk, bc, printf or printf()).

Guideline  9:

All options should precede operands on the command line.

Guideline 10:

The argument -- should be accepted as a delimiter indicating the end of options. Any following arguments should be treated as operands, even if they begin with the "-" character. The -- argument should not be used as an option or as an operand. Applications calling any utility with a first operand starting with - should usually specify --, as indicated by Guideline 10, to mark the end of the options. This is true even if the SYNOPSIS in the XCU specification does not specify any options; implementations may provide options as extensions to the XCU specification. The standard utilities that do not support Guideline 10 indicate that fact in the OPTIONS section of the utility description.

Guideline 11:

The order of different options relative to one another should not matter, unless the options are documented as mutually exclusive and such an option is documented to override any incompatible options preceding it. If an option that has option-arguments is repeated, the option and option-argument combinations should be interpreted in the order specified on the command line. The order of repeated options that also have option-arguments may be significant; therefore, such options are required to be interpreted in the order that they are specified. The make utility is an instance of a historical utility that uses repeated options in which the order is significant. Multiple files are specified by giving multiple instances of the -f option, for example:

make -f common_header -f specific_rules target

Guideline 12:

The order of operands may matter and position-related interpretations should be determined on a utility-specific basis.

Guideline 13:

For utilities that use operands to represent files to be opened for either reading or writing, the "-" operand should be used only to mean standard input (or standard output when it is clear from context that an output file is being specified). Guideline 13 does not imply that all of the standard utilities automatically accept the operand "-" to mean standard input or output, nor does it specify the actions of the utility upon encountering multiple "-" operands. It simply says that, by default, "-" operands are not used for other purposes in the file reading or writing (but not when using stat(), unlink(), touch, and so forth) utilities. All information concerning actual treatment of the "-" operand is found in the individual utility sections.

The utilities in the XCU specification that claim conformance to these guidelines were written as if the term should imposed a specific requirement on their interface and applications and users can rely on the behaviour stated here; the Guidelines are rules for the standard utilities that claim conformance to them. On some systems, the utilities will accept usage in violation of these guidelines for backward compatibility as well as accepting the required form.

It is recommended that all future utilities and applications use these guidelines to enhance user portability. The fact that some historical utilities could not be changed (to avoid breaking existing applications) should not deter this future goal.