Loading...
--- Libc/Libc-320/stdlib/FreeBSD/getopt_long.3
+++ /dev/null
@@ -1,400 +0,0 @@
-.\" $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $
-.\"
-.\" Copyright (c) 1988, 1991, 1993
-.\" The Regents of the University of California. All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
-.\" may be used to endorse or promote products derived from this software
-.\" without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
-.\" $FreeBSD: src/lib/libc/stdlib/getopt_long.3,v 1.3 2002/12/18 12:45:10 ru Exp $
-.\"
-.Dd April 1, 2000
-.Dt GETOPT_LONG 3
-.Os
-.Sh NAME
-.Nm getopt_long
-.Nd get long options from command line argument list
-.Sh LIBRARY
-.Lb libc
-.Sh SYNOPSIS
-.In getopt.h
-.Ft int
-.Fo getopt_long
-.Fa "int argc" "char * const *argv" "const char *optstring"
-.Fa "struct option *long options" "int *index"
-.Fc
-.Sh DESCRIPTION
-The
-.Fn getopt_long
-function is similar to
-.Xr getopt 3
-but it accepts options in two forms: words and characters.
-The
-.Fn getopt_long
-function provides a superset of the functionality of
-.Xr getopt 3 .
-The
-.Fn getopt_long
-function
-can be used in two ways.
-In the first way, every long option understood
-by the program has a corresponding short option, and the option
-structure is only used to translate from long options to short
-options.
-When used in this fashion,
-.Fn getopt_long
-behaves identically to
-.Xr getopt 3 .
-This is a good way to add long option processing to an existing program
-with the minimum of rewriting.
-.Pp
-In the second mechanism, a long option sets a flag in the
-.Vt option
-structure passed, or will store a pointer to the command line argument
-in the
-.Vt option
-structure passed to it for options that take arguments.
-Additionally,
-the long option's argument may be specified as a single argument with
-an equal sign, e.g.,
-.Pp
-.Dl "myprogram --myoption=somevalue"
-.Pp
-When a long option is processed, the call to
-.Fn getopt_long
-will return 0.
-For this reason, long option processing without
-shortcuts is not backwards compatible with
-.Xr getopt 3 .
-.Pp
-It is possible to combine these methods, providing for long options
-processing with short option equivalents for some options.
-Less
-frequently used options would be processed as long options only.
-.Pp
-The
-.Fn getopt_long
-call requires a structure to be initialized describing the long
-options.
-The structure is:
-.Bd -literal -offset indent
-struct option {
- char *name;
- int has_arg;
- int *flag;
- int val;
-};
-.Ed
-.Pp
-The
-.Va name
-field should contain the option name without the leading double dash.
-.Pp
-The
-.Va has_arg
-field should be one of:
-.Pp
-.Bl -tag -width ".Dv optional_argument" -offset indent -compact
-.It Dv no_argument
-no argument to the option is expect
-.It Dv required_argument
-an argument to the option is required
-.It Li optional_argument
-an argument to the option may be presented.
-.El
-.Pp
-If
-.Va flag
-is not
-.Dv NULL ,
-then the integer pointed to by it will be set to the
-value in the
-.Va val
-field.
-If the
-.Va flag
-field is
-.Dv NULL ,
-then the
-.Va val
-field will be returned.
-Setting
-.Va flag
-to
-.Dv NULL
-and setting
-.Va val
-to the corresponding short option will make this function act just
-like
-.Xr getopt 3 .
-.Sh EXAMPLES
-.Bd -literal -compact
-extern char *optarg;
-extern int optind;
-int bflag, ch, fd;
-int daggerset;
-
-/* options descriptor */
-static struct option longopts[] = {
- { "buffy", no_argument, 0, 'b' },
- { "floride", required_argument, 0, 'f' },
- { "daggerset", no_argument, \*[Am]daggerset, 1 },
- { 0, 0, 0, 0 }
-};
-
-bflag = 0;
-while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
- switch(ch) {
- case 'b':
- bflag = 1;
- break;
- case 'f':
- if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
- (void)fprintf(stderr,
- "myname: %s: %s\en", optarg, strerror(errno));
- exit(1);
- }
- break;
- case 0:
- if(daggerset) {
- fprintf(stderr,"Buffy will use her dagger to "
- "apply floride to dracula's teeth\en");
- }
- break;
- case '?':
- default:
- usage();
-}
-argc -= optind;
-argv += optind;
-.Ed
-.Sh IMPLEMENTATION DIFFERENCES
-This section describes differences to the
-.Tn GNU
-implementation
-found in glibc-2.1.3:
-.Bl -bullet
-.It
-Handling of
-.Ql -
-as first char of option string in presence of
-environment variable
-.Ev POSIXLY_CORRECT :
-.Bl -tag -width ".Nx"
-.It Tn GNU
-ignores
-.Ev POSIXLY_CORRECT
-and returns non-options as
-arguments to option '\e1'.
-.It Nx
-honors
-.Ev POSIXLY_CORRECT
-and stops at the first non-option.
-.El
-.It
-Handling of
-.Ql ::
-in options string in presence of
-.Ev POSIXLY_CORRECT :
-.Bl -tag -width ".Nx"
-.It Both
-.Tn GNU
-and
-.Nx
-ignore
-.Ev POSIXLY_CORRECT
-here and take
-.Ql ::
-to
-mean the preceding option takes an optional argument.
-.El
-.It
-Return value in case of missing argument if first character
-(after
-.Ql +
-or
-.Ql - )
-in option string is not
-.Ql \&: :
-.Bl -tag -width ".Nx"
-.It Tn GNU
-returns
-.Ql \&?
-.It Nx
-returns
-.Ql \&:
-(since
-.Nx Ns 's
-.Fn getopt
-does).
-.El
-.It
-Handling of
-.Ql --a
-in getopt:
-.Bl -tag -width ".Nx"
-.It Tn GNU
-parses this as option
-.Ql - ,
-option
-.Ql a .
-.It Nx
-parses this as
-.Ql -- ,
-and returns \-1 (ignoring the
-.Ql a ) .
-(Because the original
-.Fn getopt
-does.)
-.El
-.It
-Setting of
-.Va optopt
-for long options with
-.Va flag
-!=
-.Dv NULL :
-.Bl -tag -width ".Nx"
-.It Tn GNU
-sets
-.Va optopt
-to
-.Va val .
-.It Nx
-sets
-.Va optopt
-to 0 (since
-.Va val
-would never be returned).
-.El
-.It
-Handling of
-.Ql -W
-with
-.Ql W ;
-in option string in
-.Fn getopt
-(not
-.Fn getopt_long ) :
-.Bl -tag -width ".Nx"
-.It Tn GNU
-causes a segfault.
-.It Nx
-returns \-1, with
-.Va optind
-pointing past the argument of
-.Ql -W
-(as if
-.Ql "-W arg"
-were
-.Ql --arg ,
-and thus
-.Ql --
-had been found).
-.\" How should we treat W; in the option string when called via
-.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning?
-.El
-.It
-Setting of
-.Va optarg
-for long options without an argument that are
-invoked via
-.Ql -W
-.Ql ( W ;
-in option string):
-.Bl -tag -width ".Nx"
-.It Tn GNU
-sets
-.Va optarg
-to the option name (the argument of
-.Ql -W ) .
-.It Nx
-sets
-.Va optarg
-to
-.Dv NULL
-(the argument of the long option).
-.El
-.It
-Handling of
-.Ql -W
-with an argument that is not (a prefix to) a known
-long option
-.Ql ( W ;
-in option string):
-.Bl -tag -width ".Nx"
-.It Tn GNU
-returns
-.Ql -W
-with
-.Va optarg
-set to the unknown option.
-.It Nx
-treats this as an error (unknown option) and returns
-.Ql \&?
-with
-.Va optopt
-set to 0 and
-.Va optarg
-set to
-.Dv NULL
-(as
-.Tn GNU Ns 's
-man page documents).
-.El
-.It
-The error messages are different.
-.It
-.Nx
-does not permute the argument vector at the same points in
-the calling sequence as
-.Tn GNU
-does.
-The aspects normally used by
-the caller (ordering after \-1 is returned, value of
-.Va optind
-relative
-to current positions) are the same, though.
-(We do fewer variable swaps.)
-.El
-.Sh SEE ALSO
-.Xr getopt 3
-.Sh HISTORY
-The
-.Fn getopt_long
-function first appeared in
-.Tn GNU
-libiberty.
-The first
-.Nx
-implementation appeared in 1.5.
-.Sh BUGS
-The implementation can completely replace
-.Xr getopt 3 ,
-but right now we are using separate code.