Commands for communicating with other systems.
Commands specific to SunOS.
Unless otherwise noted, commands described in the SYNOPSIS section of a manual
page accept options and other arguments according to the following syntax and
should be interpreted as explained below.
name [-option...] [cmdarg...]
where:
[ ]
Surround an option or cmdarg that is not
required.
...
Indicates multiple occurrences of the option or
cmdarg.
name
The name of an executable file.
{ }
The options and/or arguments enclosed within braces are
interdependent, such that everything enclosed must be treated as a unit.
option
(Always preceded by a "−".)
noargletter... or, argletter optarg[,...]
noargletter
A single letter representing an option without an
option-argument. Notice that more than one noargletter option can be
grouped after one "−" (Guideline 5, below).
argletter
A single letter representing an option requiring an
option-argument.
optarg
An option-argument (character string) satisfying a
preceding argletter. Notice that groups of optargs following an
argletter must be separated by commas, or separated by a tab or space
character and quoted (Guideline 8, below).
cmdarg
Path name (or other command argument) not
beginning with "−", or "−" by itself
indicating the standard input.
Unless otherwise specified, whenever an operand or option-argument
is, or contains, a numeric value:
- o
- The number is interpreted as a decimal integer.
- o
- Numerals in the range 0 to 2147483647 are syntactically recognized as
numeric values.
- o
- When the utility description states that it accepts negative numbers as
operands or option-arguments, numerals in the range -2147483647 to
2147483647 are syntactically recognized as numeric values.
- o
- Ranges greater than those listed here are allowed.
These command syntax guidelines are not followed by all current commands, but
new commands are likely to obey them. getopts(1) should be used by all
shell procedures to parse positional parameters and to check for legal
options. It supports Guidelines 3-10 below. The enforcement of the other
guidelines must be done by the command itself.
- 1.
- Command names (name above) should be between two and nine
characters long.
- 2.
- Command names should include only lower-case letters and digits.
- 3.
- Option names (option above) must be one character long.
- 4.
- All options must be preceded by "−".
- 5.
- Options with no arguments can be grouped after a single
"−".
- 6.
- The first option-argument (optarg above) following an option must
be preceded by a tab or space character.
- 7.
- Option-arguments cannot be optional.
- 8.
- Groups of option-arguments following an option must either be separated by
commas or separated by tab or space character and quoted (-o
xxx,z,yy or -o"xxx z yy").
- 9.
- All options must precede operands (cmdarg above) on the command
line.
- 10.
- "−−" can be used to indicate the end of the
options.
- 11.
- The order of the options relative to one another should not matter.
- 12.
- The relative order of the operands (cmdarg above) can affect their
significance in ways determined by the command with which they
appear.
- 13.
- "−" preceded and followed by a white space character
should only be used to mean standard input.
An expanded set of guidelines referred to as CLIP for Command Line
Interface Paradigm has been developed for Solaris and other Sun products.
Its intent is to provide a command line syntax more closely aligned with the
GNU command line syntax popular on Linux systems.There is no intent to
retrofit existing utilities or even to apply this to all new utilities. It
is only intended to be applied to sets of utilities being developed when
appropriate.
CLIP is a full superset of the guidelines discussed above which
are closely aligned with IEEE Std. 1003.1-2001 (SUSv3). It does not include
all the GNU syntax. The GNU syntax allows constructs that either conflict
with the IEEE rules or are ambiguous. These constructs are not allowed.
The expanded CLIP command line syntax is:
utility_name -a --longopt1 -c option_argument \
-f option_argument --longopt2=option_argument \
--longopt3 option_argument operand
The utility in the example is named utility_name. It is
followed by options, option-arguments, and operands, collectively referred
to as arguments. The arguments that consist of a hyphen followed a single
letter or digit, such as -a, are known as short-options . The
arguments that consist of two hyphens followed by a series of letters,
digits and hyphens, such as --longopt1, are known as long-options .
Collectively, short-options and long-options are referred to 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. Once the first operand is
encountered, all subsequent arguments are interpreted to be operands.
Option-arguments are sometimes shown separated from their
short-options by BLANKSs, 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. This
specification requires that the option be a separate argument from its
option-argument, but there are some exceptions to ensure continued operation
of historical applications:
- o
- If the SYNOPSIS of a utility shows a SPACE between a short-option
and option-argument (as with -c option_argument in the example),
the application uses separate arguments for that option and its
option-argument.
- o
- If a SPACE is not shown (as with -f option_argument in the
example), the application expects an option and its option-argument
directly adjacent in the same argument string, without intervening
BLANKs.
- o
- Notwithstanding the preceding requirements, an application should accept
short-options and option-arguments as a single argument or as separate
arguments whether or not a SPACE is shown on the synopsis line.
- o
- Long-options with option-arguments are always documented as using an
equals sign as the separator between the option name and the
option-argument. If the OPTIONS section of a utility shows an
equals sign (=) between a long-option and its option-argument (as
with --longopt2= option_argument in the example), a application
shall also permit the use of separate arguments for that option and its
option-argument (as with --longopt1 option_argument in the
example).
CLIP expands the guidelines discussed with the following
additional guidelines:
14.
The form command subcommand [options] [operands]
is appropriate for grouping similar operations. Subcommand names should follow
the same conventions as command names as specified in guidelines 1 and
2.
15.
Long-options should be preceded by -- and should
include only alphanumeric characters and hyphens from the portable character
set. Option names are typically one to three words long, with hyphens to
separate words.
16.
--name=argument should be used to specify an
option-argument for a long-option. The form --name argument is also
accepted.
17.
All utilities should support two standard long-options:
--version (with the short-option synonym -V ) and --help
(with the short-option synonym -? ). The short option synonyms for
--version can vary if the preferred synonym is already in use (but a
synonym shall be provided). Both of these options stop further argument
processing when encountered and after displaying the appropriate output, the
utility successfully exits.
18.
Every short-option should have exactly one corresponding
long-option and every long-option should have exactly one corresponding
short-option. Synonymous options can be allowed in the interest of
compatibility with historical practice or community versions of equivalent
utilities.
19.
The short-option name should get its name from the
long-option name according to these rules:
- 1.
- Use the first letter of the long-option name for the short-option
name.
- 2.
- If the first letter conflicts with other short-option names, choose a
prominent consonant.
- 3.
- If the first letter and the prominent consonant conflict with other
shortoption names, choose a prominent vowel.
- 4.
- If none of the letters of the long-option name are usable, select an
arbitrary character.
20.
If a long-option name consists of a single character, it
must use the same character as the short-option name. Single character
long-options should be avoided. They are only allowed for the exceptionally
rare case that a single character is the most descriptive name.
21.
The subcommand in the form described in guideline 1 of
the additional CLIP guidelines is generally required. In the case where it is
omitted, the command shall take no operands and only options which are defined
to stop further argument processing when encountered are allowed. Invoking a
command of this form without a subcommand and no arguments is an error. This
guideline is provided to allow the common forms command --help, command
-?, command --version, and command -V to be accepted in
the command-subcommand construct.
Several of these guidelines are only of interest to the authors of
utilities. They are provided here for the use of anyone wanting to author
utilities following this syntax.