diff options
Diffstat (limited to 'lib/libc/stdlib/getopt_long.3')
| -rw-r--r-- | lib/libc/stdlib/getopt_long.3 | 506 |
1 files changed, 0 insertions, 506 deletions
diff --git a/lib/libc/stdlib/getopt_long.3 b/lib/libc/stdlib/getopt_long.3 deleted file mode 100644 index 72f6534..0000000 --- a/lib/libc/stdlib/getopt_long.3 +++ /dev/null @@ -1,506 +0,0 @@ -.\" $OpenBSD: getopt_long.3,v 1.10 2004/01/06 23:44:28 fgsch Exp $ -.\" $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 agc 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 -.\" $FreeBSD$ -.\" -.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 LIBRARY -.Lb libc -.Sh SYNOPSIS -.In getopt.h -.Vt extern char *optarg ; -.Vt extern int optind ; -.Vt extern int optopt ; -.Vt extern int opterr ; -.Vt extern int optreset ; -.Ft int -.Fo getopt_long -.Fa "int argc" "char * const *argv" "const char *optstring" -.Fa "const struct option *longopts" "int *longindex" -.Fc -.Ft int -.Fo getopt_long_only -.Fa "int argc" "char * const *argv" "const char *optstring" -.Fa "const struct option *longopts" "int *longindex" -.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 Dv 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 . -.Pp -If the -.Fa longindex -field is not -.Dv NULL , -then the integer pointed to by it will be set to the index of the long -option relative to -.Fa longopts . -.Pp -The last element of the -.Fa longopts -array has to be filled with zeroes. -.Pp -The -.Fn getopt_long_only -function behaves identically to -.Fn getopt_long -with the exception that long options may start with -.Ql - -in addition to -.Ql -- . -If an option starting with -.Ql - -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 -.Vt "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 -.Ql \&: -if there was a missing option argument, -.Ql \&? -if the user specified an unknown or ambiguous option, and -\-1 when the argument list has been exhausted. -.Sh ENVIRONMENT -.Bl -tag -width ".Ev POSIXLY_CORRECT" -.It Ev POSIXLY_CORRECT -If set, option processing stops when the first non-option is found and -a leading -.Ql - -or -.Ql + -in the -.Fa optstring -is ignored. -.El -.Sh EXAMPLES -.Bd -literal -compact -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, \*[Am]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)) == -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; - 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 ".Bx" -.\" .It Tn GNU -.\" ignores -.\" .Ev POSIXLY_CORRECT -.\" and returns non-options as -.\" arguments to option '\e1'. -.\" .It Bx -.\" honors -.\" .Ev POSIXLY_CORRECT -.\" and stops at the first non-option. -.\" .El -.\" .It -.\" Handling of -.\" .Ql - -.\" within the option string (not the first character): -.\" .Bl -tag -width ".Bx" -.\" .It Tn GNU -.\" treats a -.\" .Ql - -.\" on the command line as a non-argument. -.\" .It Bx -.\" 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 -.\" Handling of -.\" .Ql :: -.\" in options string in presence of -.\" .Ev POSIXLY_CORRECT : -.\" .Bl -tag -width ".Bx" -.\" .It Both -.\" .Tn GNU -.\" and -.\" .Bx -.\" 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 ".Bx" -.\" .It Tn GNU -.\" returns -.\" .Ql \&? -.\" .It Bx -.\" returns -.\" .Ql \&: -.\" (since -.\" .Bx Ns 's -.\" .Fn getopt -.\" does). -.\" .El -.\" .It -.\" Handling of -.\" .Ql --a -.\" in getopt: -.\" .Bl -tag -width ".Bx" -.\" .It Tn GNU -.\" parses this as option -.\" .Ql - , -.\" option -.\" .Ql a . -.\" .It Bx -.\" 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 ".Bx" -.It Tn GNU -sets -.Va optopt -to -.Va val . -.It Bx -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 ".Bx" -.\" .It Tn GNU -.\" causes a segfault. -.\" .It Bx -.\" no special handling is done; -.\" .Ql W; -.\" is interpreted as two separate options, neither of which take an argument. -.\" .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 ".Bx" -.It Tn GNU -sets -.Va optarg -to the option name (the argument of -.Ql -W ) . -.It Bx -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 ".Bx" -.It Tn GNU -returns -.Ql -W -with -.Va optarg -set to the unknown option. -.It Bx -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 -.Bx -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 -and -.Fn getopt_long_only -functions first appeared in the -.Tn GNU -libiberty library. -The first -.Bx -implementation of -.Fn getopt_long -appeared in -.Nx 1.5 , -the first -.Bx -implementation of -.Fn getopt_long_only -in -.Ox 3.3 . -.Fx -first included -.Fn getopt_long -in -.Fx 5.0 , -.Fn getopt_long_only -in -.Fx 5.2 . -.Sh BUGS -The -.Fa argv -argument is not really -.Vt const -as its elements may be permuted (unless -.Ev POSIXLY_CORRECT -is set). -.Pp -The implementation can completely replace -.Xr getopt 3 , -but right now we are using separate code. |
