2006-12-19 20:48:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GETOPT(3) Linux Programmer's Manual GETOPT(3)
|
|
|
|
|
|
|
|
|
|
|
|
NAME
|
|
|
|
getopt - Parse command line options
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
#include <unistd.h>
|
|
|
|
|
|
|
|
int getopt(int argc, char * const argv[],
|
|
|
|
const char *optstring);
|
|
|
|
|
|
|
|
extern char *optarg;
|
|
|
|
extern int optind, opterr, optopt;
|
|
|
|
|
|
|
|
#include <getopt.h>
|
|
|
|
|
|
|
|
int getopt_long(int argc, char * const argv[],
|
|
|
|
const char *optstring,
|
|
|
|
const struct option *longopts, int *longindex);
|
|
|
|
|
|
|
|
int getopt_long_only(int argc, char * const argv[],
|
|
|
|
const char *optstring,
|
|
|
|
const struct option *longopts, int *longindex);
|
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
The getopt() function parses the command line arguments.
|
|
|
|
Its arguments argc and argv are the argument count and
|
|
|
|
array as passed to the main() function on program invoca-
|
|
|
|
tion. An element of argv that starts with `-' (and is not
|
|
|
|
exactly "-" or "--") is an option element. The characters
|
|
|
|
of this element (aside from the initial `-') are option
|
|
|
|
characters. If getopt() is called repeatedly, it returns
|
|
|
|
successively each of the option characters from each of
|
|
|
|
the option elements.
|
|
|
|
|
|
|
|
If getopt() finds another option character, it returns
|
|
|
|
that character, updating the external variable optind and
|
|
|
|
a static variable nextchar so that the next call to
|
|
|
|
getopt() can resume the scan with the following option
|
|
|
|
character or argv-element.
|
|
|
|
|
|
|
|
If there are no more option characters, getopt() returns
|
|
|
|
EOF. Then optind is the index in argv of the first argv-
|
|
|
|
element that is not an option.
|
|
|
|
|
|
|
|
optstring is a string containing the legitimate option
|
|
|
|
characters. If such a character is followed by a colon,
|
|
|
|
the option requires an argument, so getopt places a
|
|
|
|
pointer to the following text in the same argv-element, or
|
|
|
|
the text of the following argv-element, in optarg. Two
|
|
|
|
colons mean an option takes an optional arg; if there is
|
|
|
|
text in the current argv-element, it is returned in
|
|
|
|
optarg, otherwise optarg is set to zero.
|
|
|
|
|
|
|
|
By default, getargs() permutes the contents of argv as it
|
|
|
|
scans, so that eventually all the non-options are at the
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GNU Aug 30, 1995 1
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GETOPT(3) Linux Programmer's Manual GETOPT(3)
|
|
|
|
|
|
|
|
|
|
|
|
end. Two other modes are also implemented. If the first
|
|
|
|
character of optstring is `+' or the environment variable
|
|
|
|
POSIXLY_CORRECT is set, then option processing stops as
|
|
|
|
soon as a non-option argument is encountered. If the
|
|
|
|
first character of optstring is `-', then each non-option
|
|
|
|
argv-element is handled as if it were the argument of an
|
|
|
|
option with character code 1. (This is used by programs
|
|
|
|
that were written to expect options and other argv-ele-
|
|
|
|
ments in any order and that care about the ordering of the
|
|
|
|
two.) The special argument `--' forces an end of option-
|
|
|
|
scanning regardless of the scanning mode.
|
|
|
|
|
|
|
|
If getopt() does not recognize an option character, it
|
|
|
|
prints an error message to stderr, stores the character in
|
|
|
|
optopt, and returns `?'. The calling program may prevent
|
|
|
|
the error message by setting opterr to 0.
|
|
|
|
|
|
|
|
The getopt_long() function works like getopt() except that
|
|
|
|
it also accepts long options, started out by two dashes.
|
|
|
|
Long option names may be abbreviated if the abbreviation
|
|
|
|
is unique or is an exact match for some defined option. A
|
|
|
|
long option may take a parameter, of the form --arg=param
|
|
|
|
or --arg param.
|
|
|
|
|
|
|
|
longopts is a pointer to the first element of an array of
|
|
|
|
struct option declared in <getopt.h> as
|
|
|
|
|
|
|
|
struct option {
|
|
|
|
const char *name;
|
|
|
|
int has_arg;
|
|
|
|
int *flag;
|
|
|
|
int val;
|
|
|
|
};
|
|
|
|
|
|
|
|
The meanings of the different fields are:
|
|
|
|
|
|
|
|
name is the name of the long option.
|
|
|
|
|
|
|
|
has_arg
|
|
|
|
is: no_argument (or 0) if the option does not take
|
|
|
|
an argument, required_argument (or 1) if the option
|
|
|
|
requires an argument, or optional_argument (or 2)
|
|
|
|
if the option takes an optional argument.
|
|
|
|
|
|
|
|
flag specifies how results are returned for a long
|
|
|
|
option. If flag is NULL, then getopt_long()
|
|
|
|
returns val. (For example, the calling program may
|
|
|
|
set val to the equivalent short option character.)
|
|
|
|
Otherwise, getopt_long() returns 0, and flag points
|
|
|
|
to a variable which is set to val if the option is
|
|
|
|
found, but left unchanged if the option is not
|
|
|
|
found.
|
|
|
|
|
|
|
|
val is the value to return, or to load into the
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GNU Aug 30, 1995 2
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GETOPT(3) Linux Programmer's Manual GETOPT(3)
|
|
|
|
|
|
|
|
|
|
|
|
variable pointed to by flag.
|
|
|
|
|
|
|
|
The last element of the array has to be filled with
|
|
|
|
zeroes.
|
|
|
|
|
|
|
|
If longindex is not NULL, it points to a variable which is
|
|
|
|
set to the index of the long option relative to longopts.
|
|
|
|
|
|
|
|
getopt_long_only() is like getopt_long(), but `-' as well
|
|
|
|
as `--' can indicate a long option. If an option that
|
|
|
|
starts with `-' (not `--') doesn't match a long option,
|
|
|
|
but does match a short option, it is parsed as a short
|
|
|
|
option instead.
|
|
|
|
|
|
|
|
RETURN VALUE
|
|
|
|
The getopt() function returns the option character if the
|
|
|
|
option was found successfully, `:' if there was a missing
|
|
|
|
parameter for one of the options, `?' for an unknown
|
|
|
|
option character, or EOF for the end of the option list.
|
|
|
|
|
|
|
|
getopt_long() and getopt_long_only() also return the
|
|
|
|
option character when a short option is recognized. For a
|
|
|
|
long option, they return val if flag is NULL, and 0 other-
|
|
|
|
wise. Error and EOF returns are the same as for getopt(),
|
|
|
|
plus `?' for an ambiguous match or an extraneous parame-
|
|
|
|
ter.
|
|
|
|
|
|
|
|
ENVIRONMENT VARIABLES
|
|
|
|
POSIXLY_CORRECT
|
|
|
|
If this is set, then option processing stops as
|
|
|
|
soon as a non-option argument is encountered.
|
|
|
|
|
|
|
|
EXAMPLE
|
|
|
|
The following example program, from the source code,
|
|
|
|
illustrates the use of getopt_long() with most of its fea-
|
|
|
|
tures.
|
|
|
|
|
|
|
|
#include <stdio.h>
|
|
|
|
|
|
|
|
int
|
|
|
|
main (argc, argv)
|
|
|
|
int argc;
|
|
|
|
char **argv;
|
|
|
|
{
|
|
|
|
int c;
|
|
|
|
int digit_optind = 0;
|
|
|
|
|
|
|
|
while (1)
|
|
|
|
{
|
|
|
|
int this_option_optind = optind ? optind : 1;
|
|
|
|
int option_index = 0;
|
|
|
|
static struct option long_options[] =
|
|
|
|
{
|
|
|
|
{"add", 1, 0, 0},
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GNU Aug 30, 1995 3
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GETOPT(3) Linux Programmer's Manual GETOPT(3)
|
|
|
|
|
|
|
|
|
|
|
|
{"append", 0, 0, 0},
|
|
|
|
{"delete", 1, 0, 0},
|
|
|
|
{"verbose", 0, 0, 0},
|
|
|
|
{"create", 1, 0, 'c'},
|
|
|
|
{"file", 1, 0, 0},
|
|
|
|
{0, 0, 0, 0}
|
|
|
|
};
|
|
|
|
|
|
|
|
c = getopt_long (argc, argv, "abc:d:012",
|
|
|
|
long_options, &option_index);
|
|
|
|
if (c == -1)
|
|
|
|
break;
|
|
|
|
|
|
|
|
switch (c)
|
|
|
|
{
|
|
|
|
case 0:
|
|
|
|
printf ("option %s", long_options[option_index].name);
|
|
|
|
if (optarg)
|
|
|
|
printf (" with arg %s", optarg);
|
|
|
|
printf ("\n");
|
|
|
|
break;
|
|
|
|
|
|
|
|
case '0':
|
|
|
|
case '1':
|
|
|
|
case '2':
|
|
|
|
if (digit_optind != 0 && digit_optind != this_option_optind)
|
|
|
|
printf ("digits occur in two different argv-elements.\n");
|
|
|
|
digit_optind = this_option_optind;
|
|
|
|
printf ("option %c\n", c);
|
|
|
|
break;
|
|
|
|
|
|
|
|
case 'a':
|
|
|
|
printf ("option a\n");
|
|
|
|
break;
|
|
|
|
|
|
|
|
case 'b':
|
|
|
|
printf ("option b\n");
|
|
|
|
break;
|
|
|
|
|
|
|
|
case 'c':
|
|
|
|
printf ("option c with value `%s'\n", optarg);
|
|
|
|
break;
|
|
|
|
|
|
|
|
case 'd':
|
|
|
|
printf ("option d with value `%s'\n", optarg);
|
|
|
|
break;
|
|
|
|
|
|
|
|
case '?':
|
|
|
|
break;
|
|
|
|
|
|
|
|
default:
|
|
|
|
printf ("?? getopt returned character code 0%o ??\n", c);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GNU Aug 30, 1995 4
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GETOPT(3) Linux Programmer's Manual GETOPT(3)
|
|
|
|
|
|
|
|
|
|
|
|
if (optind < argc)
|
|
|
|
{
|
|
|
|
printf ("non-option ARGV-elements: ");
|
|
|
|
while (optind < argc)
|
|
|
|
printf ("%s ", argv[optind++]);
|
|
|
|
printf ("\n");
|
|
|
|
}
|
|
|
|
|
|
|
|
exit (0);
|
|
|
|
}
|
|
|
|
|
|
|
|
BUGS
|
|
|
|
This manpage is confusing.
|
|
|
|
|
|
|
|
CONFORMING TO
|
|
|
|
getopt():
|
|
|
|
POSIX.1, provided the environment variable
|
|
|
|
POSIXLY_CORRECT is set. Otherwise, the elements of
|
|
|
|
argv aren't really const, because we permute them.
|
|
|
|
We pretend they're const in the prototype to be
|
|
|
|
compatible with other systems.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GNU Aug 30, 1995 5
|
|
|
|
|
|
|
|
|