INTRO(1) User Commands INTRO(1)

NAME

Intro, intro - introduction to commands and application programs

DESCRIPTION

This section describes, in alphabetical order, commands available
with this operating system.


Pages of special interest are categorized as follows:

1B
Commands found only in the SunOS/BSD Compatibility Package.


1C
Commands for communicating with other systems.


1S
Commands specific to SunOS.

OTHER SECTIONS

See the following sections of the SunOS Reference Manual for more
information.

o Section 5 for information on file formats.

o Section 7 for descriptions of publicly available files and
miscellaneous information pages.

o Section 8 for system maintenance commands.


For tutorial information about these commands and procedures, see
Solaris Advanced User's Guide.

Manual Page Command Syntax

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.

Command Syntax Standard: Guidelines
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.

ATTRIBUTES

See attributes(7) for a discussion of the attributes listed in this
section.

ACKNOWLEDGMENTS

Sun Microsystems, Inc. gratefully acknowledges The Open Group for
permission to reproduce portions of its copyrighted documentation.
Original documentation from The Open Group can be obtained online at
http://www.opengroup.org/bookstore/.


The Institute of Electrical and Electronics Engineers and The Open
Group, have given us permission to reprint portions of their
documentation.


In the following statement, the phrase ``this text'' refers to
portions of the system documentation.


Portions of this text are reprinted and reproduced in electronic form
in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6,
Copyright (C) 2001-2004 by the Institute of Electrical and
Electronics Engineers, Inc and The Open Group. In the event of any
discrepancy between these versions and the original IEEE and The Open
Group Standard, the original IEEE and The Open Group Standard is the
referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html.


This notice shall appear on any product containing this material.

SEE ALSO

getopts(1), wait(1), exit(2), getopt(3C), attributes(7)

DIAGNOSTICS

Upon termination, each command returns two bytes of status, one
supplied by the system and giving the cause for termination, and (in
the case of "normal" termination) one supplied by the program [see
exit(2)]. The former byte is 0 for normal termination. The latter
byte is customarily 0 for successful execution and non-zero to
indicate troubles such as erroneous parameters, or bad or
inaccessible data. It is called variously "exit code", "exit status",
or "return code", and is described only where special conventions are
involved.

WARNINGS

Some commands produce unexpected results when processing files
containing null characters. These commands often treat text input
lines as strings and therefore become confused upon encountering a
null character (the string terminator) within a line.

May 13, 2017 INTRO(1)