unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

getopts(1)                       User Commands                      getopts(1)



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-argu-
       ments 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 stan-
       dard  error;  otherwise, the shell variable OPTARG is unset and a diag-
       nostic message is written to standard error. This condition is  consid-
       ered 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 condi-
            tion  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 variable 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 spe-
       cial  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 parameters or new arg val-
       ues. 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  syntax  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 arguments, 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  argu-
       ments  (argument  ...)  are  given on the getopts command line, getopts
       parses them instead.

       /usr/lib/getoptcvt reads the shell script in filename, converts  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  standard
       described in intro(1), they should use getopts or getopt to parse posi-
       tional parameters and check for options that are valid  for  that  com-
       mand.

       getopts  prints  an error message on the standard error when it encoun-
       ters 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 positional parame-
       ters are used. An option argument begins with a + or a -. An option not
       beginning  with  +  or  - or the argument - 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  variable  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  fol-
                       lowed  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 characters that are not alphanumeric  pro-
                       duces  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 opt-
                       string  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  environment,  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 arguments:

       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_MES-
       SAGES, 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 arguments.



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 attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE   VALUE   AvailabilitySUNWcsu
       Interface StabilityStandard


SEE ALSO
       intro(1), getoptcvt(1), ksh(1), sh(1), getopt(3C), attributes(5), envi-
       ron(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 invok-
            ing  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  optstring,  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 identified and the invalid
            option character is identified in the message.




SunOS 5.10                        21 Jul 2004                       getopts(1)