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