getopt_long.3 (a35a7e761a63f7a815238324cdadf28be4da1848) getopt_long.3 (187f61df6186304822a9ae3706aa27ec2e0033fb)
1.\" $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $
1.\" $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $
2.\" $FreeBSD$
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

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

28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
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

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

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
35.\" $FreeBSD$
36.\"
37.Dd April 1, 2000
38.Dt GETOPT_LONG 3
39.Os
40.Sh NAME
41.Nm getopt_long
42.Nd get long options from command line argument list
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
36.\"
37.Dd April 1, 2000
38.Dt GETOPT_LONG 3
39.Os
40.Sh NAME
41.Nm getopt_long
42.Nd get long options from command line argument list
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.Fd #include \*[Lt]getopt.h\*[Gt]
46.In getopt.h
47.Ft int
47.Ft int
48.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long options" "int *index"
48.Fo getopt_long
49.Fa "int argc" "char * const *argv" "const char *optstring"
50.Fa "struct option *long options" "int *index"
51.Fc
49.Sh DESCRIPTION
50The
51.Fn getopt_long
52function is similar to
53.Xr getopt 3
52.Sh DESCRIPTION
53The
54.Fn getopt_long
55function is similar to
56.Xr getopt 3
54but it accepts options in two forms: words and characters. The
57but it accepts options in two forms: words and characters.
58The
55.Fn getopt_long
59.Fn getopt_long
56function provides a superset of of the functionality of
60function provides a superset of the functionality of
57.Xr getopt 3 .
58.Fn getopt_long
61.Xr getopt 3 .
62.Fn getopt_long
59can be used in two ways. In the first way, every long option understood
63can be used in two ways.
64In the first way, every long option understood
60by the program has a corresponding short option, and the option
61structure is only used to translate from long options to short
65by the program has a corresponding short option, and the option
66structure is only used to translate from long options to short
62options. When used in this fashion,
67options.
68When used in this fashion,
63.Fn getopt_long
64behaves identically to
65.Xr getopt 3 .
66This is a good way to add long option processing to an existing program
67with the minimum of rewriting.
68.Pp
69In the second mechanism, a long option sets a flag in the
69.Fn getopt_long
70behaves identically to
71.Xr getopt 3 .
72This is a good way to add long option processing to an existing program
73with the minimum of rewriting.
74.Pp
75In the second mechanism, a long option sets a flag in the
70.Fa option
76.Vt option
71structure passed, or will store a pointer to the command line argument
72in the
77structure passed, or will store a pointer to the command line argument
78in the
73.Fa option
74structure passed to it for options that take arguments. Additionally,
79.Vt option
80structure passed to it for options that take arguments.
81Additionally,
75the long option's argument may be specified as a single argument with
82the long option's argument may be specified as a single argument with
76an equal sign, e.g.
77.Bd -literal
78myprogram --myoption=somevalue
79.Ed
83an equal sign, e.g.,
80.Pp
84.Pp
81When a long option is processed the call to
85.Dl "myprogram --myoption=somevalue"
86.Pp
87When a long option is processed, the call to
82.Fn getopt_long
88.Fn getopt_long
83will return 0. For this reason, long option processing without
89will return 0.
90For this reason, long option processing without
84shortcuts is not backwards compatible with
85.Xr getopt 3 .
86.Pp
87It is possible to combine these methods, providing for long options
91shortcuts is not backwards compatible with
92.Xr getopt 3 .
93.Pp
94It is possible to combine these methods, providing for long options
88processing with short option equivalents for some options. Less
95processing with short option equivalents for some options.
96Less
89frequently used options would be processed as long options only.
90.Pp
91The
92.Fn getopt_long
93call requires a structure to be initialized describing the long
97frequently used options would be processed as long options only.
98.Pp
99The
100.Fn getopt_long
101call requires a structure to be initialized describing the long
94options. The structure is:
95.Bd -literal
102options.
103The structure is:
104.Bd -literal -offset indent
96struct option {
97 char *name;
98 int has_arg;
99 int *flag;
100 int val;
101};
102.Ed
103.Pp
104The
105struct option {
106 char *name;
107 int has_arg;
108 int *flag;
109 int val;
110};
111.Ed
112.Pp
113The
105.Fa name
114.Va name
106field should contain the option name without the leading double dash.
107.Pp
108The
115field should contain the option name without the leading double dash.
116.Pp
117The
109.Fa has_arg
118.Va has_arg
110field should be one of:
119field should be one of:
111.Bl -tag -width "optional_argument"
112.It Li no_argument
113no argument to the option is expect.
114.It Li required_argument
115an argument to the option is required.
120.Pp
121.Bl -tag -width ".Dv optional_argument" -offset indent -compact
122.It Dv no_argument
123no argument to the option is expect
124.It Dv required_argument
125an argument to the option is required
116.It Li optional_argument
117an argument to the option may be presented.
118.El
119.Pp
120If
126.It Li optional_argument
127an argument to the option may be presented.
128.El
129.Pp
130If
121.Fa flag
122is non-NULL, then the integer pointed to by it will be set to the
131.Va flag
132is not
133.Dv NULL ,
134then the integer pointed to by it will be set to the
123value in the
135value in the
124.Fa val
125field. If the
126.Fa flag
127field is NULL, then the
128.Fa val
129field will be returned. Setting
130.Fa flag
131to NULL and setting
132.Fa val
136.Va val
137field.
138If the
139.Va flag
140field is
141.Dv NULL ,
142then the
143.Va val
144field will be returned.
145Setting
146.Va flag
147to
148.Dv NULL
149and setting
150.Va val
133to the corresponding short option will make this function act just
134like
135.Xr getopt 3 .
136.Sh EXAMPLES
137.Bd -literal -compact
138extern char *optarg;
139extern int optind;
140int bflag, ch, fd;

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

170 case '?':
171 default:
172 usage();
173}
174argc -= optind;
175argv += optind;
176.Ed
177.Sh IMPLEMENTATION DIFFERENCES
151to the corresponding short option will make this function act just
152like
153.Xr getopt 3 .
154.Sh EXAMPLES
155.Bd -literal -compact
156extern char *optarg;
157extern int optind;
158int bflag, ch, fd;

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

188 case '?':
189 default:
190 usage();
191}
192argc -= optind;
193argv += optind;
194.Ed
195.Sh IMPLEMENTATION DIFFERENCES
178This section describes differences to the GNU implementation
196This section describes differences to the
197.Tn GNU
198implementation
179found in glibc-2.1.3:
199found in glibc-2.1.3:
180.Bl -tag -width "xxx"
181.It Li o
182handling of - as first char of option string in presence of
183environment variable POSIXLY_CORRECT:
184.Bl -tag -width "NetBSD"
185.It Li GNU
186ignores POSIXLY_CORRECT and returns non-options as
200.Bl -bullet
201.It
202Handling of
203.Ql -
204as first char of option string in presence of
205environment variable
206.Ev POSIXLY_CORRECT :
207.Bl -tag -width ".Nx"
208.It Tn GNU
209ignores
210.Ev POSIXLY_CORRECT
211and returns non-options as
187arguments to option '\e1'.
212arguments to option '\e1'.
188.It Li NetBSD
189honors POSIXLY_CORRECT and stops at the first non-option.
213.It Nx
214honors
215.Ev POSIXLY_CORRECT
216and stops at the first non-option.
190.El
217.El
191.It Li o
192handling of :: in options string in presence of POSIXLY_CORRECT:
193.Bl -tag -width "NetBSD"
194.It Li Both
195GNU and NetBSD ignore POSIXLY_CORRECT here and take :: to
218.It
219Handling of
220.Ql ::
221in options string in presence of
222.Ev POSIXLY_CORRECT :
223.Bl -tag -width ".Nx"
224.It Both
225.Tn GNU
226and
227.Nx
228ignore
229.Ev POSIXLY_CORRECT
230here and take
231.Ql ::
232to
196mean the preceding option takes an optional argument.
197.El
233mean the preceding option takes an optional argument.
234.El
198.It Li o
199return value in case of missing argument if first character
200(after + or -) in option string is not ':':
201.Bl -tag -width "NetBSD"
202.It Li GNU
203returns '?'
204.It NetBSD
205returns ':' (since NetBSD's getopt does).
235.It
236Return value in case of missing argument if first character
237(after
238.Ql +
239or
240.Ql - )
241in option string is not
242.Ql \&: :
243.Bl -tag -width ".Nx"
244.It Tn GNU
245returns
246.Ql \&?
247.It Nx
248returns
249.Ql \&:
250(since
251.Nx Ns 's
252.Fn getopt
253does).
206.El
254.El
207.It Li o
208handling of --a in getopt:
209.Bl -tag -width "NetBSD"
210.It Li GNU
211parses this as option '-', option 'a'.
212.It Li NetBSD
213parses this as '--', and returns -1 (ignoring the a). (Because
214the original getopt does.)
255.It
256Handling of
257.Ql --a
258in getopt:
259.Bl -tag -width ".Nx"
260.It Tn GNU
261parses this as option
262.Ql - ,
263option
264.Ql a .
265.It Nx
266parses this as
267.Ql -- ,
268and returns \-1 (ignoring the
269.Ql a ) .
270(Because the original
271.Fn getopt
272does.)
215.El
273.El
216.It Li o
217setting of optopt for long options with flag != NULL:
218.Bl -tag -width "NetBSD"
219.It Li GNU
220sets optopt to val.
221.It Li NetBSD
222sets optopt to 0 (since val would never be returned).
274.It
275Setting of
276.Va optopt
277for long options with
278.Va flag
279!=
280.Dv NULL :
281.Bl -tag -width ".Nx"
282.It Tn GNU
283sets
284.Va optopt
285to
286.Va val .
287.It Nx
288sets
289.Va optopt
290to 0 (since
291.Va val
292would never be returned).
223.El
293.El
224.It Li o
225handling of -W with W; in option string in getopt (not getopt_long):
226.Bl -tag -width "NetBSD"
227.It Li GNU
294.It
295Handling of
296.Ql -W
297with
298.Ql W ;
299in option string in
300.Fn getopt
301(not
302.Fn getopt_long ) :
303.Bl -tag -width ".Nx"
304.It Tn GNU
228causes a segfault.
305causes a segfault.
229.It Li NetBSD
230returns -1, with optind pointing past the argument of -W
231(as if `-W arg' were `--arg', and thus '--' had been found).
306.It Nx
307returns \-1, with
308.Va optind
309pointing past the argument of
310.Ql -W
311(as if
312.Ql "-W arg"
313were
314.Ql --arg ,
315and thus
316.Ql --
317had been found).
232.\" How should we treat W; in the option string when called via
233.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning?
234.El
318.\" How should we treat W; in the option string when called via
319.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning?
320.El
235.It Li o
236setting of optarg for long options without an argument that are
237invoked via -W (W; in option string):
238.Bl -tag -width "NetBSD"
239.It Li GNU
240sets optarg to the option name (the argument of -W).
241.It Li NetBSD
242sets optarg to NULL (the argument of the long option).
321.It
322Setting of
323.Va optarg
324for long options without an argument that are
325invoked via
326.Ql -W
327.Ql ( W ;
328in option string):
329.Bl -tag -width ".Nx"
330.It Tn GNU
331sets
332.Va optarg
333to the option name (the argument of
334.Ql -W ) .
335.It Nx
336sets
337.Va optarg
338to
339.Dv NULL
340(the argument of the long option).
243.El
341.El
244.It Li o
245handling of -W with an argument that is not (a prefix to) a known
246long option (W; in option string):
247.Bl -tag -width "NetBSD"
248.It Li GNU
249returns -W with optarg set to the unknown option.
250.It Li NetBSD
251treats this as an error (unknown option) and returns '?' with
252optopt set to 0 and optarg set to NULL (as GNU's man page
253documents).
342.It
343Handling of
344.Ql -W
345with an argument that is not (a prefix to) a known
346long option
347.Ql ( W ;
348in option string):
349.Bl -tag -width ".Nx"
350.It Tn GNU
351returns
352.Ql -W
353with
354.Va optarg
355set to the unknown option.
356.It Nx
357treats this as an error (unknown option) and returns
358.Ql \&?
359with
360.Va optopt
361set to 0 and
362.Va optarg
363set to
364.Dv NULL
365(as
366.Tn GNU Ns 's
367man page documents).
254.El
368.El
255.It Li o
369.It
256The error messages are different.
370The error messages are different.
257.It Li o
258NetBSD does not permute the argument vector at the same points in
259the calling sequence as GNU does. The aspects normally used by
260the caller (ordering after -1 is returned, value of optind relative
261to current positions) are the same, though. (We do fewer variable
262swaps.)
371.It
372.Nx
373does not permute the argument vector at the same points in
374the calling sequence as
375.Tn GNU
376does.
377The aspects normally used by
378the caller (ordering after \-1 is returned, value of
379.Va optind
380relative
381to current positions) are the same, though.
382(We do fewer variable swaps.)
263.El
264.Sh SEE ALSO
265.Xr getopt 3
266.Sh HISTORY
267The
268.Fn getopt_long
383.El
384.Sh SEE ALSO
385.Xr getopt 3
386.Sh HISTORY
387The
388.Fn getopt_long
269function first appeared in GNU libiberty. The first
389function first appeared in
390.Tn GNU
391libiberty.
392The first
270.Nx
271implementation appeared in 1.5.
272.Sh BUGS
393.Nx
394implementation appeared in 1.5.
395.Sh BUGS
273The implementation, can completelely replace
396The implementation can completely replace
274.Xr getopt 3 ,
275but right now we are using separate code.
397.Xr getopt 3 ,
398but right now we are using separate code.