[src/trunk]: src/lib/libc/stdlib getopt long functionality

[mcr <mcr%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e2f0a723ccdf
branches:  trunk
changeset: 474859:e2f0a723ccdf
user:      mcr <mcr%NetBSD.org@localhost>
date:      Fri Jul 23 03:55:27 1999 +0000

description:
getopt long functionality

diffstat:

 lib/libc/stdlib/getopt_long.3 |  419 ++++++++++++++++++++++++++++++++++++++++++
 lib/libc/stdlib/getopt_long.c |  218 +++++++++++++++++++++
 2 files changed, 637 insertions(+), 0 deletions(-)

diffs (truncated from 645 to 300 lines):

diff -r cf5853d47636 -r e2f0a723ccdf lib/libc/stdlib/getopt_long.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/stdlib/getopt_long.3     Fri Jul 23 03:55:27 1999 +0000
@@ -0,0 +1,419 @@
+.\"    $NetBSD: getopt_long.3,v 1.1 1999/07/23 03:55:27 mcr 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
+.\"
+.Dd November 19, 1998
+.Dt GETOPT_LONG 3
+.Os NetBSD 4.4
+.Sh NAME
+.Nm getopt_long
+.Nd get long options from command line argument list
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.Fd #include <unistd.h>
+.Fd #include <getopt.h>
+.Vt struct option {
+.Vt    char *  name;
+.Vt    int  has_arg;
+.Vt    int * flag;
+.Vt    int val;
+.Vt };
+.Vt extern char *optarg;
+.Vt extern int   optind;
+.Vt extern int   optopt;
+.Vt extern int   opterr;
+.Vt extern int   optreset;
+.Ft int
+.Fn getopt "int argc" "char * const *argv" "const char *optstring"
+.Ft int
+.Fn getopt_long "int argc" "char * const *argv" "const char *optstring"
+"struct options *long options" "int *index"
+.Sh DESCRIPTION
+The
+.Fn getopt
+function incrementally parses a command line argument list
+.Fa argv
+and returns the next
+.Em known
+option character.
+An option character is
+.Em known
+if it has been specified in the string of accepted option characters,
+.Fa optstring .
+.Pp
+The 
+.Fn getopt_long
+function is similar to 
+.Fn getopt
+but it accepts options in two forms: words and characters. The
+.Fn getopt_long
+function provides a superset of of the functionality of 
+.Fn getopt
+The additional functionality is described in the section GETOPT_LONG.
+.Pp
+The option string
+.Fa optstring
+may contain the following elements: individual characters, and
+characters followed by a colon to indicate an option argument
+is to follow.
+For example, an option string
+.Li "\&""x""
+recognizes an option
+.Dq Fl x ,
+and an option string
+.Li "\&""x:""
+recognizes an option and argument
+.Dq Fl x Ar argument .
+It does not matter to
+.Fn getopt
+if a following argument has leading white space.
+.Pp
+On return from
+.Fn getopt ,
+.Va optarg
+points to an option argument, if it is anticipated,
+and the variable
+.Va optind
+contains the index to the next
+.Fa argv
+argument for a subsequent call
+to
+.Fn getopt .
+The variable
+.Va optopt
+saves the last
+.Em known
+option character returned by
+.Fn getopt .
+.Pp
+The variable
+.Va opterr
+and
+.Va optind
+are both initialized to 1.
+The
+.Va optind
+variable may be set to another value before a set of calls to
+.Fn getopt
+in order to skip over more or less argv entries.
+.Pp
+In order to use
+.Fn getopt
+to evaluate multiple sets of arguments, or to evaluate a single set of
+arguments multiple times,
+the variable
+.Va optreset
+must be set to 1 before the second and each additional set of calls to
+.Fn getopt ,
+and the variable
+.Va optind
+must be reinitialized.
+.Pp
+The
+.Fn getopt
+function
+returns \-1
+when the argument list is exhausted, or a non-recognized
+option is encountered.
+The interpretation of options in the argument list may be cancelled
+by the option
+.Ql --
+(double dash) which causes
+.Fn getopt
+to signal the end of argument processing and returns \-1.
+When all options have been processed (i.e., up to the first non-option
+argument),
+.Fn getopt
+returns \-1.
+.Sh GETOPT_LONG
+.Pp
+.Fn getopt_long
+can be used in two ways. In the first way, every long option understood
+by the program has a coresponding short option, and the option
+structure is only used to translate from long option to short
+options. When used in this fashion, 
+.Fn getopt_long
+behaves identically to 
+.Fn getopt.
+This is good way to add long option processing to an existing program
+with the minimum of rewriting.
+.Pp
+In the second mechanism, a long option set 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 are not backwards compatible with 
+.Fn getopt.
+.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.
+.Sh USAGE OF GETOPT_LONG
+.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
+.It no_argument
+no argument to the option is expect.
+.It required_argument
+an argument to the option is required.
+.It optional_argument
+an argument to the option may be presented.
+.El
+.Pp
+If
+.Fa flag
+is non-NULL, then the integer pointed to by it will set to the value 
+in the 
+.Fa val
+field. If the 
+.Fa flag 
+field is NULL, then the 
+.Fa val
+field will be returned. Setting 
+.Fa flag
+to NULL and setting
+.Fa val
+to the corresponding short option will make this function act just
+like
+.Fa getopt.
+.Sh DIAGNOSTICS
+If the
+.Fn getopt
+function encounters a character not found in the string
+.Fa optstring
+or detects
+a missing option argument it writes an error message to
+.Va stderr
+and returns
+.Ql ? .
+Setting
+.Va opterr
+to a zero will disable these error messages.
+If
+.Va optstring
+has a leading
+.Ql \&:
+then a missing option argument causes a
+.Ql \&:
+to be returned in addition to suppressing any error messages.
+.Pp
+Option arguments are allowed to begin with
+.Dq Li \- ;
+this is reasonable but
+reduces the amount of error checking possible.
+.Sh GETOPT_LONG
+.Sh EXTENSIONS
+The
+.Va optreset
+variable was added to make it possible to call the
+.Fn getopt
+function multiple times.
+This is an extension to the
+.St -p1003.2
+specification.
+.Sh EXAMPLE
+.Bd -literal -compact
+extern char *optarg;
+extern int optind;
+int bflag, ch, fd;
+
+bflag = 0;
+while ((ch = getopt(argc, argv, "bf:")) != -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 '?':
+       default: