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 .\"
  33 .Dd February 19, 2022
  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:
  66 .Bl -bullet -offset indent
  67 .It
  68 An individual character.
  69 For example, an option string
  70 .Li \&"x"
  71 recognizes an option
  72 .Dq Fl x .
  73 .It
  74 A character followed by a colon, which indicates the option requires
  75 an argument.
  76 It does not matter if a following argument has leading white space.
  77 For example, an option string
  78 .Li \&"x:"
  79 recognizes an option and argument
  80 .Dq Fl x Ar argument
  81 or
  82 .Dq Fl x Ns Ar argument .
  83 .It
  84 A character followed by two colons, which indicates the option argument
  85 is optional.
  86 The following argument must be in the
  87 .Em same
  88 word as the option name itself.
  89 The
  90 .Va optarg
  91 is set to the rest of the
  92 .Em current
  93 .Fa argv
  94 word, or
  95 .Dv NULL
  96 if there were no more characters in the current word.
  97 This is a
  98 .Tn GNU
  99 extension.
 100 For example, an option string
 101 .Li \&"x::"
 102 recognizes an option
 103 .Dq Fl x
 104 or an option and argument
 105 .Dq Fl x Ns Ar argument .
 106 .El
 107 .Pp
 108 On return from
 109 .Fn getopt ,
 110 .Va optarg
 111 points to an option argument, if it is anticipated,
 112 and the variable
 113 .Va optind
 114 contains the index to the next
 115 .Fa argv
 116 argument for a subsequent call
 117 to
 118 .Fn getopt .
 119 The variable
 120 .Va optopt
 121 saves the last
 122 .Em known
 123 option character returned by
 124 .Fn getopt .
 125 .Pp
 126 The variables
 127 .Va opterr
 128 and
 129 .Va optind
 130 are both initialized to 1.
 131 The
 132 .Va optind
 133 variable may be set to another value before a set of calls to
 134 .Fn getopt
 135 in order to skip over more or less
 136 .Fa argv
 137 entries.
 138 .Pp
 139 In order to use
 140 .Fn getopt
 141 to evaluate multiple sets of arguments, or to evaluate a single set of
 142 arguments multiple times,
 143 the variable
 144 .Va optreset
 145 must be set to 1 before the second and each additional set of calls to
 146 .Fn getopt ,
 147 and the variable
 148 .Va optind
 149 must be reinitialized.
 150 .Pp
 151 The
 152 .Fn getopt
 153 function returns \-1 when the argument list is exhausted.
 154 The interpretation of options in the argument list may be cancelled
 155 by the option
 156 .Ql --
 157 (double dash) which causes
 158 .Fn getopt
 159 to signal the end of argument processing and return \-1.
 160 When all options have been processed (i.e., up to the first non-option
 161 argument),
 162 .Fn getopt
 163 returns \-1.
 164 .Sh RETURN VALUES
 165 The
 166 .Fn getopt
 167 function returns the next known option character in
 168 .Fa optstring .
 169 If
 170 .Fn getopt
 171 encounters a character not found in
 172 .Fa optstring
 173 or if it detects a missing option argument,
 174 it returns
 175 .Ql \&?
 176 (question mark).
 177 If
 178 .Fa optstring
 179 has a leading
 180 .Ql \&:
 181 then a missing option argument causes
 182 .Ql \&:
 183 to be returned instead of
 184 .Ql \&? .
 185 In either case, the variable
 186 .Va optopt
 187 is set to the character that caused the error.
 188 The
 189 .Fn getopt
 190 function returns \-1 when the argument list is exhausted.
 191 .Sh EXAMPLES
 192 .Bd -literal -compact
 193 #include <unistd.h>
 194 int bflag, ch, fd;
 195
 196 bflag = 0;
 197 while ((ch = getopt(argc, argv, "bf:")) != -1) {
 198         switch (ch) {
 199         case 'b':
 200                 bflag = 1;
 201                 break;
 202         case 'f':
 203                 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
 204                         fprintf(stderr,
 205                             "myname: %s: %s\en", optarg, strerror(errno));
 206                         exit(1);
 207                 }
 208                 break;
 209         default:
 210                 usage();
 211         }
 212 }
 213 argc -= optind;
 214 argv += optind;
 215 .Ed
 216 .Sh DIAGNOSTICS
 217 If the
 218 .Fn getopt
 219 function encounters a character not found in the string
 220 .Fa optstring
 221 or detects
 222 a missing option argument it writes an error message to the
 223 .Dv stderr
 224 and returns
 225 .Ql \&? .
 226 Setting
 227 .Va opterr
 228 to a zero will disable these error messages.
 229 If
 230 .Fa optstring
 231 has a leading
 232 .Ql \&:
 233 then a missing option argument causes a
 234 .Ql \&:
 235 to be returned in addition to suppressing any error messages.
 236 .Pp
 237 Option arguments are allowed to begin with
 238 .Dq Li \- ;
 239 this is reasonable but reduces the amount of error checking possible.
 240 .Sh SEE ALSO
 241 .Xr getopt 1 ,
 242 .Xr getopt_long 3 ,
 243 .Xr getsubopt 3
 244 .Sh STANDARDS
 245 The
 246 .Va optreset
 247 variable was added to make it possible to call the
 248 .Fn getopt
 249 function multiple times.
 250 This is an extension to the
 251 .St -p1003.2
 252 specification.
 253 .Sh HISTORY
 254 The
 255 .Fn getopt
 256 function appeared in
 257 .Bx 4.3 .
 258 .Sh BUGS
 259 The
 260 .Fn getopt
 261 function was once specified to return
 262 .Dv EOF
 263 instead of \-1.
 264 This was changed by
 265 .St -p1003.2-92
 266 to decouple
 267 .Fn getopt
 268 from
 269 .In stdio.h .
 270 .Pp
 271 A single dash
 272 .Dq Li -
 273 may be specified as a character in
 274 .Fa optstring ,
 275 however it should
 276 .Em never
 277 have an argument associated with it.
 278 This allows
 279 .Fn getopt
 280 to be used with programs that expect
 281 .Dq Li -
 282 as an option flag.
 283 This practice is wrong, and should not be used in any current development.
 284 It is provided for backward compatibility
 285 .Em only .
 286 Care should be taken not to use
 287 .Ql \&-
 288 as the first character in
 289 .Fa optstring
 290 to avoid a semantic conflict with
 291 .Tn GNU
 292 .Fn getopt ,
 293 which assigns different meaning to an
 294 .Fa optstring
 295 that begins with a
 296 .Ql \&- .
 297 By default, a single dash causes
 298 .Fn getopt
 299 to return \-1.
 300 .Pp
 301 It is also possible to handle digits as option letters.
 302 This allows
 303 .Fn getopt
 304 to be used with programs that expect a number
 305 .Pq Dq Li \&-\&3
 306 as an option.
 307 This practice is wrong, and should not be used in any current development.
 308 It is provided for backward compatibility
 309 .Em only .
 310 The following code fragment works in most cases.
 311 .Bd -literal -offset indent
 312 int ch;
 313 long length;
 314 char *p, *ep;
 315
 316 while ((ch = getopt(argc, argv, "0123456789")) != -1) {
 317         switch (ch) {
 318         case '0': case '1': case '2': case '3': case '4':
 319         case '5': case '6': case '7': case '8': case '9':
 320                 p = argv[optind - 1];
 321                 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2]) {
 322                         length = ch - '0';
 323                         ep = "";
 324                 } else if (argv[optind] \*[Am]\*[Am] argv[optind][1] == ch) {
 325                         length = strtol((p = argv[optind] + 1),
 326                             \*[Am]ep, 10);
 327                         optind++;
 328                         optreset = 1;
 329                 } else
 330                         usage();
 331                 if (*ep != '\e0')
 332                         errx(EX_USAGE, "illegal number -- %s", p);
 333                 break;
 334         }
 335 }
 336 .Ed