libbb/getopt_ulflags.c

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