GETOPTS(1P)                                         POSIX Programmer's Manual                                        GETOPTS(1P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       getopts - parse utility options

SYNOPSIS
       getopts optstring name [arg...]

DESCRIPTION
       The  getopts  utility shall retrieve options and option-arguments from a list of parameters. It shall support the Utility
       Syntax Guidelines 3 to 10, inclusive, described in the Base Definitions volume  of  IEEE Std 1003.1-2001,  Section  12.2,
       Utility Syntax Guidelines.

       Each  time it is invoked, the getopts utility shall place 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 shall be initialized to 1.

       When  the  option  requires  an  option-argument, the getopts utility shall place 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 shall be 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 shall be set to the question-mark ( '?' ) character. In this case, if the first character in
       optstring is a colon ( ':' ), the shell variable OPTARG shall be set to the option character found, but no  output  shall
       be written to standard error; otherwise, the shell variable OPTARG shall be unset and a diagnostic message shall be writ-
       ten to standard error. This condition shall be considered to be an error detected in the way arguments were presented  to
       the invoking application, but shall not be an error in getopts processing.

       If an option-argument is missing:

        * If the first character of optstring is a colon, the shell variable specified by name shall be set to the colon charac-
          ter and the shell variable OPTARG shall be set to the option character found.

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

       When  the  end of options is encountered, the getopts utility shall exit with a return value greater than zero; the shell
       variable OPTIND shall be 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 shall be set to the question-mark character. Any of  the  following  shall
       identify 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 shall be local to the caller of getopts and shall not be exported by default.

       The shell variable specified by the name operand, OPTIND , and OPTARG shall affect the current shell  execution  environ-
       ment; see Shell Execution Environment .

       If the application sets OPTIND to the value 1, a new set of parameters can be used: either the current positional parame-
       ters 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 mod-
       ified to be a value other than 1, produces unspecified results.

OPTIONS
       None.

OPERANDS
       The following operands shall be supported:

       optstring
              A string containing the option characters recognized by the utility invoking getopts. If a character  is  followed
              by  a  colon,  the  option shall be expected to have an argument, which should be supplied as a separate argument.
              Applications should specify an option character and its option-argument as separate arguments, but  getopts  shall
              interpret  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 recognized if it is not supplied as a  separate  argument  when
              getopts   is   invoked.   (See   also   the   getopt()  function  defined  in  the  System  Interfaces  volume  of
              IEEE Std 1003.1-2001.)  The characters question-mark and colon shall not be used as option characters by an appli-
              cation.  The use of other option characters 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 shall  be  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 missing.

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


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

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of getopts:

       LANG   Provide  a  default value for the internationalization variables that are unset or null. (See the Base Definitions
              volume of IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for the precedence  of  international-
              ization variables used to determine the values of locale categories.)

       LC_ALL If set to a non-empty string value, override the values of all the other internationalization variables.

       LC_CTYPE
              Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-
              byte as opposed to multi-byte characters in arguments and input files).

       LC_MESSAGES
              Determine the locale that should be used to affect the format and contents of diagnostic messages written to stan-
              dard error.

       NLSPATH
              Determine the location of message catalogs for the processing of LC_MESSAGES .

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


ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

STDERR
       Whenever  an error is detected and the first character in the optstring operand is not a colon ( ':' ), a diagnostic mes-
       sage shall be written to standard error with the following information in an unspecified format:

        * The invoking program name shall be identified in the message. The invoking program name shall  be  the  value  of  the
          shell special parameter 0 (see Special Parameters ) at the time the getopts utility is invoked. A name equivalent to:


          basename "$0"

       may be used.

        * If  an  option is found that was not specified in optstring, this error is identified and the invalid option character
          shall be identified in the message.

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

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

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

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


CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION 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.

       Note that shell functions share OPTIND with the calling shell even though the positional parameters are changed.  If  the
       calling shell and any of its functions uses getopts to parse arguments, the results are unspecified.

EXAMPLES
       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" "$*"

RATIONALE
       The getopts utility was chosen in preference to the System V getopt utility because getopts handles option-arguments con-
       taining <blank>s.

       The OPTARG variable is not mentioned in the ENVIRONMENT VARIABLES section because it does not  affect  the  execution  of
       getopts; it is one of the few "output-only" variables used by the standard utilities.

       The colon is not allowed as an option character because that is not historical behavior, and it violates the Utility Syn-
       tax Guidelines. The colon is now specified to behave as in the KornShell version of the getopts utility; when used as the
       first  character  in  the  optstring  operand, it disables diagnostics concerning missing option-arguments and unexpected
       option characters. This replaces the use of the OPTERR variable that was specified in an early proposal.

       The formats of the diagnostic messages produced by the getopts utility and the getopt() function are not fully  specified
       because implementations with superior (``friendlier") formats objected to the formats used by some historical implementa-
       tions. The standard developers considered it important that the information in  the  messages  used  be  uniform  between
       getopts  and  getopt().  Exact  duplication  of the messages might not be possible, particularly if a utility is built on
       another system that has a different getopt() function, but the messages must have specific information included  so  that
       the program name, invalid option character, and type of error can be distinguished by a user.

       Only a rare application program intercepts a getopts standard error message and wants to parse it. Therefore, implementa-
       tions are free to choose the most usable messages they can devise. The following formats  are  used  by  many  historical
       implementations:


              "%s: illegal option -- %c\n", <program name>, <option character>


              "%s: option requires an argument -- %c\n", <program name>, \
                  <option character>

       Historical shells with built-in versions of getopt() or getopts have used different formats, frequently not even indicat-
       ing the option character found in error.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Special Parameters, the System Interfaces volume of IEEE Std 1003.1-2001, getopt()

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003  Edition,  Standard  for
       Information  Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
       discrepancy  between this version 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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                   GETOPTS(1P)