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