man/man3/getopt.3

   1 .\" Copyright (c) 1985 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)getopt.3    6.4 (Berkeley) 5/27/86
   6 .\"
   7 .TH GETOPT 3 "May 27, 1986"
   8 .UC 6
   9 .SH NAME
  10 getopt \- get option letter from argv
  11 .SH SYNOPSIS
  12 .ft B
  13 int getopt(argc, argv, optstring)
  14 .br
  15 int argc;
  16 .br
  17 char **argv;
  18 .br
  19 char *optstring;
  20 .sp
  21 extern char *optarg;
  22 .br
  23 extern int optind;
  24 .ft
  25 .SH DESCRIPTION
  26 .I Getopt
  27 returns the next option letter in
  28 .I argv
  29 that matches a letter in
  30 .IR optstring .
  31 .I Optstring
  32 is a string of recognized option letters;
  33 if a letter is followed by a colon, the option is expected to have
  34 an argument that may or may not be separated from it by white space.
  35 .I Optarg
  36 is set to point to the start of the option argument on return from
  37 .IR getopt .
  38 .PP
  39 .I Getopt
  40 places in
  41 .I optind
  42 the
  43 .I argv
  44 index of the next argument to be processed.
  45 Because
  46 .I optind
  47 is external, it is normally initialized to zero automatically
  48 before the first call to
  49 .IR getopt .
  50 .PP
  51 When all options have been processed (i.e., up to the first
  52 non-option argument),
  53 .I getopt
  54 returns
  55 .BR EOF .
  56 The special option
  57 .B \-\-
  58 may be used to delimit the end of the options;
  59 .B EOF
  60 will be returned, and
  61 .B \-\-
  62 will be skipped.
  63 .SH DIAGNOSTICS
  64 .I Getopt
  65 prints an error message on
  66 .I stderr
  67 and returns a question mark
  68 .RB ( ? )
  69 when it encounters an option letter not included in
  70 .IR optstring .
  71 .SH EXAMPLE
  72 The following code fragment shows how one might process the arguments
  73 for a command that can take the mutually exclusive options
  74 .B a
  75 and
  76 .BR b ,
  77 and the options
  78 .B f
  79 and
  80 .BR o ,
  81 both of which require arguments:
  82 .PP
  83 .RS
  84 .nf
  85 main(argc, argv)
  86 int argc;
  87 char **argv;
  88 {
  89         int c;
  90         extern int optind;
  91         extern char *optarg;
  92         \&.
  93         \&.
  94         \&.
  95         while ((c = getopt(argc, argv, "abf:o:")) != EOF)
  96                 switch (c) {
  97                 case `a':
  98                         if (bflg)
  99                                 errflg++;
 100                         else
 101                                 aflg++;
 102                         break;
 103                 case `b':
 104                         if (aflg)
 105                                 errflg++;
 106                         else
 107                                 bproc();
 108                         break;
 109                 case `f':
 110                         ifile = optarg;
 111                         break;
 112                 case `o':
 113                         ofile = optarg;
 114                         break;
 115                 case `?':
 116                 default:
 117                         errflg++;
 118                         break;
 119                 }
 120         if (errflg) {
 121                 fprintf(stderr, "Usage: ...");
 122                 exit(2);
 123         }
 124         for (; optind < argc; optind++) {
 125                 \&.
 126                 \&.
 127                 \&.
 128         }
 129         \&.
 130         \&.
 131         \&.
 132 }
 133 .RE
 134 .SH HISTORY
 135 Written by Henry Spencer, working from a Bell Labs manual page.
 136 Modified by Keith Bostic to behave more like the System V version.
 137 .SH BUGS
 138 It is not obvious how
 139 `\-'
 140 standing alone should be treated;  this version treats it as
 141 a non-option argument, which is not always right.
 142 .PP
 143 Option arguments are allowed to begin with `\-';
 144 this is reasonable but reduces the amount of error checking possible.
 145 .PP
 146 .I Getopt
 147 is quite flexible but the obvious price must be paid:  there is much
 148 it could do that it doesn't, like
 149 checking mutually exclusive options, checking type of
 150 option arguments, etc.