stdlib/FreeBSD/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 .\" 4. 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 .\"
  33 .Dd April 27, 1995
  34 .Dt GETOPT 3
  35 .Os
  36 .Sh NAME
  37 .Nm getopt
  38 .Nd get option character from command line argument list
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Vt extern char *optarg ;
  44 .Vt extern int optind ;
  45 .Vt extern int optopt ;
  46 .Vt extern int opterr ;
  47 .Vt extern int optreset ;
  48 .Ft int
  49 .Fn getopt "int argc" "char * const argv[]" "const char *optstring"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn getopt
  53 function incrementally parses a command line argument list
  54 .Fa argv
  55 and returns the next
  56 .Em known
  57 option character.
  58 An option character is
  59 .Em known
  60 if it has been specified in the string of accepted option characters,
  61 .Fa optstring .
  62 .Pp
  63 The option string
  64 .Fa optstring
  65 may contain the following elements: individual characters, and
  66 characters followed by a colon to indicate an option argument
  67 is to follow.
  68 For example, an option string
  69 .Li "\&""x""
  70 recognizes an option
  71 .Dq Fl x ,
  72 and an option string
  73 .Li "\&""x:""
  74 recognizes an option and argument
  75 .Dq Fl x Ar argument .
  76 It does not matter to
  77 .Fn getopt
  78 if a following argument has leading white space.
  79 .Pp
  80 On return from
  81 .Fn getopt ,
  82 .Va optarg
  83 points to an option argument, if it is anticipated,
  84 and the variable
  85 .Va optind
  86 contains the index to the next
  87 .Fa argv
  88 argument for a subsequent call
  89 to
  90 .Fn getopt .
  91 The variable
  92 .Va optopt
  93 saves the last
  94 .Em known
  95 option character returned by
  96 .Fn getopt .
  97 .Pp
  98 The variables
  99 .Va opterr
 100 and
 101 .Va optind
 102 are both initialized to 1.
 103 The
 104 .Va optind
 105 variable may be set to another value before a set of calls to
 106 .Fn getopt
 107 in order to skip over more or less argv entries.
 108 .Pp
 109 In order to use
 110 .Fn getopt
 111 to evaluate multiple sets of arguments, or to evaluate a single set of
 112 arguments multiple times,
 113 the variable
 114 .Va optreset
 115 must be set to 1 before the second and each additional set of calls to
 116 .Fn getopt ,
 117 and the variable
 118 .Va optind
 119 must be reinitialized.
 120 .Pp
 121 The
 122 .Fn getopt
 123 function returns \-1 when the argument list is exhausted.
 124 The interpretation of options in the argument list may be cancelled
 125 by the option
 126 .Ql --
 127 (double dash) which causes
 128 .Fn getopt
 129 to signal the end of argument processing and return \-1.
 130 When all options have been processed (i.e., up to the first non-option
 131 argument),
 132 .Fn getopt
 133 returns \-1.
 134 .Sh RETURN VALUES
 135 The
 136 .Fn getopt
 137 function returns the next known option character in
 138 .Fa optstring .
 139 If
 140 .Fn getopt
 141 encounters a character not found in
 142 .Fa optstring
 143 or if it detects a missing option argument,
 144 it returns
 145 .Ql \&?
 146 (question mark).
 147 If
 148 .Fa optstring
 149 has a leading
 150 .Ql \&:
 151 then a missing option argument causes
 152 .Ql \&:
 153 to be returned instead of
 154 .Ql \&? .
 155 In either case, the variable
 156 .Va optopt
 157 is set to the character that caused the error.
 158 The
 159 .Fn getopt
 160 function returns \-1 when the argument list is exhausted.
 161 .Sh EXAMPLES
 162 .Bd -literal -compact
 163 #include <unistd.h>
 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 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 .Ed