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 tarball for details.
   8  */
   9
  10 #include <getopt.h>
  11 #include "libbb.h"
  12
  13 /*      Documentation
  14
  15 uint32_t
  16 getopt32(int argc, char **argv, const char *applet_opts, ...)
  17
  18         The command line options must be declared in const char
  19         *applet_opts as a string of chars, for example:
  20
  21         flags = getopt32(argc, argv, "rnug");
  22
  23         If one of the given options is found, a flag value is added to
  24         the return value (an unsigned long).
  25
  26         The flag value is determined by the position of the char in
  27         applet_opts string.  For example, in the above case:
  28
  29         flags = getopt32(argc, argv, "rnug");
  30
  31         "r" will add 1    (bit 0)
  32         "n" will add 2    (bit 1)
  33         "u  will add 4    (bit 2)
  34         "g" will add 8    (bit 3)
  35
  36         and so on.  You can also look at the return value as a bit
  37         field and each option sets one bit.
  38
  39         On exit, global variable optind is set so that if you
  40         will do argc -= optind; argv += optind; then
  41         argc will be equal to number of remaining non-option
  42         arguments, first one would be in argv[0], next in argv[1] and so on
  43         (options and their parameters will be moved into argv[]
  44         positions prior to argv[optind]).
  45
  46  ":"    If one of the options requires an argument, then add a ":"
  47         after the char in applet_opts and provide a pointer to store
  48         the argument.  For example:
  49
  50         char *pointer_to_arg_for_a;
  51         char *pointer_to_arg_for_b;
  52         char *pointer_to_arg_for_c;
  53         char *pointer_to_arg_for_d;
  54
  55         flags = getopt32(argc, argv, "a:b:c:d:",
  56                         &pointer_to_arg_for_a, &pointer_to_arg_for_b,
  57                         &pointer_to_arg_for_c, &pointer_to_arg_for_d);
  58
  59         The type of the pointer (char* or llist_t*) may be controlled
  60         by the "::" special separator that is set in the external string
  61         opt_complementary (see below for more info).
  62
  63  "::"   If option can have an *optional* argument, then add a "::"
  64         after its char in applet_opts and provide a pointer to store
  65         the argument.  Note that optional arguments _must_
  66         immediately follow the option: -oparam, not -o param.
  67
  68  "+"    If the first character in the applet_opts string is a plus,
  69         then option processing will stop as soon as a non-option is
  70         encountered in the argv array.  Useful for applets like env
  71         which should not process arguments to subprograms:
  72         env -i ls -d /
  73         Here we want env to process just the '-i', not the '-d'.
  74
  75 const struct option *applet_long_options
  76
  77         This struct allows you to define long options.  The syntax for
  78         declaring the array is just like that of getopt's longopts.
  79         (see getopt(3))
  80
  81         static const struct option applet_long_options[] = {
  82                 //name,has_arg,flag,val
  83                 { "verbose", 0, 0, 'v' },
  84                 { 0, 0, 0, 0 }
  85         };
  86         applet_long_options = applet_long_options;
  87
  88         The last member of struct option (val) typically is set to
  89         matching short option from applet_opts. If there is no matching
  90         char in applet_opts, then:
  91         - return bit have next position after short options
  92         - if has_arg is not "no_argument", use ptr for arg also
  93         - opt_complementary affects it too
  94
  95         Note: a good applet will make long options configurable via the
  96         config process and not a required feature.  The current standard
  97         is to name the config option CONFIG_FEATURE_<applet>_LONG_OPTIONS.
  98
  99 const char *opt_complementary
 100
 101  ":"    The colon (":") is used to separate groups of two or more chars
 102         and/or groups of chars and special characters (stating some
 103         conditions to be checked).
 104
 105  "abc"  If groups of two or more chars are specified, the first char
 106         is the main option and the other chars are secondary options.
 107         Their flags will be turned on if the main option is found even
 108         if they are not specifed on the command line.  For example:
 109
 110         opt_complementary = "abc";
 111         flags = getopt32(argc, argv, "abcd")
 112
 113         If getopt() finds "-a" on the command line, then
 114         getopt32's return value will be as if "-a -b -c" were
 115         found.
 116
 117  "ww"   Adjacent double options have a counter associated which indicates
 118         the number of occurences of the option.
 119         For example the ps applet needs:
 120         if w is given once, GNU ps sets the width to 132,
 121         if w is given more than once, it is "unlimited"
 122
 123         int w_counter = 0;
 124         opt_complementary = "ww";
 125         getopt32(argc, argv, "w", &w_counter);
 126         if (w_counter)
 127                 width = (w_counter == 1) ? 132 : INT_MAX;
 128         else
 129                 get_terminal_width(...&width...);
 130
 131         w_counter is a pointer to an integer. It has to be passed to
 132         getopt32() after all other option argument sinks.
 133
 134         For example: accept multiple -v to indicate the level of verbosity
 135         and for each -b optarg, add optarg to my_b. Finally, if b is given,
 136         turn off c and vice versa:
 137
 138         llist_t *my_b = NULL;
 139         int verbose_level = 0;
 140         opt_complementary = "vv:b::b-c:c-b";
 141         f = getopt32(argc, argv, "vb:c", &my_b, &verbose_level);
 142         if (f & 2)       // -c after -b unsets -b flag
 143                 while (my_b) { dosomething_with(my_b->data); my_b = my_b->link; }
 144         if (my_b)        // but llist is stored if -b is specified
 145                 free_llist(my_b);
 146         if (verbose_level) printf("verbose level is %d\n", verbose_level);
 147
 148 Special characters:
 149
 150  "-"    A dash as the first char in a opt_complementary group forces
 151         all arguments to be treated as options, even if they have
 152         no leading dashes. Next char in this case can't be a digit (0-9),
 153         use ':' or end of line. For example:
 154
 155         opt_complementary = "-:w-x:x-w";
 156         getopt32(argc, argv, "wx");
 157
 158         Allows any arguments to be given without a dash (./program w x)
 159         as well as with a dash (./program -x).
 160
 161  "--"   A double dash at the beginning of opt_complementary means the
 162         argv[1] string should always be treated as options, even if it isn't
 163         prefixed with a "-".  This is useful for special syntax in applets
 164         such as "ar" and "tar":
 165         tar xvf foo.tar
 166
 167  "-N"   A dash as the first char in a opt_complementary group followed
 168         by a single digit (0-9) means that at least N non-option
 169         arguments must be present on the command line
 170
 171  "=N"   An equal sign as the first char in a opt_complementary group followed
 172         by a single digit (0-9) means that exactly N non-option
 173         arguments must be present on the command line
 174
 175  "?N"   A "?" as the first char in a opt_complementary group followed
 176         by a single digit (0-9) means that at most N arguments must be present
 177         on the command line.
 178
 179  "V-"   An option with dash before colon or end-of-line results in
 180         bb_show_usage being called if this option is encountered.
 181         This is typically used to implement "print verbose usage message
 182         and exit" option.
 183
 184  "-"    A dash between two options causes the second of the two
 185         to be unset (and ignored) if it is given on the command line.
 186
 187         [FIXME: what if they are the same? like "x-x"? Is it ever useful?]
 188
 189         For example:
 190         The du applet has the options "-s" and "-d depth".  If
 191         getopt32 finds -s, then -d is unset or if it finds -d
 192         then -s is unset.  (Note:  busybox implements the GNU
 193         "--max-depth" option as "-d".)  To obtain this behavior, you
 194         set opt_complementary = "s-d:d-s".  Only one flag value is
 195         added to getopt32's return value depending on the
 196         position of the options on the command line.  If one of the
 197         two options requires an argument pointer (":" in applet_opts
 198         as in "d:") optarg is set accordingly.
 199
 200         char *smax_print_depth;
 201
 202         opt_complementary = "s-d:d-s:x-x";
 203         opt = getopt32(argc, argv, "sd:x", &smax_print_depth);
 204
 205         if (opt & 2)
 206                 max_print_depth = atoi(smax_print_depth);
 207         if (opt & 4)
 208                 printf("Detected odd -x usage\n");
 209
 210  "--"   A double dash between two options, or between an option and a group
 211         of options, means that they are mutually exclusive.  Unlike
 212         the "-" case above, an error will be forced if the options
 213         are used together.
 214
 215         For example:
 216         The cut applet must have only one type of list specified, so
 217         -b, -c and -f are mutally exclusive and should raise an error
 218         if specified together.  In this case you must set
 219         opt_complementary = "b--cf:c--bf:f--bc".  If two of the
 220         mutually exclusive options are found, getopt32 will call
 221         bb_show_usage() and die.
 222
 223  "x--x" Variation of the above, it means that -x option should occur
 224         at most once.
 225
 226  "::"   A double colon after a char in opt_complementary means that the
 227         option can occur multiple times. Each occurrence will be saved as
 228         a llist_t element instead of char*.
 229
 230         For example:
 231         The grep applet can have one or more "-e pattern" arguments.
 232         In this case you should use getopt32() as follows:
 233
 234         llist_t *patterns = NULL;
 235
 236         (this pointer must be initializated to NULL if the list is empty
 237         as required by llist_add_to_end(llist_t **old_head, char *new_item).)
 238
 239         opt_complementary = "e::";
 240
 241         getopt32(argc, argv, "e:", &patterns);
 242         $ grep -e user -e root /etc/passwd
 243         root:x:0:0:root:/root:/bin/bash
 244         user:x:500:500::/home/user:/bin/bash
 245
 246  "?"    An "?" between an option and a group of options means that
 247         at least one of them is required to occur if the first option
 248         occurs in preceding command line arguments.
 249
 250         For example from "id" applet:
 251
 252         // Don't allow -n -r -rn -ug -rug -nug -rnug
 253         opt_complementary = "r?ug:n?ug:?u--g:g--u";
 254         flags = getopt32(argc, argv, "rnug");
 255
 256         This example allowed only:
 257         $ id; id -u; id -g; id -ru; id -nu; id -rg; id -ng; id -rnu; id -rng
 258
 259  "X"    A opt_complementary group with just a single letter means
 260         that this option is required. If more than one such group exists,
 261         at least one option is required to occur (not all of them).
 262         For example from "start-stop-daemon" applet:
 263
 264         // Don't allow -KS -SK, but -S or -K is required
 265         opt_complementary = "K:S:?K--S:S--K";
 266         flags = getopt32(argc, argv, "KS...);
 267
 268
 269         Don't forget to use ':'. For example, "?322-22-23X-x-a"
 270         is interpreted as "?3:22:-2:2-2:2-3Xa:2--x" -
 271         max 3 args; count uses of '-2'; min 2 args; if there is
 272         a '-2' option then unset '-3', '-X' and '-a'; if there is
 273         a '-2' and after it a '-x' then error out.
 274 */
 275
 276 /* Code here assumes that 'unsigned' is at least 32 bits wide */
 277
 278 const char *opt_complementary;
 279
 280 typedef struct {
 281         int opt;
 282         int list_flg;
 283         unsigned switch_on;
 284         unsigned switch_off;
 285         unsigned incongruously;
 286         unsigned requires;
 287         void **optarg;               /* char **optarg or llist_t **optarg */
 288         int *counter;
 289 } t_complementary;
 290
 291 /* You can set applet_long_options for parse called long options */
 292 #if ENABLE_GETOPT_LONG
 293 static const struct option bb_default_long_options[] = {
 294 /*      { "help", 0, NULL, '?' }, */
 295         { 0, 0, 0, 0 }
 296 };
 297
 298 const struct option *applet_long_options = bb_default_long_options;
 299 #endif
 300
 301 uint32_t option_mask32;
 302
 303 uint32_t
 304 getopt32(int argc, char **argv, const char *applet_opts, ...)
 305 {
 306         unsigned flags = 0;
 307         unsigned requires = 0;
 308         t_complementary complementary[33];
 309         int c;
 310         const unsigned char *s;
 311         t_complementary *on_off;
 312         va_list p;
 313 #if ENABLE_GETOPT_LONG
 314         const struct option *l_o;
 315 #endif
 316         unsigned trigger;
 317         char **pargv = NULL;
 318         int min_arg = 0;
 319         int max_arg = -1;
 320
 321 #define SHOW_USAGE_IF_ERROR     1
 322 #define ALL_ARGV_IS_OPTS        2
 323 #define FIRST_ARGV_IS_OPT       4
 324 #define FREE_FIRST_ARGV_IS_OPT  8
 325         int spec_flgs = 0;
 326
 327         va_start(p, applet_opts);
 328
 329         c = 0;
 330         on_off = complementary;
 331         memset(on_off, 0, sizeof(complementary));
 332
 333         /* skip GNU extension */
 334         s = (const unsigned char *)applet_opts;
 335         if (*s == '+' || *s == '-')
 336                 s++;
 337         while (*s) {
 338                 if (c >= 32) break;
 339                 on_off->opt = *s;
 340                 on_off->switch_on = (1 << c);
 341                 if (*++s == ':') {
 342                         on_off->optarg = va_arg(p, void **);
 343                         while (*++s == ':') /* skip */;
 344                 }
 345                 on_off++;
 346                 c++;
 347         }
 348
 349 #if ENABLE_GETOPT_LONG
 350         for (l_o = applet_long_options; l_o->name; l_o++) {
 351                 if (l_o->flag)
 352                         continue;
 353                 for (on_off = complementary; on_off->opt != 0; on_off++)
 354                         if (on_off->opt == l_o->val)
 355                                 goto next_long;
 356                 if (c >= 32) break;
 357                 on_off->opt = l_o->val;
 358                 on_off->switch_on = (1 << c);
 359                 if (l_o->has_arg != no_argument)
 360                         on_off->optarg = va_arg(p, void **);
 361                 c++;
 362  next_long: ;
 363         }
 364 #endif /* ENABLE_GETOPT_LONG */
 365         for (s = (const unsigned char *)opt_complementary; s && *s; s++) {
 366                 t_complementary *pair;
 367                 unsigned *pair_switch;
 368
 369                 if (*s == ':')
 370                         continue;
 371                 c = s[1];
 372                 if (*s == '?') {
 373                         if (c < '0' || c > '9') {
 374                                 spec_flgs |= SHOW_USAGE_IF_ERROR;
 375                         } else {
 376                                 max_arg = c - '0';
 377                                 s++;
 378                         }
 379                         continue;
 380                 }
 381                 if (*s == '-') {
 382                         if (c < '0' || c > '9') {
 383                                 if (c == '-') {
 384                                         spec_flgs |= FIRST_ARGV_IS_OPT;
 385                                         s++;
 386                                 } else
 387                                         spec_flgs |= ALL_ARGV_IS_OPTS;
 388                         } else {
 389                                 min_arg = c - '0';
 390                                 s++;
 391                         }
 392                         continue;
 393                 }
 394                 if (*s == '=') {
 395                         min_arg = max_arg = c - '0';
 396                         s++;
 397                         continue;
 398                 }
 399                 for (on_off = complementary; on_off->opt; on_off++)
 400                         if (on_off->opt == *s)
 401                                 break;
 402                 if (c == ':' && s[2] == ':') {
 403                         on_off->list_flg++;
 404                         continue;
 405                 }
 406                 if (c == ':' || c == '\0') {
 407                         requires |= on_off->switch_on;
 408                         continue;
 409                 }
 410                 if (c == '-' && (s[2] == ':' || s[2] == '\0')) {
 411                         flags |= on_off->switch_on;
 412                         on_off->incongruously |= on_off->switch_on;
 413                         s++;
 414                         continue;
 415                 }
 416                 if (c == *s) {
 417                         on_off->counter = va_arg(p, int *);
 418                         s++;
 419                 }
 420                 pair = on_off;
 421                 pair_switch = &(pair->switch_on);
 422                 for (s++; *s && *s != ':'; s++) {
 423                         if (*s == '?') {
 424                                 pair_switch = &(pair->requires);
 425                         } else if (*s == '-') {
 426                                 if (pair_switch == &(pair->switch_off))
 427                                         pair_switch = &(pair->incongruously);
 428                                 else
 429                                         pair_switch = &(pair->switch_off);
 430                         } else {
 431                                 for (on_off = complementary; on_off->opt; on_off++)
 432                                         if (on_off->opt == *s) {
 433                                                 *pair_switch |= on_off->switch_on;
 434                                                 break;
 435                                         }
 436                         }
 437                 }
 438                 s--;
 439         }
 440         va_end(p);
 441
 442         if (spec_flgs & FIRST_ARGV_IS_OPT) {
 443                 if (argv[1] && argv[1][0] != '-' && argv[1][0] != '\0') {
 444                         argv[1] = xasprintf("-%s", argv[1]);
 445                         if (ENABLE_FEATURE_CLEAN_UP)
 446                                 spec_flgs |= FREE_FIRST_ARGV_IS_OPT;
 447                 }
 448         }
 449
 450         /* In case getopt32 was already called, reinit some state */
 451         optind = 1;
 452         /* optarg = NULL; opterr = 0; optopt = 0; ?? */
 453
 454         /* Note: just "getopt() <= 0" will not work good for
 455          * "fake" short options, like this one:
 456          * wget $'-\203' "Test: test" http://kernel.org/
 457          * (supposed to act as --header, but doesn't) */
 458 #if ENABLE_GETOPT_LONG
 459         while ((c = getopt_long(argc, argv, applet_opts,
 460                                  applet_long_options, NULL)) != -1) {
 461 #else
 462         while ((c = getopt(argc, argv, applet_opts)) != -1) {
 463 #endif
 464                 c &= 0xff; /* fight libc's sign extends */
 465  loop_arg_is_opt:
 466                 for (on_off = complementary; on_off->opt != c; on_off++) {
 467                         /* c==0 if long opt have non NULL flag */
 468                         if (on_off->opt == 0 && c != 0)
 469                                 bb_show_usage();
 470                 }
 471                 if (flags & on_off->incongruously)
 472                         bb_show_usage();
 473                 trigger = on_off->switch_on & on_off->switch_off;
 474                 flags &= ~(on_off->switch_off ^ trigger);
 475                 flags |= on_off->switch_on ^ trigger;
 476                 flags ^= trigger;
 477                 if (on_off->counter)
 478                         (*(on_off->counter))++;
 479                 if (on_off->list_flg) {
 480                         llist_add_to_end((llist_t **)(on_off->optarg), optarg);
 481                 } else if (on_off->optarg) {
 482                         *(char **)(on_off->optarg) = optarg;
 483                 }
 484                 if (pargv != NULL)
 485                         break;
 486         }
 487
 488         if (spec_flgs & ALL_ARGV_IS_OPTS) {
 489                 /* process argv is option, for example "ps" applet */
 490                 if (pargv == NULL)
 491                         pargv = argv + optind;
 492                 while (*pargv) {
 493                         c = **pargv;
 494                         if (c == '\0') {
 495                                 pargv++;
 496                         } else {
 497                                 (*pargv)++;
 498                                 goto loop_arg_is_opt;
 499                         }
 500                 }
 501         }
 502
 503 #if (ENABLE_AR || ENABLE_TAR) && ENABLE_FEATURE_CLEAN_UP
 504         if (spec_flgs & FREE_FIRST_ARGV_IS_OPT)
 505                 free(argv[1]);
 506 #endif
 507         /* check depending requires for given options */
 508         for (on_off = complementary; on_off->opt; on_off++) {
 509                 if (on_off->requires && (flags & on_off->switch_on) &&
 510                                         (flags & on_off->requires) == 0)
 511                         bb_show_usage();
 512         }
 513         if (requires && (flags & requires) == 0)
 514                 bb_show_usage();
 515         argc -= optind;
 516         if (argc < min_arg || (max_arg >= 0 && argc > max_arg))
 517                 bb_show_usage();
 518
 519         option_mask32 = flags;
 520         return flags;
 521 }