lib/libc/stdlib/getopt.3

   1 .\"     $NetBSD: getopt.3,v 1.31 2003/09/23 10:26:54 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 .\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.26 2007/01/09 00:28:10 imp Exp $
  32 .\" $DragonFly: src/lib/libc/stdlib/getopt.3,v 1.5 2006/05/26 19:39:37 swildner Exp $
  33 .\"
  34 .Dd April 27, 1995
  35 .Dt GETOPT 3
  36 .Os
  37 .Sh NAME
  38 .Nm getopt
  39 .Nd get option character from command line argument list
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In unistd.h
  44 .Vt extern char *optarg ;
  45 .Vt extern int optind ;
  46 .Vt extern int optopt ;
  47 .Vt extern int opterr ;
  48 .Vt extern int optreset ;
  49 .Ft int
  50 .Fn getopt "int argc" "char * const argv[]" "const char *optstring"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn getopt
  54 function incrementally parses a command line argument list
  55 .Fa argv
  56 and returns the next
  57 .Em known
  58 option character.
  59 An option character is
  60 .Em known
  61 if it has been specified in the string of accepted option characters,
  62 .Fa optstring .
  63 .Pp
  64 The option string
  65 .Fa optstring
  66 may contain the following elements: individual characters, and
  67 characters followed by a colon to indicate an option argument
  68 is to follow.
  69 For example, an option string
  70 .Li \&"x"
  71 recognizes an option
  72 .Dq Fl x ,
  73 and an option string
  74 .Li \&"x:"
  75 recognizes an option and argument
  76 .Dq Fl x Ar argument .
  77 It does not matter to
  78 .Fn getopt
  79 if a following argument has leading white space.
  80 .Pp
  81 On return from
  82 .Fn getopt ,
  83 .Va optarg
  84 points to an option argument, if it is anticipated,
  85 and the variable
  86 .Va optind
  87 contains the index to the next
  88 .Fa argv
  89 argument for a subsequent call
  90 to
  91 .Fn getopt .
  92 The variable
  93 .Va optopt
  94 saves the last
  95 .Em known
  96 option character returned by
  97 .Fn getopt .
  98 .Pp
  99 The variables
 100 .Va opterr
 101 and
 102 .Va optind
 103 are both initialized to 1.
 104 The
 105 .Va optind
 106 variable may be set to another value before a set of calls to
 107 .Fn getopt
 108 in order to skip over more or less argv entries.
 109 .Pp
 110 In order to use
 111 .Fn getopt
 112 to evaluate multiple sets of arguments, or to evaluate a single set of
 113 arguments multiple times,
 114 the variable
 115 .Va optreset
 116 must be set to 1 before the second and each additional set of calls to
 117 .Fn getopt ,
 118 and the variable
 119 .Va optind
 120 must be reinitialized.
 121 .Pp
 122 The
 123 .Fn getopt
 124 function returns \-1 when the argument list is exhausted.
 125 The interpretation of options in the argument list may be cancelled
 126 by the option
 127 .Ql --
 128 (double dash) which causes
 129 .Fn getopt
 130 to signal the end of argument processing and return \-1.
 131 When all options have been processed (i.e., up to the first non-option
 132 argument),
 133 .Fn getopt
 134 returns \-1.
 135 .Sh RETURN VALUES
 136 The
 137 .Fn getopt
 138 function returns the next known option character in
 139 .Fa optstring .
 140 If
 141 .Fn getopt
 142 encounters a character not found in
 143 .Fa optstring
 144 or if it detects a missing option argument,
 145 it returns
 146 .Ql \&?
 147 (question mark).
 148 If
 149 .Fa optstring
 150 has a leading
 151 .Ql \&:
 152 then a missing option argument causes
 153 .Ql \&:
 154 to be returned instead of
 155 .Ql \&? .
 156 In either case, the variable
 157 .Va optopt
 158 is set to the character that caused the error.
 159 The
 160 .Fn getopt
 161 function returns \-1 when the argument list is exhausted.
 162 .Sh EXAMPLES
 163 .Bd -literal -compact
 164 #include <unistd.h>
 165 int bflag, ch, fd;
 166
 167 bflag = 0;
 168 while ((ch = getopt(argc, argv, "bf:")) != -1) {
 169         switch (ch) {
 170         case 'b':
 171                 bflag = 1;
 172                 break;
 173         case 'f':
 174                 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
 175                         fprintf(stderr,
 176                             "myname: %s: %s\en", optarg, strerror(errno));
 177                         exit(1);
 178                 }
 179                 break;
 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 the
 194 .Dv stderr
 195 and returns
 196 .Ql \&? .
 197 Setting
 198 .Va opterr
 199 to a zero will disable these error messages.
 200 If
 201 .Fa optstring
 202 has a leading
 203 .Ql \&:
 204 then a missing option argument causes a
 205 .Ql \&:
 206 to be returned in addition to suppressing any error messages.
 207 .Pp
 208 Option arguments are allowed to begin with
 209 .Dq Li \- ;
 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 .In stdio.h .
 241 .Pp
 242 A single dash
 243 .Dq Li -
 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 .Dq Li -
 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 .Ql \&-
 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 .Ql \&- .
 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, *ep;
 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                         ep = "";
 295                 } else if (argv[optind] \*[Am]\*[Am] argv[optind][1] == ch) {
 296                         length = strtol((p = argv[optind] + 1),
 297                             \*[Am]ep, 10);
 298                         optind++;
 299                         optreset = 1;
 300                 } else
 301                         usage();
 302                 if (*ep != '\e0')
 303                         errx(EX_USAGE, "illegal number -- %s", p);
 304                 break;
 305         }
 306 }
 307 .Ed