lib/libc/stdlib/getopt.3

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