man3p/getopt.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "GETOPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" getopt
   4 .SH NAME
   5 getopt, optarg, opterr, optind, optopt \- command option parsing
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <unistd.h>
   9 .br
  10 .sp
  11 int getopt(int\fP \fIargc\fP\fB, char * const\fP \fIargv\fP\fB[],
  12 const char *\fP\fIoptstring\fP\fB);
  13 .br
  14 extern char *optarg;
  15 .br
  16 extern int optind, opterr, optopt;
  17 .br
  18 \fP
  19 .SH DESCRIPTION
  20 .LP
  21 The \fIgetopt\fP() function is a command-line parser that shall follow
  22 Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in
  23 the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2,
  24 Utility Syntax Guidelines.
  25 .LP
  26 The parameters \fIargc\fP and \fIargv\fP are the argument count and
  27 argument array as passed to \fImain\fP() (see \fIexec\fP() ). The
  28 argument \fIoptstring\fP is a string of recognized
  29 option characters; if a character is followed by a colon, the option
  30 takes an argument. All option characters allowed by Utility
  31 Syntax Guideline 3 are allowed in \fIoptstring\fP. The implementation
  32 may accept other characters as an extension.
  33 .LP
  34 The variable \fIoptind\fP is the index of the next element of the
  35 \fIargv\fP[] vector to be processed. It shall be initialized
  36 to 1 by the system, and \fIgetopt\fP() shall update it when it finishes
  37 with each element of \fIargv\fP[]. When an element of
  38 \fIargv\fP[] contains multiple option characters, it is unspecified
  39 how \fIgetopt\fP() determines which options have already been
  40 processed.
  41 .LP
  42 The \fIgetopt\fP() function shall return the next option character
  43 (if one is found) from \fIargv\fP that matches a character
  44 in \fIoptstring\fP, if there is one that matches. If the option takes
  45 an argument, \fIgetopt\fP() shall set the variable
  46 \fIoptarg\fP to point to the option-argument as follows:
  47 .IP " 1." 4
  48 If the option was the last character in the string pointed to by an
  49 element of \fIargv\fP, then \fIoptarg\fP shall contain the
  50 next element of \fIargv\fP, and \fIoptind\fP shall be incremented
  51 by 2. If the resulting value of \fIoptind\fP is greater than
  52 \fIargc\fP, this indicates a missing option-argument, and \fIgetopt\fP()
  53 shall return an error indication.
  54 .LP
  55 .IP " 2." 4
  56 Otherwise, \fIoptarg\fP shall point to the string following the option
  57 character in that element of \fIargv\fP, and
  58 \fIoptind\fP shall be incremented by 1.
  59 .LP
  60 .LP
  61 If, when \fIgetopt\fP() is called:
  62 .sp
  63 .RS
  64 .nf
  65
  66 \fIargv\fP\fB[optind]\fP  is a null pointer\fB*\fP
  67 \fIargv\fP\fB[optind]\fP  is not the character \fB- \fP
  68 \fIargv\fP\fB[optind]\fP  points to the string \fB"-"\fP
  69 .fi
  70 .RE
  71 .LP
  72 \fIgetopt\fP() shall return -1 without changing \fIoptind\fP. If:
  73 .sp
  74 .RS
  75 .nf
  76
  77 \fIargv\fP\fB[optind] \fP  points to the string \fB"--"
  78 \fP
  79 .fi
  80 .RE
  81 .LP
  82 \fIgetopt\fP() shall return -1 after incrementing \fIoptind\fP.
  83 .LP
  84 If \fIgetopt\fP() encounters an option character that is not contained
  85 in \fIoptstring\fP, it shall return the question-mark (
  86 \fB'?'\fP ) character. If it detects a missing option-argument, it
  87 shall return the colon character ( \fB':'\fP ) if the
  88 first character of \fIoptstring\fP was a colon, or a question-mark
  89 character ( \fB'?'\fP ) otherwise. In either case,
  90 \fIgetopt\fP() shall set the variable \fIoptopt\fP to the option character
  91 that caused the error. If the application has not set
  92 the variable \fIopterr\fP to 0 and the first character of \fIoptstring\fP
  93 is not a colon, \fIgetopt\fP() shall also print a
  94 diagnostic message to \fIstderr\fP in the format specified for the
  95 \fIgetopts\fP
  96 utility.
  97 .LP
  98 The \fIgetopt\fP() function need not be reentrant. A function that
  99 is not required to be reentrant is not required to be
 100 thread-safe.
 101 .SH RETURN VALUE
 102 .LP
 103 The \fIgetopt\fP() function shall return the next option character
 104 specified on the command line.
 105 .LP
 106 A colon ( \fB':'\fP ) shall be returned if \fIgetopt\fP() detects
 107 a missing argument and the first character of
 108 \fIoptstring\fP was a colon ( \fB':'\fP ).
 109 .LP
 110 A question mark ( \fB'?'\fP ) shall be returned if \fIgetopt\fP()
 111 encounters an option character not in \fIoptstring\fP or
 112 detects a missing argument and the first character of \fIoptstring\fP
 113 was not a colon ( \fB':'\fP ).
 114 .LP
 115 Otherwise, \fIgetopt\fP() shall return -1 when all command line options
 116 are parsed.
 117 .SH ERRORS
 118 .LP
 119 No errors are defined.
 120 .LP
 121 \fIThe following sections are informative.\fP
 122 .SH EXAMPLES
 123 .SS Parsing Command Line Options
 124 .LP
 125 The following code fragment shows how you might process the arguments
 126 for a utility that can take the mutually-exclusive options
 127 \fIa\fP and \fIb\fP and the options \fIf\fP and \fIo\fP, both of which
 128 require arguments:
 129 .sp
 130 .RS
 131 .nf
 132
 133 \fB#include <unistd.h>
 134 .sp
 135
 136 int
 137 main(int argc, char *argv[ ])
 138 {
 139     int c;
 140     int bflg, aflg, errflg;
 141     char *ifile;
 142     char *ofile;
 143     extern char *optarg;
 144     extern int optind, optopt;
 145     . . .
 146     while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
 147         switch(c) {
 148         case 'a':
 149             if (bflg)
 150                 errflg++;
 151             else
 152                 aflg++;
 153             break;
 154         case 'b':
 155             if (aflg)
 156                 errflg++;
 157             else {
 158                 bflg++;
 159                 bproc();
 160             }
 161             break;
 162         case 'f':
 163             ifile = optarg;
 164             break;
 165         case 'o':
 166             ofile = optarg;
 167             break;
 168             case ':':       /* -f or -o without operand */
 169                     fprintf(stderr,
 170                             "Option -%c requires an operand\\n", optopt);
 171                     errflg++;
 172                     break;
 173         case '?':
 174                     fprintf(stderr,
 175                             "Unrecognized option: -%c\\n", optopt);
 176             errflg++;
 177         }
 178     }
 179     if (errflg) {
 180         fprintf(stderr, "usage: . . . ");
 181         exit(2);
 182     }
 183     for ( ; optind < argc; optind++) {
 184         if (access(argv[optind], R_OK)) {
 185     . . .
 186 }
 187 \fP
 188 .fi
 189 .RE
 190 .LP
 191 This code accepts any of the following as equivalent:
 192 .sp
 193 .RS
 194 .nf
 195
 196 \fBcmd -ao arg path path
 197 cmd -a -o arg path path
 198 cmd -o arg -a path path
 199 cmd -a -o arg -- path path
 200 cmd -a -oarg path path
 201 cmd -aoarg path path
 202 \fP
 203 .fi
 204 .RE
 205 .SS Checking Options and Arguments
 206 .LP
 207 The following example parses a set of command line options and prints
 208 messages to standard output for each option and argument
 209 that it encounters.
 210 .sp
 211 .RS
 212 .nf
 213
 214 \fB#include <unistd.h>
 215 #include <stdio.h>
 216 \&...
 217 int c;
 218 char *filename;
 219 extern char *optarg;
 220 extern int optind, optopt, opterr;
 221 \&...
 222 while ((c = getopt(argc, argv, ":abf:")) != -1) {
 223     switch(c) {
 224     case 'a':
 225         printf("a is set\\n");
 226         break;
 227     case 'b':
 228         printf("b is set\\n");
 229         break;
 230     case 'f':
 231         filename = optarg;
 232         printf("filename is %s\\n", filename);
 233         break;
 234     case ':':
 235         printf("-%c without filename\\n", optopt);
 236         break;
 237     case '?':
 238         printf("unknown arg %c\\n", optopt);
 239         break;
 240     }
 241 }
 242 \fP
 243 .fi
 244 .RE
 245 .SS Selecting Options from the Command Line
 246 .LP
 247 The following example selects the type of database routines the user
 248 wants to use based on the \fIOptions\fP argument.
 249 .sp
 250 .RS
 251 .nf
 252
 253 \fB#include <unistd.h>
 254 #include <string.h>
 255 \&...
 256 char *Options = "hdbtl";
 257 \&...
 258 int dbtype, i;
 259 char c;
 260 char *st;
 261 \&...
 262 dbtype = 0;
 263 while ((c = getopt(argc, argv, Options)) != -1) {
 264     if ((st = strchr(Options, c)) != NULL) {
 265         dbtype = st - Options;
 266         break;
 267     }
 268 }
 269 \fP
 270 .fi
 271 .RE
 272 .SH APPLICATION USAGE
 273 .LP
 274 The \fIgetopt\fP() function is only required to support option characters
 275 included in Utility Syntax Guideline 3. Many
 276 historical implementations of \fIgetopt\fP() support other characters
 277 as options. This is an allowed extension, but applications
 278 that use extensions are not maximally portable. Note that support
 279 for multi-byte option characters is only possible when such
 280 characters can be represented as type \fBint\fP.
 281 .SH RATIONALE
 282 .LP
 283 The \fIoptopt\fP variable represents historical practice and allows
 284 the application to obtain the identity of the invalid
 285 option.
 286 .LP
 287 The description has been written to make it clear that \fIgetopt\fP(),
 288 like the \fIgetopts\fP utility, deals with option-arguments whether
 289 separated from the option by
 290 <blank>s or not. Note that the requirements on \fIgetopt\fP() and
 291 \fIgetopts\fP are
 292 more stringent than the Utility Syntax Guidelines.
 293 .LP
 294 The \fIgetopt\fP() function shall return -1, rather than EOF, so that
 295 \fI<stdio.h>\fP is not required.
 296 .LP
 297 The special significance of a colon as the first character of \fIoptstring\fP
 298 makes \fIgetopt\fP() consistent with the \fIgetopts\fP utility. It
 299 allows an application to make a distinction between a missing
 300 argument and an incorrect option letter without having to examine
 301 the option letter. It is true that a missing argument can only be
 302 detected in one case, but that is a case that has to be considered.
 303 .SH FUTURE DIRECTIONS
 304 .LP
 305 None.
 306 .SH SEE ALSO
 307 .LP
 308 \fIexec\fP() , the Base Definitions volume of
 309 IEEE\ Std\ 1003.1-2001, \fI<unistd.h>\fP, the Shell and Utilities
 310 volume of
 311 IEEE\ Std\ 1003.1-2001
 312 .SH COPYRIGHT
 313 Portions of this text are reprinted and reproduced in electronic form
 314 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 315 -- Portable Operating System Interface (POSIX), The Open Group Base
 316 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 317 Electrical and Electronics Engineers, Inc and The Open Group. In the
 318 event of any discrepancy between this version and the original IEEE and
 319 The Open Group Standard, the original IEEE and The Open Group Standard
 320 is the referee document. The original Standard can be obtained online at
 321 http://www.opengroup.org/unix/online.html .