1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
## Name
getopt - parse command-line options
## Synopsis
```**c++
#include <getopt.h>
extern int opterr;
extern int optopt;
extern int optind;
extern int optreset;
extern char* optarg;
struct option {
const char* name;
int has_arg;
int* flag;
int val;
};
int getopt(int argc, char** argv, const char* short_options);
int getopt_long(int argc, char** argv, const char* short_options, const struct option* long_options, int* out_long_option_index);
```
## Description
`getopt()` and `getopt_long()` parse options according to the syntax specified
in [`getopt`(5)](../getopt.md). `getopt()` only supports short options;
`getopt_long()` supports both short and long options.
One invocation of either function extracts at most one option from command line
arguments, which are passed to it as the `argc`/`argv` pair, starting from
argument at index `optind`, which is initially set to 1 at program startup.
The `short_options` string should specify the short options to be recognized, as
single characters. If a short option requires a value, it is to be followed by a
colon character (`:`); if a short option optionally accepts a value, it is to be
followed by a double colon (`::`). If the first character in the `short_options`
is `+`, `getopt()` and `getopt_long()` won't look for further options once first
non-option argument is encountered.
`getopt_long()` additionally accepts an array of values describing long options
to be recognized. To specify whether a long option has a value, the `has_arg`
member of `struct option` must be set to one of the following predefined macro
values:
* `no_argument`, if no value is accepted;
* `required_argument`, if a value is optionally accepted;
* `optional_argument`, if a value is optionally accepted.
If an option is parsed successfully, `getopt()` and `getopt_long()`
automatically increase the `optind` variable to point to the next command-line
argument to be parsed. This makes it possible to invoke `getopt()` or
`getopt_long()` in a loop unless they indicate either an error or the end of
options, and then treat the remaining command-line arguments, starting from the
one pointed to be `optind`, as non-option argument.
Unless `+` is specified as the first character of `short_options`, `getopt()`
and `getopt_long()` automatically reorder elements of `argv` to put options and
their values before any non-option arguments.
If, after having used `getopt()` or `getopt_long()` to parse a set of
command-line arguments, the program intends to use the `getopt()` or
`getopt_long()` to parse a different set of command-line arguments, it must ask
`getopt()` and `getopt_long()` to reset the internal state that they keep across
calls to handle some tricky cases. To do so, the program must either set the
`optreset` variable to a non-zero value, or set `optind` variable to 0. Doing
either of these things will reset the internal state, and option parsing will
start from command-line argument at index 1 in either case.
## Return value
If no option has been found, `getopt()` and `getopt_long()` return -1.
In case some invalid configuration of options and their values are passed in
`argv`, `getopt()` and `getopt_long()` return the `'?'` character. If the error
is related to a short option, the variable `optopt` is set to the option
character. If the variable `opterr` has a non-zero value (as it does by
default), an appropriate error message is printed to the standard error stream.
If a short option has been successfully parsed, `getopt()` and `getopt_long()`
return its character. Its value, if any, is assigned to the `optarg` variable.
If the option has been given no value, `optarg` is set to `nullptr`.
If a long option has been successfully parsed, `getopt_long()` return value
depends on the value of the `flag` pointer for that option. If `flag` is
`nullptr`, `getopt_long()` returns the value of `val` for that option.
Otherwise, the pointee of `flag` is set to `val`, and `getopt_long()` returns 0.
In either case, the index of the long option in the `long_options` array is
stored to the pointee of `out_long_option_index`, if it's not a `nullptr`. Same
as for short options, the `optarg` variable is set to point to the value of the
option, or to `nullptr` is none has been given.
## Examples
```c++
#include <getopt.h>
int verbose = 0;
const char* pad = nullptr;
const char* source = nullptr;
while (true) {
// Accept short options: -h, -l, -s value, -p [value], -N.
const char* short_options = "hls:p::N";
// Accept long options: --pad [value], --verbose.
const option long_options[] {
{ "pad", optional_argument, nullptr, 'p' },
{ "verbose", no_argument, &verbose, 1 },
};
int opt = getopt(argc, argv, short_options, long_options, nullptr);
switch (opt) {
case -1:
// No more options.
return true;
case '?':
// Some error; getopt() has already printed an error message.
exit(1);
case 'h':
// Handle the -h option...
break;
case 'l':
// Handle the -l option...
break;
case 's':
// Handle the -s option.
source = optarg;
break;
case 'p':
// Handle the -p short option or the --pad long option.
if (optarg)
pad = optarg;
else
pad = ' ';
break;
case 'N':
// Handle the -N option.
break;
case 0:
// A long option (--verbose) has been parsed, but its
// effect was setting the verbose variable to 1.
break;
}
}
const char* file_name = argv[optind];
```
## See also
* [`getopt`(5)](../man5/getopt.md)
|
