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