summaryrefslogtreecommitdiff
path: root/src/lib/libc/stdlib/getopt.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/stdlib/getopt.3')
-rw-r--r--src/lib/libc/stdlib/getopt.3365
1 files changed, 0 insertions, 365 deletions
diff --git a/src/lib/libc/stdlib/getopt.3 b/src/lib/libc/stdlib/getopt.3
deleted file mode 100644
index c7e28ff91f..0000000000
--- a/src/lib/libc/stdlib/getopt.3
+++ /dev/null
@@ -1,365 +0,0 @@
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. Neither the name of the University nor the names of its contributors
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" $OpenBSD: getopt.3,v 1.48 2022/07/25 02:25:55 jsg Exp $
29.\"
30.Dd $Mdocdate: July 25 2022 $
31.Dt GETOPT 3
32.Os
33.Sh NAME
34.Nm getopt
35.Nd get option character from command line argument list
36.Sh SYNOPSIS
37.In unistd.h
38.Vt extern char *optarg;
39.Vt extern int opterr;
40.Vt extern int optind;
41.Vt extern int optopt;
42.Vt extern int optreset;
43.Ft int
44.Fn getopt "int argc" "char * const *argv" "const char *optstring"
45.Sh DESCRIPTION
46The
47.Fn getopt
48function incrementally parses a command line argument list
49.Fa argv
50and returns the next
51.Em known
52option character.
53An option character is
54.Em known
55if it has been specified in the string of accepted option characters,
56.Fa optstring .
57.Pp
58The option string
59.Fa optstring
60may contain the following elements: individual characters,
61characters followed by a colon, and characters followed by two colons.
62A character followed by a single colon indicates that an argument
63is to follow the option on the command line.
64Two colons indicates that the argument is optional \- this is an
65extension not covered by POSIX.
66For example, an option string
67.Qq x
68recognizes an option
69.Fl x ,
70and an option string
71.Qq Li x:
72recognizes an option and argument
73.Fl x Ar argument .
74It does not matter to
75.Fn getopt
76if a following argument has leading whitespace; except in the case where
77the argument is optional, denoted with two colons, no leading whitespace
78is permitted.
79.Pp
80On return from
81.Fn getopt ,
82.Va optarg
83points to an option argument, if it is anticipated,
84and the variable
85.Va optind
86contains the index to the next
87.Fa argv
88argument for a subsequent call
89to
90.Fn getopt .
91.Pp
92The variables
93.Va opterr
94and
95.Va optind
96are both initialized to 1.
97The
98.Va optind
99variable may be set to another value larger than 0 before a set of calls to
100.Fn getopt
101in order to skip over more or less
102.Fa argv
103entries.
104An
105.Va optind
106value of 0 is reserved for compatibility with GNU
107.Fn getopt .
108.Pp
109In order to use
110.Fn getopt
111to evaluate multiple sets of arguments, or to evaluate a single set of
112arguments multiple times,
113the variable
114.Va optreset
115must be set to 1 before the second and each additional set of calls to
116.Fn getopt ,
117and the variable
118.Va optind
119must be reinitialized.
120.Pp
121The
122.Fn getopt
123function returns \-1 when the argument list is exhausted.
124The interpretation of options in the argument list may be cancelled
125by the option
126.Ql --
127(double dash) which causes
128.Fn getopt
129to signal the end of argument processing and return \-1.
130When all options have been processed (i.e., up to the first non-option
131argument),
132.Fn getopt
133returns \-1.
134.Sh RETURN VALUES
135The
136.Fn getopt
137function returns the next known option character in
138.Fa optstring .
139If
140.Fn getopt
141encounters a character not found in
142.Fa optstring
143or if it detects a missing option argument,
144it returns
145.Sq \&?
146(question mark).
147If
148.Fa optstring
149has a leading
150.Sq \&:
151then a missing option argument causes
152.Sq \&:
153to be returned instead of
154.Sq \&? .
155In either case, the variable
156.Va optopt
157is set to the character that caused the error.
158The
159.Fn getopt
160function returns \-1 when the argument list is exhausted.
161.Sh EXAMPLES
162The following code accepts the options
163.Fl b
164and
165.Fl f Ar argument
166and adjusts
167.Va argc
168and
169.Va argv
170after option argument processing has completed.
171.Bd -literal -offset indent
172int bflag, ch, fd;
173
174bflag = 0;
175while ((ch = getopt(argc, argv, "bf:")) != -1) {
176 switch (ch) {
177 case 'b':
178 bflag = 1;
179 break;
180 case 'f':
181 if ((fd = open(optarg, O_RDONLY)) == -1)
182 err(1, "%s", optarg);
183 break;
184 default:
185 usage();
186 }
187}
188argc -= optind;
189argv += optind;
190.Ed
191.Sh DIAGNOSTICS
192If the
193.Fn getopt
194function encounters a character not found in the string
195.Fa optstring
196or detects
197a missing option argument, it writes an error message to
198.Em stderr
199and returns
200.Ql \&? .
201Setting
202.Va opterr
203to a zero will disable these error messages.
204If
205.Fa optstring
206has a leading
207.Ql \&:
208then a missing option argument causes a
209.Ql \&:
210to be returned in addition to suppressing any error messages.
211.Pp
212Option arguments are allowed to begin with
213.Ql - ;
214this is reasonable but reduces the amount of error checking possible.
215.Sh SEE ALSO
216.Xr getopt 1 ,
217.Xr getopt_long 3 ,
218.Xr getsubopt 3
219.Sh STANDARDS
220The
221.Fn getopt
222function implements a superset of the functionality specified by
223.St -p1003.1 .
224.Pp
225The following extensions are supported:
226.Bl -bullet
227.It
228The
229.Va optreset
230variable was added to make it possible to call the
231.Fn getopt
232function multiple times.
233.It
234If the
235.Va optind
236variable is set to 0,
237.Fn getopt
238will behave as if the
239.Va optreset
240variable has been set.
241This is for compatibility with
242.Tn GNU
243.Fn getopt .
244New code should use
245.Va optreset
246instead.
247.It
248If the first character of
249.Fa optstring
250is a plus sign
251.Pq Ql + ,
252it will be ignored.
253This is for compatibility with
254.Tn GNU
255.Fn getopt .
256.It
257If the first character of
258.Fa optstring
259is a dash
260.Pq Ql - ,
261non-options will be returned as arguments to the option character
262.Ql \e1 .
263This is for compatibility with
264.Tn GNU
265.Fn getopt .
266.It
267A single dash
268.Pq Ql -
269may be specified as a character in
270.Fa optstring ,
271however it should
272.Em never
273have an argument associated with it.
274This allows
275.Fn getopt
276to be used with programs that expect
277.Ql -
278as an option flag.
279This practice is wrong, and should not be used in any current development.
280It is provided for backward compatibility
281.Em only .
282Care should be taken not to use
283.Ql -
284as the first character in
285.Fa optstring
286to avoid a semantic conflict with
287.Tn GNU
288.Fn getopt
289semantics (see above).
290By default, a single dash causes
291.Fn getopt
292to return \-1.
293.El
294.Pp
295Historic
296.Bx
297versions of
298.Fn getopt
299set
300.Fa optopt
301to the last option character processed.
302However, this conflicts with
303.St -p1003.1
304which stipulates that
305.Fa optopt
306be set to the last character that caused an error.
307.Sh HISTORY
308The
309.Fn getopt
310function first appeared in
311.At III
312and was reimplemented for
313.Bx 4.3 .
314.Sh BUGS
315The
316.Fn getopt
317function was once specified to return
318.Dv EOF
319instead of \-1.
320This was changed by
321.St -p1003.2-92
322to decouple
323.Fn getopt
324from
325.In stdio.h .
326.Pp
327It is possible to handle digits as option letters.
328This allows
329.Fn getopt
330to be used with programs that expect a number
331.Pq Dq Li \-3
332as an option.
333This practice is wrong, and should not be used in any current development.
334It is provided for backward compatibility
335.Em only .
336The following code fragment works in most cases and can handle mixed
337number and letter arguments.
338.Bd -literal -offset indent
339int aflag = 0, bflag = 0, ch, lastch = '\e0';
340int length = -1, newarg = 1, prevoptind = 1;
341
342while ((ch = getopt(argc, argv, "0123456789ab")) != -1) {
343 switch (ch) {
344 case '0': case '1': case '2': case '3': case '4':
345 case '5': case '6': case '7': case '8': case '9':
346 if (newarg || !isdigit(lastch))
347 length = 0;
348 else if (length > INT_MAX / 10)
349 usage();
350 length = (length * 10) + (ch - '0');
351 break;
352 case 'a':
353 aflag = 1;
354 break;
355 case 'b':
356 bflag = 1;
357 break;
358 default:
359 usage();
360 }
361 lastch = ch;
362 newarg = optind != prevoptind;
363 prevoptind = optind;
364}
365.Ed
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-26 11:14:45 +0000