Penguin
Recent Changes
Blame: getopt_long_only(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of getopt_long_only(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 GETOPT
2 !!!GETOPT
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 ENVIRONMENT VARIABLES
8 EXAMPLE
9 BUGS
10 CONFORMING TO
11 ----
12 !!NAME
13
14
15 getopt - Parse command line options
16 !!SYNOPSIS
17
18
19 __#include
20 __ ''argc''__, char * const__ ''argv[[]''__,
21 const char *__''optstring''__);
22 extern char *__''optarg''__;
23 extern int__ ''optind''__,__ ''opterr''__,__ ''optopt''__;
24 #define _GNU_SOURCE
25 #include
26 __ ''argc''__, char * const__ ''argv[[]''__,
27 const char *__''optstring''__,
28 const struct option *__''longopts''__, int *__''longindex''__);
29 int getopt_long_only(int__ ''argc''__, char * const__ ''argv[[]''__,
30 const char *__''optstring''__,
31 const struct option *__''longopts''__, int *__''longindex''__);
32 __
33 !!DESCRIPTION
34
35
36 The __getopt()__ function parses the command line
37 arguments. Its arguments ''argc'' and ''argv'' are the
38 argument count and array as passed to the __main()__
39 function on program invocation. An element of ''argv''
40 that starts with `-' (and is not exactly
41 ''getopt()__ is called repeatedly, it returns
42 successively each of the option characters from each of the
43 option elements.
44
45
46 If __getopt()__ finds another option character, it
47 returns that character, updating the external variable
48 ''optind'' and a static variable ''nextchar'' so that
49 the next call to __getopt()__ can resume the scan with
50 the following option character or
51 ''argv''-element.
52
53
54 If there are no more option characters, __getopt()__
55 returns -1. Then ''optind'' is the index in ''argv''
56 of the first ''argv''-element that is not an
57 option.
58
59
60 ''optstring'' is a string containing the legitimate
61 option characters. If such a character is followed by a
62 colon, the option requires an argument, so __getopt__
63 places a pointer to the following text in the same
64 ''argv''-element, or the text of the following
65 ''argv''-element, in ''optarg''. Two colons mean an
66 option takes an optional arg; if there is text in the
67 current ''argv''-element, it is returned in
68 ''optarg'', otherwise ''optarg'' is set to zero. This
69 is a GNU extension. If ''optstring'' contains __W__
70 followed by a semicolon, then __-W foo__ is treated as
71 the long option __--foo__. (The __-W__ option is
72 reserved by POSIX.2 for implementation extensions.) This
73 behaviour is a GNU extension, not available with libraries
74 before GNU libc 2.
75
76
77 By default, __getopt()__ permutes the contents of
78 ''argv'' as it scans, so that eventually all the
79 non-options are at the end. Two other modes are also
80 implemented. If the first character of ''optstring'' is
81 `+' or the environment variable POSIXLY_CORRECT is set, then
82 option processing stops as soon as a non-option argument is
83 encountered. If the first character of ''optstring'' is
84 `-', then each non-option ''argv''-element is handled as
85 if it were the argument of an option with character code 1.
86 (This is used by programs that were written to expect
87 options and other ''argv''-elements in any order and that
88 care about the ordering of the two.) The special argument
89 `--' forces an end of option-scanning regardless of the
90 scanning mode.
91
92
93 If __getopt()__ does not recognize an option character,
94 it prints an error message to stderr, stores the character
95 in ''optopt'', and returns `?'. The calling program may
96 prevent the error message by setting ''opterr'' to
97 0.
98
99
100 The __getopt_long()__ function works like __getopt()__
101 except that it also accepts long options, started out by two
102 dashes. Long option names may be abbreviated if the
103 abbreviation is unique or is an exact match for some defined
104 option. A long option may take a parameter, of the form
105 __--arg=param__ or __--arg param__.
106
107
108 ''longopts'' is a pointer to the first element of an
109 array of __struct option__ declared in
110 ____ as
111
112
113 struct option {
114 const char *name;
115 int has_arg;
116 int *flag;
117 int val;
118 };
119 The meanings of the different fields are:
120
121
122 ''name''
123
124
125 is the name of the long option.
126
127
128 ''has_arg''
129
130
131 is: __no_argument__ (or 0) if the option does not take an
132 argument, __required_argument__ (or 1) if the option
133 requires an argument, or __optional_argument__ (or 2) if
134 the option takes an optional argument.
135
136
137 ''flag''
138
139
140 specifies how results are returned for a long option. If
141 ''flag'' is __NULL__, then __getopt_long()__
142 returns ''val''. (For example, the calling program may
143 set ''val'' to the equivalent short option character.)
144 Otherwise, __getopt_long()__ returns 0, and ''flag''
145 points to a variable which is set to ''val'' if the
146 option is found, but left unchanged if the option is not
147 found.
148
149
150 ''val''
151
152
153 is the value to return, or to load into the variable pointed
154 to by ''flag''.
155
156
157 The last element of the array has to be filled with
158 zeroes.
159
160
161 If ''longindex'' is not __NULL__, it points to a
162 variable which is set to the index of the long option
163 relative to ''longopts''.
164
165
166 __getopt_long_only()__ is like __getopt_long()__, but
167 `-' as well as `--' can indicate a long option. If an option
168 that starts with `-' (not `--') doesn't match a long option,
169 but does match a short option, it is parsed as a short
170 option instead.
171 !!RETURN VALUE
172
173
174 The __getopt()__ function returns the option character if
175 the option was found successfully, `:' if there was a
176 missing parameter for one of the options, `?' for an unknown
177 option character, or -1 for the end of the option
178 list.
179
180
181 __getopt_long()__ and __getopt_long_only()__ also
182 return the option character when a short option is
183 recognized. For a long option, they return ''val'' if
184 ''flag'' is __NULL__, and 0 otherwise. Error and -1
185 returns are the same as for __getopt()__, plus `?' for an
186 ambiguous match or an extraneous parameter.
187 !!ENVIRONMENT VARIABLES
188
189
190 __POSIXLY_CORRECT__
191
192
193 If this is set, then option processing stops as soon as a
194 non-option argument is encountered.
195
196
197 _____
198
199
200 This variable was used by __bash__ 2.0 to communicate to
201 GNU libc which arguments are the results of wildcard
202 expansion and so should not be considered as options. This
203 behaviour was removed in __bash__ version 2.01, but the
204 support remains in GNU libc.
205 !!EXAMPLE
206
207
208 The following example program illustrates the use of
209 __getopt_long()__ with most of its features.
210
211
212 #include
213 !!BUGS
214
215
216 The POSIX.2 specification of __getopt()__ has a technical
217 error described in POSIX.2 Interpretation 150. The GNU
218 implementation (and probably all other implementations)
219 implements the correct behaviour rather than that
220 specified.
221 !!CONFORMING TO
222
223
224 __getopt()__:
225
226
227 POSIX.2, provided the environment variable POSIXLY_CORRECT
228 is set. Otherwise, the elements of ''argv'' aren't really
229 const, because we permute them. We pretend they're const in
230 the prototype to be compatible with other
231 systems.
232 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.