Print this page
9659 Missing man page for getopt_long(3C)
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/getopt.3c
+++ new/usr/src/man/man3c/getopt.3c
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
|
↓ open down ↓ |
35 lines elided |
↑ open up ↑ |
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 41 .\"
42 42 .\"
43 43 .\" Copyright 1989 AT&T
44 44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 45 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
46 +.\" Copyright 2018 Jason King
46 47 .\"
47 -.TH GETOPT 3C "Oct 16, 2007"
48 +.TH GETOPT 3C "July 17, 2018"
48 49 .SH NAME
49 50 getopt \- command option parsing
50 51 .SH SYNOPSIS
51 52 .SS "SVID3, XPG3"
52 53 .LP
53 54 .nf
54 55 #include <stdio.h>
55 56
56 57 \fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
57 58 .fi
58 59
59 60 .LP
60 61 .nf
61 62 \fBextern char *\fR\fIoptarg\fR;
62 63 .fi
63 64
64 65 .LP
65 66 .nf
66 67 \fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
67 68 .fi
68 69
69 70 .SS "POSIX.2, XPG4, SUS, SUSv2, SUSv3"
70 71 .LP
71 72 .nf
72 73 #include <unistd.h>
73 74
74 75 \fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
75 76 .fi
76 77
77 78 .LP
78 79 .nf
79 80 \fBextern char *\fR\fIoptarg\fR;
80 81 .fi
81 82
82 83 .LP
83 84 .nf
84 85 \fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
85 86 .fi
86 87
87 88 .SH DESCRIPTION
88 89 .LP
89 90 The \fBgetopt()\fR function is a command line parser that can be used by
90 91 applications that follow Basic Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and
91 92 10 which parallel those defined by application portability standards (see
92 93 Intro(1)). It can also be used by applications which additionally follow the
93 94 Command Line Interface Paradigm (CLIP) syntax extension guidelines 15, 16, and
94 95 17. It partially enforces guideline 18 by requiring that every option has a
95 96 short-name, but it allows multiple long-names to be associated with an option.
96 97 The remaining guidelines are not addressed by \fBgetopt()\fR and are the
97 98 responsibility of the application.
98 99 .sp
99 100 .LP
100 101 The \fIargc\fR and \fIargv\fR arguments are the argument count and argument
101 102 array as passed to main (see \fBexec\fR(2)). The \fIoptstring\fR argument
102 103 specifies the acceptable options. For utilities wanting to conform to the Basic
103 104 Utility Syntax Guidelines, \fIoptstring\fR is a string of recognized option
104 105 characters. All option characters allowed by Utility Syntax Guideline 3 are
105 106 allowed in \fIoptstring\fR. If a character is followed by a colon (:), the
106 107 option is expected to have an option-argument, which can be separated from it
107 108 by white space. Utilities wanting to conform to the extended CLIP guidelines
108 109 can specify long-option equivalents to short options by following the
109 110 short-option character (and optional colon) with a sequence of strings, each
110 111 enclosed in parentheses, that specify the long-option aliases.
111 112 .sp
112 113 .LP
113 114 The \fBgetopt()\fR function returns the short-option character in
114 115 \fIoptstring\fR that corresponds to the next option found in \fIargv\fR.
115 116 .sp
116 117 .LP
117 118 The \fBgetopt()\fR function places in \fIoptind\fR the \fIargv\fR index of the
118 119 next argument to be processed. The \fIoptind\fR variable is external and is
119 120 initialized to 1 before the first call to \fBgetopt()\fR. The \fBgetopt()\fR
120 121 function sets the variable \fIoptarg\fR to point to the start of the
121 122 option-argument as follows:
122 123 .RS +4
123 124 .TP
124 125 .ie t \(bu
125 126 .el o
126 127 If the option is a short option and that character is the last character in the
127 128 argument, then \fIoptarg\fR contains the next element of \fIargv\fR, and
128 129 \fIoptind\fR is incremented by 2.
129 130 .RE
130 131 .RS +4
131 132 .TP
132 133 .ie t \(bu
133 134 .el o
134 135 If the option is a short option and that character is not the last character in
135 136 the argument, then \fIoptarg\fR points to the string following the option
136 137 character in that argument, and \fIoptind\fR is incremented by 1.
137 138 .RE
138 139 .RS +4
139 140 .TP
140 141 .ie t \(bu
141 142 .el o
142 143 If the option is a long option and the character equals is not found in the
143 144 argument, then \fIoptarg\fR contains the next element of \fIargv\fR, and
144 145 \fIoptind\fR is incremented by 2.
145 146 .RE
146 147 .RS +4
147 148 .TP
148 149 .ie t \(bu
149 150 .el o
150 151 If the option is a long option and the character equals is found in the
151 152 argument, then \fIoptarg\fR points to the string following the equals character
152 153 in that argument and \fIoptind\fR is incremented by 1.
153 154 .RE
154 155 .sp
155 156 .LP
156 157 In all cases, if the resulting value of \fIoptind\fR is not less than
157 158 \fIargc\fR, this indicates a missing option-argument and \fBgetopt()\fR returns
158 159 an error indication.
159 160 .sp
160 161 .LP
161 162 When all options have been processed (that is, up to the first operand),
162 163 \fBgetopt()\fR returns -1. The special option "--"(two hyphens) can be used to
163 164 delimit the end of the options; when it is encountered, -1 is returned and "--"
164 165 is skipped. This is useful in delimiting non-option arguments that begin with
165 166 "-" (hyphen).
166 167 .sp
167 168 .LP
168 169 If \fBgetopt()\fR encounters a short-option character or a long-option string
169 170 not described in the \fIopstring\fR argument, it returns the question-mark (?)
170 171 character. If it detects a missing option-argument, it also returns the
171 172 question-mark (?) character, unless the first character of the \fIoptstring\fR
172 173 argument was a colon (:), in which case \fBgetopt()\fR returns the colon (:)
173 174 character. For short options, \fBgetopt()\fR sets the variable \fIoptopt\fR to
174 175 the option character that caused the error. For long options, \fIoptopt\fR is
175 176 set to the hyphen (-) character and the failing long option can be identified
176 177 through \fIargv\fR[\fIoptind\fR-1]. If the application has not set the variable
177 178 \fIopterr\fR to 0 and the first character of \fIoptstring\fR is not a colon
178 179 (:), \fBgetopt()\fR also prints a diagnostic message to \fBstderr\fR.
179 180 .SH RETURN VALUES
180 181 .LP
181 182 The \fBgetopt()\fR function returns the short-option character associated with
182 183 the option recognized.
183 184 .sp
184 185 .LP
185 186 A colon (:) is returned if \fBgetopt()\fR detects a missing argument and the
186 187 first character of \fIoptstring\fR was a colon (:).
187 188 .sp
188 189 .LP
189 190 A question mark (?) is returned if \fBgetopt()\fR encounters an option not
190 191 specified in \fIoptstring\fR or detects a missing argument and the first
191 192 character of \fIoptstring\fR was not a colon (:).
192 193 .sp
193 194 .LP
194 195 Otherwise, \fBgetopt()\fR returns -1 when all command line options are parsed.
195 196 .SH ERRORS
196 197 .LP
197 198 No errors are defined.
198 199 .SH EXAMPLES
199 200 .LP
200 201 \fBExample 1 \fRParsing Command Line Options
201 202 .sp
202 203 .LP
203 204 The following code fragment shows how you might process the arguments for a
204 205 utility that can take the mutually-exclusive options \fBa\fR and \fBb\fR and
205 206 the options \fBf\fR and \fBo\fR, both of which require arguments:
206 207
207 208 .sp
208 209 .in +2
209 210 .nf
210 211 #include <unistd.h>
211 212
212 213 int
213 214 main(int argc, char *argv[ ])
214 215 {
215 216 int c;
216 217 int bflg, aflg, errflg;
217 218 char *ifile;
218 219 char *ofile;
219 220 extern char *optarg;
220 221 extern int optind, optopt;
221 222 ...
222 223 while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
223 224 switch(c) {
224 225 case 'a':
225 226 if (bflg)
226 227 errflg++;
227 228 else
228 229 aflg++;
229 230 break;
230 231 case 'b':
231 232 if (aflg)
232 233 errflg++;
233 234 else {
234 235 bflg++;
235 236 bproc();
236 237 }
237 238 break;
238 239 case 'f':
239 240 ifile = optarg;
240 241 break;
241 242 case 'o':
242 243 ofile = optarg;
243 244 break;
244 245 case ':': /* -f or -o without operand */
245 246 fprintf(stderr,
246 247 "Option -%c requires an operand\en", optopt);
247 248 errflg++;
248 249 break;
249 250 case '?':
250 251 fprintf(stderr,
251 252 "Unrecognized option: -%c\en", optopt);
252 253 errflg++;
253 254 }
254 255 }
255 256 if (errflg) {
256 257 fprintf(stderr, "usage: ... ");
257 258 exit(2);
258 259 }
259 260 for ( ; optind < argc; optind++) {
260 261 if (access(argv[optind], R_OK)) {
261 262 ...
262 263 }
263 264 .fi
264 265 .in -2
265 266
266 267 .sp
267 268 .LP
268 269 This code accepts any of the following as equivalent:
269 270
270 271 .sp
271 272 .in +2
272 273 .nf
273 274 cmd -ao arg path path
274 275 cmd -a -o arg path path
275 276 cmd -o arg -a path path
276 277 cmd -a -o arg -- path path
277 278 cmd -a -oarg path path
278 279 cmd -aoarg path path
279 280 .fi
280 281 .in -2
281 282
282 283 .LP
283 284 \fBExample 2 \fRCheck Options and Arguments.
284 285 .sp
285 286 .LP
286 287 The following example parses a set of command line options and prints messages
287 288 to standard output for each option and argument that it encounters.
288 289
289 290 .sp
290 291 .in +2
291 292 .nf
292 293 #include <unistd.h>
293 294 #include <stdio.h>
294 295 \&...
295 296 int c;
296 297 char *filename;
297 298 extern char *optarg;
298 299 extern int optind, optopt, opterr;
299 300 \&...
300 301 while ((c = getopt(argc, argv, ":abf:")) != -1) {
301 302 switch(c) {
302 303 case 'a':
303 304 printf("a is set\en");
304 305 break;
305 306 case 'b':
306 307 printf("b is set\en");
307 308 break;
308 309 case 'f':
309 310 filename = optarg;
310 311 printf("filename is %s\en", filename);
311 312 break;
312 313 case ':':
313 314 printf("-%c without filename\en", optopt);
314 315 break;
315 316 case '?':
316 317 printf("unknown arg %c\en", optopt);
317 318 break;
318 319 }
319 320 }
320 321 .fi
321 322 .in -2
322 323
323 324 .sp
324 325 .LP
325 326 This example can be expanded to be CLIP-compliant by substituting the following
326 327 string for the \fIoptstring\fR argument:
327 328
328 329 .sp
329 330 .in +2
330 331 .nf
331 332 :a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)
332 333 .fi
333 334 .in -2
334 335
335 336 .sp
336 337 .LP
337 338 and by replacing the '?' case processing with:
338 339
339 340 .sp
340 341 .in +2
341 342 .nf
342 343 case 'V':
343 344 fprintf(stdout, "cmd 1.1\en");
344 345 exit(0);
345 346 case '?':
346 347 if (optopt == '?') {
347 348 print_help();
348 349 exit(0);
349 350 }
350 351 if (optopt == '-')
351 352 fprintf(stderr,
352 353 "unrecognized option: %s\en", argv[optind-1]);
353 354 else
354 355 fprintf(stderr,
355 356 "unrecognized option: -%c\en", optopt);
356 357 errflg++;
357 358 break;
358 359 .fi
359 360 .in -2
360 361
361 362 .sp
362 363 .LP
363 364 and by replacing the ':' case processing with:
364 365
365 366 .sp
366 367 .in +2
367 368 .nf
368 369 case ':': /* -f or -o without operand */
369 370 if (optopt == '-')
370 371 fprintf(stderr,
371 372 "Option %s requires an operand\en", argv[optind-1]);
372 373 else
373 374 fprintf(stderr,
374 375 "Option -%c requires an operand\en", optopt);
375 376 errflg++;
376 377 break;
377 378 .fi
378 379 .in -2
379 380
380 381 .sp
381 382 .LP
382 383 While not encouraged by the CLIP specification, multiple long-option aliases
383 384 can also be assigned as shown in the following example:
384 385
385 386 .sp
386 387 .in +2
387 388 .nf
388 389 :a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)
389 390 .fi
390 391 .in -2
391 392
392 393 .SH ENVIRONMENT VARIABLES
393 394 .LP
394 395 See \fBenviron\fR(5) for descriptions of the following environment variables
395 396 that affect the execution of \fBgetopt()\fR: \fBLANG\fR, \fBLC_ALL\fR, and
396 397 \fBLC_MESSAGES\fR.
397 398 .sp
398 399 .ne 2
399 400 .na
400 401 \fB\fBLC_CTYPE\fR\fR
401 402 .ad
402 403 .RS 12n
403 404 Determine the locale for the interpretation of sequences of bytes as characters
404 405 in \fIoptstring\fR.
405 406 .RE
406 407
407 408 .SH USAGE
408 409 .LP
409 410 The \fBgetopt()\fR function does not fully check for mandatory arguments
410 411 because there is no unambiguous algorithm to do so. Given an option string
411 412 \fBa\fR:\fBb\fR and the input \fB-a\fR \fB-b\fR, \fBgetopt()\fR assumes that
412 413 \fB-b\fR is the mandatory argument to the \fB-a\fR option and not that \fB-a\fR
413 414 is missing a mandatory argument. Indeed, the only time a missing
414 415 option-argument can be reliably detected is when the option is the final option
415 416 on the command line and is not followed by any command arguments.
416 417 .sp
417 418 .LP
418 419 It is a violation of the Basic Utility Command syntax standard (see
419 420 \fBIntro\fR(1)) for options with arguments to be grouped with other options, as
420 421 in \fBcmd\fR \fB-abo\fR \fIfilename\fR , where \fBa\fR and \fBb\fR are options,
421 422 \fBo\fR is an option that requires an argument, and \fIfilename\fR is the
422 423 argument to \fBo\fR. Although this syntax is permitted in the current
423 424 implementation, it should not be used because it may not be supported in future
424 425 releases. The correct syntax to use is:
425 426 .sp
426 427 .in +2
427 428 .nf
428 429 cmd \(miab \(mio filename
429 430 .fi
430 431 .in -2
431 432 .sp
432 433
433 434 .SH ATTRIBUTES
434 435 .LP
435 436 See \fBattributes\fR(5) for descriptions of the following attributes:
436 437 .sp
437 438
438 439 .sp
439 440 .TS
440 441 box;
441 442 c | c
442 443 l | l .
443 444 ATTRIBUTE TYPE ATTRIBUTE VALUE
444 445 _
445 446 Interface Stability Committed
446 447 _
|
↓ open down ↓ |
389 lines elided |
↑ open up ↑ |
447 448 MT-Level Unsafe
448 449 _
449 450 Standard See below.
450 451 .TE
451 452
452 453 .sp
453 454 .LP
454 455 For the Basic Utility Command syntax is Standard, see \fBstandards\fR(5).
455 456 .SH SEE ALSO
456 457 .LP
457 -\fBIntro\fR(1), \fBgetopt\fR(1), \fBgetopts\fR(1), \fBgetsubopt\fR(3C),
458 -\fBgettext\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5),
459 -\fBstandards\fR(5)
458 +\fBIntro\fR(1), \fBgetopt\fR(1), \fBgetopts\fR(1), \fBgetopt_long\fR(3C),
459 +\fBgetsubopt\fR(3C), \fBgettext\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
460 +\fBenviron\fR(5), \fBstandards\fR(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX