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. |