lib/libc/stdlib/getopt.3

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