Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1‎ > ‎

getopts


NAME
     getopts - parse utility options

SYNOPSIS
     /usr/bin/getopts optstring name [ arg...]

  sh
     getopts optstring name [argument...]

  ksh
     getopts optstring name [arg...]

DESCRIPTION
  /usr/bin/getopts
     The getopts utility can be  used  to  retrieve  options  and
     option-arguments from a list of parameters.

     Each time it is invoked,  the  getopts  utility  places  the
     value  of the next option in the shell variable specified by
     the name operand and the index of the next  argument  to  be
     processed  in  the shell variable OPTIND. Whenever the shell
     is invoked, OPTIND is initialized to 1.

     When the option requires  an  option-argument,  the  getopts
     utility places it in the shell variable OPTARG. If no option
     was found, or if the option that was found does not have  an
     option-argument, OPTARG is unset.

     If an  option  character  not  contained  in  the  optstring
     operand  is found where an option character is expected, the
     shell variable specified by name is set to the question-mark
     (  ?  )  character.  In this case, if the first character in
     optstring is a colon (:, the shell variable OPTARG is set to
     the  option  character  found,  but  no output is written to
     standard error; otherwise,  the  shell  variable  OPTARG  is
     unset and a diagnostic message is written to standard error.
     This condition is considered to be an error detected in  the
     way  arguments  were  presented to the invoking application,
     but is not an error in getopts processing.

     If an option-argument is missing:

       o  If the first character of optstring  is  a  colon,  the
          shell  variable  specified  by name is set to the colon
          character and the shell variable OPTARG is set  to  the
          option character found.

       o  Otherwise, the shell variable specified by name is  set
          to  the question-mark character (?), the shell variable
          OPTARG is unset, and a diagnostic message is written to
          standard  error.  This condition is considered to be an
          error detected in the way arguments were  presented  to
          the  invoking  application,  but  is  not  an  error in
          getopts processing; a diagnostic message is written  as
          stated, but the exit status is zero.


     When the end of options is encountered, the getopts  utility
     exits with a return value greater than zero; the shell vari-
     able OPTIND is set to the index  of  the  first  non-option-
     argument, where the first -- argument is considered to be an
     option-argument if there are no  other  non-option-arguments
     appearing  before  it,  or  the value $# + 1 if there are no
     non-option-arguments;  the  name  variable  is  set  to  the
     question-mark character. Any of the following identifies the
     end of options:  the special option --, finding an  argument
     that does not begin with a -, or encountering an error.

     The shell variables OPTIND  and  OPTARG  are  local  to  the
     caller of getopts and are not exported by default.

     The shell variable specified by the name operand, OPTIND and
     OPTARG affect the current shell execution environment.

     If the application sets OPTIND to the value 1, a new set  of
     parameters can be used: either the current positional param-
     eters or new arg values. Any other attempt to invoke getopts
     multiple  times in a single shell execution environment with
     parameters (positional parameters or arg operands) that  are
     not  the  same  in  all invocations, or with an OPTIND value
     modified to be a value other than  1,  produces  unspecified
     results.

  sh
     getopts is a built-in Bourne shell  command  used  to  parse
     positional  parameters  and  to check for valid options. See
     sh(1). It supports all applicable rules of the command  syn-
     tax  standard  (see Rules 3-10, intro(1)). It should be used
     in place of the getopt command.

     optstring must contain the option letters the command  using
     getopts  recognizes. If a letter is followed by a colon, the
     option is expected to have an argument, or  group  of  argu-
     ments, which must be separated from it by white space.

     Each time it is invoked, getopts places the next  option  in
     the  shell  variable name and the index of the next argument
     to be processed in the shell variable OPTIND.  Whenever  the
     shell or a shell script is invoked, OPTIND is initialized to
     1.

     When an option requires an option-argument,  getopts  places
     it in the shell variable OPTARG.

     If an illegal option is encountered, ? is placed in name.

     When the end of options is encountered, getopts exits with a
     non-zero  exit  status.  The special option - can be used to
     delimit the end of the options.

     By default, getopts parses  the  positional  parameters.  If
     extra arguments (argument ...) are given on the getopts com-
     mand line, getopts parses them instead.

     /usr/lib/getoptcvt reads the shell script in filename,  con-
     verts  it  to  use getopts instead of getopt, and writes the
     results on the standard output.

     So that all new commands adhere to the command syntax  stan-
     dard  described  in  intro(1),  they  should  use getopts or
     getopt to parse positional parameters and check for  options
     that are valid for that command.

     getopts prints an error message on the standard  error  when
     it encounters an option letter not included in optstring.

     Although the following command syntax  rule  (see  intro(1))
     relaxations  are permitted under the current implementation,
     they should not be used because they can not be supported in
     future  releases  of  the system. As in the EXAMPLES section
     below, -a and -b are options, and the option -o requires  an
     option-argument.

     The following example violates Rule 5: options with  option-
     arguments must not be grouped with other options:

     example% cmd -aboxxx filename

     The following example violates Rule 6: there must  be  white
     space after an option that takes an option-argument:

     example% cmd -ab oxxx filename

     Changing the value of the shell variable OPTIND  or  parsing
     different sets of arguments can lead to unexpected results.

  ksh
     Checks arg for legal options. If arg is omitted,  the  posi-
     tional parameters are used. An option argument begins with a
     + or a -. An option not beginning with + or - or  the  argu-
     ment - ends the options. optstring contains the letters that
     getopts recognizes. If a letter is followed  by  a  :,  that
     option  is  expected to have an argument. The options can be
     separated from the argument by blanks.


     getopts places the next option letter it finds inside  vari-
     able  name  each  time it is invoked with a + prepended when
     arg begins with a +. The index of the next arg is stored  in
     OPTIND. The option argument, if any, gets stored in OPTARG.

     A leading : in optstring causes getopts to store the  letter
     of  an invalid option in OPTARG, and to set name to ? for an
     unknown option and to : when a required option  is  missing.
     Otherwise,  getopts prints an error message. The exit status
     is non-zero when there are no more options.

     getopts supports  both  traditional  single-character  short
     options  and  long  options  defined  by  Sun's Command Line
     Interface Paradigm (CLIP).

     Each long option is an alias  for  a  short  option  and  is
     specified  in  parentheses  following  its  equivalent short
     option.  For example, you can specify the long  option  file
     as  an  alias  for  the  short  option f using the following
     script line:

     getopts "f(file)" opt

     Precede long options on the command line with -- or  ++.  In
     the  example  above, --file on the command line would be the
     equivalent of -f, and ++file on the command  line  would  be
     the equivalent of +f.

     Each short option can have multiple long option equivalents,
     although  this is in violation of the CLIP specification and
     should be used with caution.  You  must  enclose  each  long
     option equivalent parentheses, as follows:

     getopts "f:(file)(input-file)o:(output-file)"

     In the above example, both --file and --input-file  are  the
     equivalent of -f, and --output-file is the equivalent of -o.

     The variable name is always set to a short  option.  When  a
     long option is specified on the command line, name is set to
     the short-option equivalent.

     For a further discussion of the Korn shell's getopts  built-
     in  command, see the previous discussion in the Bourne shell
     (sh) section of this manpage.

OPERANDS
     The following operands are supported:

     optstring       A string containing  the  option  characters
                     recognised  by the utility invoking getopts.
                     If a character is followed by a  colon,  the
                     option  is  expected  to  have  an argument,
                     which should be supplied as a separate argu-
                     ment.  Applications should specify an option
                     character   and   its   option-argument   as
                     separate  arguments,  but getopts interprets
                     the characters following an option character
                     requiring  arguments  as an argument whether
                     or  not  this  is  done.  An  explicit  null
                     option-argument need not be recognised if it
                     is not supplied as a separate argument  when
                     getopts  is  invoked;  see  getopt(3C).  The
                     characters question-mark (?) and  colon  (:)
                     must  not be used as option characters by an
                     application. The use of other option charac-
                     ters  that  are  not  alphanumeric  produces
                     unspecified results. If the  option-argument
                     is  not supplied as a separate argument from
                     the option character, the value in OPTARG is
                     stripped  of the option character and the -.
                     The first character in optstring  determines
                     how  getopts  behaves if an option character
                     is not known or an option-argument is  miss-
                     ing.



     name            The name of a shell variable that is set  by
                     the  getopts utility to the option character
                     that was found.



     The getopts utility by default parses positional  parameters
     passed  to  the invoking shell procedure. If args are given,
     they are parsed instead of the positional parameters.

USAGE
     Since getopts affects the current shell  execution  environ-
     ment,  it is generally provided as a shell regular built-in.
     If it is called in a subshell or separate utility  execution
     environment, such as one of the following:

           (getopts abc value "$@")
            nohup getopts ...
            find . -exec getopts ... \;


     it does not affect  the  shell  variables  in  the  caller's
     environment.

     Notice that shell functions share OPTIND  with  the  calling
     shell  even  though  the  positional parameters are changed.
     Functions that want to use getopts to parse their  arguments
     usually  want  to  save  the  value  of  OPTIND on entry and
     restore it before returning. However, there are cases when a
     function wants to change OPTIND for the calling shell.

EXAMPLES
     Example 1: Parsing and Displaying Arguments

     The following example script parses and displays  its  argu-
     ments:

     aflag=
     bflag=
     while getopts ab: name
     do
          case $name in
          a)      aflag=1;;
          b)      bflag=1
                  bval="$OPTARG";;
          ?)     printf "Usage: %s: [-a] [-b value] args\n"  $0
                 exit 2;;
          esac
     done
     if [ ! -z "$aflag" ]; then
        printf "Option -a specified\n"
     fi
     if [ ! -z "$bflag" ]; then
          printf 'Option -b "%s" specified\n' "$bval"
     fi
     shift $(($OPTIND - 1))
     printf "Remaining arguments are: %s\n" "$*"


     Example 2: Processing Arguments for a Command with Options

     The following fragment of  a  shell  program  processes  the
     arguments  for a command that can take the options -a or -b.
     It also processes the option -o, which requires  an  option-
     argument:


     while getopts abo: c
     do
           case $c in
          a | b)   FLAG=$c;;
          o)       OARG=$OPTARG;;
          \?)      echo $USAGE
             exit 2;;
          esac
     done
     shift `expr $OPTIND - 1`

     Example 3: Equivalent Code Expressions

     This  code  example  accepts  any  of   the   following   as
     equivalent:

     cmd -a -b -o "xxx z yy" filename
     cmd -a -b -o "xxx z yy" -- filename
     cmd -ab -o xxx,z,yy filename
     cmd -ab -o "xxx z yy" filename
     cmd -o xxx,z,yy -b -a filename

ENVIRONMENT VARIABLES
     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution  of  getopts:  LANG,
     LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.

     OPTIND          This variable is  used  by  getopts  as  the
                     index of the next argument to be processed.



     OPTARG          This variable is used by  getopts  to  store
                     the  argument  if  an  option is using argu-
                     ments.



EXIT STATUS
     The following exit values are returned:

     0        An option, specified or unspecified  by  optstring,
              was found.



     >0       The end of options  was  encountered  or  an  error
              occurred.



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|

SEE ALSO
     intro(1), getoptcvt(1), ksh(1),  sh(1),  getopt(3C),  attri-
     butes(5), environ(5), standards(5)

DIAGNOSTICS
     Whenever an error is detected and the first character in the
     optstring  operand  is not a colon (:), a diagnostic message
     is written to standard error with the following  information
     in an unspecified format:

       o  The invoking program name is identified in the message.
          The  invoking  program  name  is the value of the shell
          special parameter 0 at the time the getopts utility  is
          invoked. A name equivalent to


          basename "$0"

          can be used.

       o  If an option is found that was not  specified  in  opt-
          string, this error is identified and the invalid option
          character is identified in the message.

       o  If an option requiring an option-argument is found, but
          an  option-argument is not found, this error is identi-
          fied and the invalid option character is identified  in
          the message.










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments