1CGETOPT_LONG(3) Common Library CGETOPT_LONG(3)
2
6 Cgetopt_long - get long options from command line argument list
7
9 #include <Cgetopt.h>
10 int Cgetopt (int argc, char **argv, char *optstring)
12 int Cgetopt_long (int argc, char **argv, char *optstring, Coptions_t
13 *long_options, int *index)
14
17 The Cgetopt function incrementally parses a command line argument list
18 argv and returns the next known option character. An option character
19 is known if it has been specified in the string of accepted option
20 characters optstring.
21 The Cgetopt_long function is similar to Cgetopt but it accepts options
23 in two forms: words and characters. The Cgetopt_long function provides
24 a superset of the functionality of Cgetopt. The additional functional‐
25 ity is described in the section CGETOPT_LONG.
26 The option string optstring may contain the following elements: indi‐
28 vidual characters, and characters followed by a colon to indicate an
29 option argument is to follow. For example, an option string x recog‐
30 nizes an option x , and an option string x: recognizes an option x tak‐
31 ing an argument. It does not matter to Cgetopt if a following argument
32 has leading white space.
33 On return from Cgetopt, Coptarg points to an option argument, if it is
35 anticipated, and the variable Coptind contains the index to the next
36 argv argument for a subsequent call to Cgetopt. The variable Coptopt
37 saves the last known option character returned by Cgetopt.
38 The variables Copterr and Coptind are both initialized to 1. The
40 Coptind variable may be set to another value before a set of calls to
41 Cgetopt in order to skip over more or less argv entries.
42 In order to use Cgetopt to evaluate multiple sets of arguments, or to
44 evaluate a single set of arguments multiple times, the variable Coptre‐
45 set must be set to 1 before the second and each additional set of calls
46 to Cgetopt and the variable Coptind must be reinitialized.
47 The Cgetopt function returns -1 when the argument list is exhausted, or
49 a non-recognized option is encountered. The interpretation of options
50 in the argument list may be cancelled by the option -- (double dash)
51 which causes Cgetopt to signal the end of argument processing and
52 returns -1. When all options have been processed (i.e., up to the first
53 non-option argument), Cgetopt returns -1. .P Cgetopt_long can be used
54 in two ways. In the first way, every long option understood by the pro‐
55 gram has a coresponding short option, and the option structure is only
56 used to translate from long option to short options. When used in this
57 fashion, Cgetopt_long behaves identically to Cgetopt. This is good way
58 to add long option processing to an existing program with the minimum
59 of rewriting.
60 In the second mechanism, a long option set a flag in the Coptions_t
62 structure passed, or will store a pointer to the command line argument
63 in the Coptions_t structure passed to it for options that take argu‐
64 ments. Additionally, the long option's argument may be specified as a
65 single argument with an equal sign, e.g myprogram --myoption=somevalue
66 When a long option is processed the call to Cgetopt_long will return 0.
68 For this reason, long option processing without shortcuts are not back‐
69 wards compatible with Cgetopt.
70 It is possible to combine these methods, providing for long options
72 processing with short option equivalents for some options. Less fre‐
73 quently used options would be processed as long options only.
74
76 The Cgetopt_long call requires a structure to be initialized describing
77 the long options. The structure is:
78 Coptions_t {
80 char *name;
81 int has_arg;
82 int *flag;
83 int val;
84 };
85 The name field should contain the option name without the leading dou‐
87 ble dash.
88 The has_arg field should be one of: NO_ARGUMENT if no argument to the
90 option is expected, REQUIRED_ARGUMENT if an argument to the option is
91 required or OPTIONAL_ARGUMENT if an argument to the option may be pre‐
92 sented.
93 If flag is non-NULL, then the integer pointed to by it will set to the
95 value in the val field. If the flag field is NULL, then the val field
96 will be returned. Setting flag to NULL and setting val to the corre‐
97 sponding short option will make this function act just like Cgetopt.
98
100 If the Cgetopt function encounters a character not found in the string
101 optstring or detects a missing option argument it writes an error mes‐
102 sage to stderr and returns ?. Setting Copterr to a zero will disable
103 these error messages. If optstring has a leading : then a missing
104 option argument causes a : to be returned in addition to suppressing
105 any error messages.
106 Option arguments are allowed to begin with - ; this is reasonable but
108 reduces the amount of error checking possible.
109
111 The Coptreset variable was added to make it possible to call the Cge‐
112 topt function multiple times. This is an extension to the -p1003.2
113 specification.
114
116 #include <Cgetopt.h>
117 int bflag, ch, fd;
118 Coptind = 1; /* Required */
120 Copterr = 1; /* Some stderr output if you want */
121 bflag = 0;
123 while ((ch = Cgetopt(argc, argv, "bf:")) != -1)
124 switch(ch) {
125 case 'b':
126 bflag = 1;
127 break;
128 case 'f':
129 if ((fd = open(Coptarg, O_RDONLY, 0)) < 0) {
130 (void)fprintf(stderr,
131 "myname: %s: %s\n", Coptarg, strerror(errno));
132 exit(1);
133 }
134 break;
135 case '?':
136 default:
137 usage();
138 }
139 argc -= Coptind;
140 argv += Coptind;
141
143 #include <Cgetopt.h>
144 int bflag, ch, fd;
145 int daggerset;
146 /* options descriptor */
148 Coptions_t longopts[] =
149 {
150 {"buffy", NO_ARGUMENT, NULL, 'b'},
151 {"floride", REQUIRED_ARGUMENT, NULL, 'f'},
152 {"daggerset", NO_ARGUMENT, &daggerset, 1},
153 {NULL, 0, NULL, 0}
154 };
155 Coptind = 1; /* Required */
157 Copterr = 1; /* Some stderr output if you want */
158 bflag = 0;
160 while ((ch = Cgetopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
161 switch(ch) {
162 case 'b':
163 bflag = 1;
164 break;
165 case 'f':
166 if ((fd = open(Coptarg, O_RDONLY, 0)) < 0) {
167 (void)fprintf(stderr,
168 "myname: %s: %s\n", Coptarg, strerror(errno));
169 exit(1);
170 }
171 break;
172 case 0:
173 if(daggerset) {
174 fprintf(stderr,"Buffy will put use her dagger"
175 "to apply floride to dracula's teeth");
176 }
177 break;
178 case '?':
179 default:
180 usage();
181 }
182 argc -= Coptind;
183 argv += Coptind;
184
186 The Cgetopt function appeared in BSD 4.3. The Cgetopt_long function
187 first appeared in GNU library. This implementation was imported to Net‐
188 BSD from a Kerberos distribution.
189
191 The Cgetopt function was once specified to return EOF instead of -1.
192 This was changed by -p1003.2-92 to decouple Cgetopt from <stdio.h>.
193 A single dash - may be specified as an character in optstring, however
195 it should never have an argument associated with it. This allows Cge‐
196 topt to be used with programs that expect - as an option flag. This
197 practice is wrong, and should not be used in any current development.
198 It is provided for backward compatibility only. By default, a single
199 dash causes Cgetopt to return -1. This is, we believe, compatible with
200 System V.
201 It is also possible to handle digits as option letters. This allows
203 Cgetopt to be used with programs that expect a number -3 as an option.
204 This practice is wrong, and should not be used in any current develop‐
205 ment. It is provided for backward compatibility only. The following
206 code fragment works in most cases.
207 int length;
209 char *p;
210 Coptind = 1; /* Required */
212 Copterr = 1; /* Some stderr output if you want */
213 while ((c = Cgetopt(argc, argv, "0123456789")) != -1)
215 switch (c) {
216 case '0': case '1': case '2': case '3': case '4':
217 case '5': case '6': case '7': case '8': case '9':
218 p = argv[Coptind - 1];
219 if (p[0] == '-' && p[1] == ch && !p[2])
220 length = atoi(++p);
221 else
222 length = atoi(argv[Coptind] + 1);
223 break;
224 }
225 }
226 The OPTIONAL_ARGUMENT always eats the following argument unless the
228 argument is included via the --option=argument notation.
229
231 Copyright (c) 1988, 1991, 1993 The Regents of the University of Cali‐
232 fornia. All rights reserved.
233 Redistribution and use in source and binary forms, with or without mod‐
234 ification, are permitted provided that the following conditions are
235 met:
236 1. Redistributions of source code must retain the above copyright
237 notice, this list of conditions and the following disclaimer.
238 2. Redistributions in binary form must reproduce the above copyright
239 notice, this list of conditions and the following disclaimer in the
240 documentation and/or other materials provided with the distribution.
241 3. All advertising materials mentioning features or use of this soft‐
242 ware must display the following acknowledgement: This product includes
243 software developed by the University of California, Berkeley and its
244 contributors.
245 4. Neither the name of the University nor the names of its contributors
246 may be used to endorse or promote products derived from this software
247 without specific prior written permission.
248 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
249 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
250 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR‐
251 POSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
252 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
253 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
254 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI‐
255 NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
256 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
257 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
258 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
259LCG $Date: 2010-04-05 09:51:26 +0200 (Mon, 05 Apr 2010)CG$ETOPT_LONG(3)