GETOPT(1)               System General Commands Manual               GETOPT(1)

NAME
     getopt - parse short command options
     getopt_long - parse long command options

SYNOPSIS
     set -- `getopt optstring $*`
     set -- `getopt_long optstring longoptstring $*`

DESCRIPTION
     getopt and getopt_long are used to break up options in command lines for
     easy parsing by shell procedures, and to check for legal options.
     [optstring] is a string of recognized option letters (see getopt(3)); if
     a letter is followed by a colon, the option is expected to have an argu-
     ment which may or may not be separated from it by whitespace.

     With getopt_long the string [longoptstring] describes the long options
     and to which short option they are to be converted.  Long option descrip-
     tions are a set of strings comma separated. Each string is composed of
     three part: long name, argument option flag and short name.  The long
     name is the word suffixing a "--" (double dash). The option flag indi-
     cates if the long option has an option argument. A colon (:) indicates an
     option while a semi-colon (;) indicates no option. The short name is the
     next single character following the option flag. Any character between
     the short name and the next comma will be silently ignored.

     The special option ``--'' is used to delimit the end of the options.
     getopt and getopt_long will place ``--'' in the arguments at the end of
     the options, or recognize it if used explicitly.  The shell arguments ($1
     $2 ...) are reset so that each option is preceded by a ``-'' and in its
     own shell argument; each option argument is also in its own shell argu-
     ment.

EXAMPLES
     The following code fragment shows how one might use getopt to process the
     arguments for a command that can take the options -a and -b, and the
     option -o, which requires an argument.

           set -- `getopt abo: $*`
           if test $? != 0
           then
                   echo 'Usage: ...'
                   exit 2
           fi
           for i
           do
                   case "$i"
                   in
                           -a|-b)
                                   flag=$i; shift;;
                           -o)
                                   oarg=$2; shift; shift;;
                           --)
                                   shift; break;;
                   esac
           done

     This code will accept any of the following as equivalent:

           cmd -aoarg file file
           cmd -a -o arg file file
           cmd -oarg -a file file
           cmd -a -oarg -- file file

     The following code fragment shows how one might use getopt_long to pro-
     cess the arguments for a command that can take the options -a and -v, the
     option -o, which requires an argument, and two long options with their
     mapping.

           set -- `getopt ao:v "all;a,output:o,version;v" $*`
           if test $? != 0
           then
                   echo 'Usage: ...'
                   exit 2
           fi
           for i
           do
                   case "$i"
                   in
                           -a)
                                   flag=$i; shift;;
                           -o)
                                   oarg=$2; shift; shift;;
                           -v)
                                   echo "version $ver"; exit 0;;
                           --)
                                   shift; break;;
                   esac
           done

     This code will accept any of the following as equivalent:

           cmd -aoarg file file
           cmd -a -o arg file file
           cmd -oarg -a file file
           cmd -a -oarg -- file file
           cmd --all --output arg -- file file
           cmd --version
           cmd --all -o arg file file

     getopt prints an error message on the standard error output when it
     encounters an option letter not included in [optstring].

SEE ALSO
     sh(1), getopt(3)

HISTORY
     Written by Henry Spencer, working from a Bell Labs manual page.  Behavior
     believed identical to the Bell version.

BUGS
     Whatever getopt(3) has.

     Arguments containing whitespace or embedded shell metacharacters gener-
     ally will not survive intact; this looks easy to fix but isn't.

     The error message for an invalid option is identified as coming from
     getopt rather than from the shell procedure containing the invocation of
     getopt; this again is hard to fix.

     The precise best way to use the set command to set the arguments without
     disrupting the value(s) of shell options varies from one shell version to
     another.

Interix                          May 21, 2009                          Interix