Print this page
9659 Missing man page for getopt_long(3C)
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/getopt.3c.man.txt
+++ new/usr/src/man/man3c/getopt.3c.man.txt
1 1 GETOPT(3C) Standard C Library Functions GETOPT(3C)
2 2
3 3
4 4
5 5 NAME
6 6 getopt - command option parsing
7 7
8 8 SYNOPSIS
9 9 SVID3, XPG3
10 10 #include <stdio.h>
11 11
12 12 int getopt(int argc, char * const argv[], const char *optstring);
13 13
14 14
15 15 extern char *optarg;
16 16
17 17
18 18 extern int optind, opterr, optopt;
19 19
20 20
21 21 POSIX.2, XPG4, SUS, SUSv2, SUSv3
22 22 #include <unistd.h>
23 23
24 24 int getopt(int argc, char * const argv[], const char *optstring);
25 25
26 26
27 27 extern char *optarg;
28 28
29 29
30 30 extern int optind, opterr, optopt;
31 31
32 32
33 33 DESCRIPTION
34 34 The getopt() function is a command line parser that can be used by
35 35 applications that follow Basic Utility Syntax Guidelines 3, 4, 5, 6, 7,
36 36 9, and 10 which parallel those defined by application portability
37 37 standards (see Intro(1)). It can also be used by applications which
38 38 additionally follow the Command Line Interface Paradigm (CLIP) syntax
39 39 extension guidelines 15, 16, and 17. It partially enforces guideline 18
40 40 by requiring that every option has a short-name, but it allows multiple
41 41 long-names to be associated with an option. The remaining guidelines
42 42 are not addressed by getopt() and are the responsibility of the
43 43 application.
44 44
45 45
46 46 The argc and argv arguments are the argument count and argument array
47 47 as passed to main (see exec(2)). The optstring argument specifies the
48 48 acceptable options. For utilities wanting to conform to the Basic
49 49 Utility Syntax Guidelines, optstring is a string of recognized option
50 50 characters. All option characters allowed by Utility Syntax Guideline 3
51 51 are allowed in optstring. If a character is followed by a colon (:),
52 52 the option is expected to have an option-argument, which can be
53 53 separated from it by white space. Utilities wanting to conform to the
54 54 extended CLIP guidelines can specify long-option equivalents to short
55 55 options by following the short-option character (and optional colon)
56 56 with a sequence of strings, each enclosed in parentheses, that specify
57 57 the long-option aliases.
58 58
59 59
60 60 The getopt() function returns the short-option character in optstring
61 61 that corresponds to the next option found in argv.
62 62
63 63
64 64 The getopt() function places in optind the argv index of the next
65 65 argument to be processed. The optind variable is external and is
66 66 initialized to 1 before the first call to getopt(). The getopt()
67 67 function sets the variable optarg to point to the start of the option-
68 68 argument as follows:
69 69
70 70 o If the option is a short option and that character is the
71 71 last character in the argument, then optarg contains the
72 72 next element of argv, and optind is incremented by 2.
73 73
74 74 o If the option is a short option and that character is not
75 75 the last character in the argument, then optarg points to
76 76 the string following the option character in that argument,
77 77 and optind is incremented by 1.
78 78
79 79 o If the option is a long option and the character equals is
80 80 not found in the argument, then optarg contains the next
81 81 element of argv, and optind is incremented by 2.
82 82
83 83 o If the option is a long option and the character equals is
84 84 found in the argument, then optarg points to the string
85 85 following the equals character in that argument and optind
86 86 is incremented by 1.
87 87
88 88
89 89 In all cases, if the resulting value of optind is not less than argc,
90 90 this indicates a missing option-argument and getopt() returns an error
91 91 indication.
92 92
93 93
94 94 When all options have been processed (that is, up to the first
95 95 operand), getopt() returns -1. The special option "--"(two hyphens) can
96 96 be used to delimit the end of the options; when it is encountered, -1
97 97 is returned and "--" is skipped. This is useful in delimiting non-
98 98 option arguments that begin with "-" (hyphen).
99 99
100 100
101 101 If getopt() encounters a short-option character or a long-option string
102 102 not described in the opstring argument, it returns the question-mark
103 103 (?) character. If it detects a missing option-argument, it also returns
104 104 the question-mark (?) character, unless the first character of the
105 105 optstring argument was a colon (:), in which case getopt() returns the
106 106 colon (:) character. For short options, getopt() sets the variable
107 107 optopt to the option character that caused the error. For long options,
108 108 optopt is set to the hyphen (-) character and the failing long option
109 109 can be identified through argv[optind-1]. If the application has not
110 110 set the variable opterr to 0 and the first character of optstring is
111 111 not a colon (:), getopt() also prints a diagnostic message to stderr.
112 112
113 113 RETURN VALUES
114 114 The getopt() function returns the short-option character associated
115 115 with the option recognized.
116 116
117 117
118 118 A colon (:) is returned if getopt() detects a missing argument and the
119 119 first character of optstring was a colon (:).
120 120
121 121
122 122 A question mark (?) is returned if getopt() encounters an option not
123 123 specified in optstring or detects a missing argument and the first
124 124 character of optstring was not a colon (:).
125 125
126 126
127 127 Otherwise, getopt() returns -1 when all command line options are
128 128 parsed.
129 129
130 130 ERRORS
131 131 No errors are defined.
132 132
133 133 EXAMPLES
134 134 Example 1 Parsing Command Line Options
135 135
136 136
137 137 The following code fragment shows how you might process the arguments
138 138 for a utility that can take the mutually-exclusive options a and b and
139 139 the options f and o, both of which require arguments:
140 140
141 141
142 142 #include <unistd.h>
143 143
144 144 int
145 145 main(int argc, char *argv[ ])
146 146 {
147 147 int c;
148 148 int bflg, aflg, errflg;
149 149 char *ifile;
150 150 char *ofile;
151 151 extern char *optarg;
152 152 extern int optind, optopt;
153 153 ...
154 154 while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
155 155 switch(c) {
156 156 case 'a':
157 157 if (bflg)
158 158 errflg++;
159 159 else
160 160 aflg++;
161 161 break;
162 162 case 'b':
163 163 if (aflg)
164 164 errflg++;
165 165 else {
166 166 bflg++;
167 167 bproc();
168 168 }
169 169 break;
170 170 case 'f':
171 171 ifile = optarg;
172 172 break;
173 173 case 'o':
174 174 ofile = optarg;
175 175 break;
176 176 case ':': /* -f or -o without operand */
177 177 fprintf(stderr,
178 178 "Option -%c requires an operand\n", optopt);
179 179 errflg++;
180 180 break;
181 181 case '?':
182 182 fprintf(stderr,
183 183 "Unrecognized option: -%c\n", optopt);
184 184 errflg++;
185 185 }
186 186 }
187 187 if (errflg) {
188 188 fprintf(stderr, "usage: ... ");
189 189 exit(2);
190 190 }
191 191 for ( ; optind < argc; optind++) {
192 192 if (access(argv[optind], R_OK)) {
193 193 ...
194 194 }
195 195
196 196
197 197
198 198 This code accepts any of the following as equivalent:
199 199
200 200
201 201 cmd -ao arg path path
202 202 cmd -a -o arg path path
203 203 cmd -o arg -a path path
204 204 cmd -a -o arg -- path path
205 205 cmd -a -oarg path path
206 206 cmd -aoarg path path
207 207
208 208
209 209 Example 2 Check Options and Arguments.
210 210
211 211
212 212 The following example parses a set of command line options and prints
213 213 messages to standard output for each option and argument that it
214 214 encounters.
215 215
216 216
217 217 #include <unistd.h>
218 218 #include <stdio.h>
219 219 ...
220 220 int c;
221 221 char *filename;
222 222 extern char *optarg;
223 223 extern int optind, optopt, opterr;
224 224 ...
225 225 while ((c = getopt(argc, argv, ":abf:")) != -1) {
226 226 switch(c) {
227 227 case 'a':
228 228 printf("a is set\n");
229 229 break;
230 230 case 'b':
231 231 printf("b is set\n");
232 232 break;
233 233 case 'f':
234 234 filename = optarg;
235 235 printf("filename is %s\n", filename);
236 236 break;
237 237 case ':':
238 238 printf("-%c without filename\n", optopt);
239 239 break;
240 240 case '?':
241 241 printf("unknown arg %c\n", optopt);
242 242 break;
243 243 }
244 244 }
245 245
246 246
247 247
248 248 This example can be expanded to be CLIP-compliant by substituting the
249 249 following string for the optstring argument:
250 250
251 251
252 252 :a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)
253 253
254 254
255 255
256 256 and by replacing the '?' case processing with:
257 257
258 258
259 259 case 'V':
260 260 fprintf(stdout, "cmd 1.1\n");
261 261 exit(0);
262 262 case '?':
263 263 if (optopt == '?') {
264 264 print_help();
265 265 exit(0);
266 266 }
267 267 if (optopt == '-')
268 268 fprintf(stderr,
269 269 "unrecognized option: %s\n", argv[optind-1]);
270 270 else
271 271 fprintf(stderr,
272 272 "unrecognized option: -%c\n", optopt);
273 273 errflg++;
274 274 break;
275 275
276 276
277 277
278 278 and by replacing the ':' case processing with:
279 279
280 280
281 281 case ':': /* -f or -o without operand */
282 282 if (optopt == '-')
283 283 fprintf(stderr,
284 284 "Option %s requires an operand\n", argv[optind-1]);
285 285 else
286 286 fprintf(stderr,
287 287 "Option -%c requires an operand\n", optopt);
288 288 errflg++;
289 289 break;
290 290
291 291
292 292
293 293 While not encouraged by the CLIP specification, multiple long-option
294 294 aliases can also be assigned as shown in the following example:
295 295
296 296
297 297 :a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)
298 298
299 299
300 300 ENVIRONMENT VARIABLES
301 301 See environ(5) for descriptions of the following environment variables
302 302 that affect the execution of getopt(): LANG, LC_ALL, and LC_MESSAGES.
303 303
304 304 LC_CTYPE
305 305 Determine the locale for the interpretation of sequences of
306 306 bytes as characters in optstring.
307 307
308 308
309 309 USAGE
310 310 The getopt() function does not fully check for mandatory arguments
311 311 because there is no unambiguous algorithm to do so. Given an option
312 312 string a:b and the input -a -b, getopt() assumes that -b is the
313 313 mandatory argument to the -a option and not that -a is missing a
314 314 mandatory argument. Indeed, the only time a missing option-argument
315 315 can be reliably detected is when the option is the final option on the
316 316 command line and is not followed by any command arguments.
317 317
318 318
319 319 It is a violation of the Basic Utility Command syntax standard (see
320 320 Intro(1)) for options with arguments to be grouped with other options,
321 321 as in cmd -abo filename , where a and b are options, o is an option
322 322 that requires an argument, and filename is the argument to o. Although
323 323 this syntax is permitted in the current implementation, it should not
324 324 be used because it may not be supported in future releases. The
325 325 correct syntax to use is:
326 326
327 327 cmd -ab -o filename
328 328
329 329
330 330
331 331 ATTRIBUTES
332 332 See attributes(5) for descriptions of the following attributes:
333 333
334 334
335 335
336 336
337 337 +--------------------+-----------------+
338 338 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
339 339 +--------------------+-----------------+
340 340 |Interface Stability | Committed |
|
↓ open down ↓ |
340 lines elided |
↑ open up ↑ |
341 341 +--------------------+-----------------+
342 342 |MT-Level | Unsafe |
343 343 +--------------------+-----------------+
344 344 |Standard | See below. |
345 345 +--------------------+-----------------+
346 346
347 347
348 348 For the Basic Utility Command syntax is Standard, see standards(5).
349 349
350 350 SEE ALSO
351 - Intro(1), getopt(1), getopts(1), getsubopt(3C), gettext(3C),
352 - setlocale(3C), attributes(5), environ(5), standards(5)
351 + Intro(1), getopt(1), getopts(1), getopt_long(3C), getsubopt(3C),
352 + gettext(3C), setlocale(3C), attributes(5), environ(5), standards(5)
353 353
354 354
355 355
356 - October 16, 2007 GETOPT(3C)
356 + July 17, 2018 GETOPT(3C)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX