libbb/getopt32.c

   1 /* vi: set sw=4 ts=4: */
   2 /*
   3  * universal getopt32 implementation for busybox
   4  *
   5  * Copyright (C) 2003-2005  Vladimir Oleynik  <dzo@simtreas.ru>
   6  *
   7  * Licensed under GPLv2 or later, see file LICENSE in this source tree.
   8  */
   9
  10 #if ENABLE_LONG_OPTS || ENABLE_FEATURE_GETOPT_LONG
  11 # include <getopt.h>
  12 #endif
  13 #include "libbb.h"
  14
  15 /*      Documentation
  16
  17 uint32_t
  18 getopt32(char **argv, const char *applet_opts, ...)
  19
  20         The command line options are passed as the applet_opts string.
  21
  22         If one of the given options is found, a flag value is added to
  23         the return value.
  24
  25         The flag value is determined by the position of the char in
  26         applet_opts string.  For example:
  27
  28         flags = getopt32(argv, "rnug");
  29
  30         "r" will set 1    (bit 0)
  31         "n" will set 2    (bit 1)
  32         "u" will set 4    (bit 2)
  33         "g" will set 8    (bit 3)
  34
  35         and so on.  You can also look at the return value as a bit
  36         field and each option sets one bit.
  37
  38         On exit, global variable optind is set so that if you
  39         will do argc -= optind; argv += optind; then
  40         argc will be equal to number of remaining non-option
  41         arguments, first one would be in argv[0], next in argv[1] and so on
  42         (options and their parameters will be moved into argv[]
  43         positions prior to argv[optind]).
  44
  45  "o:"   If one of the options requires an argument, then add a ":"
  46         after the char in applet_opts and provide a pointer to store
  47         the argument.  For example:
  48
  49         char *pointer_to_arg_for_a;
  50         char *pointer_to_arg_for_b;
  51         char *pointer_to_arg_for_c;
  52         char *pointer_to_arg_for_d;
  53
  54         flags = getopt32(argv, "a:b:c:d:",
  55                         &pointer_to_arg_for_a, &pointer_to_arg_for_b,
  56                         &pointer_to_arg_for_c, &pointer_to_arg_for_d);
  57
  58         The type of the pointer may be controlled by "o::" or "o+" in
  59         the external string opt_complementary (see below for more info).
  60
  61  "o::"  If option can have an *optional* argument, then add a "::"
  62         after its char in applet_opts and provide a pointer to store
  63         the argument.  Note that optional arguments _must_
  64         immediately follow the option: -oparam, not -o param.
  65
  66  "o:+"  This means that the parameter for this option is a nonnegative integer.
  67         It will be processed with xatoi_positive() - allowed range
  68         is 0..INT_MAX.
  69
  70         int param;  // "unsigned param;" will also work
  71         getopt32(argv, "p:+", &param);
  72
  73  "o:*"  This means that the option can occur multiple times. Each occurrence
  74         will be saved as a llist_t element instead of char*.
  75
  76         For example:
  77         The grep applet can have one or more "-e pattern" arguments.
  78         In this case you should use getopt32() as follows:
  79
  80         llist_t *patterns = NULL;
  81
  82         (this pointer must be initializated to NULL if the list is empty
  83         as required by llist_add_to_end(llist_t **old_head, char *new_item).)
  84
  85         getopt32(argv, "e:*", &patterns);
  86
  87         $ grep -e user -e root /etc/passwd
  88         root:x:0:0:root:/root:/bin/bash
  89         user:x:500:500::/home/user:/bin/bash
  90
  91  "+"    If the first character in the applet_opts string is a plus,
  92         then option processing will stop as soon as a non-option is
  93         encountered in the argv array.  Useful for applets like env
  94         which should not process arguments to subprograms:
  95         env -i ls -d /
  96         Here we want env to process just the '-i', not the '-d'.
  97
  98  "!"    Report bad option, missing required options,
  99         inconsistent options with all-ones return value (instead of abort).
 100
 101 const char *applet_long_options
 102
 103         This struct allows you to define long options:
 104
 105         static const char applet_longopts[] ALIGN1 =
 106                 //"name\0"  has_arg     val
 107                 "verbose\0" No_argument "v"
 108                 ;
 109         applet_long_options = applet_longopts;
 110
 111         The last member of struct option (val) typically is set to
 112         matching short option from applet_opts. If there is no matching
 113         char in applet_opts, then:
 114         - return bit has next position after short options
 115         - if has_arg is not "No_argument", use ptr for arg also
 116         - opt_complementary affects it too
 117
 118         Note: a good applet will make long options configurable via the
 119         config process and not a required feature.  The current standard
 120         is to name the config option CONFIG_FEATURE_<applet>_LONG_OPTIONS.
 121
 122 const char *opt_complementary
 123
 124  ":"    The colon (":") is used to separate groups of two or more chars
 125         and/or groups of chars and special characters (stating some
 126         conditions to be checked).
 127
 128  "abc"  If groups of two or more chars are specified, the first char
 129         is the main option and the other chars are secondary options.
 130         Their flags will be turned on if the main option is found even
 131         if they are not specified on the command line.  For example:
 132
 133         opt_complementary = "abc";
 134         flags = getopt32(argv, "abcd")
 135
 136         If getopt() finds "-a" on the command line, then
 137         getopt32's return value will be as if "-a -b -c" were
 138         found.
 139
 140  "ww"   Adjacent double options have a counter associated which indicates
 141         the number of occurrences of the option.
 142         For example the ps applet needs:
 143         if w is given once, GNU ps sets the width to 132,
 144         if w is given more than once, it is "unlimited"
 145
 146         int w_counter = 0; // must be initialized!
 147         opt_complementary = "ww";
 148         getopt32(argv, "w", &w_counter);
 149         if (w_counter)
 150                 width = (w_counter == 1) ? 132 : INT_MAX;
 151         else
 152                 get_terminal_width(...&width...);
 153
 154         w_counter is a pointer to an integer. It has to be passed to
 155         getopt32() after all other option argument sinks.
 156
 157         For example: accept multiple -v to indicate the level of verbosity
 158         and for each -b optarg, add optarg to my_b. Finally, if b is given,
 159         turn off c and vice versa:
 160
 161         llist_t *my_b = NULL;
 162         int verbose_level = 0;
 163         opt_complementary = "vv:b-c:c-b";
 164         f = getopt32(argv, "vb:*c", &my_b, &verbose_level);
 165         if (f & 2)       // -c after -b unsets -b flag
 166                 while (my_b) dosomething_with(llist_pop(&my_b));
 167         if (my_b)        // but llist is stored if -b is specified
 168                 free_llist(my_b);
 169         if (verbose_level) printf("verbose level is %d\n", verbose_level);
 170
 171 Special characters:
 172
 173  "-"    A group consisting of just a dash forces all arguments
 174         to be treated as options, even if they have no leading dashes.
 175         Next char in this case can't be a digit (0-9), use ':' or end of line.
 176         Example:
 177
 178         opt_complementary = "-:w-x:x-w"; // "-w-x:x-w" would also work,
 179         getopt32(argv, "wx");            // but is less readable
 180
 181         This makes it possible to use options without a dash (./program w x)
 182         as well as with a dash (./program -x).
 183
 184         NB: getopt32() will leak a small amount of memory if you use
 185         this option! Do not use it if there is a possibility of recursive
 186         getopt32() calls.
 187
 188  "--"   A double dash at the beginning of opt_complementary means the
 189         argv[1] string should always be treated as options, even if it isn't
 190         prefixed with a "-".  This is useful for special syntax in applets
 191         such as "ar" and "tar":
 192         tar xvf foo.tar
 193
 194         NB: getopt32() will leak a small amount of memory if you use
 195         this option! Do not use it if there is a possibility of recursive
 196         getopt32() calls.
 197
 198  "-N"   A dash as the first char in a opt_complementary group followed
 199         by a single digit (0-9) means that at least N non-option
 200         arguments must be present on the command line
 201
 202  "=N"   An equal sign as the first char in a opt_complementary group followed
 203         by a single digit (0-9) means that exactly N non-option
 204         arguments must be present on the command line
 205
 206  "?N"   A "?" as the first char in a opt_complementary group followed
 207         by a single digit (0-9) means that at most N arguments must be present
 208         on the command line.
 209
 210  "V-"   An option with dash before colon or end-of-line results in
 211         bb_show_usage() being called if this option is encountered.
 212         This is typically used to implement "print verbose usage message
 213         and exit" option.
 214
 215  "a-b"  A dash between two options causes the second of the two
 216         to be unset (and ignored) if it is given on the command line.
 217
 218         [FIXME: what if they are the same? like "x-x"? Is it ever useful?]
 219
 220         For example:
 221         The du applet has the options "-s" and "-d depth".  If
 222         getopt32 finds -s, then -d is unset or if it finds -d
 223         then -s is unset.  (Note:  busybox implements the GNU
 224         "--max-depth" option as "-d".)  To obtain this behavior, you
 225         set opt_complementary = "s-d:d-s".  Only one flag value is
 226         added to getopt32's return value depending on the
 227         position of the options on the command line.  If one of the
 228         two options requires an argument pointer (":" in applet_opts
 229         as in "d:") optarg is set accordingly.
 230
 231         char *smax_print_depth;
 232
 233         opt_complementary = "s-d:d-s:x-x";
 234         opt = getopt32(argv, "sd:x", &smax_print_depth);
 235
 236         if (opt & 2)
 237                 max_print_depth = atoi(smax_print_depth);
 238         if (opt & 4)
 239                 printf("Detected odd -x usage\n");
 240
 241  "a--b" A double dash between two options, or between an option and a group
 242         of options, means that they are mutually exclusive.  Unlike
 243         the "-" case above, an error will be forced if the options
 244         are used together.
 245
 246         For example:
 247         The cut applet must have only one type of list specified, so
 248         -b, -c and -f are mutually exclusive and should raise an error
 249         if specified together.  In this case you must set
 250         opt_complementary = "b--cf:c--bf:f--bc".  If two of the
 251         mutually exclusive options are found, getopt32 will call
 252         bb_show_usage() and die.
 253
 254  "x--x" Variation of the above, it means that -x option should occur
 255         at most once.
 256
 257  "o+"   A plus after a char in opt_complementary means that the parameter
 258         for this option is a nonnegative integer. It will be processed
 259         with xatoi_positive() - allowed range is 0..INT_MAX.
 260
 261         int param;  // "unsigned param;" will also work
 262         opt_complementary = "p+";
 263         getopt32(argv, "p:", &param);
 264
 265  "o::"  A double colon after a char in opt_complementary means that the
 266         option can occur multiple times. Each occurrence will be saved as
 267         a llist_t element instead of char*.
 268
 269         For example:
 270         The grep applet can have one or more "-e pattern" arguments.
 271         In this case you should use getopt32() as follows:
 272
 273         llist_t *patterns = NULL;
 274
 275         (this pointer must be initializated to NULL if the list is empty
 276         as required by llist_add_to_end(llist_t **old_head, char *new_item).)
 277
 278         opt_complementary = "e::";
 279         getopt32(argv, "e:", &patterns);
 280
 281         $ grep -e user -e root /etc/passwd
 282         root:x:0:0:root:/root:/bin/bash
 283         user:x:500:500::/home/user:/bin/bash
 284
 285         "o+" and "o::" can be handled by "o:+" and "o:*" specifiers
 286         in option string (and it is preferred), but this does not work
 287         for "long options only" cases, such as tar --exclude=PATTERN,
 288         wget --header=HDR cases.
 289
 290  "a?b"  A "?" between an option and a group of options means that
 291         at least one of them is required to occur if the first option
 292         occurs in preceding command line arguments.
 293
 294         For example from "id" applet:
 295
 296         // Don't allow -n -r -rn -ug -rug -nug -rnug
 297         opt_complementary = "r?ug:n?ug:u--g:g--u";
 298         flags = getopt32(argv, "rnug");
 299
 300         This example allowed only:
 301         $ id; id -u; id -g; id -ru; id -nu; id -rg; id -ng; id -rnu; id -rng
 302
 303  "X"    A opt_complementary group with just a single letter means
 304         that this option is required. If more than one such group exists,
 305         at least one option is required to occur (not all of them).
 306         For example from "start-stop-daemon" applet:
 307
 308         // Don't allow -KS -SK, but -S or -K is required
 309         opt_complementary = "K:S:K--S:S--K";
 310         flags = getopt32(argv, "KS...);
 311
 312
 313         Don't forget to use ':'. For example, "?322-22-23X-x-a"
 314         is interpreted as "?3:22:-2:2-2:2-3Xa:2--x" -
 315         max 3 args; count uses of '-2'; min 2 args; if there is
 316         a '-2' option then unset '-3', '-X' and '-a'; if there is
 317         a '-2' and after it a '-x' then error out.
 318         But it's far too obfuscated. Use ':' to separate groups.
 319 */
 320
 321 /* Code here assumes that 'unsigned' is at least 32 bits wide */
 322
 323 const char *const bb_argv_dash[] = { "-", NULL };
 324
 325 const char *opt_complementary;
 326
 327 enum {
 328         PARAM_STRING,
 329         PARAM_LIST,
 330         PARAM_INT,
 331 };
 332
 333 typedef struct {
 334         unsigned char opt_char;
 335         smallint param_type;
 336         unsigned switch_on;
 337         unsigned switch_off;
 338         unsigned incongruously;
 339         unsigned requires;
 340         void **optarg;  /* char**, llist_t** or int *. */
 341         int *counter;
 342 } t_complementary;
 343
 344 /* You can set applet_long_options for parse called long options */
 345 #if ENABLE_LONG_OPTS || ENABLE_FEATURE_GETOPT_LONG
 346 static const struct option bb_null_long_options[1] = {
 347         { 0, 0, 0, 0 }
 348 };
 349 const char *applet_long_options;
 350 #endif
 351
 352 uint32_t option_mask32;
 353
 354 uint32_t FAST_FUNC
 355 getopt32(char **argv, const char *applet_opts, ...)
 356 {
 357         int argc;
 358         unsigned flags = 0;
 359         unsigned requires = 0;
 360         t_complementary complementary[33]; /* last stays zero-filled */
 361         char first_char;
 362         int c;
 363         const unsigned char *s;
 364         t_complementary *on_off;
 365         va_list p;
 366 #if ENABLE_LONG_OPTS || ENABLE_FEATURE_GETOPT_LONG
 367         const struct option *l_o;
 368         struct option *long_options = (struct option *) &bb_null_long_options;
 369 #endif
 370         unsigned trigger;
 371         char **pargv;
 372         int min_arg = 0;
 373         int max_arg = -1;
 374
 375 #define SHOW_USAGE_IF_ERROR     1
 376 #define ALL_ARGV_IS_OPTS        2
 377 #define FIRST_ARGV_IS_OPT       4
 378
 379         int spec_flgs = 0;
 380
 381         /* skip 0: some applets cheat: they do not actually HAVE argv[0] */
 382         argc = 1 + string_array_len(argv + 1);
 383
 384         va_start(p, applet_opts);
 385
 386         on_off = complementary;
 387         memset(on_off, 0, sizeof(complementary));
 388
 389         applet_opts = strcpy(alloca(strlen(applet_opts) + 1), applet_opts);
 390
 391         /* skip bbox extension */
 392         first_char = applet_opts[0];
 393         if (first_char == '!')
 394                 applet_opts++;
 395
 396         /* skip GNU extension */
 397         s = (const unsigned char *)applet_opts;
 398         if (*s == '+' || *s == '-')
 399                 s++;
 400         c = 0;
 401         while (*s) {
 402                 if (c >= 32)
 403                         break;
 404                 on_off->opt_char = *s;
 405                 on_off->switch_on = (1U << c);
 406                 if (*++s == ':') {
 407                         on_off->optarg = va_arg(p, void **);
 408                         if (s[1] == '+' || s[1] == '*') {
 409                                 /* 'o:+' or 'o:*' */
 410                                 on_off->param_type = (s[1] == '+') ?
 411                                         PARAM_INT : PARAM_LIST;
 412                                 overlapping_strcpy((char*)s + 1, (char*)s + 2);
 413                         }
 414                         /* skip possible 'o::' (or 'o:+:' !) */
 415                         while (*++s == ':')
 416                                 continue;
 417                 }
 418                 on_off++;
 419                 c++;
 420         }
 421
 422 #if ENABLE_LONG_OPTS || ENABLE_FEATURE_GETOPT_LONG
 423         if (applet_long_options) {
 424                 const char *optstr;
 425                 unsigned i, count;
 426
 427                 count = 1;
 428                 optstr = applet_long_options;
 429                 while (optstr[0]) {
 430                         optstr += strlen(optstr) + 3; /* skip NUL, has_arg, val */
 431                         count++;
 432                 }
 433                 /* count == no. of longopts + 1 */
 434                 long_options = alloca(count * sizeof(*long_options));
 435                 memset(long_options, 0, count * sizeof(*long_options));
 436                 i = 0;
 437                 optstr = applet_long_options;
 438                 while (--count) {
 439                         long_options[i].name = optstr;
 440                         optstr += strlen(optstr) + 1;
 441                         long_options[i].has_arg = (unsigned char)(*optstr++);
 442                         /* long_options[i].flag = NULL; */
 443                         long_options[i].val = (unsigned char)(*optstr++);
 444                         i++;
 445                 }
 446                 for (l_o = long_options; l_o->name; l_o++) {
 447                         if (l_o->flag)
 448                                 continue;
 449                         for (on_off = complementary; on_off->opt_char; on_off++)
 450                                 if (on_off->opt_char == l_o->val)
 451                                         goto next_long;
 452                         if (c >= 32)
 453                                 break;
 454                         on_off->opt_char = l_o->val;
 455                         on_off->switch_on = (1U << c);
 456                         if (l_o->has_arg != no_argument)
 457                                 on_off->optarg = va_arg(p, void **);
 458                         c++;
 459  next_long: ;
 460                 }
 461                 /* Make it unnecessary to clear applet_long_options
 462                  * by hand after each call to getopt32
 463                  */
 464                 applet_long_options = NULL;
 465         }
 466 #endif /* ENABLE_LONG_OPTS || ENABLE_FEATURE_GETOPT_LONG */
 467
 468         for (s = (const unsigned char *)opt_complementary; s && *s; s++) {
 469                 t_complementary *pair;
 470                 unsigned *pair_switch;
 471
 472                 if (*s == ':')
 473                         continue;
 474                 c = s[1];
 475                 if (*s == '?') {
 476                         if (c < '0' || c > '9') {
 477                                 spec_flgs |= SHOW_USAGE_IF_ERROR;
 478                         } else {
 479                                 max_arg = c - '0';
 480                                 s++;
 481                         }
 482                         continue;
 483                 }
 484                 if (*s == '-') {
 485                         if (c < '0' || c > '9') {
 486                                 if (c == '-') {
 487                                         spec_flgs |= FIRST_ARGV_IS_OPT;
 488                                         s++;
 489                                 } else
 490                                         spec_flgs |= ALL_ARGV_IS_OPTS;
 491                         } else {
 492                                 min_arg = c - '0';
 493                                 s++;
 494                         }
 495                         continue;
 496                 }
 497                 if (*s == '=') {
 498                         min_arg = max_arg = c - '0';
 499                         s++;
 500                         continue;
 501                 }
 502                 for (on_off = complementary; on_off->opt_char; on_off++)
 503                         if (on_off->opt_char == *s)
 504                                 goto found_opt;
 505                 /* Without this, diagnostic of such bugs is not easy */
 506                 bb_error_msg_and_die("NO OPT %c!", *s);
 507  found_opt:
 508                 if (c == ':' && s[2] == ':') {
 509                         on_off->param_type = PARAM_LIST;
 510                         continue;
 511                 }
 512                 if (c == '+' && (s[2] == ':' || s[2] == '\0')) {
 513                         on_off->param_type = PARAM_INT;
 514                         s++;
 515                         continue;
 516                 }
 517                 if (c == ':' || c == '\0') {
 518                         requires |= on_off->switch_on;
 519                         continue;
 520                 }
 521                 if (c == '-' && (s[2] == ':' || s[2] == '\0')) {
 522                         flags |= on_off->switch_on;
 523                         on_off->incongruously |= on_off->switch_on;
 524                         s++;
 525                         continue;
 526                 }
 527                 if (c == *s) {
 528                         on_off->counter = va_arg(p, int *);
 529                         s++;
 530                 }
 531                 pair = on_off;
 532                 pair_switch = &pair->switch_on;
 533                 for (s++; *s && *s != ':'; s++) {
 534                         if (*s == '?') {
 535                                 pair_switch = &pair->requires;
 536                         } else if (*s == '-') {
 537                                 if (pair_switch == &pair->switch_off)
 538                                         pair_switch = &pair->incongruously;
 539                                 else
 540                                         pair_switch = &pair->switch_off;
 541                         } else {
 542                                 for (on_off = complementary; on_off->opt_char; on_off++)
 543                                         if (on_off->opt_char == *s) {
 544                                                 *pair_switch |= on_off->switch_on;
 545                                                 break;
 546                                         }
 547                         }
 548                 }
 549                 s--;
 550         }
 551         opt_complementary = NULL;
 552         va_end(p);
 553
 554         if (spec_flgs & (FIRST_ARGV_IS_OPT | ALL_ARGV_IS_OPTS)) {
 555                 pargv = argv + 1;
 556                 while (*pargv) {
 557                         if (pargv[0][0] != '-' && pargv[0][0] != '\0') {
 558                                 /* Can't use alloca: opts with params will
 559                                  * return pointers to stack!
 560                                  * NB: we leak these allocations... */
 561                                 char *pp = xmalloc(strlen(*pargv) + 2);
 562                                 *pp = '-';
 563                                 strcpy(pp + 1, *pargv);
 564                                 *pargv = pp;
 565                         }
 566                         if (!(spec_flgs & ALL_ARGV_IS_OPTS))
 567                                 break;
 568                         pargv++;
 569                 }
 570         }
 571
 572         /* In case getopt32 was already called:
 573          * reset the libc getopt() function, which keeps internal state.
 574          * run_nofork_applet() does this, but we might end up here
 575          * also via gunzip_main() -> gzip_main(). Play safe.
 576          */
 577         GETOPT_RESET();
 578
 579         /* Note: just "getopt() <= 0" will not work well for
 580          * "fake" short options, like this one:
 581          * wget $'-\203' "Test: test" http://kernel.org/
 582          * (supposed to act as --header, but doesn't) */
 583 #if ENABLE_LONG_OPTS || ENABLE_FEATURE_GETOPT_LONG
 584         while ((c = getopt_long(argc, argv, applet_opts,
 585                         long_options, NULL)) != -1) {
 586 #else
 587         while ((c = getopt(argc, argv, applet_opts)) != -1) {
 588 #endif
 589                 /* getopt prints "option requires an argument -- X"
 590                  * and returns '?' if an option has no arg, but one is reqd */
 591                 c &= 0xff; /* fight libc's sign extension */
 592                 for (on_off = complementary; on_off->opt_char != c; on_off++) {
 593                         /* c can be NUL if long opt has non-NULL ->flag,
 594                          * but we construct long opts so that flag
 595                          * is always NULL (see above) */
 596                         if (on_off->opt_char == '\0' /* && c != '\0' */) {
 597                                 /* c is probably '?' - "bad option" */
 598                                 goto error;
 599                         }
 600                 }
 601                 if (flags & on_off->incongruously)
 602                         goto error;
 603                 trigger = on_off->switch_on & on_off->switch_off;
 604                 flags &= ~(on_off->switch_off ^ trigger);
 605                 flags |= on_off->switch_on ^ trigger;
 606                 flags ^= trigger;
 607                 if (on_off->counter)
 608                         (*(on_off->counter))++;
 609                 if (optarg) {
 610                         if (on_off->param_type == PARAM_LIST) {
 611                                 llist_add_to_end((llist_t **)(on_off->optarg), optarg);
 612                         } else if (on_off->param_type == PARAM_INT) {
 613 //TODO: xatoi_positive indirectly pulls in printf machinery
 614                                 *(unsigned*)(on_off->optarg) = xatoi_positive(optarg);
 615                         } else if (on_off->optarg) {
 616                                 *(char **)(on_off->optarg) = optarg;
 617                         }
 618                 }
 619         }
 620
 621         /* check depending requires for given options */
 622         for (on_off = complementary; on_off->opt_char; on_off++) {
 623                 if (on_off->requires
 624                  && (flags & on_off->switch_on)
 625                  && (flags & on_off->requires) == 0
 626                 ) {
 627                         goto error;
 628                 }
 629         }
 630         if (requires && (flags & requires) == 0)
 631                 goto error;
 632         argc -= optind;
 633         if (argc < min_arg || (max_arg >= 0 && argc > max_arg))
 634                 goto error;
 635
 636         option_mask32 = flags;
 637         return flags;
 638
 639  error:
 640         if (first_char != '!')
 641                 bb_show_usage();
 642         return (int32_t)-1;
 643 }