head	1.1;
access;
symbols
	GETOPT_20051005:1.1;
locks; strict;
comment	@# @;


1.1
date	2003.03.07.10.35.16;	author rse;	state Exp;
branches;
next	;


desc
@@


1.1
log
@add an OSSP collection of GNU getopt sources
@
text
@@@node Getopt, Argp, , Parsing Program Arguments
@@section Parsing program options using @@code{getopt}

The @@code{getopt} and @@code{getopt_long} functions automate some of the
chore involved in parsing typical unix command line options.

@@menu
* Using Getopt::                Using the @@code{getopt} function.
* Example of Getopt::           An example of parsing options with @@code{getopt}.
* Getopt Long Options::         GNU suggests utilities accept long-named
                                 options; here is one way to do.
* Getopt Long Option Example::  An example of using @@code{getopt_long}.
@@end menu

@@node Using Getopt, Example of Getopt, , Getopt
@@subsection Using the @@code{getopt} function

Here are the details about how to call the @@code{getopt} function.  To
use this facility, your program must include the header file
@@file{unistd.h}.
@@pindex unistd.h

@@comment unistd.h
@@comment POSIX.2
@@deftypevar int opterr
If the value of this variable is nonzero, then @@code{getopt} prints an
error message to the standard error stream if it encounters an unknown
option character or an option with a missing required argument.  This is
the default behavior.  If you set this variable to zero, @@code{getopt}
does not print any messages, but it still returns the character @@code{?}
to indicate an error.
@@end deftypevar

@@comment unistd.h
@@comment POSIX.2
@@deftypevar int optopt
When @@code{getopt} encounters an unknown option character or an option
with a missing required argument, it stores that option character in
this variable.  You can use this for providing your own diagnostic
messages.
@@end deftypevar

@@comment unistd.h
@@comment POSIX.2
@@deftypevar int optind
This variable is set by @@code{getopt} to the index of the next element
of the @@var{argv} array to be processed.  Once @@code{getopt} has found
all of the option arguments, you can use this variable to determine
where the remaining non-option arguments begin.  The initial value of
this variable is @@code{1}.
@@end deftypevar

@@comment unistd.h
@@comment POSIX.2
@@deftypevar {char *} optarg
This variable is set by @@code{getopt} to point at the value of the
option argument, for those options that accept arguments.
@@end deftypevar

@@comment unistd.h
@@comment POSIX.2
@@deftypefun int getopt (int @@var{argc}, char **@@var{argv}, const char *@@var{options})
The @@code{getopt} function gets the next option argument from the
argument list specified by the @@var{argv} and @@var{argc} arguments.
Normally these values come directly from the arguments received by
@@code{main}.

The @@var{options} argument is a string that specifies the option
characters that are valid for this program.  An option character in this
string can be followed by a colon (@@samp{:}) to indicate that it takes a
required argument.  If an option character is followed by two colons
(@@samp{::}), its argument is optional; this is a GNU extension.

@@code{getopt} has three ways to deal with options that follow
non-options @@var{argv} elements.  The special argument @@samp{--} forces
in all cases the end of option scanning.

@@itemize @@bullet
@@item
The default is to permute the contents of @@var{argv} while scanning it
so that eventually all the non-options are at the end.  This allows
options to be given in any order, even with programs that were not
written to expect this.

@@item
If the @@var{options} argument string begins with a hyphen (@@samp{-}), this
is treated specially.  It permits arguments that are not options to be
returned as if they were associated with option character @@samp{\1}.

@@item
POSIX demands the following behavior: The first non-option stops option
processing.  This mode is selected by either setting the environment
variable @@code{POSIXLY_CORRECT} or beginning the @@var{options} argument
string with a plus sign (@@samp{+}).
@@end itemize

The @@code{getopt} function returns the option character for the next
command line option.  When no more option arguments are available, it
returns @@code{-1}.  There may still be more non-option arguments; you
must compare the external variable @@code{optind} against the @@var{argc}
parameter to check this.

If the option has an argument, @@code{getopt} returns the argument by
storing it in the variable @@var{optarg}.  You don't ordinarily need to
copy the @@code{optarg} string, since it is a pointer into the original
@@var{argv} array, not into a static area that might be overwritten.

If @@code{getopt} finds an option character in @@var{argv} that was not
included in @@var{options}, or a missing option argument, it returns
@@samp{?} and sets the external variable @@code{optopt} to the actual
option character.  If the first character of @@var{options} is a colon
(@@samp{:}), then @@code{getopt} returns @@samp{:} instead of @@samp{?} to
indicate a missing option argument.  In addition, if the external
variable @@code{opterr} is nonzero (which is the default), @@code{getopt}
prints an error message.
@@end deftypefun

@@node Example of Getopt
@@subsection Example of Parsing Arguments with @@code{getopt}

Here is an example showing how @@code{getopt} is typically used.  The
key points to notice are:

@@itemize @@bullet
@@item
Normally, @@code{getopt} is called in a loop.  When @@code{getopt} returns
@@code{-1}, indicating no more options are present, the loop terminates.

@@item
A @@code{switch} statement is used to dispatch on the return value from
@@code{getopt}.  In typical use, each case just sets a variable that
is used later in the program.

@@item
A second loop is used to process the remaining non-option arguments.
@@end itemize

@@smallexample
@@include testopt.c.texi
@@end smallexample

Here are some examples showing what this program prints with different
combinations of arguments:

@@smallexample
% testopt
aflag = 0, bflag = 0, cvalue = (null)

% testopt -a -b
aflag = 1, bflag = 1, cvalue = (null)

% testopt -ab
aflag = 1, bflag = 1, cvalue = (null)

% testopt -c foo
aflag = 0, bflag = 0, cvalue = foo

% testopt -cfoo
aflag = 0, bflag = 0, cvalue = foo

% testopt arg1
aflag = 0, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -a arg1
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -c foo arg1
aflag = 0, bflag = 0, cvalue = foo
Non-option argument arg1

% testopt -a -- -b
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -b

% testopt -a -
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -
@@end smallexample

@@node Getopt Long Options
@@subsection Parsing Long Options with @@code{getopt_long}

To accept GNU-style long options as well as single-character options,
use @@code{getopt_long} instead of @@code{getopt}.  This function is
declared in @@file{getopt.h}, not @@file{unistd.h}.  You should make every
program accept long options if it uses any options, for this takes
little extra work and helps beginners remember how to use the program.

@@comment getopt.h
@@comment GNU
@@deftp {Data Type} {struct option}
This structure describes a single long option name for the sake of
@@code{getopt_long}.  The argument @@var{longopts} must be an array of
these structures, one for each long option.  Terminate the array with an
element containing all zeros.

The @@code{struct option} structure has these fields:

@@table @@code
@@item const char *name
This field is the name of the option.  It is a string.

@@item int has_arg
This field says whether the option takes an argument.  It is an integer,
and there are three legitimate values: @@w{@@code{no_argument}},
@@code{required_argument} and @@code{optional_argument}.

@@item int *flag
@@itemx int val
These fields control how to report or act on the option when it occurs.

If @@code{flag} is a null pointer, then the @@code{val} is a value which
identifies this option.  Often these values are chosen to uniquely
identify particular long options.

If @@code{flag} is not a null pointer, it should be the address of an
@@code{int} variable which is the flag for this option.  The value in
@@code{val} is the value to store in the flag to indicate that the option
was seen.
@@end table
@@end deftp

@@comment getopt.h
@@comment GNU
@@deftypefun int getopt_long (int @@var{argc}, char *const *@@var{argv}, const char *@@var{shortopts}, const struct option *@@var{longopts}, int *@@var{indexptr})
Decode options from the vector @@var{argv} (whose length is @@var{argc}).
The argument @@var{shortopts} describes the short options to accept, just as
it does in @@code{getopt}.  The argument @@var{longopts} describes the long
options to accept (see above).

When @@code{getopt_long} encounters a short option, it does the same
thing that @@code{getopt} would do: it returns the character code for the
option, and stores the options argument (if it has one) in @@code{optarg}.

When @@code{getopt_long} encounters a long option, it takes actions based
on the @@code{flag} and @@code{val} fields of the definition of that
option.

If @@code{flag} is a null pointer, then @@code{getopt_long} returns the
contents of @@code{val} to indicate which option it found.  You should
arrange distinct values in the @@code{val} field for options with
different meanings, so you can decode these values after
@@code{getopt_long} returns.  If the long option is equivalent to a short
option, you can use the short option's character code in @@code{val}.

If @@code{flag} is not a null pointer, that means this option should just
set a flag in the program.  The flag is a variable of type @@code{int}
that you define.  Put the address of the flag in the @@code{flag} field.
Put in the @@code{val} field the value you would like this option to
store in the flag.  In this case, @@code{getopt_long} returns @@code{0}.

For any long option, @@code{getopt_long} tells you the index in the array
@@var{longopts} of the options definition, by storing it into
@@code{*@@var{indexptr}}.  You can get the name of the option with
@@code{@@var{longopts}[*@@var{indexptr}].name}.  So you can distinguish among
long options either by the values in their @@code{val} fields or by their
indices.  You can also distinguish in this way among long options that
set flags.

When a long option has an argument, @@code{getopt_long} puts the argument
value in the variable @@code{optarg} before returning.  When the option
has no argument, the value in @@code{optarg} is a null pointer.  This is
how you can tell whether an optional argument was supplied.

When @@code{getopt_long} has no more options to handle, it returns
@@code{-1}, and leaves in the variable @@code{optind} the index in
@@var{argv} of the next remaining argument.
@@end deftypefun

Since long option names were used before before the @@code{getopt_long}
options was invented there are program interfaces which require programs
to recognize options like @@w{@@samp{-option value}} instead of
@@w{@@samp{--option value}}.  To enable these programs to use the GNU
getopt functionality there is one more function available.

@@comment getopt.h
@@comment GNU
@@deftypefun int getopt_long_only (int @@var{argc}, char *const *@@var{argv}, const char *@@var{shortopts}, const struct option *@@var{longopts}, int *@@var{indexptr})

The @@code{getopt_long_only} function is equivalent to the
@@code{getopt_long} function but it allows to specify the user of the
application to pass long options with only @@samp{-} instead of
@@samp{--}.  The @@samp{--} prefix is still recognized but instead of
looking through the short options if a @@samp{-} is seen it is first
tried whether this parameter names a long option.  If not, it is parsed
as a short option.

Assuming @@code{getopt_long_only} is used starting an application with

@@smallexample
  app -foo
@@end smallexample

@@noindent
the @@code{getopt_long_only} will first look for a long option named
@@samp{foo}.  If this is not found, the short options @@samp{f}, @@samp{o},
and again @@samp{o} are recognized.
@@end deftypefun

@@node Getopt Long Option Example
@@subsection Example of Parsing Long Options with @@code{getopt_long}

@@smallexample
@@include longopt.c.texi
@@end smallexample
@