lib/libc/stdlib/getopt.3

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