Penguin
Recent Changes
Annotated edit history of getopt(3) version 7, including all changes. View license author blame.
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
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.

PHP Warning

lib/blame.php:177: Warning: Invalid argument supplied for foreach() (...repeated 6 times)