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