1CGETOPT_LONG(3) Common Library
2CGETOPT_LONG(3)
3[1mNAME[0m
7 Cgetopt_long ‐ get long options from command line argument
8list
9[1mSYNOPSIS[0m
11 [1m#include <Cgetopt.h>[0m
12 [1mint Cgetopt (int [4m[22margc[24m[1m, char
14**[4m[22margv[24m[1m, char *[4m[22moptstring[24m[1m)[0m
15 [1mint Cgetopt_long (int [4m[22margc[24m[1m, char
16**[4m[22margv[24m[1m, char *[4m[22moptstring[24m[1m, Cop‐
17tions_t[0m
18 [1m*[4m[22mlong_options[24m[1m, int *[4m[22min‐
19dex[24m[1m)[0m
20[1mDESCRIPTION[0m
23 The [1mCgetopt [22mfunction incrementally parses a command
24line argument list
25 [4margv[24m and returns the next known option character.
26An option character
27 is known if it has been specified in the string of ac‐
28cepted option
29 characters [4moptstring[24m.
30 The [1mCgetopt_long [22mfunction is similar to [1mCgetopt
32[22mbut it accepts options
33 in two forms: words and characters. The [1mCgetopt_long
34[22mfunction provides
35 a superset of the functionality of [1mCgetopt[22m. The
36additional functional‐
37 ity is described in the section CGETOPT_LONG.
38 The option string [4moptstring[24m may contain the follow‐
40ing elements: indi‐
41 vidual characters, and characters followed by a colon
42to indicate an
43 option argument is to follow. For example, an option
44string [1mx [22mrecog‐
45 nizes an option [1mx , [22mand an option string [1mx:
46[22mrecognizes an option [1mx [22mtak‐
47 ing an argument. It does not matter to [1mCgetopt [22mif
48a following argument
49 has leading white space.
50 On return from [1mCgetopt[22m, [1mCoptarg [22mpoints to
52an option argument, if it is
53 anticipated, and the variable [1mCoptind [22mcontains the
54index to the next
55 [4margv[24m argument for a subsequent call to [1mCge‐
56topt[22m. The variable [1mCoptopt[0m
57 saves the last known option character returned by [1mCge‐
58topt[22m.
59 The variables [1mCopterr [22mand [1mCoptind [22mare both
61initialized to 1. The
62 [1mCoptind [22mvariable may be set to another value be‐
63fore a set of calls to
64 [1mCgetopt [22min order to skip over more or less argv en‐
65tries.
66 In order to use [1mCgetopt [22mto evaluate multiple sets
68of arguments, or to
69 evaluate a single set of arguments multiple times, the
70variable [1mCoptre‐[0m
71 [1mset [22mmust be set to 1 before the second and each ad‐
72ditional set of calls
73 to [1mCgetopt [22mand the variable [1mCoptind [22mmust be
74reinitialized.
75 The [1mCgetopt [22mfunction returns ‐1 when the argument
77list is exhausted, or
78 a non‐recognized option is encountered. The interpreta‐
79tion of options
80 in the argument list may be cancelled by the option
81[1m‐‐ [22m(double dash)
82 which causes [1mCgetopt [22mto signal the end of argu‐
83ment processing and
84 returns ‐1. When all options have been processed (i.e., up
85to the first
86 non‐option argument), [1mCgetopt [22mreturns ‐1. .P
87[1mCgetopt_long [22mcan be used
88 in two ways. In the first way, every long option under‐
89stood by the pro‐
90 gram has a coresponding short option, and the option
91structure is only
92 used to translate from long option to short options. When
93used in this
94 fashion, [1mCgetopt_long [22mbehaves identically to
95[1mCgetopt[22m. This is good way
96 to add long option processing to an existing program
97with the minimum
98 of rewriting.
99 In the second mechanism, a long option set a flag in
101the [1mCoptions_t[0m
102 structure passed, or will store a pointer to the command
103line argument
104 in the [1mCoptions_t [22mstructure passed to it for op‐
105tions that take argu‐
106 ments. Additionally, the long option’s argument may be
107specified as a
108 single argument with an equal sign, e.g [1mmyprogram ‐‐my‐
109option=somevalue[0m
110 When a long option is processed the call to [1mCge‐
112topt_long [22mwill return 0.
113 For this reason, long option processing without shortcuts
114are not back‐
115 wards compatible with [1mCgetopt.[0m
116 It is possible to combine these methods, providing for
118long options
119 processing with short option equivalents for some op‐
120tions. Less fre‐
121 quently used options would be processed as long options
122only.
123[1mUSAGE OF CGETOPT_LONG[0m
125 The [1mCgetopt_long [22mcall requires a structure to be
126initialized describing
127 the long options. The structure is:
128 [1mCoptions_t {[0m
130 char *name;
131 int has_arg;
132 int *flag;
133 int val;
134 };
135 The [4mname[24m field should contain the option name
137without the leading dou‐
138 ble dash.
139 The [4mhas_arg[24m field should be one of: [1mNO_ARGUMENT
141[22mif no argument to the
142 option is expected, [1mREQUIRED_ARGUMENT [22mif an argu‐
143ment to the option is
144 required or [1mOPTIONAL_ARGUMENT [22mif an argument to the
145option may be pre‐
146 sented.
147 If [4mflag[24m is non‐NULL, then the integer pointed to
149by it will set to the
150 value in the [4mval[24m field. If the [4mflag[24m field is
151NULL, then the [4mval[24m field
152 will be returned. Setting [4mflag[24m to NULL and set‐
153ting [4mval[24m to the corre‐
154 sponding short option will make this function act just
155like [1mCgetopt[22m.
156[1mDIAGNOSTICS[0m
158 If the [1mCgetopt [22mfunction encounters a character not
159found in the string
160 [4moptstring[24m or detects a missing option argument it
161writes an error mes‐
162 sage to [1mstderr [22mand returns [1m?[22m. Setting
163[1mCopterr [22mto a zero will disable
164 these error messages. If [4moptstring[24m has a
165leading [1m: [22mthen a missing
166 option argument causes a [1m: [22mto be returned in addi‐
167tion to suppressing
168 any error messages.
169 Option arguments are allowed to begin with [1m‐ [22m;
171this is reasonable but
172 reduces the amount of error checking possible.
173[1mCGETOPT_LONG EXTENSIONS[0m
175 The [1mCoptreset [22mvariable was added to make it possi‐
176ble to call the [1mCge‐[0m
177 [1mtopt [22mfunction multiple times. This is an ex‐
178tension to the [1m‐p1003.2[0m
179 specification.
180[1mEXAMPLE[0m
182 #include <Cgetopt.h>
183 int bflag, ch, fd;
184 Coptind = 1; /* Required */
186 Copterr = 1; /* Some stderr output if you want
187*/
188 bflag = 0;
190 while ((ch = Cgetopt(argc, argv, "bf:")) != ‐1)
191 switch(ch) {
192 case ’b’:
193 bflag = 1;
194 break;
195 case ’f’:
196 if ((fd = open(Coptarg, O_RDONLY, 0)) < 0) {
197 (void)fprintf(stderr,
198 "myname: %s: %s0, Coptarg, strerror(er‐
199rno));
200 exit(1);
201 }
202 break;
203 case ’?’:
204 default:
205 usage();
206 }
207 argc ‐= Coptind;
208 argv += Coptind;
209[1mLONG EXAMPLE[0m
211 #include <Cgetopt.h>
212 int bflag, ch, fd;
213 int daggerset;
214 /* options descriptor */
216 Coptions_t longopts[] =
217 {
218 {"buffy", NO_ARGUMENT, NULL, ’b’},
219 {"floride", REQUIRED_ARGUMENT, NULL, ’f’},
220 {"daggerset", NO_ARGUMENT, &daggerset, 1},
221 {NULL, 0, NULL, 0}
222 };
223 Coptind = 1; /* Required */
225 Copterr = 1; /* Some stderr output if you want
226*/
227 bflag = 0;
229 while ((ch = Cgetopt_long(argc, argv, "bf:", longopts,
230NULL)) != ‐1)
231 switch(ch) {
232 case ’b’:
233 bflag = 1;
234 break;
235 case ’f’:
236 if ((fd = open(Coptarg, O_RDONLY, 0)) < 0) {
237 (void)fprintf(stderr,
238 "myname: %s: %s0, Coptarg, strerror(er‐
239rno));
240 exit(1);
241 }
242 break;
243 case 0:
244 if(daggerset) {
245 fprintf(stderr,"Buffy will put use her dag‐
246ger"
247 "to apply floride to dracula’s
248teeth");
249 }
250 break;
251 case ’?’:
252 default:
253 usage();
254 }
255 argc ‐= Coptind;
256 argv += Coptind;
257[1mHISTORY[0m
259 The [1mCgetopt [22mfunction appeared in BSD 4.3. The
260[1mCgetopt_long [22mfunction
261 first appeared in GNU library. This implementation was im‐
262ported to Net‐
263 BSD from a Kerberos distribution.
264[1mBUGS[0m
266 The [1mCgetopt [22mfunction was once specified to return
267[1mEOF [22minstead of ‐1.
268 This was changed by [1m‐p1003.2‐92 [22mto decouple [1mCge‐
269topt [22mfrom <stdio.h>.
270 A single dash [1m‐ [22mmay be specified as an character
272in [4moptstring[24m, however
273 it should [1mnever [22mhave an argument associated with
274it. This allows [1mCge‐[0m
275 [1mtopt [22mto be used with programs that expect [1m‐
276[22mas an option flag. This
277 practice is wrong, and should not be used in any current
278development.
279 It is provided for backward compatibility [1monly[22m.
280By default, a single
281 dash causes [1mCgetopt [22mto return ‐1. This is, we be‐
282lieve, compatible with
283 System V.
284 It is also possible to handle digits as option letters.
286This allows
287 [1mCgetopt [22mto be used with programs that expect a num‐
288ber [1m‐3 [22mas an option.
289 This practice is wrong, and should not be used in any
290current develop‐
291 ment. It is provided for backward compatibility [1mon‐
292ly[22m. The following
293 code fragment works in most cases.
294 int length;
296 char *p;
297 Coptind = 1; /* Required */
299 Copterr = 1; /* Some stderr output if you want
300*/
301 while ((c = Cgetopt(argc, argv, "0123456789")) != ‐1)
303 switch (c) {
304 case ’0’: case ’1’: case ’2’: case ’3’: case ’4’:
305 case ’5’: case ’6’: case ’7’: case ’8’: case ’9’:
306 p = argv[Coptind ‐ 1];
307 if (p[0] == ’‐’ && p[1] == ch && !p[2])
308 length = atoi(++p);
309 else
310 length = atoi(argv[Coptind] + 1);
311 break;
312 }
313 }
314 The [1mOPTIONAL_ARGUMENT [22malways eats the following
316argument unless the
317 argument is included via the [1m‐‐option=argument [22mno‐
318tation.
319[1mAUTHOR[0m
321 Copyright (c) 1988, 1991, 1993 The Regents of the Univer‐
322sity of Cali‐
323 fornia. All rights reserved.
324 Redistribution and use in source and binary forms, with or
325without mod‐
326 ification, are permitted provided that the following
327conditions are
328 met:
329 1. Redistributions of source code must retain the
330above copyright
331 notice, this list of conditions and the following dis‐
332claimer.
333 2. Redistributions in binary form must reproduce the
334above copyright
335 notice, this list of conditions and the following dis‐
336claimer in the
337 documentation and/or other materials provided with the
338distribution.
339 3. All advertising materials mentioning features or use of
340this soft‐
341 ware must display the following acknowledgement: This
342product includes
343 software developed by the University of California,
344Berkeley and its
345 contributors.
346 4. Neither the name of the University nor the names of its
347contributors
348 may be used to endorse or promote products derived from
349this software
350 without specific prior written permission.
351 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS
352‘‘AS IS’’ AND
353 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIM‐
354ITED TO, THE
355 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
356PARTICULAR PUR‐
357 POSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
358CONTRIBUTORS BE
359 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
360EXEMPLARY, OR
361 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
362PROCUREMENT OF
363 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
364PROFITS; OR BUSI‐
365 NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
366OF LIABILITY,
367 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
368NEGLIGENCE OR
369 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFT‐
370WARE, EVEN IF
371 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
372LCG $Date$
376CGETOPT_LONG(3)
377