Annotation of src/lib/libc/stdlib/getopt_long.3, Revision 1.1
1.1 ! mcr 1: .\" $NetBSD: getopt.3,v 1.13 1998/04/28 21:19:49 fair 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.
! 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
! 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
! 35: .\"
! 36: .Dd November 19, 1998
! 37: .Dt GETOPT_LONG 3
! 38: .Os NetBSD 4.4
! 39: .Sh NAME
! 40: .Nm getopt_long
! 41: .Nd get long options from command line argument list
! 42: .Sh LIBRARY
! 43: .Lb libc
! 44: .Sh SYNOPSIS
! 45: .Fd #include <unistd.h>
! 46: .Fd #include <getopt.h>
! 47: .Vt struct option {
! 48: .Vt char * name;
! 49: .Vt int has_arg;
! 50: .Vt int * flag;
! 51: .Vt int val;
! 52: .Vt };
! 53: .Vt extern char *optarg;
! 54: .Vt extern int optind;
! 55: .Vt extern int optopt;
! 56: .Vt extern int opterr;
! 57: .Vt extern int optreset;
! 58: .Ft int
! 59: .Fn getopt "int argc" "char * const *argv" "const char *optstring"
! 60: .Ft int
! 61: .Fn getopt_long "int argc" "char * const *argv" "const char *optstring"
! 62: "struct options *long options" "int *index"
! 63: .Sh DESCRIPTION
! 64: The
! 65: .Fn getopt
! 66: function incrementally parses a command line argument list
! 67: .Fa argv
! 68: and returns the next
! 69: .Em known
! 70: option character.
! 71: An option character is
! 72: .Em known
! 73: if it has been specified in the string of accepted option characters,
! 74: .Fa optstring .
! 75: .Pp
! 76: The
! 77: .Fn getopt_long
! 78: function is similar to
! 79: .Fn getopt
! 80: but it accepts options in two forms: words and characters. The
! 81: .Fn getopt_long
! 82: function provides a superset of of the functionality of
! 83: .Fn getopt
! 84: The additional functionality is described in the section GETOPT_LONG.
! 85: .Pp
! 86: The option string
! 87: .Fa optstring
! 88: may contain the following elements: individual characters, and
! 89: characters followed by a colon to indicate an option argument
! 90: is to follow.
! 91: For example, an option string
! 92: .Li "\&""x""
! 93: recognizes an option
! 94: .Dq Fl x ,
! 95: and an option string
! 96: .Li "\&""x:""
! 97: recognizes an option and argument
! 98: .Dq Fl x Ar argument .
! 99: It does not matter to
! 100: .Fn getopt
! 101: if a following argument has leading white space.
! 102: .Pp
! 103: On return from
! 104: .Fn getopt ,
! 105: .Va optarg
! 106: points to an option argument, if it is anticipated,
! 107: and the variable
! 108: .Va optind
! 109: contains the index to the next
! 110: .Fa argv
! 111: argument for a subsequent call
! 112: to
! 113: .Fn getopt .
! 114: The variable
! 115: .Va optopt
! 116: saves the last
! 117: .Em known
! 118: option character returned by
! 119: .Fn getopt .
! 120: .Pp
! 121: The variable
! 122: .Va opterr
! 123: and
! 124: .Va optind
! 125: are both initialized to 1.
! 126: The
! 127: .Va optind
! 128: variable may be set to another value before a set of calls to
! 129: .Fn getopt
! 130: in order to skip over more or less argv entries.
! 131: .Pp
! 132: In order to use
! 133: .Fn getopt
! 134: to evaluate multiple sets of arguments, or to evaluate a single set of
! 135: arguments multiple times,
! 136: the variable
! 137: .Va optreset
! 138: must be set to 1 before the second and each additional set of calls to
! 139: .Fn getopt ,
! 140: and the variable
! 141: .Va optind
! 142: must be reinitialized.
! 143: .Pp
! 144: The
! 145: .Fn getopt
! 146: function
! 147: returns \-1
! 148: when the argument list is exhausted, or a non-recognized
! 149: option is encountered.
! 150: The interpretation of options in the argument list may be cancelled
! 151: by the option
! 152: .Ql --
! 153: (double dash) which causes
! 154: .Fn getopt
! 155: to signal the end of argument processing and returns \-1.
! 156: When all options have been processed (i.e., up to the first non-option
! 157: argument),
! 158: .Fn getopt
! 159: returns \-1.
! 160: .Sh GETOPT_LONG
! 161: .Pp
! 162: .Fn getopt_long
! 163: can be used in two ways. In the first way, every long option understood
! 164: by the program has a coresponding short option, and the option
! 165: structure is only used to translate from long option to short
! 166: options. When used in this fashion,
! 167: .Fn getopt_long
! 168: behaves identically to
! 169: .Fn getopt.
! 170: This is good way to add long option processing to an existing program
! 171: with the minimum of rewriting.
! 172: .Pp
! 173: In the second mechanism, a long option set a flag in the
! 174: .Fa option
! 175: structure passed, or will store a pointer to the command line argument
! 176: in the
! 177: .Fa option
! 178: structure passed to it for options that take arguments. Additionally,
! 179: the long option's argument may be specified as a single argument with
! 180: an equal sign, e.g
! 181: .Bd -literal
! 182: myprogram --myoption=somevalue
! 183: .Ed
! 184: .Pp
! 185: When a long option is processed the call to
! 186: .Fn getopt_long
! 187: will return 0. For this reason, long option processing without
! 188: shortcuts are not backwards compatible with
! 189: .Fn getopt.
! 190: .Pp
! 191: It is possible to combine these methods, providing for long options
! 192: processing with short option equivalents for some options. Less
! 193: frequently used options would be processed as long options only.
! 194: .Sh USAGE OF GETOPT_LONG
! 195: .Pp
! 196: The
! 197: .Fn getopt_long
! 198: call requires a structure to be initialized describing the long
! 199: options. The structure is:
! 200: .Bd -literal
! 201: struct option {
! 202: char * name;
! 203: int has_arg;
! 204: int * flag;
! 205: int val;
! 206: };
! 207: .Ed
! 208: .Pp
! 209: The
! 210: .Fa name
! 211: field should contain the option name without the leading double dash.
! 212: .Pp
! 213: The
! 214: .Fa has_arg
! 215: field should be one of
! 216: .Bl -tag
! 217: .It no_argument
! 218: no argument to the option is expect.
! 219: .It required_argument
! 220: an argument to the option is required.
! 221: .It optional_argument
! 222: an argument to the option may be presented.
! 223: .El
! 224: .Pp
! 225: If
! 226: .Fa flag
! 227: is non-NULL, then the integer pointed to by it will set to the value
! 228: in the
! 229: .Fa val
! 230: field. If the
! 231: .Fa flag
! 232: field is NULL, then the
! 233: .Fa val
! 234: field will be returned. Setting
! 235: .Fa flag
! 236: to NULL and setting
! 237: .Fa val
! 238: to the corresponding short option will make this function act just
! 239: like
! 240: .Fa getopt.
! 241: .Sh DIAGNOSTICS
! 242: If the
! 243: .Fn getopt
! 244: function encounters a character not found in the string
! 245: .Fa optstring
! 246: or detects
! 247: a missing option argument it writes an error message to
! 248: .Va stderr
! 249: and returns
! 250: .Ql ? .
! 251: Setting
! 252: .Va opterr
! 253: to a zero will disable these error messages.
! 254: If
! 255: .Va optstring
! 256: has a leading
! 257: .Ql \&:
! 258: then a missing option argument causes a
! 259: .Ql \&:
! 260: to be returned in addition to suppressing any error messages.
! 261: .Pp
! 262: Option arguments are allowed to begin with
! 263: .Dq Li \- ;
! 264: this is reasonable but
! 265: reduces the amount of error checking possible.
! 266: .Sh GETOPT_LONG
! 267: .Sh EXTENSIONS
! 268: The
! 269: .Va optreset
! 270: variable was added to make it possible to call the
! 271: .Fn getopt
! 272: function multiple times.
! 273: This is an extension to the
! 274: .St -p1003.2
! 275: specification.
! 276: .Sh EXAMPLE
! 277: .Bd -literal -compact
! 278: extern char *optarg;
! 279: extern int optind;
! 280: int bflag, ch, fd;
! 281:
! 282: bflag = 0;
! 283: while ((ch = getopt(argc, argv, "bf:")) != -1)
! 284: switch(ch) {
! 285: case 'b':
! 286: bflag = 1;
! 287: break;
! 288: case 'f':
! 289: if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
! 290: (void)fprintf(stderr,
! 291: "myname: %s: %s\en", optarg, strerror(errno));
! 292: exit(1);
! 293: }
! 294: break;
! 295: case '?':
! 296: default:
! 297: usage();
! 298: }
! 299: argc -= optind;
! 300: argv += optind;
! 301: .Ed
! 302: .Sh LONG EXAMPLE
! 303: .Bd -literal -compact
! 304: extern char *optarg;
! 305: extern int optind;
! 306: int bflag, ch, fd;
! 307: int daggerset;
! 308:
! 309: /* options descriptor */
! 310: static struct option longopts[] =
! 311: {
! 312: {"buffy", no_argument, 0, 'b'},
! 313: {"floride", required_argument, 0, 'f'},
! 314: {"daggerset", no_argument, &daggerset, 1},
! 315: {0, 0, 0, 0}
! 316: };
! 317:
! 318: bflag = 0;
! 319: while ((ch = getopt_long(argc, argv, "bf:")) != -1)
! 320: switch(ch) {
! 321: case 'b':
! 322: bflag = 1;
! 323: break;
! 324: case 'f':
! 325: if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
! 326: (void)fprintf(stderr,
! 327: "myname: %s: %s\en", optarg, strerror(errno));
! 328: exit(1);
! 329: }
! 330: break;
! 331: case 0:
! 332: if(daggerset) {
! 333: fprintf(stderr,"Buffy will put use her dagger"
! 334: "to apply floride to dracula's teeth");
! 335: }
! 336: break;
! 337: case '?':
! 338: default:
! 339: usage();
! 340: }
! 341: argc -= optind;
! 342: argv += optind;
! 343: .Ed
! 344: .Sh HISTORY
! 345: The
! 346: .Fn getopt
! 347: function appeared
! 348: .Bx 4.3 .
! 349: The
! 350: .Fn getopt_long
! 351: function first appeared in GNU libiberty. This implementation was
! 352: imported to NetBSD from a Kerberos distribution.
! 353: .Sh BUGS
! 354: The
! 355: .Fn getopt
! 356: function was once specified to return
! 357: .Dv EOF
! 358: instead of \-1.
! 359: This was changed by
! 360: .St -p1003.2-92
! 361: to decouple
! 362: .Fn getopt
! 363: from
! 364: .Pa <stdio.h> .
! 365: .Pp
! 366: A single dash
! 367: .Dq Li -
! 368: may be specified as an character in
! 369: .Fa optstring ,
! 370: however it should
! 371: .Em never
! 372: have an argument associated with it.
! 373: This allows
! 374: .Fn getopt
! 375: to be used with programs that expect
! 376: .Dq Li -
! 377: as an option flag.
! 378: This practice is wrong, and should not be used in any current development.
! 379: It is provided for backward compatibility
! 380: .Em only .
! 381: By default, a single dash causes
! 382: .Fn getopt
! 383: to return \-1.
! 384: This is, we believe, compatible with System V.
! 385: .Pp
! 386: It is also possible to handle digits as option letters.
! 387: This allows
! 388: .Fn getopt
! 389: to be used with programs that expect a number
! 390: .Pq Dq Li \&-\&3
! 391: as an option.
! 392: This practice is wrong, and should not be used in any current development.
! 393: It is provided for backward compatibility
! 394: .Em only .
! 395: The following code fragment works in most cases.
! 396: .Bd -literal -offset indent
! 397: int length;
! 398: char *p;
! 399:
! 400: while ((c = getopt(argc, argv, "0123456789")) != -1)
! 401: switch (c) {
! 402: case '0': case '1': case '2': case '3': case '4':
! 403: case '5': case '6': case '7': case '8': case '9':
! 404: p = argv[optind - 1];
! 405: if (p[0] == '-' && p[1] == ch && !p[2])
! 406: length = atoi(++p);
! 407: else
! 408: length = atoi(argv[optind] + 1);
! 409: break;
! 410: }
! 411: }
! 412: .Ed
! 413: .Pp
! 414: The
! 415: .Fa optional_argument
! 416: always eats the following argument unless the argument is included via
! 417: the
! 418: .Em --option=argument
! 419: notation.
CVSweb <webmaster@jp.NetBSD.org>