diff options
Diffstat (limited to 'lib/libc/stdlib/getopt_long.3')
| -rw-r--r-- | lib/libc/stdlib/getopt_long.3 | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/lib/libc/stdlib/getopt_long.3 b/lib/libc/stdlib/getopt_long.3 new file mode 100644 index 0000000..869dd1e --- /dev/null +++ b/lib/libc/stdlib/getopt_long.3 @@ -0,0 +1,275 @@ +.\" $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $ +.\" $FreeBSD$ +.\" +.\" 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 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 +.Fd #include \*[Lt]getopt.h\*[Gt] +.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 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 non-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 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 +.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 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 != 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 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 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 completelely replace +.Xr getopt 3 , +but right now we are using separate code. |
