stdlib/getopt.3

   1 .\" Copyright (c) 1988, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)getopt.3    8.5 (Berkeley) 4/27/95
  33 .\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.20 2001/09/07 14:46:35 asmodai Exp $
  34 .\"
  35 .Dd April 27, 1995
  36 .Dt GETOPT 3
  37 .Os
  38 .Sh NAME
  39 .Nm getopt
  40 .Nd get option character from command line argument list
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Vt extern char *optarg ;
  46 .Vt extern int   optind ;
  47 .Vt extern int   optopt ;
  48 .Vt extern int   opterr ;
  49 .Vt extern int   optreset ;
  50 .Ft int
  51 .Fn getopt "int argc" "char * const *argv" "const char *optstring"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn getopt
  55 function incrementally parses a command line argument list
  56 .Fa argv
  57 and returns the next
  58 .Em known
  59 option character.
  60 An option character is
  61 .Em known
  62 if it has been specified in the string of accepted option characters,
  63 .Fa optstring .
  64 .Pp
  65 The option string
  66 .Fa optstring
  67 may contain the following elements: individual characters, and
  68 characters followed by a colon to indicate an option argument
  69 is to follow.
  70 For example, an option string
  71 .Li "\&""x""
  72 recognizes an option
  73 .Dq Fl x ,
  74 and an option string
  75 .Li "\&""x:""
  76 recognizes an option and argument
  77 .Dq Fl x Ar argument .
  78 It does not matter to
  79 .Fn getopt
  80 if a following argument has leading white space.
  81 .Pp
  82 On return from
  83 .Fn getopt ,
  84 .Va optarg
  85 points to an option argument, if it is anticipated,
  86 and the variable
  87 .Va optind
  88 contains the index to the next
  89 .Fa argv
  90 argument for a subsequent call
  91 to
  92 .Fn getopt .
  93 The variable
  94 .Va optopt
  95 saves the last
  96 .Em known
  97 option character returned by
  98 .Fn getopt .
  99 .Pp
 100 The variable
 101 .Va opterr
 102 and
 103 .Va optind
 104 are both initialized to 1.
 105 The
 106 .Va optind
 107 variable may be set to another value before a set of calls to
 108 .Fn getopt
 109 in order to skip over more or less argv entries.
 110 .Pp
 111 In order to use
 112 .Fn getopt
 113 to evaluate multiple sets of arguments, or to evaluate a single set of
 114 arguments multiple times,
 115 the variable
 116 .Va optreset
 117 must be set to 1 before the second and each additional set of calls to
 118 .Fn getopt ,
 119 and the variable
 120 .Va optind
 121 must be reinitialized.
 122 .Pp
 123 The
 124 .Fn getopt
 125 function
 126 returns \-1
 127 when the argument list is exhausted, or
 128 .Ql ?\&
 129 if a non-recognized
 130 option is encountered.
 131 The interpretation of options in the argument list may be cancelled
 132 by the option
 133 .Ql --
 134 (double dash) which causes
 135 .Fn getopt
 136 to signal the end of argument processing and return \-1.
 137 When all options have been processed (i.e., up to the first non-option
 138 argument),
 139 .Fn getopt
 140 returns \-1.
 141 .Sh DIAGNOSTICS
 142 If the
 143 .Fn getopt
 144 function encounters a character not found in the string
 145 .Va optstring
 146 or detects
 147 a missing option argument it writes an error message to the
 148 .Em stderr
 149 and returns
 150 .Ql ?\& .
 151 Setting
 152 .Va opterr
 153 to a zero will disable these error messages.
 154 If
 155 .Va optstring
 156 has a leading
 157 .Ql \&:
 158 then a missing option argument causes a
 159 .Ql \&:
 160 to be returned in addition to suppressing any error messages.
 161 .Pp
 162 Option arguments are allowed to begin with
 163 .Dq Li \- ;
 164 this is reasonable but
 165 reduces the amount of error checking possible.
 166 .Sh EXTENSIONS
 167 The
 168 .Va optreset
 169 variable was added to make it possible to call the
 170 .Fn getopt
 171 function multiple times.
 172 This is an extension to the
 173 .St -p1003.2
 174 specification.
 175 .Sh EXAMPLES
 176 .Bd -literal -compact
 177 int bflag, ch, fd;
 178
 179 bflag = 0;
 180 while ((ch = getopt(argc, argv, "bf:")) != -1)
 181         switch (ch) {
 182         case 'b':
 183                 bflag = 1;
 184                 break;
 185         case 'f':
 186                 if ((fd = open(optarg, O_RDONLY, 0)) < 0)
 187                         err(1, "%s", optarg);
 188                 break;
 189         case '?':
 190         default:
 191                 usage();
 192         }
 193 argc -= optind;
 194 argv += optind;
 195 .Ed
 196 .Sh HISTORY
 197 The
 198 .Fn getopt
 199 function appeared in
 200 .Bx 4.3 .
 201 .Sh BUGS
 202 The
 203 .Fn getopt
 204 function was once specified to return
 205 .Dv EOF
 206 instead of \-1.
 207 This was changed by
 208 .St -p1003.2-92
 209 to decouple
 210 .Fn getopt
 211 from
 212 .Pa <stdio.h> .
 213 .Pp
 214 A single dash
 215 .Dq Li -
 216 may be specified as a character in
 217 .Fa optstring ,
 218 however it should
 219 .Em never
 220 have an argument associated with it.
 221 This allows
 222 .Fn getopt
 223 to be used with programs that expect
 224 .Dq Li -
 225 as an option flag.
 226 This practice is wrong, and should not be used in any current development.
 227 It is provided for backward compatibility
 228 .Em only .
 229 By default, a single dash causes
 230 .Fn getopt
 231 to return \-1.
 232 This is, we believe, compatible with System V.
 233 .Pp
 234 It is also possible to handle digits as option letters.
 235 This allows
 236 .Fn getopt
 237 to be used with programs that expect a number
 238 .Pq Dq Li \&-\&3
 239 as an option.
 240 This practice is wrong, and should not be used in any current development.
 241 It is provided for backward compatibility
 242 .Em only .
 243 The following code fragment works in most (but not all) cases.
 244 .Bd -literal -offset indent
 245 int length;
 246 char *p, *ep;
 247
 248 while ((ch = getopt(argc, argv, "0123456789")) != -1)
 249         switch (ch) {
 250         case '0': case '1': case '2': case '3': case '4':
 251         case '5': case '6': case '7': case '8': case '9':
 252                 p = argv[optind - 1];
 253                 if (p[0] == '-' && p[1] == ch && !p[2])
 254                         length = strtol(++p, &ep, 10);
 255                 else if (argv[optind] && argv[optind][1] == ch) {
 256                         length = strtol((p = argv[optind] + 1),
 257                             &ep, 10);
 258                         optind++;
 259                         optreset = 1;
 260                 } else
 261                         usage();
 262                 if (*ep != '\0')
 263                         errx(EX_USAGE, "illegal number -- %s", p);
 264                 break;
 265         }
 266 .Ed