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