1 files changed, 366 insertions, 0 deletions

diff --git a/src/lib/libc/stdlib/getopt_long.3 b/src/lib/libc/stdlib/getopt_long.3
new file mode 100644
index 0000000000..6226dfe99f
--- /dev/null
+++ b/src/lib/libc/stdlib/getopt_long.3
@@ -0,0 +1,366 @@
+.\"     $OpenBSD: getopt_long.3,v 1.9 2003/09/02 18:24:21 jmc Exp $
+.\"     $NetBSD: getopt_long.3,v 1.11 2002/10/02 10:54:19 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. 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
+.\"
+.Dd April 1, 2000
+.Dt GETOPT_LONG 3
+.Os
+.Sh NAME
+.Nm getopt_long ,
+.Nm getopt_long_only
+.Nd get long options from command line argument list
+.Sh SYNOPSIS
+.Fd #include <getopt.h>
+.Vt extern char *optarg;
+.Vt extern int optind;
+.Vt extern int optopt;
+.Vt extern int opterr;
+.Vt extern int optreset;
+.Ft int
+.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *index"
+.Ft int
+.Fn getopt_long_only "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *index"
+.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 .
+.Fn getopt_long
+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
+.Fa option
+structure passed, or will store a pointer to the command line argument
+in the
+.Fa 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.
+.Bd -literal
+myprogram --myoption=somevalue
+.Ed
+.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
+struct option {
+        char *name;
+        int has_arg;
+        int *flag;
+        int val;
+};
+.Ed
+.Pp
+The
+.Fa name
+field should contain the option name without the leading double dash.
+.Pp
+The
+.Fa has_arg
+field should be one of:
+.Bl -tag -width "optional_argument"
+.It Li no_argument
+no argument to the option is expect.
+.It Li required_argument
+an argument to the option is required.
+.It Li optional_argument
+an argument to the option may be presented.
+.El
+.Pp
+If
+.Fa flag
+is not
+.Dv NULL ,
+then the integer pointed to by it will be set to the value in the
+.Fa val
+field.
+If the
+.Fa flag
+field is
+.Dv NULL ,
+then the
+.Fa val
+field will be returned.
+Setting
+.Fa flag
+to
+.Dv NULL
+and setting
+.Fa val
+to the corresponding short option will make this function act just
+like
+.Xr getopt 3 .
+.Pp
+The
+.Fn getopt_long_only
+function behaves identically to
+.Fn getopt_long
+with the exception that long options may start with
+.Sq -
+in addition to
+.Sq -- .
+If an option starting with
+.Sq -
+does not match a long option but does match a single-character option,
+the single-character option is returned.
+.Sh RETURN VALUES
+If the
+.Fa flag
+field in
+.Li struct option
+is
+.Dv NULL ,
+.Fn getopt_long
+and
+.Fn getopt_long_only
+return the value specified in the
+.Fa val
+field, which is usually just the corresponding short option.
+If
+.Fa flag
+is not
+.Dv NULL ,
+these functions return 0 and store
+.Fa val
+in the location pointed to by
+.Fa flag .
+These functions return
+.Sq \:
+if there was a missing option argument,
+.Sq \&?
+if the user specified an unknown or ambiguous option, and
+\-1 when the argument list has been exhausted.
+.Sh EXAMPLES
+.Bd -literal -compact
+int bflag, ch, fd;
+int daggerset;
+
+/* options descriptor */
+static struct option longopts[] = {
+        { "buffy",      no_argument,            0,              'b' },
+        { "fluoride",   required_argument,      0,              'f' },
+        { "daggerset",  no_argument,            &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)) == -1)
+                        err(1, "unable to open %s", optarg);
+                break;
+        case 0:
+                if (daggerset) {
+                        fprintf(stderr,"Buffy will use her dagger to "
+                                       "apply fluoride to dracula's teeth\en");
+                }
+                break;
+        case '?':
+        default:
+                usage();
+}
+argc -= optind;
+argv += optind;
+.Ed
+.Sh IMPLEMENTATION DIFFERENCES
+This section describes differences to the GNU implementation
+found in glibc-2.1.3:
+.Bl -tag -width "xxx"
+.It Li o
+handling of - as first char of option string in presence of
+environment variable POSIXLY_CORRECT:
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+ignores POSIXLY_CORRECT and returns non-options as
+arguments to option '\e1'.
+.It Li OpenBSD
+honors POSIXLY_CORRECT and stops at the first non-option.
+.El
+.It Li o
+handling of - within the option string (not the first character):
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+treats a
+.Ql -
+on the command line as a non-argument.
+.It Li OpenBSD
+a
+.Ql -
+within the option string matches a
+.Ql -
+(single dash) on the command line.
+This functionality is provided for backward compatibility with
+programs, such as
+.Xr su 1 ,
+that use
+.Ql -
+as an option flag.
+This practice is wrong, and should not be used in any current development.
+.El
+.It Li o
+handling of :: in options string in presence of POSIXLY_CORRECT:
+.Bl -tag -width "OpenBSD"
+.It Li Both
+GNU and OpenBSD ignore POSIXLY_CORRECT here and take :: to
+mean the preceding option takes an optional argument.
+.El
+.It Li o
+return value in case of missing argument if first character
+(after + or -) in option string is not ':':
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+returns '?'
+.It OpenBSD
+returns ':' (since OpenBSD's getopt does).
+.El
+.It Li o
+handling of --a in getopt:
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+parses this as option '-', option 'a'.
+.It Li OpenBSD
+parses this as '--', and returns \-1 (ignoring the a).
+(Because the original getopt does.)
+.El
+.It Li o
+setting of optopt for long options with flag !=
+.Dv NULL :
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+sets optopt to val.
+.It Li OpenBSD
+sets optopt to 0 (since val would never be returned).
+.El
+.It Li o
+handling of -W with W; in option string in getopt (not getopt_long):
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+causes a segfault.
+.It Li OpenBSD
+no special handling is done;
+.Dq W;
+is interpreted as two separate options, neither of which take an argument.
+.El
+.It Li o
+setting of optarg for long options without an argument that are
+invoked via -W (W; in option string):
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+sets optarg to the option name (the argument of -W).
+.It Li OpenBSD
+sets optarg to
+.Dv NULL
+(the argument of the long option).
+.El
+.It Li o
+handling of -W with an argument that is not (a prefix to) a known
+long option (W; in option string):
+.Bl -tag -width "OpenBSD"
+.It Li GNU
+returns -W with optarg set to the unknown option.
+.It Li OpenBSD
+treats this as an error (unknown option) and returns '?' with
+optopt set to 0 and optarg set to
+.Dv NULL
+(as GNU's man page documents).
+.El
+.It Li o
+The error messages are different.
+.It Li o
+OpenBSD does not permute the argument vector at the same points in
+the calling sequence as GNU does.
+The aspects normally used by the caller
+(ordering after \-1 is returned, value of optind relative
+to current positions) are the same, though.
+(We do fewer variable swaps.)
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width POSIXLY_CORRECT
+.It Ev POSIXLY_CORRECT
+If set, option processing stops when the first non-option is found and
+a leading
+.Sq -
+or
+.Sq +
+in the
+.Ar optstring
+is ignored.
+.El
+.Sh SEE ALSO
+.Xr getopt 3
+.Sh HISTORY
+The
+.Fn getopt_long
+and
+.Fn getopt_long_only
+functions first appeared in GNU libiberty.
+This implementation first appeared in
+.Ox 3.3 .
+.Sh BUGS
+The
+.Ar argv
+argument is not really
+.Dv const
+as its elements may be permuted (unless
+.Ev POSIXLY_CORRECT
+is set).