Man Linux: Main Page and Category List

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

       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 character 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  environment;  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  parameters  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.

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 application. 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  internationalization  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 standard 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 message 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 identified 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
                  printfOption -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 containing <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 Syntax 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   implementations.   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, implementations 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  indicating 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, Copyright (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.opengroup.org/unix/online.html .