1GETOPT(3P)                 POSIX Programmer's Manual                GETOPT(3P)
2
3
4

PROLOG

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
11

NAME

13       getopt, optarg, opterr, optind, optopt — command option parsing
14

SYNOPSIS

16       #include <unistd.h>
17
18       int getopt(int argc, char * const argv[], const char *optstring);
19       extern char *optarg;
20       extern int opterr, optind, optopt;
21

DESCRIPTION

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
27       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
34       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
42       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
47        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
53        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
57       If, when getopt() is called:
58
59            argv[optind]  is a null pointer
60           *argv[optind]  is not the character 
61            argv[optind]  points to the string "−"
62
63       getopt() shall return −1 without changing optind.  If:
64
65           argv[optind]   points to the string "−−"
66
67       getopt() shall return −1 after incrementing optind.
68
69       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
80       The getopt() function need not be thread-safe.
81

RETURN VALUE

83       The  getopt() function shall return the next option character specified
84       on the command line.
85
86       A <colon> (':') shall be returned if getopt() detects a  missing  argu‐
87       ment and the first character of optstring was a <colon> (':').
88
89       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
93       Otherwise,  getopt()  shall return −1 when all command line options are
94       parsed.
95

ERRORS

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
103       The following sections are informative.
104

EXAMPLES

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
111           #include <stdio.h>
112           #include <stdlib.h>
113           #include <unistd.h>
114
115           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
163       This code accepts any of the following as equivalent:
164
165           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
172   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
176           #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

APPLICATION USAGE

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
200       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

RATIONALE

207       The optopt variable  represents  historical  practice  and  allows  the
208       application to obtain the identity of the invalid option.
209
210       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
216       The  getopt()  function  shall  return  −1,  rather  than  EOF, so that
217       <stdio.h> is not required.
218
219       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

FUTURE DIRECTIONS

227       None.
228

SEE ALSO

230       exec
231
232       The Base Definitions volume of POSIX.1‐2008, Section 12.2, Utility Syn‐
233       tax Guidelines, <unistd.h>
234
235       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
249       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 .
253
254
255
256IEEE/The Open Group                  2013                           GETOPT(3P)
Impressum