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