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/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
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.
25 .\" This notice shall appear on any product containing this material.
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.
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.
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]
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
48 .TH GETOPT 3C "July 17, 2018"
50 getopt \- command option parsing
57 \fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
62 \fBextern char *\fR\fIoptarg\fR;
67 \fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
70 .SS "POSIX.2, XPG4, SUS, SUSv2, SUSv3"
75 \fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
80 \fBextern char *\fR\fIoptarg\fR;
85 \fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
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.
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.
114 The \fBgetopt()\fR function returns the short-option character in
115 \fIoptstring\fR that corresponds to the next option found in \fIargv\fR.
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:
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.
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.
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.
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.
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
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
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.
182 The \fBgetopt()\fR function returns the short-option character associated with
183 the option recognized.
186 A colon (:) is returned if \fBgetopt()\fR detects a missing argument and the
187 first character of \fIoptstring\fR was a colon (:).
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 (:).
195 Otherwise, \fBgetopt()\fR returns -1 when all command line options are parsed.
198 No errors are defined.
201 \fBExample 1 \fRParsing Command Line Options
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:
214 main(int argc, char *argv[ ])
217 int bflg, aflg, errflg;
221 extern int optind, optopt;
223 while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
245 case ':': /* -f or -o without operand */
247 "Option -%c requires an operand\en", optopt);
252 "Unrecognized option: -%c\en", optopt);
257 fprintf(stderr, "usage: ... ");
260 for ( ; optind < argc; optind++) {
261 if (access(argv[optind], R_OK)) {
269 This code accepts any of the following as equivalent:
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
284 \fBExample 2 \fRCheck Options and Arguments.
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.
299 extern int optind, optopt, opterr;
301 while ((c = getopt(argc, argv, ":abf:")) != -1) {
304 printf("a is set\en");
307 printf("b is set\en");
311 printf("filename is %s\en", filename);
314 printf("-%c without filename\en", optopt);
317 printf("unknown arg %c\en", optopt);
326 This example can be expanded to be CLIP-compliant by substituting the following
327 string for the \fIoptstring\fR argument:
332 :a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)
338 and by replacing the '?' case processing with:
344 fprintf(stdout, "cmd 1.1\en");
353 "unrecognized option: %s\en", argv[optind-1]);
356 "unrecognized option: -%c\en", optopt);
364 and by replacing the ':' case processing with:
369 case ':': /* -f or -o without operand */
372 "Option %s requires an operand\en", argv[optind-1]);
375 "Option -%c requires an operand\en", optopt);
383 While not encouraged by the CLIP specification, multiple long-option aliases
384 can also be assigned as shown in the following example:
389 :a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)
393 .SH ENVIRONMENT VARIABLES
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
404 Determine the locale for the interpretation of sequences of bytes as characters
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.
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:
429 cmd \(miab \(mio filename
436 See \fBattributes\fR(5) for descriptions of the following attributes:
444 ATTRIBUTE TYPE ATTRIBUTE VALUE
446 Interface Stability Committed
455 For the Basic Utility Command syntax is Standard, see \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)