xref: /netbsd-src/lib/libc/stdlib/getopt.3 (revision da5f4674a3fc214be3572d358b66af40ab9401e7)
1.\"	$NetBSD: getopt.3,v 1.26 2003/08/07 16:43:39 agc 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.\"
32.Dd August 11, 2002
33.Dt GETOPT 3
34.Os
35.Sh NAME
36.Nm getopt
37.Nd get option character from command line argument list
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In unistd.h
42.Vt extern char *optarg;
43.Vt extern int   optind;
44.Vt extern int   optopt;
45.Vt extern int   opterr;
46.Vt extern int   optreset;
47.Ft int
48.Fn getopt "int argc" "char * const argv[]" "const char *optstring"
49.Sh DESCRIPTION
50The
51.Fn getopt
52function incrementally parses a command line argument list
53.Fa argv
54and returns the next
55.Em known
56option character.
57An option character is
58.Em known
59if it has been specified in the string of accepted option characters,
60.Fa optstring .
61.Pp
62The option string
63.Fa optstring
64may contain the following elements: individual characters, and
65characters followed by a colon to indicate an option argument
66is to follow.
67For example, an option string
68.Li "\&""x""
69recognizes an option
70.Dq Fl x ,
71and an option string
72.Li "\&""x:""
73recognizes an option and argument
74.Dq Fl x Ar argument .
75It does not matter to
76.Fn getopt
77if a following argument has leading white space.
78.Pp
79On return from
80.Fn getopt ,
81.Va optarg
82points to an option argument, if it is anticipated,
83and the variable
84.Va optind
85contains the index to the next
86.Fa argv
87argument for a subsequent call
88to
89.Fn getopt .
90The variable
91.Va optopt
92saves the last
93.Em known
94option character returned by
95.Fn getopt .
96.Pp
97The variable
98.Va opterr
99and
100.Va optind
101are both initialized to 1.
102The
103.Va optind
104variable may be set to another value before a set of calls to
105.Fn getopt
106in order to skip over more or less argv entries.
107.Pp
108In order to use
109.Fn getopt
110to evaluate multiple sets of arguments, or to evaluate a single set of
111arguments multiple times,
112the variable
113.Va optreset
114must be set to 1 before the second and each additional set of calls to
115.Fn getopt ,
116and the variable
117.Va optind
118must be reinitialized.
119.Pp
120The
121.Fn getopt
122function
123returns \-1
124when the argument list is exhausted.
125The interpretation of options in the argument list may be cancelled
126by the option
127.Ql --
128(double dash) which causes
129.Fn getopt
130to signal the end of argument processing and returns \-1.
131When all options have been processed (i.e., up to the first non-option
132argument),
133.Fn getopt
134returns \-1.
135.Sh DIAGNOSTICS
136If the
137.Fn getopt
138function encounters a character not found in the string
139.Fa optstring
140or detects
141a missing option argument it writes an error message to
142.Va stderr
143and returns
144.Ql \&? .
145Setting
146.Va opterr
147to a zero will disable these error messages.
148If
149.Va optstring
150has a leading
151.Ql \&:
152then a missing option argument causes a
153.Ql \&:
154to be returned in addition to suppressing any error messages.
155.Pp
156Option arguments are allowed to begin with
157.Dq Li \- ;
158this is reasonable but
159reduces the amount of error checking possible.
160.Sh EXTENSIONS
161The
162.Va optreset
163variable was added to make it possible to call the
164.Fn getopt
165function multiple times.
166This is an extension to the
167.St -p1003.2
168specification.
169.Sh EXAMPLES
170.Bd -literal -compact
171extern char *optarg;
172extern int optind;
173int bflag, ch, fd;
174
175bflag = 0;
176while ((ch = getopt(argc, argv, "bf:")) != -1)
177	switch (ch) {
178	case 'b':
179		bflag = 1;
180		break;
181	case 'f':
182		if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
183			(void)fprintf(stderr,
184			    "myname: %s: %s\en", optarg, strerror(errno));
185			exit(1);
186		}
187		break;
188	case '?':
189	default:
190		usage();
191	}
192argc -= optind;
193argv += optind;
194.Ed
195.Sh HISTORY
196The
197.Fn getopt
198function appeared in
199.Bx 4.3 .
200.Sh BUGS
201The
202.Fn getopt
203function was once specified to return
204.Dv EOF
205instead of \-1.
206This was changed by
207.St -p1003.2-92
208to decouple
209.Fn getopt
210from
211.Pa \*[Lt]stdio.h\*[Gt] .
212.Pp
213A single dash
214.Dq Li -
215may be specified as a character in
216.Fa optstring ,
217however it should
218.Em never
219have an argument associated with it.
220This allows
221.Fn getopt
222to be used with programs that expect
223.Dq Li -
224as an option flag.
225This practice is wrong, and should not be used in any current development.
226It is provided for backward compatibility
227.Em only .
228By default, a single dash causes
229.Fn getopt
230to return \-1.
231This is, we believe, compatible with System V.
232.Pp
233It is also possible to handle digits as option letters.
234This allows
235.Fn getopt
236to be used with programs that expect a number
237.Pq Dq Li \&-\&3
238as an option.
239This practice is wrong, and should not be used in any current development.
240It is provided for backward compatibility
241.Em only .
242The following code fragment works in most cases.
243.Bd -literal -offset indent
244int length;
245char *p;
246
247while ((c = getopt(argc, argv, "0123456789")) != -1) {
248	switch (c) {
249	case '0': case '1': case '2': case '3': case '4':
250	case '5': case '6': case '7': case '8': case '9':
251		p = argv[optind - 1];
252		if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2])
253			length = atoi(++p);
254		else
255			length = atoi(argv[optind] + 1);
256		break;
257	}
258}
259.Ed
260