diff -r 000000000000 -r e4d67989cc36 genericopenlibs/openenvcore/include/getopt.dosc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/genericopenlibs/openenvcore/include/getopt.dosc Tue Feb 02 02:01:42 2010 +0200 @@ -0,0 +1,377 @@ +/** @file ../include/getopt.h +@internalComponent +*/ + +/** @fn getopt_long(int argc, char * const *argv, const char *optstring, const struct option *longopts, int *longindex) +@param argc +@param argv +@param optstring +@param longopts +@param longindex +@return If the flag field in struct option +is NULL, getopt_long returns the value specified in the val field, which is usually just the corresponding short option. +If flag is not NULL, this function returns 0 and stores val in the location pointed to by flag. This function returns ' : ' +if there was a missing option argument, ' ? ' +if the user specified an unknown or ambiguous option, and +-1 when the argument list has been exhausted. + + + The getopt_long function is similar to getopt but it accepts options in two forms: words and characters. +The getopt_long function provides a superset of the functionality of getopt . +The 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, getopt_long behaves identically to getopt . +This is a good way to add long option processing to an existing program +with the minimum of rewriting. + + In the second mechanism, a long option sets a flag in the option +structure passed, or will store a pointer to the command line argument +in the 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., + +@code +myprogram --myoption=somevalue +@endcode + +When a long option is processed, the call to getopt_long will return 0. +For this reason, long option processing without +shortcuts is not backwards compatible with getopt . 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. The getopt_long call requires a structure to be initialized describing the long +options. +@code +The structure is: struct option { +char *name; +int has_arg; +int *flag; +int val; +}; +@endcode + The name field should contain the option name without the leading double dash. + + The has_arg field should be one of: + + no argument no argument to the option is expect required_argument + an argument to the option is required optional_argument an argument to the option may be presented. + + If flag is not NULL, then the integer pointed to by it will be set to the +value in the val field. +If the flag field is NULL, then the val field will be returned. +Setting flag to NULL and setting val to the corresponding short option will make this function act just +like getopt . + + If the longindex field is not NULL, then the integer pointed to by it will be set to the index of the long +option relative to longopts. + + The last element of the longopts array has to be filled with zeroes. + + + +Examples: +@code +#include +#include +#include +#include +#include +int main() +{ + int bflag, ch, fd; + int daggerset; + + int argc = 3; + + char *argv[] = { "getopt", "--daggerset","hi" }; + + 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': + printf("option is \"buffy\" +"); + bflag = 1; + break; + + case 'f': + printf("option is \"fluoride\" +"); + if ((fd = open(optarg, O_RDONLY, 0)) == -1) + printf("unable to open %s", optarg); + break; + + case 0: + if (daggerset) { + fprintf(stderr,"Buffy will use her dagger to apply +fluoride to dracula's teeth +"); + } + break; + default: + printf("unknown option +"); + + }//end of switch + }//end of while + +return 0; +} + +@endcode + Output +@code +Buffy will use her dagger to apply fluoride to dracula's teeth + +@endcode +@see getopt() + + + + +@publishedAll +@externallyDefinedApi +*/ + +/** @fn getopt(int argc, char * const argv[], const char *optstring) +@param argc +@param argv[] +@param optstring +@return The getopt function returns the next known option character in optstring. If getopt encounters a character not found in optstring or if it detects a missing option argument, it returns ' ? ' (question mark). If optstring has a leading ' : ' then a missing option argument causes ' : ' to be returned instead of ' ?. ' In either case, the variable optopt is set to the character that caused the error. The getopt function returns -1 when the argument list is exhausted. + + The getopt function incrementally parses a command line argument list argv and returns the next known option character. +An option character is known if it has been specified in the string of accepted option characters, optstring. + + The option string 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 x recognizes an option "- x ", and an option string x: recognizes an option and argument "- x argument. " It does not matter to getopt if a following argument has leading white space. + + On return from getopt, optarg points to an option argument, if it is anticipated, +and the variable optind contains the index to the next argv argument for a subsequent call +to getopt. The variable optopt saves the last known option character returned by getopt. + + The variables opterr and optind are both initialized to 1. +The optind variable may be set to another value before a set of calls to getopt in order to skip over more or less argv entries. + + In order to use getopt to evaluate multiple sets of arguments, or to evaluate a single set of +arguments multiple times, +the variable optreset must be set to 1 before the second and each additional set of calls to getopt, and the variable optind must be reinitialized. + + The getopt function returns -1 when the argument list is exhausted. +The interpretation of options in the argument list may be cancelled +by the option ' -- ' +(double dash) which causes getopt to signal the end of argument processing and return -1. +When all options have been processed (i.e., up to the first non-option +argument), getopt returns -1. + + + +Examples: +@code +#include +#include +#include +#include +#include + +int main() +{ + int argc = 3; + + char *argv[] = + { + "getopt","-f","hi" + }; + + int bflag, ch, fd; + bflag = 0; + + while ((ch = getopt(argc, argv, "bf:")) != -1) { + + switch (ch) { + case 'b': + bflag = 1; + printf("option is 'b' \n"); + break; + case 'f': + printf("option is 'f' \n"); + if ((fd = open(optarg, O_RDONLY, 0)) != 0) { + (void)fprintf(stderr, + "myname: %s: %s\n", optarg, strerror(errno)); + } + break; + case '?': + printf("missing option!"); + default: + printf("unknown option!"); + } + +} +argc -= optind; +return 0; +} + + +@endcode + Output +@code +option is 'f' +myname: hi: No such file or directory + +@endcode +Diagnostics: + If the getopt function encounters a character not found in the string optstring or detects +a missing option argument it writes an error message to the stderr and returns ' ?. ' +Setting opterr to a zero will disable these error messages. +If optstring has a leading ' : ' +then a missing option argument causes a ' : ' +to be returned in addition to suppressing any error messages. Option arguments are allowed to begin with "-"; +this is reasonable but reduces the amount of error checking possible. +@see getopt_long() + + +Bugs: + + The getopt function was once specified to return EOF instead of -1. +This was changed by -p1003.2-92 to decouple getopt from \#include \< stdio.h \> A single dash "-" may be specified as a character in optstring, however it should never have an argument associated with it. This allows getopt to be used with programs that expect "-" as an option flag. This practice is wrong and should not be used in any + current development. It is provided for backward compatibility only. Care should be taken not to use ' - ' as the first character in optstring to avoid a semantic conflict with GNU getopt, which assigns different meaning to an optstring that begins with a ' -. ' By default, a single dash causes getopt to return -1. It is also possible to handle digits as option letters. +This allows getopt to be used with programs that expect a number ("-3") +as an option. +This practice is wrong, and should not be used in any current development. +It is provided for backward compatibility only. The following code fragment works in most cases. +@code +int ch; +long length; +char *p, *ep; +while ((ch = getopt(argc, argv, "0123456789")) != -1) + switch (ch) { + case ’0’: case ’1’: case ’2’: case ’3’: case ’4’: + case ’5’: case ’6’: case ’7’: case ’8’: case ’9’: + p = argv[optind - 1]; + if (p[0] == ’-’ Am]Am] p[1] == ch Am]Am] !p[2]) { + length = ch - ’0’; + ep = ""; + } else if (argv[optind] Am]Am] argv[optind][1] == ch) { + length = strtol((p = argv[optind] + 1), + Am]ep, 10); + optind++; + optreset = 1; + } else + usage(); + if (*ep != ’\0’) + errx(EX_USAGE, "illegal number -- %s", p); + break; + } + + +@endcode + + + +@publishedAll +@externallyDefinedApi +*/ + + +/** @def optopt + +getopt(3) external variables. character checked for validity. + +@publishedAll +@externallyDefinedApi +*/ + +/** @def opterr + +getopt(3) external variables. if error message should be printed. + +@publishedAll +@externallyDefinedApi +*/ + +/** @def optind + +getopt(3) external variables. index into parent argv vector. + +@publishedAll +@externallyDefinedApi +*/ + +/** @def optarg + +argument associated with option + +@publishedAll +@externallyDefinedApi +*/ + +/** @def optreset + +reset getopt + +@publishedAll +@externallyDefinedApi +*/ + +/** @def no_argument + +no argument required + +@publishedAll +@released +*/ + +/** @def required_argument + +argument is required + +@publishedAll +@released +*/ + +/** @def optional_argument + +argument is optional + +@publishedAll +@released +*/ + +/** @struct option + +Includes following members, + +@publishedAll +@released +*/ + +/** @var option::name +name of long option +*/ + +/** @var option::has_arg +one of no_argument, required_argument, and optional_argument: whether option takes an argument +*/ + +/** @var option::flag +if not NULL, set flag to val when option found +*/ + +/** @var option::val +if flag not NULL, value to set flag to; else return value +*/