docs: Added All NetBSD Manuals

1 files changed, 310 insertions, 0 deletions

diff --git a/static/netbsd/man3/getopt_long.3 b/static/netbsd/man3/getopt_long.3
new file mode 100644
index 00000000..4fc6fce6
--- /dev/null
+++ b/static/netbsd/man3/getopt_long.3
@@ -0,0 +1,310 @@
+.\"	$NetBSD: getopt_long.3,v 1.22 2022/01/04 19:36:16 uwe 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 December 9, 2018
+.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
+.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "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
+Abbreviated long option names are accepted when
+.Fn getopt_long
+processes long options if the abbreviation is unique.
+An exact match is always preferred for a defined long option.
+.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 expected.
+.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
+If the
+.Fa index
+argument is not
+.Dv NULL ,
+the integer it points to will be set to the index of the long option
+in the
+.Fa long_options
+array.
+.Pp
+The last element of the
+.Fa long_options
+array has to be filled with zeroes (see
+.Sx EXAMPLES
+section).
+.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,		NULL, 		'b' },
+	{ "fluoride",	required_argument,	NULL, 	       	'f' },
+	{ "daggerset",	no_argument,		&daggerset,	1 },
+	{ NULL,		0,			NULL, 		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)) < 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 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 "NetBSD"
+.It Li GNU
+ignores POSIXLY_CORRECT and returns non-options as
+arguments to option '\e1'.
+.It Li NetBSD
+honors POSIXLY_CORRECT and stops at the first non-option.
+.El
+.It Li o
+handling of :: in options string in presence of POSIXLY_CORRECT:
+.Bl -tag -width "NetBSD"
+.It Li Both
+GNU and NetBSD 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 "NetBSD"
+.It Li GNU
+returns '?'
+.It NetBSD
+returns ':' (since NetBSD's getopt does).
+.El
+.It Li o
+handling of --a in getopt:
+.Bl -tag -width "NetBSD"
+.It Li GNU
+parses this as option '-', option 'a'.
+.It Li NetBSD
+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 "NetBSD"
+.It Li GNU
+sets optopt to val.
+.It Li NetBSD
+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 "NetBSD"
+.It Li GNU
+causes a segfault.
+.It Li NetBSD
+returns \-1, with optind pointing past the argument of -W
+(as if `-W arg' were `--arg', and thus '--' 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 Li o
+setting of optarg for long options without an argument that are
+invoked via -W (W; in option string):
+.Bl -tag -width "NetBSD"
+.It Li GNU
+sets optarg to the option name (the argument of -W).
+.It Li NetBSD
+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 "NetBSD"
+.It Li GNU
+returns -W with optarg set to the unknown option.
+.It Li NetBSD
+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
+NetBSD 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 SEE ALSO
+.Xr getopt 3
+.Sh HISTORY
+The
+.Fn getopt_long
+function first appeared in 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.
+.Pp
+The
+.Fa argv
+argument is not really const.