ARK-OS/arkos/kernel/glibc/manual/getopt.texi

@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

@deftypevar int opterr
@standards{POSIX.2, unistd.h}
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

@deftypevar int optopt
@standards{POSIX.2, unistd.h}
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

@deftypevar int optind
@standards{POSIX.2, unistd.h}
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

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

@deftypefun int getopt (int @var{argc}, char *const *@var{argv}, const char *@var{options})
@standards{POSIX.2, unistd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@c Swapping elements of passed-in argv may be partial in case of
@c cancellation.  Gettext brings about a whole lot of AS and AC safety
@c issues.  The getopt API involves returning values in the
@c non-thread-specific optarg variable, which adds another thread-safety
@c issue.  Given print_errors, it may output errors to stderr, which may
@c self-deadlock, leak locks, or encounter (in a signal handler) or
@c leave (in case of cancellation) stderr in an inconsistent state.
@c Various implicit, indirect uses of malloc, in uses of memstream and
@c asprintf for error-printing, bring about the usual malloc issues.
@c
@c _getopt_internal
@c  _getopt_internal_r
@c   gettext
@c   _getopt_initialize
@c    getenv
@c   open_memstream
@c   lockfile, unlockfile, __fxprintf -> stderr
@c   asprintf
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.

@deftp {Data Type} {struct option}
@standards{GNU, getopt.h}
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

@deftypefun int getopt_long (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
@standards{GNU, getopt.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@c Same issues as getopt.
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 option's 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.  The option name may be abbreviated as long as the abbreviation is
unique.

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 @code{getopt_long}
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.

@deftypefun int getopt_long_only (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
@standards{GNU, getopt.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@c Same issues as getopt.

The @code{getopt_long_only} function is equivalent to the
@code{getopt_long} function but it allows 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.  In case both short and long options could be
matched (this can happen with single letter long options), the short
option is preferred (with some caveats).  For long options,
abbreviations are detected as well.

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.

It gets more interesting with single letter long options.  If we
define options in the following way

@smallexample
  static struct option long_options[] = @{
          @{"f",       no_argument,       0,  0 @},
          @{"foo",     no_argument,       0,  0 @},
          @{0,         0,                 0,  0 @},
  @};
@end smallexample

@noindent
use @code{"f"} (as a C string) as an option string and start the
application with @option{-f}, the short option will be matched.
@option{--f} will match the long one.  And both @option{-fo} and
@option{-foo} will match the long option @code{"foo"}.

Be aware that if the option string would be @code{"f:"} (thus the
short option requires an argument), using just @option{-f} leads to an
error.  But using @option{-fo} results in the long option being
matched.  For passing an argument in this situation, you need to do it
as two arguments (@option{-f}, @option{o}).  Though any other value
would work in a single argument (e.g., @option{-f1}), since it would
not match a long option (or its abbreviation).

@end deftypefun

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

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