1CGETOPT_LONG(3)                           Common          Library
2CGETOPT_LONG(3)
3
4
5
6[1mNAME[0m
7       Cgetopt_long ‐ get long options from command line argument
8list
9
10[1mSYNOPSIS[0m
11       [1m#include <Cgetopt.h>[0m
12
13       [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
21
22[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
31       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
39       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
51       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
60       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
67       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
76       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
100       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
111       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
117       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
124[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
129       [1mCoptions_t {[0m
130           char *name;
131           int has_arg;
132           int *flag;
133           int val;
134       };
135
136       The   [4mname[24m  field  should  contain  the option name
137without the leading dou‐
138       ble dash.
139
140       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
148       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
157[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
170       Option  arguments  are allowed to begin  with  [1m‐  [22m;
171this is reasonable but
172       reduces the amount of error checking possible.
173
174[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
181[1mEXAMPLE[0m
182       #include <Cgetopt.h>
183       int bflag, ch, fd;
184
185       Coptind = 1;            /* Required */
186       Copterr  = 1;            /* Some stderr output if you want
187*/
188
189       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
210[1mLONG EXAMPLE[0m
211       #include <Cgetopt.h>
212       int bflag, ch, fd;
213       int daggerset;
214
215       /* 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
224       Coptind = 1;            /* Required */
225       Copterr  = 1;            /* Some stderr output if you want
226*/
227
228       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
258[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
265[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
271       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
285       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
295       int length;
296       char *p;
297
298       Coptind = 1;            /* Required */
299       Copterr = 1;            /* Some stderr output if you  want
300*/
301
302       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
315       The  [1mOPTIONAL_ARGUMENT  [22malways  eats  the following
316argument unless the
317       argument is included via the [1m‐‐option=argument  [22mno‐
318tation.
319
320[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.
372
373
374
375LCG                                                        $Date$
376CGETOPT_LONG(3)
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
Impressum