- Uniformly use .In for header file references.
[dragonfly.git] / lib / libc / stdlib / getopt.3
CommitLineData
984263bc
MD
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 $
44cb301e 34.\" $DragonFly: src/lib/libc/stdlib/getopt.3,v 1.5 2006/05/26 19:39:37 swildner Exp $
984263bc
MD
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
54The
55.Fn getopt
56function incrementally parses a command line argument list
57.Fa argv
58and returns the next
59.Em known
60option character.
61An option character is
62.Em known
63if it has been specified in the string of accepted option characters,
64.Fa optstring .
65.Pp
66The option string
67.Fa optstring
68may contain the following elements: individual characters, and
69characters followed by a colon to indicate an option argument
70is to follow.
71For example, an option string
72.Li "\&""x""
73recognizes an option
74.Dq Fl x ,
75and an option string
76.Li "\&""x:""
77recognizes an option and argument
78.Dq Fl x Ar argument .
79It does not matter to
80.Fn getopt
81if a following argument has leading white space.
82.Pp
83On return from
84.Fn getopt ,
85.Va optarg
86points to an option argument, if it is anticipated,
87and the variable
88.Va optind
89contains the index to the next
90.Fa argv
91argument for a subsequent call
92to
93.Fn getopt .
94The variable
95.Va optopt
96saves the last
97.Em known
98option character returned by
99.Fn getopt .
100.Pp
101The variable
102.Va opterr
103and
104.Va optind
105are both initialized to 1.
106The
107.Va optind
108variable may be set to another value before a set of calls to
109.Fn getopt
110in order to skip over more or less argv entries.
111.Pp
112In order to use
113.Fn getopt
114to evaluate multiple sets of arguments, or to evaluate a single set of
115arguments multiple times,
116the variable
117.Va optreset
118must be set to 1 before the second and each additional set of calls to
119.Fn getopt ,
120and the variable
121.Va optind
122must be reinitialized.
123.Pp
124The
125.Fn getopt
126function
127returns \-1
128when the argument list is exhausted, or
129.Ql ?\&
130if a non-recognized
131option is encountered.
132The interpretation of options in the argument list may be cancelled
133by the option
134.Ql --
135(double dash) which causes
136.Fn getopt
137to signal the end of argument processing and return \-1.
138When all options have been processed (i.e., up to the first non-option
139argument),
140.Fn getopt
141returns \-1.
0b84df5c
SW
142.Sh EXAMPLES
143.Bd -literal -compact
144int bflag, ch, fd;
145
146bflag = 0;
147while ((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}
160argc -= optind;
161argv += optind;
162.Ed
984263bc
MD
163.Sh DIAGNOSTICS
164If the
165.Fn getopt
166function encounters a character not found in the string
167.Va optstring
168or detects
169a missing option argument it writes an error message to the
170.Em stderr
171and returns
172.Ql ?\& .
173Setting
174.Va opterr
175to a zero will disable these error messages.
176If
177.Va optstring
178has a leading
179.Ql \&:
180then a missing option argument causes a
181.Ql \&:
182to be returned in addition to suppressing any error messages.
183.Pp
184Option arguments are allowed to begin with
185.Dq Li \- ;
186this is reasonable but
187reduces the amount of error checking possible.
188.Sh EXTENSIONS
189The
190.Va optreset
191variable was added to make it possible to call the
192.Fn getopt
193function multiple times.
194This is an extension to the
195.St -p1003.2
196specification.
984263bc
MD
197.Sh HISTORY
198The
199.Fn getopt
200function appeared in
201.Bx 4.3 .
202.Sh BUGS
203The
204.Fn getopt
205function was once specified to return
206.Dv EOF
207instead of \-1.
208This was changed by
209.St -p1003.2-92
210to decouple
211.Fn getopt
212from
44cb301e 213.In stdio.h .
984263bc
MD
214.Pp
215A single dash
216.Dq Li -
217may be specified as a character in
218.Fa optstring ,
219however it should
220.Em never
221have an argument associated with it.
222This allows
223.Fn getopt
224to be used with programs that expect
225.Dq Li -
226as an option flag.
227This practice is wrong, and should not be used in any current development.
228It is provided for backward compatibility
229.Em only .
230By default, a single dash causes
231.Fn getopt
232to return \-1.
233This is, we believe, compatible with System V.
234.Pp
235It is also possible to handle digits as option letters.
236This allows
237.Fn getopt
238to be used with programs that expect a number
239.Pq Dq Li \&-\&3
240as an option.
241This practice is wrong, and should not be used in any current development.
242It is provided for backward compatibility
243.Em only .
244The following code fragment works in most (but not all) cases.
245.Bd -literal -offset indent
246int length;
247char *p, *ep;
248
f3bc7b98 249while ((ch = getopt(argc, argv, "0123456789")) != -1) {
984263bc
MD
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 }
f3bc7b98 267}
984263bc 268.Ed