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