1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/getopt.dosc Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,377 @@
1.4 +/** @file ../include/getopt.h
1.5 +@internalComponent
1.6 +*/
1.7 +
1.8 +/** @fn getopt_long(int argc, char * const *argv, const char *optstring, const struct option *longopts, int *longindex)
1.9 +@param argc
1.10 +@param argv
1.11 +@param optstring
1.12 +@param longopts
1.13 +@param longindex
1.14 +@return If the flag field in struct option
1.15 +is NULL, getopt_long returns the value specified in the val field, which is usually just the corresponding short option.
1.16 +If flag is not NULL, this function returns 0 and stores val in the location pointed to by flag. This function returns ' : '
1.17 +if there was a missing option argument, ' ? '
1.18 +if the user specified an unknown or ambiguous option, and
1.19 +-1 when the argument list has been exhausted.
1.20 +
1.21 +
1.22 + The getopt_long function is similar to getopt but it accepts options in two forms: words and characters.
1.23 +The getopt_long function provides a superset of the functionality of getopt .
1.24 +The getopt_long function
1.25 +can be used in two ways.
1.26 +In the first way, every long option understood
1.27 +by the program has a corresponding short option, and the option
1.28 +structure is only used to translate from long options to short
1.29 +options.
1.30 +When used in this fashion, getopt_long behaves identically to getopt .
1.31 +This is a good way to add long option processing to an existing program
1.32 +with the minimum of rewriting.
1.33 +
1.34 + In the second mechanism, a long option sets a flag in the option
1.35 +structure passed, or will store a pointer to the command line argument
1.36 +in the option
1.37 +structure passed to it for options that take arguments.
1.38 +Additionally,
1.39 +the long option's argument may be specified as a single argument with
1.40 +an equal sign, e.g.,
1.41 +
1.42 +@code
1.43 +myprogram --myoption=somevalue
1.44 +@endcode
1.45 +
1.46 +When a long option is processed, the call to getopt_long will return 0.
1.47 +For this reason, long option processing without
1.48 +shortcuts is not backwards compatible with getopt . It is possible to combine these methods, providing for long options
1.49 +processing with short option equivalents for some options.
1.50 +Less
1.51 +frequently used options would be processed as long options only. The getopt_long call requires a structure to be initialized describing the long
1.52 +options.
1.53 +@code
1.54 +The structure is: struct option {
1.55 +char *name;
1.56 +int has_arg;
1.57 +int *flag;
1.58 +int val;
1.59 +};
1.60 +@endcode
1.61 + The name field should contain the option name without the leading double dash.
1.62 +
1.63 + The has_arg field should be one of:
1.64 +
1.65 + no argument no argument to the option is expect required_argument
1.66 + an argument to the option is required optional_argument an argument to the option may be presented.
1.67 +
1.68 + If flag is not NULL, then the integer pointed to by it will be set to the
1.69 +value in the val field.
1.70 +If the flag field is NULL, then the val field will be returned.
1.71 +Setting flag to NULL and setting val to the corresponding short option will make this function act just
1.72 +like getopt .
1.73 +
1.74 + If the longindex field is not NULL, then the integer pointed to by it will be set to the index of the long
1.75 +option relative to longopts.
1.76 +
1.77 + The last element of the longopts array has to be filled with zeroes.
1.78 +
1.79 +
1.80 +
1.81 +Examples:
1.82 +@code
1.83 +#include <unistd.h>
1.84 +#include <stdio.h>
1.85 +#include <fcntl.h>
1.86 +#include <getopt.h>
1.87 +#include <errno.h>
1.88 +int main()
1.89 +{
1.90 + int bflag, ch, fd;
1.91 + int daggerset;
1.92 +
1.93 + int argc = 3;
1.94 +
1.95 + char *argv[] = { "getopt", "--daggerset","hi" };
1.96 +
1.97 + struct option longopts[] = {
1.98 + { "buffy", no_argument, NULL, 'b' },
1.99 + { "fluoride", required_argument, NULL, 'f' },
1.100 + { "daggerset", no_argument, &daggerset;, 1 },
1.101 + { NULL, 0, NULL, 0 }
1.102 + };
1.103 +
1.104 + bflag = 0;
1.105 +
1.106 + while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
1.107 + switch (ch) {
1.108 +
1.109 + case 'b':
1.110 + printf("option is \"buffy\"
1.111 +");
1.112 + bflag = 1;
1.113 + break;
1.114 +
1.115 + case 'f':
1.116 + printf("option is \"fluoride\"
1.117 +");
1.118 + if ((fd = open(optarg, O_RDONLY, 0)) == -1)
1.119 + printf("unable to open %s", optarg);
1.120 + break;
1.121 +
1.122 + case 0:
1.123 + if (daggerset) {
1.124 + fprintf(stderr,"Buffy will use her dagger to apply
1.125 +fluoride to dracula's teeth
1.126 +");
1.127 + }
1.128 + break;
1.129 + default:
1.130 + printf("unknown option
1.131 +");
1.132 +
1.133 + }//end of switch
1.134 + }//end of while
1.135 +
1.136 +return 0;
1.137 +}
1.138 +
1.139 +@endcode
1.140 + Output
1.141 +@code
1.142 +Buffy will use her dagger to apply fluoride to dracula's teeth
1.143 +
1.144 +@endcode
1.145 +@see getopt()
1.146 +
1.147 +
1.148 +
1.149 +
1.150 +@publishedAll
1.151 +@externallyDefinedApi
1.152 +*/
1.153 +
1.154 +/** @fn getopt(int argc, char * const argv[], const char *optstring)
1.155 +@param argc
1.156 +@param argv[]
1.157 +@param optstring
1.158 +@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.
1.159 +
1.160 + The getopt function incrementally parses a command line argument list argv and returns the next known option character.
1.161 +An option character is known if it has been specified in the string of accepted option characters, optstring.
1.162 +
1.163 + The option string optstring may contain the following elements: individual characters
1.164 + and characters followed by a colon to indicate an option argument is to follow.
1.165 + 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.
1.166 +
1.167 + On return from getopt, optarg points to an option argument, if it is anticipated,
1.168 +and the variable optind contains the index to the next argv argument for a subsequent call
1.169 +to getopt. The variable optopt saves the last known option character returned by getopt.
1.170 +
1.171 + The variables opterr and optind are both initialized to 1.
1.172 +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.
1.173 +
1.174 + In order to use getopt to evaluate multiple sets of arguments, or to evaluate a single set of
1.175 +arguments multiple times,
1.176 +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.
1.177 +
1.178 + The getopt function returns -1 when the argument list is exhausted.
1.179 +The interpretation of options in the argument list may be cancelled
1.180 +by the option ' -- '
1.181 +(double dash) which causes getopt to signal the end of argument processing and return -1.
1.182 +When all options have been processed (i.e., up to the first non-option
1.183 +argument), getopt returns -1.
1.184 +
1.185 +
1.186 +
1.187 +Examples:
1.188 +@code
1.189 +#include <unistd.h>
1.190 +#include <stdio.h>
1.191 +#include <fcntl.h>
1.192 +#include <errno.h>
1.193 +#include <string.h>
1.194 +
1.195 +int main()
1.196 +{
1.197 + int argc = 3;
1.198 +
1.199 + char *argv[] =
1.200 + {
1.201 + "getopt","-f","hi"
1.202 + };
1.203 +
1.204 + int bflag, ch, fd;
1.205 + bflag = 0;
1.206 +
1.207 + while ((ch = getopt(argc, argv, "bf:")) != -1) {
1.208 +
1.209 + switch (ch) {
1.210 + case 'b':
1.211 + bflag = 1;
1.212 + printf("option is 'b' \n");
1.213 + break;
1.214 + case 'f':
1.215 + printf("option is 'f' \n");
1.216 + if ((fd = open(optarg, O_RDONLY, 0)) != 0) {
1.217 + (void)fprintf(stderr,
1.218 + "myname: %s: %s\n", optarg, strerror(errno));
1.219 + }
1.220 + break;
1.221 + case '?':
1.222 + printf("missing option!");
1.223 + default:
1.224 + printf("unknown option!");
1.225 + }
1.226 +
1.227 +}
1.228 +argc -= optind;
1.229 +return 0;
1.230 +}
1.231 +
1.232 +
1.233 +@endcode
1.234 + Output
1.235 +@code
1.236 +option is 'f'
1.237 +myname: hi: No such file or directory
1.238 +
1.239 +@endcode
1.240 +Diagnostics:
1.241 + If the getopt function encounters a character not found in the string optstring or detects
1.242 +a missing option argument it writes an error message to the stderr and returns ' ?. '
1.243 +Setting opterr to a zero will disable these error messages.
1.244 +If optstring has a leading ' : '
1.245 +then a missing option argument causes a ' : '
1.246 +to be returned in addition to suppressing any error messages. Option arguments are allowed to begin with "-";
1.247 +this is reasonable but reduces the amount of error checking possible.
1.248 +@see getopt_long()
1.249 +
1.250 +
1.251 +Bugs:
1.252 +
1.253 + The getopt function was once specified to return EOF instead of -1.
1.254 +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
1.255 + 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.
1.256 +This allows getopt to be used with programs that expect a number ("-3")
1.257 +as an option.
1.258 +This practice is wrong, and should not be used in any current development.
1.259 +It is provided for backward compatibility only. The following code fragment works in most cases.
1.260 +@code
1.261 +int ch;
1.262 +long length;
1.263 +char *p, *ep;
1.264 +while ((ch = getopt(argc, argv, "0123456789")) != -1)
1.265 + switch (ch) {
1.266 + case ’0’: case ’1’: case ’2’: case ’3’: case ’4’:
1.267 + case ’5’: case ’6’: case ’7’: case ’8’: case ’9’:
1.268 + p = argv[optind - 1];
1.269 + if (p[0] == ’-’ Am]Am] p[1] == ch Am]Am] !p[2]) {
1.270 + length = ch - ’0’;
1.271 + ep = "";
1.272 + } else if (argv[optind] Am]Am] argv[optind][1] == ch) {
1.273 + length = strtol((p = argv[optind] + 1),
1.274 + Am]ep, 10);
1.275 + optind++;
1.276 + optreset = 1;
1.277 + } else
1.278 + usage();
1.279 + if (*ep != ’\0’)
1.280 + errx(EX_USAGE, "illegal number -- %s", p);
1.281 + break;
1.282 + }
1.283 +
1.284 +
1.285 +@endcode
1.286 +
1.287 +
1.288 +
1.289 +@publishedAll
1.290 +@externallyDefinedApi
1.291 +*/
1.292 +
1.293 +
1.294 +/** @def optopt
1.295 +
1.296 +getopt(3) external variables. character checked for validity.
1.297 +
1.298 +@publishedAll
1.299 +@externallyDefinedApi
1.300 +*/
1.301 +
1.302 +/** @def opterr
1.303 +
1.304 +getopt(3) external variables. if error message should be printed.
1.305 +
1.306 +@publishedAll
1.307 +@externallyDefinedApi
1.308 +*/
1.309 +
1.310 +/** @def optind
1.311 +
1.312 +getopt(3) external variables. index into parent argv vector.
1.313 +
1.314 +@publishedAll
1.315 +@externallyDefinedApi
1.316 +*/
1.317 +
1.318 +/** @def optarg
1.319 +
1.320 +argument associated with option
1.321 +
1.322 +@publishedAll
1.323 +@externallyDefinedApi
1.324 +*/
1.325 +
1.326 +/** @def optreset
1.327 +
1.328 +reset getopt
1.329 +
1.330 +@publishedAll
1.331 +@externallyDefinedApi
1.332 +*/
1.333 +
1.334 +/** @def no_argument
1.335 +
1.336 +no argument required
1.337 +
1.338 +@publishedAll
1.339 +@released
1.340 +*/
1.341 +
1.342 +/** @def required_argument
1.343 +
1.344 +argument is required
1.345 +
1.346 +@publishedAll
1.347 +@released
1.348 +*/
1.349 +
1.350 +/** @def optional_argument
1.351 +
1.352 +argument is optional
1.353 +
1.354 +@publishedAll
1.355 +@released
1.356 +*/
1.357 +
1.358 +/** @struct option
1.359 +
1.360 +Includes following members,
1.361 +
1.362 +@publishedAll
1.363 +@released
1.364 +*/
1.365 +
1.366 +/** @var option::name
1.367 +name of long option
1.368 +*/
1.369 +
1.370 +/** @var option::has_arg
1.371 +one of no_argument, required_argument, and optional_argument: whether option takes an argument
1.372 +*/
1.373 +
1.374 +/** @var option::flag
1.375 +if not NULL, set flag to val when option found
1.376 +*/
1.377 +
1.378 +/** @var option::val
1.379 +if flag not NULL, value to set flag to; else return value
1.380 +*/