]>
Commit | Line | Data |
---|---|---|
b0de3e9e UD |
1 | @node Getopt, Argp, , Parsing Program Arguments |
2 | @section Parsing program options using @code{getopt} | |
3 | ||
4 | The @code{getopt} and @code{getopt_long} functions automate some of the | |
5 | chore involved in parsing typical unix command line options. | |
6 | ||
7 | @menu | |
8 | * Using Getopt:: Using the @code{getopt} function. | |
9 | * Example of Getopt:: An example of parsing options with @code{getopt}. | |
10 | * Getopt Long Options:: GNU suggests utilities accept long-named | |
11 | options; here is one way to do. | |
12 | * Getopt Long Option Example:: An example of using @code{getopt_long}. | |
13 | @end menu | |
14 | ||
15 | @node Using Getopt, Example of Getopt, , Getopt | |
16 | @subsection Using the @code{getopt} function | |
17 | ||
18 | Here are the details about how to call the @code{getopt} function. To | |
19 | use this facility, your program must include the header file | |
20 | @file{unistd.h}. | |
21 | @pindex unistd.h | |
22 | ||
b0de3e9e | 23 | @deftypevar int opterr |
d08a7e4c | 24 | @standards{POSIX.2, unistd.h} |
b0de3e9e UD |
25 | If the value of this variable is nonzero, then @code{getopt} prints an |
26 | error message to the standard error stream if it encounters an unknown | |
27 | option character or an option with a missing required argument. This is | |
28 | the default behavior. If you set this variable to zero, @code{getopt} | |
29 | does not print any messages, but it still returns the character @code{?} | |
30 | to indicate an error. | |
31 | @end deftypevar | |
32 | ||
b0de3e9e | 33 | @deftypevar int optopt |
d08a7e4c | 34 | @standards{POSIX.2, unistd.h} |
b0de3e9e UD |
35 | When @code{getopt} encounters an unknown option character or an option |
36 | with a missing required argument, it stores that option character in | |
37 | this variable. You can use this for providing your own diagnostic | |
38 | messages. | |
39 | @end deftypevar | |
40 | ||
b0de3e9e | 41 | @deftypevar int optind |
d08a7e4c | 42 | @standards{POSIX.2, unistd.h} |
b0de3e9e UD |
43 | This variable is set by @code{getopt} to the index of the next element |
44 | of the @var{argv} array to be processed. Once @code{getopt} has found | |
45 | all of the option arguments, you can use this variable to determine | |
46 | where the remaining non-option arguments begin. The initial value of | |
47 | this variable is @code{1}. | |
48 | @end deftypevar | |
49 | ||
b0de3e9e | 50 | @deftypevar {char *} optarg |
d08a7e4c | 51 | @standards{POSIX.2, unistd.h} |
b0de3e9e UD |
52 | This variable is set by @code{getopt} to point at the value of the |
53 | option argument, for those options that accept arguments. | |
54 | @end deftypevar | |
55 | ||
8ded91fb | 56 | @deftypefun int getopt (int @var{argc}, char *const *@var{argv}, const char *@var{options}) |
d08a7e4c | 57 | @standards{POSIX.2, unistd.h} |
a7b90ea9 AO |
58 | @safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} |
59 | @c Swapping elements of passed-in argv may be partial in case of | |
60 | @c cancellation. Gettext brings about a whole lot of AS and AC safety | |
61 | @c issues. The getopt API involves returning values in the | |
62 | @c non-thread-specific optarg variable, which adds another thread-safety | |
63 | @c issue. Given print_errors, it may output errors to stderr, which may | |
64 | @c self-deadlock, leak locks, or encounter (in a signal handler) or | |
65 | @c leave (in case of cancellation) stderr in an inconsistent state. | |
66 | @c Various implicit, indirect uses of malloc, in uses of memstream and | |
67 | @c asprintf for error-printing, bring about the usual malloc issues. | |
a7b90ea9 AO |
68 | @c |
69 | @c _getopt_internal | |
70 | @c _getopt_internal_r | |
71 | @c gettext | |
72 | @c _getopt_initialize | |
73 | @c getenv | |
a7b90ea9 AO |
74 | @c open_memstream |
75 | @c lockfile, unlockfile, __fxprintf -> stderr | |
76 | @c asprintf | |
b0de3e9e UD |
77 | The @code{getopt} function gets the next option argument from the |
78 | argument list specified by the @var{argv} and @var{argc} arguments. | |
79 | Normally these values come directly from the arguments received by | |
80 | @code{main}. | |
81 | ||
82 | The @var{options} argument is a string that specifies the option | |
83 | characters that are valid for this program. An option character in this | |
84 | string can be followed by a colon (@samp{:}) to indicate that it takes a | |
ec23315f AS |
85 | required argument. If an option character is followed by two colons |
86 | (@samp{::}), its argument is optional; this is a GNU extension. | |
b0de3e9e | 87 | |
dbbbaf53 UD |
88 | @code{getopt} has three ways to deal with options that follow |
89 | non-options @var{argv} elements. The special argument @samp{--} forces | |
90 | in all cases the end of option scanning. | |
91 | ||
92 | @itemize @bullet | |
93 | @item | |
94 | The default is to permute the contents of @var{argv} while scanning it | |
95 | so that eventually all the non-options are at the end. This allows | |
96 | options to be given in any order, even with programs that were not | |
97 | written to expect this. | |
98 | ||
99 | @item | |
b0de3e9e UD |
100 | If the @var{options} argument string begins with a hyphen (@samp{-}), this |
101 | is treated specially. It permits arguments that are not options to be | |
0b9fbf00 | 102 | returned as if they were associated with option character @samp{\1}. |
b0de3e9e | 103 | |
dbbbaf53 | 104 | @item |
954cbda0 | 105 | POSIX demands the following behavior: the first non-option stops option |
dbbbaf53 UD |
106 | processing. This mode is selected by either setting the environment |
107 | variable @code{POSIXLY_CORRECT} or beginning the @var{options} argument | |
108 | string with a plus sign (@samp{+}). | |
109 | @end itemize | |
110 | ||
b0de3e9e UD |
111 | The @code{getopt} function returns the option character for the next |
112 | command line option. When no more option arguments are available, it | |
113 | returns @code{-1}. There may still be more non-option arguments; you | |
114 | must compare the external variable @code{optind} against the @var{argc} | |
115 | parameter to check this. | |
116 | ||
117 | If the option has an argument, @code{getopt} returns the argument by | |
118 | storing it in the variable @var{optarg}. You don't ordinarily need to | |
119 | copy the @code{optarg} string, since it is a pointer into the original | |
120 | @var{argv} array, not into a static area that might be overwritten. | |
121 | ||
122 | If @code{getopt} finds an option character in @var{argv} that was not | |
123 | included in @var{options}, or a missing option argument, it returns | |
124 | @samp{?} and sets the external variable @code{optopt} to the actual | |
125 | option character. If the first character of @var{options} is a colon | |
126 | (@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to | |
127 | indicate a missing option argument. In addition, if the external | |
128 | variable @code{opterr} is nonzero (which is the default), @code{getopt} | |
129 | prints an error message. | |
130 | @end deftypefun | |
131 | ||
132 | @node Example of Getopt | |
133 | @subsection Example of Parsing Arguments with @code{getopt} | |
134 | ||
135 | Here is an example showing how @code{getopt} is typically used. The | |
136 | key points to notice are: | |
137 | ||
138 | @itemize @bullet | |
139 | @item | |
140 | Normally, @code{getopt} is called in a loop. When @code{getopt} returns | |
141 | @code{-1}, indicating no more options are present, the loop terminates. | |
142 | ||
143 | @item | |
144 | A @code{switch} statement is used to dispatch on the return value from | |
145 | @code{getopt}. In typical use, each case just sets a variable that | |
146 | is used later in the program. | |
147 | ||
148 | @item | |
149 | A second loop is used to process the remaining non-option arguments. | |
150 | @end itemize | |
151 | ||
152 | @smallexample | |
153 | @include testopt.c.texi | |
154 | @end smallexample | |
155 | ||
156 | Here are some examples showing what this program prints with different | |
157 | combinations of arguments: | |
158 | ||
159 | @smallexample | |
160 | % testopt | |
161 | aflag = 0, bflag = 0, cvalue = (null) | |
162 | ||
163 | % testopt -a -b | |
164 | aflag = 1, bflag = 1, cvalue = (null) | |
165 | ||
166 | % testopt -ab | |
167 | aflag = 1, bflag = 1, cvalue = (null) | |
168 | ||
169 | % testopt -c foo | |
170 | aflag = 0, bflag = 0, cvalue = foo | |
171 | ||
172 | % testopt -cfoo | |
173 | aflag = 0, bflag = 0, cvalue = foo | |
174 | ||
175 | % testopt arg1 | |
176 | aflag = 0, bflag = 0, cvalue = (null) | |
177 | Non-option argument arg1 | |
178 | ||
179 | % testopt -a arg1 | |
180 | aflag = 1, bflag = 0, cvalue = (null) | |
181 | Non-option argument arg1 | |
182 | ||
183 | % testopt -c foo arg1 | |
184 | aflag = 0, bflag = 0, cvalue = foo | |
185 | Non-option argument arg1 | |
186 | ||
187 | % testopt -a -- -b | |
188 | aflag = 1, bflag = 0, cvalue = (null) | |
189 | Non-option argument -b | |
190 | ||
191 | % testopt -a - | |
192 | aflag = 1, bflag = 0, cvalue = (null) | |
193 | Non-option argument - | |
194 | @end smallexample | |
195 | ||
196 | @node Getopt Long Options | |
197 | @subsection Parsing Long Options with @code{getopt_long} | |
198 | ||
199 | To accept GNU-style long options as well as single-character options, | |
200 | use @code{getopt_long} instead of @code{getopt}. This function is | |
201 | declared in @file{getopt.h}, not @file{unistd.h}. You should make every | |
202 | program accept long options if it uses any options, for this takes | |
203 | little extra work and helps beginners remember how to use the program. | |
204 | ||
b0de3e9e | 205 | @deftp {Data Type} {struct option} |
d08a7e4c | 206 | @standards{GNU, getopt.h} |
b0de3e9e UD |
207 | This structure describes a single long option name for the sake of |
208 | @code{getopt_long}. The argument @var{longopts} must be an array of | |
209 | these structures, one for each long option. Terminate the array with an | |
210 | element containing all zeros. | |
211 | ||
212 | The @code{struct option} structure has these fields: | |
213 | ||
214 | @table @code | |
215 | @item const char *name | |
216 | This field is the name of the option. It is a string. | |
217 | ||
218 | @item int has_arg | |
219 | This field says whether the option takes an argument. It is an integer, | |
220 | and there are three legitimate values: @w{@code{no_argument}}, | |
221 | @code{required_argument} and @code{optional_argument}. | |
222 | ||
223 | @item int *flag | |
224 | @itemx int val | |
225 | These fields control how to report or act on the option when it occurs. | |
226 | ||
227 | If @code{flag} is a null pointer, then the @code{val} is a value which | |
228 | identifies this option. Often these values are chosen to uniquely | |
229 | identify particular long options. | |
230 | ||
231 | If @code{flag} is not a null pointer, it should be the address of an | |
232 | @code{int} variable which is the flag for this option. The value in | |
233 | @code{val} is the value to store in the flag to indicate that the option | |
234 | was seen. | |
235 | @end table | |
236 | @end deftp | |
237 | ||
604febba | 238 | @deftypefun int getopt_long (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr}) |
d08a7e4c | 239 | @standards{GNU, getopt.h} |
a7b90ea9 AO |
240 | @safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} |
241 | @c Same issues as getopt. | |
b0de3e9e UD |
242 | Decode options from the vector @var{argv} (whose length is @var{argc}). |
243 | The argument @var{shortopts} describes the short options to accept, just as | |
244 | it does in @code{getopt}. The argument @var{longopts} describes the long | |
245 | options to accept (see above). | |
246 | ||
247 | When @code{getopt_long} encounters a short option, it does the same | |
248 | thing that @code{getopt} would do: it returns the character code for the | |
954cbda0 | 249 | option, and stores the option's argument (if it has one) in @code{optarg}. |
b0de3e9e UD |
250 | |
251 | When @code{getopt_long} encounters a long option, it takes actions based | |
252 | on the @code{flag} and @code{val} fields of the definition of that | |
253 | option. | |
254 | ||
255 | If @code{flag} is a null pointer, then @code{getopt_long} returns the | |
256 | contents of @code{val} to indicate which option it found. You should | |
257 | arrange distinct values in the @code{val} field for options with | |
258 | different meanings, so you can decode these values after | |
259 | @code{getopt_long} returns. If the long option is equivalent to a short | |
260 | option, you can use the short option's character code in @code{val}. | |
261 | ||
262 | If @code{flag} is not a null pointer, that means this option should just | |
263 | set a flag in the program. The flag is a variable of type @code{int} | |
264 | that you define. Put the address of the flag in the @code{flag} field. | |
265 | Put in the @code{val} field the value you would like this option to | |
266 | store in the flag. In this case, @code{getopt_long} returns @code{0}. | |
267 | ||
268 | For any long option, @code{getopt_long} tells you the index in the array | |
269 | @var{longopts} of the options definition, by storing it into | |
270 | @code{*@var{indexptr}}. You can get the name of the option with | |
271 | @code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among | |
272 | long options either by the values in their @code{val} fields or by their | |
273 | indices. You can also distinguish in this way among long options that | |
274 | set flags. | |
275 | ||
276 | When a long option has an argument, @code{getopt_long} puts the argument | |
277 | value in the variable @code{optarg} before returning. When the option | |
278 | has no argument, the value in @code{optarg} is a null pointer. This is | |
279 | how you can tell whether an optional argument was supplied. | |
280 | ||
281 | When @code{getopt_long} has no more options to handle, it returns | |
282 | @code{-1}, and leaves in the variable @code{optind} the index in | |
283 | @var{argv} of the next remaining argument. | |
284 | @end deftypefun | |
285 | ||
954cbda0 RJ |
286 | Since long option names were used before @code{getopt_long} |
287 | was invented there are program interfaces which require programs | |
6062f8d9 UD |
288 | to recognize options like @w{@samp{-option value}} instead of |
289 | @w{@samp{--option value}}. To enable these programs to use the GNU | |
290 | getopt functionality there is one more function available. | |
291 | ||
604febba | 292 | @deftypefun int getopt_long_only (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr}) |
d08a7e4c | 293 | @standards{GNU, getopt.h} |
a7b90ea9 AO |
294 | @safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} |
295 | @c Same issues as getopt. | |
6062f8d9 UD |
296 | |
297 | The @code{getopt_long_only} function is equivalent to the | |
954cbda0 | 298 | @code{getopt_long} function but it allows the user of the |
6062f8d9 UD |
299 | application to pass long options with only @samp{-} instead of |
300 | @samp{--}. The @samp{--} prefix is still recognized but instead of | |
301 | looking through the short options if a @samp{-} is seen it is first | |
302 | tried whether this parameter names a long option. If not, it is parsed | |
303 | as a short option. | |
304 | ||
305 | Assuming @code{getopt_long_only} is used starting an application with | |
306 | ||
307 | @smallexample | |
308 | app -foo | |
309 | @end smallexample | |
310 | ||
311 | @noindent | |
312 | the @code{getopt_long_only} will first look for a long option named | |
313 | @samp{foo}. If this is not found, the short options @samp{f}, @samp{o}, | |
314 | and again @samp{o} are recognized. | |
315 | @end deftypefun | |
316 | ||
b0de3e9e UD |
317 | @node Getopt Long Option Example |
318 | @subsection Example of Parsing Long Options with @code{getopt_long} | |
319 | ||
320 | @smallexample | |
321 | @include longopt.c.texi | |
322 | @end smallexample |