User Commands                                            Intro(1)


NAME

     Intro, intro - introduction to commands and application pro-
     grams


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.

     1F    Commands associated with Form and Menu Language Inter-
           preter (FMLI).

     1S    Commands specific to SunOS.

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

         o    Section 1M for system maintenance commands.

         o    Section 4 for information on file formats.

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

     For tutorial  information  about  these  commands  and  pro-
     cedures, 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.

SunOS 5.11          Last change: 18 Nov 2008                    1


User Commands                                            Intro(1)

     ...            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 every-
                    thing 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)  satis-
                    fying  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 indicat-
                    ing 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 syntacti-
              cally 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.

SunOS 5.11          Last change: 18 Nov 2008                    2


User Commands                                            Intro(1)

         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 char-
              acter.

         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  charac-
              ter should only be used to mean standard input.

SunOS 5.11          Last change: 18 Nov 2008                    3


User Commands                                            Intro(1)

     An expanded set of guidelines referred to as CLIP  for  Com-
     mand  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 retro-
     fit  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, collec-
     tively 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  inter-
     preted 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

SunOS 5.11          Last change: 18 Nov 2008                    4


User Commands                                            Intro(1)

              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 docu-
              mented  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. Subcom-
            mand names should follow the same conventions as com-
            mand 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  typi-
            cally  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

SunOS 5.11          Last change: 18 Nov 2008                    5


User Commands                                            Intro(1)

            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 con-
                     sonant.

                3.   If the first letter and the  prominent  con-
                     sonant   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 charac-
                     ter.

     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  com-
            mand  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,

SunOS 5.11          Last change: 18 Nov 2008                    6


User Commands                                            Intro(1)

            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(5) 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 copy-
     righted 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  elec-
     tronic  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), wait(3UCB), attri-
     butes(5)


DIAGNOSTICS


SunOS 5.11          Last change: 18 Nov 2008                    7


User Commands                                            Intro(1)

     Upon termination, each command returns two bytes of  status,
     one supplied by the system and giving the cause for termina-
     tion, and (in the case of "normal" termination) one supplied
     by  the  program  [see  wait(3UCB) and exit(2)].  The former
     byte is 0 for normal termination. The latter  byte  is  cus-
     tomarily 0 for successful execution and non-zero to indicate
     troubles such as erroneous parameters, or bad or  inaccessi-
     ble  data.   It  is  called  variously  "exit  code",  "exit
     status", or "return code", and is described only where  spe-
     cial 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.

SunOS 5.11          Last change: 18 Nov 2008                    8


Man(1) output converted with man2html


FhG Schily's Home VED powered