Deleted Added
sdiff udiff text old ( 126143 ) new ( 126189 )
full compact
getopt_long.3 (126143) getopt_long.3 (126189)
1.\" $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $
1.\" $OpenBSD: getopt_long.3,v 1.10 2004/01/06 23:44:28 fgsch Exp $
2.\" $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 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.
3.\"
4.\" Copyright (c) 1988, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by the University of
17.\" California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
15.\" 3. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
35.\" $FreeBSD: head/lib/libc/stdlib/getopt_long.3 126143 2004-02-23 05:07:11Z ache $
32.\" $FreeBSD: head/lib/libc/stdlib/getopt_long.3 126189 2004-02-24 08:07:26Z ache $
36.\"
37.Dd April 1, 2000
38.Dt GETOPT_LONG 3
39.Os
40.Sh NAME
33.\"
34.Dd April 1, 2000
35.Dt GETOPT_LONG 3
36.Os
37.Sh NAME
41.Nm getopt_long
38.Nm getopt_long ,
39.Nm getopt_long_only
42.Nd get long options from command line argument list
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In getopt.h
47.Vt extern char *optarg ;
40.Nd get long options from command line argument list
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In getopt.h
45.Vt extern char *optarg ;
48.Vt extern int optind ;
49.Vt extern int optopt ;
50.Vt extern int opterr ;
51.Vt extern int optreset ;
46.Vt extern int optind ;
47.Vt extern int optopt ;
48.Vt extern int opterr ;
49.Vt extern int optreset ;
52.Ft int
53.Fo getopt_long
54.Fa "int argc" "char * const *argv" "const char *optstring"
50.Ft int
51.Fo getopt_long
52.Fa "int argc" "char * const *argv" "const char *optstring"
55.Fa "struct option *long options" "int *index"
53.Fa "const struct option *longopts" "int *longindex"
56.Fc
54.Fc
55.Ft int
56.Fo getopt_long_only
57.Fa "int argc" "char * const *argv" "const char *optstring"
58.Fa "const struct option *longopts" "int *longindex"
59.Fc
57.Sh DESCRIPTION
58The
59.Fn getopt_long
60function is similar to
61.Xr getopt 3
62but it accepts options in two forms: words and characters.
63The
64.Fn getopt_long

--- 88 unchanged lines hidden (view full) ---

153.Va flag
154to
155.Dv NULL
156and setting
157.Va val
158to the corresponding short option will make this function act just
159like
160.Xr getopt 3 .
60.Sh DESCRIPTION
61The
62.Fn getopt_long
63function is similar to
64.Xr getopt 3
65but it accepts options in two forms: words and characters.
66The
67.Fn getopt_long

--- 88 unchanged lines hidden (view full) ---

156.Va flag
157to
158.Dv NULL
159and setting
160.Va val
161to the corresponding short option will make this function act just
162like
163.Xr getopt 3 .
164.Pp
165If the
166.Fa longindex
167field is not
168.Dv NULL ,
169then the integer pointed to by it will be set to the index of the long
170option relative to
171.Fa longopts .
172.Pp
173The last element of the
174.Fa longopts
175array has to be filled with zeroes.
176.Pp
177The
178.Fn getopt_long_only
179function behaves identically to
180.Fn getopt_long
181with the exception that long options may start with
182.Ql -
183in addition to
184.Ql -- .
185If an option starting with
186.Ql -
187does not match a long option but does match a single-character option,
188the single-character option is returned.
189.Sh RETURN VALUES
190If the
191.Fa flag
192field in
193.Li struct option
194is
195.Dv NULL ,
196.Fn getopt_long
197and
198.Fn getopt_long_only
199return the value specified in the
200.Fa val
201field, which is usually just the corresponding short option.
202If
203.Fa flag
204is not
205.Dv NULL ,
206these functions return 0 and store
207.Fa val
208in the location pointed to by
209.Fa flag .
210These functions return
211.Ql \&:
212if there was a missing option argument,
213.Ql \&?
214if the user specified an unknown or ambiguous option, and
215\-1 when the argument list has been exhausted.
161.Sh EXAMPLES
162.Bd -literal -compact
216.Sh EXAMPLES
217.Bd -literal -compact
163extern char *optarg;
164extern int optind;
165int bflag, ch, fd;
166int daggerset;
167
168/* options descriptor */
169static struct option longopts[] = {
218int bflag, ch, fd;
219int daggerset;
220
221/* options descriptor */
222static struct option longopts[] = {
170 { "buffy", no_argument, 0, 'b' },
171 { "floride", required_argument, 0, 'f' },
223 { "buffy", no_argument, NULL, 'b' },
224 { "fluoride", required_argument, NULL, 'f' },
172 { "daggerset", no_argument, \*[Am]daggerset, 1 },
225 { "daggerset", no_argument, \*[Am]daggerset, 1 },
173 { 0, 0, 0, 0 }
226 { NULL, 0, NULL, 0 }
174};
175
176bflag = 0;
177while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
227};
228
229bflag = 0;
230while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
178 switch(ch) {
231 switch (ch) {
179 case 'b':
180 bflag = 1;
181 break;
182 case 'f':
232 case 'b':
233 bflag = 1;
234 break;
235 case 'f':
183 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
184 (void)fprintf(stderr,
185 "myname: %s: %s\en", optarg, strerror(errno));
186 exit(1);
187 }
236 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
237 err(1, "unable to open %s", optarg);
188 break;
189 case 0:
238 break;
239 case 0:
190 if(daggerset) {
240 if (daggerset) {
191 fprintf(stderr,"Buffy will use her dagger to "
241 fprintf(stderr,"Buffy will use her dagger to "
192 "apply floride to dracula's teeth\en");
242 "apply fluoride to dracula's teeth\en");
193 }
194 break;
243 }
244 break;
195 case '?':
196 default:
197 usage();
198}
199argc -= optind;
200argv += optind;
201.Ed
202.Sh IMPLEMENTATION DIFFERENCES
203This section describes differences to the
204.Tn GNU
205implementation
206found in glibc-2.1.3:
207.Bl -bullet
208.It
209Handling of
210.Ql -
211as first char of option string in presence of
212environment variable
213.Ev POSIXLY_CORRECT :
245 default:
246 usage();
247}
248argc -= optind;
249argv += optind;
250.Ed
251.Sh IMPLEMENTATION DIFFERENCES
252This section describes differences to the
253.Tn GNU
254implementation
255found in glibc-2.1.3:
256.Bl -bullet
257.It
258Handling of
259.Ql -
260as first char of option string in presence of
261environment variable
262.Ev POSIXLY_CORRECT :
214.Bl -tag -width ".Nx"
263.Bl -tag -width ".Bx"
215.It Tn GNU
216ignores
217.Ev POSIXLY_CORRECT
218and returns non-options as
219arguments to option '\e1'.
264.It Tn GNU
265ignores
266.Ev POSIXLY_CORRECT
267and returns non-options as
268arguments to option '\e1'.
220.It Nx
269.It Bx
221honors
222.Ev POSIXLY_CORRECT
223and stops at the first non-option.
224.El
225.It
226Handling of
270honors
271.Ev POSIXLY_CORRECT
272and stops at the first non-option.
273.El
274.It
275Handling of
276.Ql -
277within the option string (not the first character):
278.Bl -tag -width ".Bx"
279.It Tn GNU
280treats a
281.Ql -
282on the command line as a non-argument.
283.It Bx
284a
285.Ql -
286within the option string matches a
287.Ql -
288(single dash) on the command line.
289This functionality is provided for backward compatibility with
290programs, such as
291.Xr su 1 ,
292that use
293.Ql -
294as an option flag.
295This practice is wrong, and should not be used in any current development.
296.El
297.It
298Handling of
227.Ql ::
228in options string in presence of
229.Ev POSIXLY_CORRECT :
299.Ql ::
300in options string in presence of
301.Ev POSIXLY_CORRECT :
230.Bl -tag -width ".Nx"
302.Bl -tag -width ".Bx"
231.It Both
232.Tn GNU
233and
303.It Both
304.Tn GNU
305and
234.Nx
306.Bx
235ignore
236.Ev POSIXLY_CORRECT
237here and take
238.Ql ::
239to
240mean the preceding option takes an optional argument.
241.El
242.It
243Return value in case of missing argument if first character
244(after
245.Ql +
246or
247.Ql - )
248in option string is not
249.Ql \&: :
307ignore
308.Ev POSIXLY_CORRECT
309here and take
310.Ql ::
311to
312mean the preceding option takes an optional argument.
313.El
314.It
315Return value in case of missing argument if first character
316(after
317.Ql +
318or
319.Ql - )
320in option string is not
321.Ql \&: :
250.Bl -tag -width ".Nx"
322.Bl -tag -width ".Bx"
251.It Tn GNU
252returns
253.Ql \&?
323.It Tn GNU
324returns
325.Ql \&?
254.It Nx
326.It Bx
255returns
256.Ql \&:
257(since
327returns
328.Ql \&:
329(since
258.Nx Ns 's
330.Bx Ns 's
259.Fn getopt
260does).
261.El
262.It
263Handling of
264.Ql --a
265in getopt:
331.Fn getopt
332does).
333.El
334.It
335Handling of
336.Ql --a
337in getopt:
266.Bl -tag -width ".Nx"
338.Bl -tag -width ".Bx"
267.It Tn GNU
268parses this as option
269.Ql - ,
270option
271.Ql a .
339.It Tn GNU
340parses this as option
341.Ql - ,
342option
343.Ql a .
272.It Nx
344.It Bx
273parses this as
274.Ql -- ,
275and returns \-1 (ignoring the
276.Ql a ) .
277(Because the original
278.Fn getopt
279does.)
280.El
281.It
282Setting of
283.Va optopt
284for long options with
285.Va flag
286!=
287.Dv NULL :
345parses this as
346.Ql -- ,
347and returns \-1 (ignoring the
348.Ql a ) .
349(Because the original
350.Fn getopt
351does.)
352.El
353.It
354Setting of
355.Va optopt
356for long options with
357.Va flag
358!=
359.Dv NULL :
288.Bl -tag -width ".Nx"
360.Bl -tag -width ".Bx"
289.It Tn GNU
290sets
291.Va optopt
292to
293.Va val .
361.It Tn GNU
362sets
363.Va optopt
364to
365.Va val .
294.It Nx
366.It Bx
295sets
296.Va optopt
297to 0 (since
298.Va val
299would never be returned).
300.El
301.It
302Handling of
303.Ql -W
304with
367sets
368.Va optopt
369to 0 (since
370.Va val
371would never be returned).
372.El
373.It
374Handling of
375.Ql -W
376with
305.Ql W ;
377.Ql W;
306in option string in
307.Fn getopt
308(not
309.Fn getopt_long ) :
378in option string in
379.Fn getopt
380(not
381.Fn getopt_long ) :
310.Bl -tag -width ".Nx"
382.Bl -tag -width ".Bx"
311.It Tn GNU
312causes a segfault.
383.It Tn GNU
384causes a segfault.
313.It Nx
314returns \-1, with
315.Va optind
316pointing past the argument of
317.Ql -W
318(as if
319.Ql "-W arg"
320were
321.Ql --arg ,
322and thus
323.Ql --
324had been found).
325.\" How should we treat W; in the option string when called via
326.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning?
385.It Bx
386no special handling is done;
387.Ql W;
388is interpreted as two separate options, neither of which take an argument.
327.El
328.It
329Setting of
330.Va optarg
331for long options without an argument that are
332invoked via
333.Ql -W
389.El
390.It
391Setting of
392.Va optarg
393for long options without an argument that are
394invoked via
395.Ql -W
334.Ql ( W ;
396.Ql ( W;
335in option string):
397in option string):
336.Bl -tag -width ".Nx"
398.Bl -tag -width ".Bx"
337.It Tn GNU
338sets
339.Va optarg
340to the option name (the argument of
341.Ql -W ) .
399.It Tn GNU
400sets
401.Va optarg
402to the option name (the argument of
403.Ql -W ) .
342.It Nx
404.It Bx
343sets
344.Va optarg
345to
346.Dv NULL
347(the argument of the long option).
348.El
349.It
350Handling of
351.Ql -W
352with an argument that is not (a prefix to) a known
353long option
354.Ql ( W ;
355in option string):
405sets
406.Va optarg
407to
408.Dv NULL
409(the argument of the long option).
410.El
411.It
412Handling of
413.Ql -W
414with an argument that is not (a prefix to) a known
415long option
416.Ql ( W ;
417in option string):
356.Bl -tag -width ".Nx"
418.Bl -tag -width ".Bx"
357.It Tn GNU
358returns
359.Ql -W
360with
361.Va optarg
362set to the unknown option.
419.It Tn GNU
420returns
421.Ql -W
422with
423.Va optarg
424set to the unknown option.
363.It Nx
425.It Bx
364treats this as an error (unknown option) and returns
365.Ql \&?
366with
367.Va optopt
368set to 0 and
369.Va optarg
370set to
371.Dv NULL
372(as
373.Tn GNU Ns 's
374man page documents).
375.El
376.It
377The error messages are different.
378.It
426treats this as an error (unknown option) and returns
427.Ql \&?
428with
429.Va optopt
430set to 0 and
431.Va optarg
432set to
433.Dv NULL
434(as
435.Tn GNU Ns 's
436man page documents).
437.El
438.It
439The error messages are different.
440.It
379.Nx
441.Bx
380does not permute the argument vector at the same points in
381the calling sequence as
382.Tn GNU
383does.
384The aspects normally used by
385the caller (ordering after \-1 is returned, value of
386.Va optind
387relative
388to current positions) are the same, though.
389(We do fewer variable swaps.)
390.El
442does not permute the argument vector at the same points in
443the calling sequence as
444.Tn GNU
445does.
446The aspects normally used by
447the caller (ordering after \-1 is returned, value of
448.Va optind
449relative
450to current positions) are the same, though.
451(We do fewer variable swaps.)
452.El
453.Sh ENVIRONMENT
454.Bl -tag -width POSIXLY_CORRECT
455.It Ev POSIXLY_CORRECT
456If set, option processing stops when the first non-option is found and
457a leading
458.Ql -
459or
460.Ql +
461in the
462.Ar optstring
463is ignored.
464.El
391.Sh SEE ALSO
392.Xr getopt 3
393.Sh HISTORY
394The
395.Fn getopt_long
465.Sh SEE ALSO
466.Xr getopt 3
467.Sh HISTORY
468The
469.Fn getopt_long
396function first appeared in
470and
471.Fn getopt_long_only
472functions first appeared in
397.Tn GNU
398libiberty.
399The first
473.Tn GNU
474libiberty.
475The first
400.Nx
401implementation appeared in 1.5.
476.Bx
477implementation of
478.Fn getopt_long
479appeared in
480.Nx 1.5 ,
481the first
482.Bx
483implementation of
484.Fn getopt_long_only
485in
486.Ox 3.3 .
487.Fx
488first included
489.Fn getopt_long
490in
491.Fx 5.0 ,
492.Fn getopt_long_only
493in
494.Fx 5.2 .
402.Sh BUGS
495.Sh BUGS
496The
497.Ar argv
498argument is not really
499.Dv const
500as its elements may be permuted (unless
501.Ev POSIXLY_CORRECT
502is set).
503.Pp
403The implementation can completely replace
404.Xr getopt 3 ,
405but right now we are using separate code.
504The implementation can completely replace
505.Xr getopt 3 ,
506but right now we are using separate code.