Option Parsing¶
Definition
struct getopt_state {
int index;
int opt;
char *arg;
};
Members
index
- Index of the next unparsed argument of argv. If
getopt()
has parsed all of argv, then index will equal argc. opt
- Option being parsed when an error occurs. opt is only
valid when
getopt()
returns?
or:
. arg
- The argument to an option, NULL if there is none. arg
is only valid when
getopt()
returns an option character.
-
void
getopt_init_state
(struct getopt_state * gs)¶ Initialize a
struct getopt_state
Parameters
struct getopt_state * gs
- The state to initialize
Description
This must be called before using gs with getopt()
.
-
int
getopt
(struct getopt_state * gs, int argc, char *const argv, const char * optstring)¶ Parse short command-line options
Parameters
struct getopt_state * gs
- Internal state and out-of-band return arguments. This must be
initialized with
getopt_init_context()
beforehand. int argc
- Number of arguments, not including the
NULL
terminator char *const argv
- Argument list, terminated by
NULL
const char * optstring
- Option specification, as described below
Description
getopt()
parses short options. Short options are single characters. They may
be followed by a required argument or an optional argument. Arguments to
options may occur in the same argument as an option (like -larg
), or
in the following argument (like -l arg
). An argument containing
options begins with a -
. If an option expects no arguments, then it may
be immediately followed by another option (like ls -alR
).
optstring is a list of accepted options. If an option is followed by :
in optstring, then it expects a mandatory argument. If an option is followed
by ::
in optstring, it expects an optional argument. gs.arg points
to the argument, if one is parsed.
getopt()
stops parsing options when it encounters the first non-option
argument, when it encounters the argument --
, or when it runs out of
arguments. For example, in ls -l foo -R
, option parsing will stop when
getopt()
encounters foo
, if l
does not expect an argument. However,
the whole list of arguments would be parsed if l
expects an argument.
An example invocation of getopt()
might look like:
char *argv[] = { "program", "-cbx", "-a", "foo", "bar", 0 };
int opt, argc = ARRAY_SIZE(argv) - 1;
struct getopt_state gs;
getopt_init_state(&gs);
while ((opt = getopt(&gs, argc, argv, "a::b:c")) != -1)
printf("opt = %c, index = %d, arg = \"%s\"\n", opt, gs.index, gs.arg);
printf("%d argument(s) left\n", argc - gs.index);
and would produce an output of:
opt = c, index = 1, arg = "<NULL>"
opt = b, index = 2, arg = "x"
opt = a, index = 4, arg = "foo"
1 argument(s) left
For further information, refer to the getopt(3) man page.
Return
- An option character if an option is found. gs.arg is set to the
argument if there is one, otherwise it is set to
NULL
. -1
if there are no more options, if a non-option argument is encountered, or if an--
argument is encountered.'?'
if we encounter an option not in optstring. gs.opt is set to the unknown option.':'
if an argument is required, but no argument follows the option. gs.opt is set to the option missing its argument.
gs.index is always set to the index of the next unparsed argument in argv.
-
int
getopt_silent
(struct getopt_state * gs, int argc, char *const argv, const char * optstring)¶ Parse short command-line options silently
Parameters
struct getopt_state * gs
- State
int argc
- Argument count
char *const argv
- Argument list
const char * optstring
- Option specification
Description
Same as getopt()
, except no error messages are printed.