1GETOPT(3P) POSIX Programmer's Manual GETOPT(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 getopt, optarg, opterr, optind, optopt — command option parsing
14
16 #include <unistd.h>
17 int getopt(int argc, char * const argv[], const char *optstring);
19 extern char *optarg;
20 extern int opterr, optind, optopt;
21
23 The getopt() function is a command-line parser that shall follow Util‐
24 ity Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in the Base Definitions
25 volume of POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
26 The parameters argc and argv are the argument count and argument array
28 as passed to main() (see exec()). The argument optstring is a string
29 of recognized option characters; if a character is followed by a
30 <colon>, the option takes an argument. All option characters allowed by
31 Utility Syntax Guideline 3 are allowed in optstring. The implementa‐
32 tion may accept other characters as an extension.
33 The variable optind is the index of the next element of the argv[] vec‐
35 tor to be processed. It shall be initialized to 1 by the system, and
36 getopt() shall update it when it finishes with each element of argv[].
37 If the application sets optind to zero before calling getopt(), the
38 behavior is unspecified. When an element of argv[] contains multiple
39 option characters, it is unspecified how getopt() determines which
40 options have already been processed.
41 The getopt() function shall return the next option character (if one is
43 found) from argv that matches a character in optstring, if there is one
44 that matches. If the option takes an argument, getopt() shall set the
45 variable optarg to point to the option-argument as follows:
46 1. If the option was the last character in the string pointed to by an
48 element of argv, then optarg shall contain the next element of
49 argv, and optind shall be incremented by 2. If the resulting value
50 of optind is greater than argc, this indicates a missing option-
51 argument, and getopt() shall return an error indication.
52 2. Otherwise, optarg shall point to the string following the option
54 character in that element of argv, and optind shall be incremented
55 by 1.
56 If, when getopt() is called:
58 argv[optind] is a null pointer
60 *argv[optind] is not the character −
61 argv[optind] points to the string "−"
62 getopt() shall return −1 without changing optind. If:
64 argv[optind] points to the string "−−"
66 getopt() shall return −1 after incrementing optind.
68 If getopt() encounters an option character that is not contained in
70 optstring, it shall return the <question-mark> ('?') character. If it
71 detects a missing option-argument, it shall return the <colon> charac‐
72 ter (':') if the first character of optstring was a <colon>, or a
73 <question-mark> character ('?') otherwise. In either case, getopt()
74 shall set the variable optopt to the option character that caused the
75 error. If the application has not set the variable opterr to 0 and the
76 first character of optstring is not a <colon>, getopt() shall also
77 print a diagnostic message to stderr in the format specified for the
78 getopts utility.
79 The getopt() function need not be thread-safe.
81
83 The getopt() function shall return the next option character specified
84 on the command line.
85 A <colon> (':') shall be returned if getopt() detects a missing argu‐
87 ment and the first character of optstring was a <colon> (':').
88 A <question-mark> ('?') shall be returned if getopt() encounters an
90 option character not in optstring or detects a missing argument and the
91 first character of optstring was not a <colon> (':').
92 Otherwise, getopt() shall return −1 when all command line options are
94 parsed.
95
97 If the application has not set the variable opterr to 0, the first
98 character of optstring is not a <colon>, and a write error occurs while
99 getopt() is printing a diagnostic message to stderr, then the error
100 indicator for stderr shall be set; but getopt() shall still succeed and
101 the value of errno after getopt() is unspecified.
102 The following sections are informative.
104
106 Parsing Command Line Options
107 The following code fragment shows how you might process the arguments
108 for a utility that can take the mutually-exclusive options a and b and
109 the options f and o, both of which require arguments:
110 #include <stdio.h>
112 #include <stdlib.h>
113 #include <unistd.h>
114 int
116 main(int argc, char *argv[ ])
117 {
118 int c;
119 int bflg = 0, aflg = 0, errflg = 0;
120 char *ifile;
121 char *ofile;
122 . . .
123 while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
124 switch(c) {
125 case 'a':
126 if (bflg)
127 errflg++;
128 else
129 aflg++;
130 break;
131 case 'b':
132 if (aflg)
133 errflg++;
134 else
135 bflg++;
136 break;
137 case 'f':
138 ifile = optarg;
139 break;
140 case 'o':
141 ofile = optarg;
142 break;
143 case ':': /* -f or -o without operand */
144 fprintf(stderr,
145 "Option -%c requires an operand\n", optopt);
146 errflg++;
147 break;
148 case '?':
149 fprintf(stderr,
150 "Unrecognized option: '-%c'\n", optopt);
151 errflg++;
152 }
153 }
154 if (errflg) {
155 fprintf(stderr, "usage: . . . ");
156 exit(2);
157 }
158 for ( ; optind < argc; optind++) {
159 if (access(argv[optind], R_OK)) {
160 . . .
161 }
162 This code accepts any of the following as equivalent:
164 cmd −ao arg path path
166 cmd −a −o arg path path
167 cmd −o arg −a path path
168 cmd −a −o arg −− path path
169 cmd −a −oarg path path
170 cmd −aoarg path path
171 Selecting Options from the Command Line
173 The following example selects the type of database routines the user
174 wants to use based on the Options argument.
175 #include <unistd.h>
177 #include <string.h>
178 ...
179 const char *Options = "hdbtl";
180 ...
181 int dbtype, c;
182 char *st;
183 ...
184 dbtype = 0;
185 while ((c = getopt(argc, argv, Options)) != −1) {
186 if ((st = strchr(Options, c)) != NULL) {
187 dbtype = st - Options;
188 break;
189 }
190 }
191
193 The getopt() function is only required to support option characters
194 included in Utility Syntax Guideline 3. Many historical implementations
195 of getopt() support other characters as options. This is an allowed
196 extension, but applications that use extensions are not maximally por‐
197 table. Note that support for multi-byte option characters is only pos‐
198 sible when such characters can be represented as type int.
199 While ferror(stderr) may be used to detect failures to write a diagnos‐
201 tic to stderr when getopt() returns '?', the value of errno is unspeci‐
202 fied in such a condition. Applications desiring more control over han‐
203 dling write failures should set opterr to 0 and independently perform
204 output to stderr, rather than relying on getopt() to do the output.
205
207 The optopt variable represents historical practice and allows the
208 application to obtain the identity of the invalid option.
209 The description has been written to make it clear that getopt(), like
211 the getopts utility, deals with option-arguments whether separated from
212 the option by <blank> characters or not. Note that the requirements on
213 getopt() and getopts are more stringent than the Utility Syntax Guide‐
214 lines.
215 The getopt() function shall return −1, rather than EOF, so that
217 <stdio.h> is not required.
218 The special significance of a <colon> as the first character of opt‐
220 string makes getopt() consistent with the getopts utility. It allows an
221 application to make a distinction between a missing argument and an
222 incorrect option letter without having to examine the option letter. It
223 is true that a missing argument can only be detected in one case, but
224 that is a case that has to be considered.
225
227 None.
228
230 exec
231 The Base Definitions volume of POSIX.1‐2008, Section 12.2, Utility Syn‐
233 tax Guidelines, <unistd.h>
234 The Shell and Utilities volume of POSIX.1‐2008, getopts
236
238 Portions of this text are reprinted and reproduced in electronic form
239 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
240 -- Portable Operating System Interface (POSIX), The Open Group Base
241 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
242 cal and Electronics Engineers, Inc and The Open Group. (This is
243 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
244 event of any discrepancy between this version and the original IEEE and
245 The Open Group Standard, the original IEEE and The Open Group Standard
246 is the referee document. The original Standard can be obtained online
247 at http://www.unix.org/online.html .
248 Any typographical or formatting errors that appear in this page are
250 most likely to have been introduced during the conversion of the source
251 files to man page format. To report such errors, see https://www.ker‐
252 nel.org/doc/man-pages/reporting_bugs.html .
253IEEE/The Open Group 2013 GETOPT(3P)