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 .\" Copyright 2018 Jason King
  47 .\"
  48 .TH GETOPT 3C "July 17, 2018"
  49 .SH NAME
  50 getopt \- command option parsing
  51 .SH SYNOPSIS
  52 .SS "SVID3, XPG3"
  53 .LP
  54 .nf
  55 #include <stdio.h>
  56 
  57 \fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
  58 .fi
  59 
  60 .LP
  61 .nf
  62 \fBextern char *\fR\fIoptarg\fR;
  63 .fi
  64 
  65 .LP
  66 .nf
  67 \fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
  68 .fi
  69 
  70 .SS "POSIX.2, XPG4, SUS, SUSv2, SUSv3"
  71 .LP
  72 .nf
  73 #include <unistd.h>
  74 
  75 \fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
  76 .fi
  77 
  78 .LP
  79 .nf
  80 \fBextern char *\fR\fIoptarg\fR;
  81 .fi
  82 
  83 .LP
  84 .nf
  85 \fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
  86 .fi
  87 
  88 .SH DESCRIPTION
  89 .LP
  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.
  99 .sp
 100 .LP
 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.
 112 .sp
 113 .LP
 114 The \fBgetopt()\fR function returns the short-option character in
 115 \fIoptstring\fR that corresponds to the next option found in \fIargv\fR.
 116 .sp
 117 .LP
 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:
 123 .RS +4
 124 .TP
 125 .ie t \(bu
 126 .el o
 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.
 130 .RE
 131 .RS +4
 132 .TP
 133 .ie t \(bu
 134 .el o
 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.
 138 .RE
 139 .RS +4
 140 .TP
 141 .ie t \(bu
 142 .el o
 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.
 146 .RE
 147 .RS +4
 148 .TP
 149 .ie t \(bu
 150 .el o
 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.
 154 .RE
 155 .sp
 156 .LP
 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
 159 an error indication.
 160 .sp
 161 .LP
 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
 166 "-" (hyphen).
 167 .sp
 168 .LP
 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.
 180 .SH RETURN VALUES
 181 .LP
 182 The \fBgetopt()\fR function returns the short-option character associated with
 183 the option recognized.
 184 .sp
 185 .LP
 186 A colon (:) is returned if \fBgetopt()\fR detects a missing argument and the
 187 first character of \fIoptstring\fR was a colon (:).
 188 .sp
 189 .LP
 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 (:).
 193 .sp
 194 .LP
 195 Otherwise, \fBgetopt()\fR returns -1 when all command line options are parsed.
 196 .SH ERRORS
 197 .LP
 198 No errors are defined.
 199 .SH EXAMPLES
 200 .LP
 201 \fBExample 1 \fRParsing Command Line Options
 202 .sp
 203 .LP
 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:
 207 
 208 .sp
 209 .in +2
 210 .nf
 211 #include <unistd.h>
 212 
 213 int
 214 main(int argc, char *argv[ ])
 215 {
 216     int c;
 217     int bflg, aflg, errflg;
 218     char *ifile;
 219     char *ofile;
 220     extern char *optarg;
 221     extern int optind, optopt;
 222     ...
 223     while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
 224         switch(c) {
 225         case 'a':
 226             if (bflg)
 227                 errflg++;
 228             else
 229                 aflg++;
 230             break;
 231         case 'b':
 232             if (aflg)
 233                 errflg++;
 234             else {
 235                 bflg++;
 236                 bproc();
 237             }
 238             break;
 239         case 'f':
 240             ifile = optarg;
 241             break;
 242         case 'o':
 243             ofile = optarg;
 244             break;
 245         case ':':   /* -f or -o without operand */
 246             fprintf(stderr,
 247                    "Option -%c requires an operand\en", optopt);
 248             errflg++;
 249             break;
 250         case '?':
 251             fprintf(stderr,
 252                    "Unrecognized option: -%c\en", optopt);
 253             errflg++;
 254         }
 255     }
 256     if (errflg) {
 257         fprintf(stderr, "usage: ... ");
 258         exit(2);
 259     }
 260     for ( ; optind < argc; optind++) {
 261         if (access(argv[optind], R_OK)) {
 262     ...
 263 }
 264 .fi
 265 .in -2
 266 
 267 .sp
 268 .LP
 269 This code accepts any of the following as equivalent:
 270 
 271 .sp
 272 .in +2
 273 .nf
 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
 279 cmd -aoarg path path
 280 .fi
 281 .in -2
 282 
 283 .LP
 284 \fBExample 2 \fRCheck Options and Arguments.
 285 .sp
 286 .LP
 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.
 289 
 290 .sp
 291 .in +2
 292 .nf
 293 #include <unistd.h>
 294 #include <stdio.h>
 295 \&...
 296 int c;
 297 char *filename;
 298 extern char *optarg;
 299 extern int optind, optopt, opterr;
 300 \&...
 301 while ((c = getopt(argc, argv, ":abf:")) != -1) {
 302     switch(c) {
 303     case 'a':
 304          printf("a is set\en");
 305          break;
 306     case 'b':
 307          printf("b is set\en");
 308          break;
 309     case 'f':
 310          filename = optarg;
 311          printf("filename is %s\en", filename);
 312          break;
 313     case ':':
 314          printf("-%c without filename\en", optopt);
 315          break;
 316     case '?':
 317          printf("unknown arg %c\en", optopt);
 318          break;
 319     }
 320 }
 321 .fi
 322 .in -2
 323 
 324 .sp
 325 .LP
 326 This example can be expanded to be CLIP-compliant by substituting the following
 327 string for the \fIoptstring\fR argument:
 328 
 329 .sp
 330 .in +2
 331 .nf
 332 :a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)
 333 .fi
 334 .in -2
 335 
 336 .sp
 337 .LP
 338 and by replacing the '?' case processing with:
 339 
 340 .sp
 341 .in +2
 342 .nf
 343 case 'V':
 344     fprintf(stdout, "cmd 1.1\en");
 345     exit(0);
 346 case '?':
 347     if (optopt == '?') {
 348         print_help();
 349         exit(0);
 350     }
 351     if (optopt == '-')
 352         fprintf(stderr,
 353             "unrecognized option: %s\en", argv[optind-1]);
 354     else
 355         fprintf(stderr,
 356             "unrecognized option: -%c\en", optopt);
 357     errflg++;
 358     break;
 359 .fi
 360 .in -2
 361 
 362 .sp
 363 .LP
 364 and by replacing the ':' case processing with:
 365 
 366 .sp
 367 .in +2
 368 .nf
 369 case ':':   /* -f or -o without operand */
 370     if (optopt == '-')
 371         fprintf(stderr,
 372             "Option %s requires an operand\en", argv[optind-1]);
 373     else
 374         fprintf(stderr,
 375             "Option -%c requires an operand\en", optopt);
 376     errflg++;
 377     break;
 378 .fi
 379 .in -2
 380 
 381 .sp
 382 .LP
 383 While not encouraged by the CLIP specification, multiple long-option aliases
 384 can also be assigned as shown in the following example:
 385 
 386 .sp
 387 .in +2
 388 .nf
 389 :a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)
 390 .fi
 391 .in -2
 392 
 393 .SH ENVIRONMENT VARIABLES
 394 .LP
 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
 397 \fBLC_MESSAGES\fR.
 398 .sp
 399 .ne 2
 400 .na
 401 \fB\fBLC_CTYPE\fR\fR
 402 .ad
 403 .RS 12n
 404 Determine the locale for the interpretation of sequences of bytes as characters
 405 in \fIoptstring\fR.
 406 .RE
 407 
 408 .SH USAGE
 409 .LP
 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.
 417 .sp
 418 .LP
 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:
 426 .sp
 427 .in +2
 428 .nf
 429 cmd \(miab \(mio filename
 430 .fi
 431 .in -2
 432 .sp
 433 
 434 .SH ATTRIBUTES
 435 .LP
 436 See \fBattributes\fR(5) for descriptions of the following attributes:
 437 .sp
 438 
 439 .sp
 440 .TS
 441 box;
 442 c | c
 443 l | l .
 444 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 445 _
 446 Interface Stability     Committed
 447 _
 448 MT-Level        Unsafe
 449 _
 450 Standard        See below.
 451 .TE
 452 
 453 .sp
 454 .LP
 455 For the Basic Utility Command syntax is Standard, see \fBstandards\fR(5).
 456 .SH SEE ALSO
 457 .LP
 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)