Rev | Author | # | Line |
---|---|---|---|
1 | perry | 1 | !!NAME |
2 | getopt - Parse command line options | ||
3 | !!SYNOPSIS | ||
2 | SamJansen | 4 | __#include <unistd.h>__ |
5 | |||
6 | __int getopt(int __''argc''__, char * const __''argv''__[],__ | ||
7 | __const char *__''optstring''__);__ | ||
8 | |||
9 | __extern char *__''optarg''__;__ | ||
10 | __extern int __''optind''__, __''opterr''__, __''optopt''__;__ | ||
11 | |||
12 | __#define _GNU_SOURCE__ | ||
13 | __#include <getopt.h>__ | ||
14 | |||
15 | __int getopt_long(int __''argc''__, char * const __''argv''__[],__ | ||
16 | __const char *__''optstring''__,__ | ||
17 | __const struct option *__''longopts''__, int *__''longindex''__);__ | ||
18 | |||
19 | __int getopt_long_only(int __''argc''__, char * const __''argv''__[],__ | ||
20 | __const char *__''optstring''__,__ | ||
21 | __const struct option *__''longopts''__, int *__''longindex''__);__ | ||
1 | perry | 22 | |
23 | |||
24 | !!DESCRIPTION | ||
25 | |||
26 | |||
27 | The __getopt()__ function parses the command line | ||
28 | arguments. Its arguments ''argc'' and ''argv'' are the | ||
29 | argument count and array as passed to the __main()__ | ||
30 | function on program invocation. An element of ''argv'' | ||
31 | that starts with `-' (and is not exactly | ||
32 | ''getopt()__ is called repeatedly, it returns | ||
33 | successively each of the option characters from each of the | ||
34 | option elements. | ||
35 | |||
36 | |||
37 | If __getopt()__ finds another option character, it | ||
38 | returns that character, updating the external variable | ||
39 | ''optind'' and a static variable ''nextchar'' so that | ||
40 | the next call to __getopt()__ can resume the scan with | ||
41 | the following option character or | ||
42 | ''argv''-element. | ||
43 | |||
44 | |||
45 | If there are no more option characters, __getopt()__ | ||
46 | returns -1. Then ''optind'' is the index in ''argv'' | ||
47 | of the first ''argv''-element that is not an | ||
48 | option. | ||
49 | |||
50 | |||
51 | ''optstring'' is a string containing the legitimate | ||
52 | option characters. If such a character is followed by a | ||
53 | colon, the option requires an argument, so __getopt__ | ||
54 | places a pointer to the following text in the same | ||
55 | ''argv''-element, or the text of the following | ||
56 | ''argv''-element, in ''optarg''. Two colons mean an | ||
57 | option takes an optional arg; if there is text in the | ||
58 | current ''argv''-element, it is returned in | ||
59 | ''optarg'', otherwise ''optarg'' is set to zero. This | ||
60 | is a GNU extension. If ''optstring'' contains __W__ | ||
61 | followed by a semicolon, then __-W foo__ is treated as | ||
62 | the long option __--foo__. (The __-W__ option is | ||
63 | reserved by POSIX.2 for implementation extensions.) This | ||
64 | behaviour is a GNU extension, not available with libraries | ||
65 | before GNU libc 2. | ||
66 | |||
67 | |||
68 | By default, __getopt()__ permutes the contents of | ||
69 | ''argv'' as it scans, so that eventually all the | ||
70 | non-options are at the end. Two other modes are also | ||
71 | implemented. If the first character of ''optstring'' is | ||
72 | `+' or the environment variable POSIXLY_CORRECT is set, then | ||
73 | option processing stops as soon as a non-option argument is | ||
74 | encountered. If the first character of ''optstring'' is | ||
75 | `-', then each non-option ''argv''-element is handled as | ||
76 | if it were the argument of an option with character code 1. | ||
77 | (This is used by programs that were written to expect | ||
78 | options and other ''argv''-elements in any order and that | ||
79 | care about the ordering of the two.) The special argument | ||
80 | `--' forces an end of option-scanning regardless of the | ||
81 | scanning mode. | ||
82 | |||
83 | |||
84 | If __getopt()__ does not recognize an option character, | ||
85 | it prints an error message to stderr, stores the character | ||
86 | in ''optopt'', and returns `?'. The calling program may | ||
87 | prevent the error message by setting ''opterr'' to | ||
88 | 0. | ||
89 | |||
90 | |||
91 | The __getopt_long()__ function works like __getopt()__ | ||
92 | except that it also accepts long options, started out by two | ||
93 | dashes. Long option names may be abbreviated if the | ||
94 | abbreviation is unique or is an exact match for some defined | ||
95 | option. A long option may take a parameter, of the form | ||
96 | __--arg=param__ or __--arg param__. | ||
97 | |||
98 | |||
99 | ''longopts'' is a pointer to the first element of an | ||
100 | array of __struct option__ declared in | ||
101 | ____ as | ||
102 | |||
103 | |||
2 | SamJansen | 104 | struct option { |
105 | const char *name; | ||
106 | int has_arg; | ||
107 | int *flag; | ||
108 | int val; | ||
109 | }; | ||
110 | |||
1 | perry | 111 | The meanings of the different fields are: |
112 | |||
113 | |||
114 | ''name'' | ||
115 | |||
116 | |||
117 | is the name of the long option. | ||
118 | |||
119 | |||
120 | ''has_arg'' | ||
121 | |||
122 | |||
123 | is: __no_argument__ (or 0) if the option does not take an | ||
124 | argument, __required_argument__ (or 1) if the option | ||
125 | requires an argument, or __optional_argument__ (or 2) if | ||
126 | the option takes an optional argument. | ||
127 | |||
128 | |||
129 | ''flag'' | ||
130 | |||
131 | |||
132 | specifies how results are returned for a long option. If | ||
133 | ''flag'' is __NULL__, then __getopt_long()__ | ||
134 | returns ''val''. (For example, the calling program may | ||
135 | set ''val'' to the equivalent short option character.) | ||
136 | Otherwise, __getopt_long()__ returns 0, and ''flag'' | ||
137 | points to a variable which is set to ''val'' if the | ||
138 | option is found, but left unchanged if the option is not | ||
139 | found. | ||
140 | |||
141 | |||
142 | ''val'' | ||
143 | |||
144 | |||
145 | is the value to return, or to load into the variable pointed | ||
146 | to by ''flag''. | ||
147 | |||
148 | |||
149 | The last element of the array has to be filled with | ||
150 | zeroes. | ||
151 | |||
152 | |||
153 | If ''longindex'' is not __NULL__, it points to a | ||
154 | variable which is set to the index of the long option | ||
155 | relative to ''longopts''. | ||
156 | |||
157 | |||
158 | __getopt_long_only()__ is like __getopt_long()__, but | ||
159 | `-' as well as `--' can indicate a long option. If an option | ||
160 | that starts with `-' (not `--') doesn't match a long option, | ||
161 | but does match a short option, it is parsed as a short | ||
162 | option instead. | ||
163 | |||
2 | SamJansen | 164 | |
165 | !!RETURN VALUE | ||
1 | perry | 166 | |
167 | The __getopt()__ function returns the option character if | ||
168 | the option was found successfully, `:' if there was a | ||
169 | missing parameter for one of the options, `?' for an unknown | ||
170 | option character, or -1 for the end of the option | ||
171 | list. | ||
172 | |||
173 | |||
174 | __getopt_long()__ and __getopt_long_only()__ also | ||
175 | return the option character when a short option is | ||
176 | recognized. For a long option, they return ''val'' if | ||
177 | ''flag'' is __NULL__, and 0 otherwise. Error and -1 | ||
178 | returns are the same as for __getopt()__, plus `?' for an | ||
179 | ambiguous match or an extraneous parameter. | ||
180 | !!ENVIRONMENT VARIABLES | ||
181 | |||
182 | |||
183 | __POSIXLY_CORRECT__ | ||
184 | |||
185 | |||
186 | If this is set, then option processing stops as soon as a | ||
187 | non-option argument is encountered. | ||
188 | |||
3 | SamJansen | 189 | ___<PID>_GNU_nonoption_argv_flags___ |
1 | perry | 190 | |
191 | This variable was used by __bash__ 2.0 to communicate to | ||
192 | GNU libc which arguments are the results of wildcard | ||
193 | expansion and so should not be considered as options. This | ||
194 | behaviour was removed in __bash__ version 2.01, but the | ||
195 | support remains in GNU libc. | ||
196 | !!EXAMPLE | ||
197 | |||
198 | |||
199 | The following example program illustrates the use of | ||
200 | __getopt_long()__ with most of its features. | ||
2 | SamJansen | 201 | |
202 | #include <stdio.h> /* for printf */ | ||
203 | #include <stdlib.h> /* for exit */ | ||
204 | #include <getopt.h> | ||
205 | |||
206 | int | ||
207 | main (int argc, char **argv) { | ||
208 | int c; | ||
209 | int digit_optind = 0; | ||
210 | |||
211 | while (1) { | ||
212 | int this_option_optind = optind ? optind : 1; | ||
213 | int option_index = 0; | ||
214 | static struct option long_options[] = { | ||
215 | {"add", 1, 0, 0}, | ||
216 | {"append", 0, 0, 0}, | ||
217 | {"delete", 1, 0, 0}, | ||
218 | {"verbose", 0, 0, 0}, | ||
219 | {"create", 1, 0, 'c'}, | ||
220 | {"file", 1, 0, 0}, | ||
221 | {0, 0, 0, 0} | ||
222 | }; | ||
223 | |||
224 | c = getopt_long (argc, argv, "abc:d:012", | ||
225 | long_options, &option_index); | ||
226 | if (c == -1) | ||
227 | break; | ||
228 | |||
229 | switch (c) { | ||
230 | case 0: | ||
4 | CraigBox | 231 | printf ("option %s", long_options[[option_index].name); |
2 | SamJansen | 232 | if (optarg) |
233 | printf (" with arg %s", optarg); | ||
234 | printf ("\n"); | ||
235 | break; | ||
236 | |||
237 | case '0': | ||
238 | case '1': | ||
239 | case '2': | ||
240 | if (digit_optind != 0 && digit_optind != this_option_optind) | ||
241 | printf ("digits occur in two different argv-elements.\n"); | ||
242 | digit_optind = this_option_optind; | ||
243 | printf ("option %c\n", c); | ||
244 | break; | ||
245 | |||
246 | case 'a': | ||
247 | printf ("option a\n"); | ||
248 | break; | ||
249 | |||
250 | case 'b': | ||
251 | printf ("option b\n"); | ||
252 | break; | ||
253 | |||
254 | case 'c': | ||
255 | printf ("option c with value `%s'\n", optarg); | ||
256 | break; | ||
257 | |||
258 | case 'd': | ||
259 | printf ("option d with value `%s'\n", optarg); | ||
260 | break; | ||
261 | case '?': | ||
262 | break; | ||
263 | |||
264 | default: | ||
265 | printf ("?? getopt returned character code 0%o ??\n", c); | ||
266 | } | ||
267 | } | ||
268 | |||
269 | if (optind < argc) { | ||
270 | printf ("non-option ARGV-elements: "); | ||
271 | while (optind < argc) | ||
4 | CraigBox | 272 | printf ("%s ", argv[[optind++]); |
2 | SamJansen | 273 | printf ("\n"); |
274 | } | ||
275 | |||
276 | exit (0); | ||
277 | } | ||
6 | SamJansen | 278 | |
279 | An short and sweet example of getopt usage: | ||
280 | int ch; /* Butchered out of [tcpperf|http://www.wand.net.nz/~stj2/nsc/software.html] by SamJansen */ | ||
281 | while ((ch = getopt(argc, argv, "c:p:s:")) != -1) | ||
282 | switch (ch) { | ||
283 | case 'c': | ||
284 | /* Client machine to connect to */ | ||
285 | client = optarg; | ||
286 | break; | ||
287 | case 'p': | ||
288 | /* port */ | ||
289 | port = atoi(optarg); | ||
290 | break; | ||
291 | case 's': | ||
292 | write_size = atoi(optarg); | ||
293 | break; | ||
294 | case '?': | ||
295 | default: | ||
296 | usage(argv[[0]); | ||
297 | } | ||
298 | argc -= optind; | ||
299 | argv += optind; | ||
300 | |||
1 | perry | 301 | |
302 | |||
303 | !!BUGS | ||
304 | |||
305 | |||
5 | JohnMcPherson | 306 | The [POSIX].2 specification of __getopt()__ has a technical |
1 | perry | 307 | error described in POSIX.2 Interpretation 150. The GNU |
308 | implementation (and probably all other implementations) | ||
309 | implements the correct behaviour rather than that | ||
310 | specified. | ||
311 | !!CONFORMING TO | ||
312 | |||
313 | |||
314 | __getopt()__: | ||
315 | |||
316 | |||
5 | JohnMcPherson | 317 | [POSIX].2, provided the environment variable [POSIXLY_CORRECT] |
1 | perry | 318 | is set. Otherwise, the elements of ''argv'' aren't really |
319 | const, because we permute them. We pretend they're const in | ||
320 | the prototype to be compatible with other | ||
321 | systems. | ||
7 | DanielLawson | 322 | |
323 | ---- | ||
324 | |||
325 | !NOTES | ||
326 | |||
327 | ! getopt keeps internal state | ||
328 | |||
329 | If you want to use getopt more than once within a program, across different inputs, you'll need to reset its internal state counters before | ||
330 | each use: | ||
331 | |||
332 | <pre> | ||
333 | printf("%d %d %d\n",optind,opterr,optopt); | ||
334 | ... do getopt stuff ... | ||
335 | printf("%d %d %d\n",optind,opterr,optopt); | ||
336 | </pre> | ||
337 | |||
338 | This outputs the following: | ||
339 | |||
340 | <pre> | ||
341 | 1 1 63 | ||
342 | 3 1 63 | ||
343 | </pre> | ||
344 | |||
345 | the '3' in my case is because I only had one option + parameter (+ program name == 3). | ||
346 | |||
347 | So, if you reset optind, opterr and optopt to 1, 1 and 63, before each new use of getopt, you should be fine. | ||
348 | |||
349 | -- DanielLawson |
lib/blame.php:177: Warning: Invalid argument supplied for foreach() (...repeated 6 times)