## SYNOPSIS

           getopt optstring parameters

           getopt [options] [--] optstring parameters

           getopt  [options]  -o|--options  optstring  [options] [--]
           parameters

## DESCRIPTION

           getopt is used to break  up  (parse)  options  in  command
           lines  for  easy parsing by shell procedures, and to check
           for legal options.  It uses the GNU getopt(3) routines  to
           do this.

           The  parameters  getopt is called with can be divided into
           two parts: options which modify the way getopt will  parse
           (options  and -o|--options optstring in the SYNOPSIS), and
           the parameters which are to be parsed (parameters  in  the
           SYNOPSIS).   The  second  part  will  start  at  the first
           non-option parameter that is not an  option  argument,  or
           after  the  first  occurence  of  `--'.   If  no  `-o'  or
           `--options' option is found in the first part,  the  first
           parameter  of the second part is used as the short options
           string.

           If the environment variable GETOPT_COMPATIBLE is  set,  or
           if  its  first  parameter is not an option (does not start
           with a `-', this is the first  format  in  the  SYNOPSIS),
           getopt  will  generate output that is compatible with that
           of other versions of getopt(1).  It will still do  parame
           ter  shuffling  and recognize optional arguments (see sec
           tion COMPATIBILITY for more information).

           Traditional implementations of  getopt(1)  are  unable  to
           cope  with  whitespace  and other (shell-specific) special
           characters in  arguments  and  non-option  parameters.  To
           solve  this  problem,  this  implementation  can  generate
           quoted output which must once again be interpreted by  the
           shell  (usually  by  using the eval command). This has the
           effect of preserving those characters, but you  must  call
           getopt  in  a  way that is no longer compatible with other
           versions (the second or third format in the SYNOPSIS).  To
           determine  whether  this  enhanced version of getopt(1) is
           installed, a special test option (-T) can be used.

## OPTIONS

           -a, --alternative
                  Allow long options to start with a single `-'.

           -h, --help
                  Output a small usage guide and exit succesfully. No
                  other output is generated.
                  getopt(1) are still reported as coming from getopt.

           -o, --options shortopts
                  The short (one-character) options to be recognized.
                  If this option is not found, the first parameter of
                  getopt  that  does not start with a `-' (and is not
                  an option argument) is used as  the  short  options
                  string.   Each  short option character in shortopts
                  may be followed by one colon to indicate it  has  a
                  required argument, and by two colons to indicate it
                  has an optional argument.  The first  character  of
                  shortopts  may  be  `+' or `-' to influence the way
                  options are parsed and  output  is  generated  (see
                  section SCANNING MODES for details).

           -q, --quiet
                  Disable error reporting by getopt(3).

           -Q, --quiet-output
                  Do  not  generate  normal  output. Errors are still
                  reported by getopt(3), unless you also use -q.

           -s, --shell shell
                  Set quoting conventions to those of shell. If no -s
                  argument  is  found, the BASH conventions are used.
                  Valid arguments are currently `sh'  `bash',  `csh',
                  and `tcsh'.

           -u, --unquoted
                  Do  not  quote the output. Note that whitespace and
                  special  (shell-dependent)  characters  can   cause
                  havoc  in  this  mode  (like  they  do  with  other
                  getopt(1) implementations).

           -T --test
                  Test if your getopt(1) is this enhanced version  or
                  an  old version. This generates no output, and sets
                  the error status to  4.  Other  implementations  of
                  getopt(1),  and  this  version  if  the environment
                  variable GETOPT_COMPATIBLE is set, will return `--'
                  and error status 0.

           -V, --version
                  Output version information and exit succesfully. No
                  other output is generated.

## PARSING

           This section specifies the format of the  second  part  of
           the parameters of getopt (the parameters in the SYNOPSIS).
           The next section (OUTPUT) describes  the  output  that  is
           generated.  These parameters were typically the parameters
           a shell function was called with.  Care must be taken that
           written directly after the option character if present.

           It  is possible to specify several short options after one
           `-', as long as all (except possibly the last) do not have
           required or optional arguments.

           A  long  option  normally begins with `--' followed by the
           long option name.  If the option has a required  argument,
           it  may  be  written  directly after the long option name,
           separated by `=', or as the next argument  (ie.  separated
           by  whitespace on the command line).  If the option has an
           optional argument, it must be written directly  after  the
           long option name, separated by `=', if present (if you add
           the `=' but nothing behind it, it is interpreted as if  no
           argument was present; this is a slight bug, see the BUGS).
           Long options may be abbreviated, as long as the  abbrevia
           tion is not ambiguous.

           Each parameter not starting with a `-', and not a required
           argument of a previous option, is a non-option  parameter.
           Each  parameter  after  a  `--' parameter is always inter
           preted as a  non-option  parameter.   If  the  environment
           variable  POSIXLY_CORRECT  is  set, or if the short option
           string started with a `+', all  remaining  parameters  are
           interpreted  as non-option parameters as soon as the first
           non-option parameter is found.

## OUTPUT

           Output is generated for each element described in the pre
           vious  section.   Output  is done in the same order as the
           elements are specified in the input, except for non-option
           parameters.  Output  can  be done in compatible (unquoted)
           mode, or in such way that  whitespace  and  other  special
           characters  within arguments and non-option parameters are
           preserved (see QUOTING).  When the output is processed  in
           the  shell script, it will seem to be composed of distinct
           elements that can be processed one by one  (by  using  the
           shift  command in most shell languages). This is imperfect
           in unquoted mode, as elements can be split  at  unexpected
           places if they contain whitespace or special characters.

           If  there are problems parsing the parameters, for example
           because a required argument is not found or an  option  is
           not recognized, an error will be reported on stderr, there
           will be  no  output  for  the  offending  element,  and  a
           non-zero error status is returned.

           For  a short option, a single `-' and the option character
           are generated as one parameter. If the option has an argu
           ment,  the  next  parameter  will  be the argument. If the
           option takes an optional argument, but none was found, the
           next  parameter  will be generated but be empty in quoting
           Normally,  no  non-option  parameters  output is generated
           until all options and their arguments have been generated.
           Then `--' is generated as a single parameter, and after it
           the non-option parameters in the order  they  were  found,
           each as a separate parameter.  Only if the first character
           of the short options string was a `-', non-option  parame
           ter output is generated at the place they are found in the
           input (this is not supported if the first  format  of  the
           SYNOPSIS is used; in that case all preceding occurences of
           `-' and `+' are ignored).

## QUOTING

           In compatible mode, whitespace or 'special' characters  in
           arguments  or  non-option  parameters are not handled cor
           rectly. As the output is fed  to  the  shell  script,  the
           script  does not know how it is supposed to break the out
           put into separate parameters.  To circumvent this problem,
           this  implementation offers quoting. The idea is that out
           put is generated with quotes around each  parameter.  When
           this  output  is once again fed to the shell (usually by a
           shell eval command), it is split correctly  into  separate
           parameters.

           Quoting   is  not  enabled  if  the  environment  variable
           GETOPT_COMPATIBLE is set, if the first form of the  SYNOP
           SIS is used, or if the option `-u' is found.

           Different  shells  use  different quoting conventions. You
           can use the `-s' option to select the shell you are using.
           The   following  shells  are  currently  supported:  `sh',
           `bash', `csh' and `tcsh'.  Actually,  only  two  `flavors'
           are   distinguished:   sh-like   quoting  conventions  and
           csh-like quoting conventions. Chances are that if you  use
           another  shell  script  language, one of these flavors can
           still be used.

## SCANNING MODES

           The first character of the short options string may  be  a
           `-'  or  a `+' to indicate a special scanning mode. If the
           first calling form  in  the  SYNOPSIS  is  used  they  are
           ignored; the environment variable POSIXLY_CORRECT is still
           examined, though.

           If the first character is `+', or if the environment vari
           able  POSIXLY_CORRECT is set, parsing stops as soon as the
           first non-option parameter (ie. a parameter that does  not
           start with a `-') is found that is not an option argument.
           The remaining parameters are all interpreted as non-option
           parameters.

           If the first character is a `-', non-option parameters are
           interpret  its  first  parameter  as  the  string of short
           options, and all other arguments will be parsed.  It  will
           still  do  parameter shuffling (ie. all non-option parame
           ters are outputed at  the  end),  unless  the  environment
           variable POSIXLY_CORRECT is set.

           The  environment  variable GETOPT_COMPATIBLE forces getopt
           into compatibility mode.  Setting  both  this  environment
           variable and POSIXLY_CORRECT offers 100% compatibility for
           `difficult' programs. Usually, though, neither is  needed.

           In  compatibility  mode, leading `-' and `+' characters in
           the short options string are ignored.

## RETURN CODES

           getopt returns error code 0 for succesful  parsing,  1  if
           getopt(3)  returns errors, 2 if it does not understand its
           own  parameters,  3  if  an  internal  error  occurs  like
           out-of-memory, and 4 if it is called with -T.

## EXAMPLES

           Example  scripts  for  (ba)sh and (t)csh are provided with
           the getopt(1) distribution, and are  optionally  installed
           in /usr/local/lib/getopt or /usr/lib/getopt.

## ENVIRONMENT

           POSIXLY_CORRECT
                  This   environment  variable  is  examined  by  the
                  getopt(3) routines.  If it is set, parsing stops as
                  soon  as a parameter is found that is not an option
                  or an option argument. All remaining parameters are
                  also  interpreted as non-option parameters, regard
                  less whether they start with a `-'.

           GETOPT_COMPATIBLE
                  Forces getopt to use the first  calling  format  as
                  specified in the SYNOPSIS.

## BUGS

           getopt(3)  can  parse long options with optional arguments
           that are given an empty optional argument (but can not  do
           this  for  short  options). This getopt(1) treats optional
           arguments that are empty as if they were not present.

           The syntax if you do not want any short  option  variables
           at  all  is  not  very  intuitive  (you  have  to set them
           explicitely to the empty string).

## AUTHOR

           Frodo Looijaard <frodol@dds.nl>