crypto/heimdal-0.6.3/lib/roken/getarg.cat3

   1
   2 GETARG(3)                  UNIX Programmer's Manual                  GETARG(3)
   3
   4 N\bNA\bAM\bME\bE
   5      g\bge\bet\bta\bar\brg\bg, a\bar\brg\bg_\b_p\bpr\bri\bin\bnt\btu\bus\bsa\bag\bge\be - collect command line options
   6
   7 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   8      _\bi_\bn_\bt
   9      g\bge\bet\bta\bar\brg\bg(_\bs_\bt_\br_\bu_\bc_\bt _\bg_\be_\bt_\ba_\br_\bg_\bs _\b*_\ba_\br_\bg_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bu_\bm_\b__\ba_\br_\bg_\bs, _\bi_\bn_\bt _\ba_\br_\bg_\bc, _\bc_\bh_\ba_\br _\b*_\b*_\ba_\br_\bg_\bv,
  10              _\bi_\bn_\bt _\b*_\bo_\bp_\bt_\bi_\bn_\bd)
  11
  12      _\bv_\bo_\bi_\bd
  13      a\bar\brg\bg_\b_p\bpr\bri\bin\bnt\btu\bus\bsa\bag\bge\be(_\bs_\bt_\br_\bu_\bc_\bt _\bg_\be_\bt_\ba_\br_\bg_\bs _\b*_\ba_\br_\bg_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bu_\bm_\b__\ba_\br_\bg_\bs,
  14              _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\br_\bo_\bg_\bn_\ba_\bm_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\be_\bx_\bt_\br_\ba_\b__\bs_\bt_\br_\bi_\bn_\bg)
  15
  16 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  17      g\bge\bet\bta\bar\brg\bg() collects any command line options given to a program in an easi-
  18      ly used way.  a\bar\brg\bg_\b_p\bpr\bri\bin\bnt\btu\bus\bsa\bag\bge\be() pretty-prints the available options, with
  19      a short help text.
  20
  21      _\ba_\br_\bg_\bs is the option specification to use, and it's an array of _\bs_\bt_\br_\bu_\bc_\bt
  22      _\bg_\be_\bt_\ba_\br_\bg_\bs elements.  _\bn_\bu_\bm_\b__\ba_\br_\bg_\bs is the size of _\ba_\br_\bg_\bs (in elements).  _\ba_\br_\bg_\bc and
  23      _\ba_\br_\bg_\bv are the argument count and argument vector to extract option from.
  24      _\bo_\bp_\bt_\bi_\bn_\bd is a pointer to an integer where the index to the last processed
  25      argument is stored, it must be initialised to the first index (minus one)
  26      to process (normally 0) before the first call.
  27
  28      _\ba_\br_\bg_\b__\bp_\br_\bi_\bn_\bt_\bu_\bs_\ba_\bg_\be take the same _\ba_\br_\bg_\bs and _\bn_\bu_\bm_\b__\ba_\br_\bg_\bs as getarg; _\bp_\br_\bo_\bg_\bn_\ba_\bm_\be is the
  29      name of the program (to be used in the help text), and _\be_\bx_\bt_\br_\ba_\b__\bs_\bt_\br_\bi_\bn_\bg is a
  30      string to print after the actual options to indicate more arguments. The
  31      usefulness of this function is realised only be people who has used pro-
  32      grams that has help strings that doesn't match what the code does.
  33
  34      The _\bg_\be_\bt_\ba_\br_\bg_\bs struct has the following elements.
  35
  36      struct getargs{
  37          const char *long_name;
  38          char short_name;
  39          enum { arg_integer,
  40                 arg_string,
  41                 arg_flag,
  42                 arg_negative_flag,
  43                 arg_strings,
  44                 arg_double,
  45                 arg_collect
  46          } type;
  47          void *value;
  48          const char *help;
  49          const char *arg_help;
  50      };
  51
  52      _\bl_\bo_\bn_\bg_\b__\bn_\ba_\bm_\be is the long name of the option, it can be NULL, if you don't
  53      want a long name.  _\bs_\bh_\bo_\br_\bt_\b__\bn_\ba_\bm_\be is the characted to use as short option, it
  54      can be zero. If the option has a value the _\bv_\ba_\bl_\bu_\be field gets filled in
  55      with that value interpreted as specified by the _\bt_\by_\bp_\be field.  _\bh_\be_\bl_\bp is a
  56      longer help string for the option as a whole, if it's NULL the help text
  57      for the option is omitted (but it's still displayed in the synopsis).
  58      _\ba_\br_\bg_\b__\bh_\be_\bl_\bp is a description of the argument, if NULL a default value will
  59      be used, depending on the type of the option:
  60
  61      arg_integer        the argument is a signed integer, and _\bv_\ba_\bl_\bu_\be should
  62                         point to an _\bi_\bn_\bt.
  63
  64      _\ba_\br_\bg_\b__\bs_\bt_\br_\bi_\bn_\bg         the argument is a string, and _\bv_\ba_\bl_\bu_\be should point to a
  65
  66                         _\bc_\bh_\ba_\br_\b*.
  67
  68      _\ba_\br_\bg_\b__\bf_\bl_\ba_\bg           the argument is a flag, and _\bv_\ba_\bl_\bu_\be should point to a
  69                         _\bi_\bn_\bt. It gets filled in with either zero or one, de-
  70                         pending on how the option is given, the normal case
  71                         being one. Note that if the option isn't given, the
  72                         value isn't altered, so it should be initialised to
  73                         some useful default.
  74
  75      _\ba_\br_\bg_\b__\bn_\be_\bg_\ba_\bt_\bi_\bv_\be_\b__\bf_\bl_\ba_\bg this is the same as _\ba_\br_\bg_\b__\bf_\bl_\ba_\bg but it reverses the mean-
  76                         ing of the flag (a given short option clears the
  77                         flag), and the synopsis of a long option is negated.
  78
  79      _\ba_\br_\bg_\b__\bs_\bt_\br_\bi_\bn_\bg_\bs        the argument can be given multiple times, and the val-
  80                         ues are collected in an array; _\bv_\ba_\bl_\bu_\be should be a
  81                         pointer to a _\bs_\bt_\br_\bu_\bc_\bt _\bg_\be_\bt_\ba_\br_\bg_\b__\bs_\bt_\br_\bi_\bn_\bg_\bs structure, which
  82                         holds a length and a string pointer.
  83
  84      _\ba_\br_\bg_\b__\bd_\bo_\bu_\bb_\bl_\be         argument is a double precision floating point value,
  85                         and _\bv_\ba_\bl_\bu_\be should point to a _\bd_\bo_\bu_\bb_\bl_\be.
  86
  87      _\ba_\br_\bg_\b__\bc_\bo_\bl_\bl_\be_\bc_\bt        allows more fine-grained control of the option parsing
  88                         process.  _\bv_\ba_\bl_\bu_\be should be a pointer to a
  89                         _\bg_\be_\bt_\ba_\br_\bg_\b__\bc_\bo_\bl_\bl_\be_\bc_\bt_\b__\bi_\bn_\bf_\bo structure:
  90
  91                         typedef int (*getarg_collect_func)(int short_opt,
  92                                                            int argc,
  93                                                            char **argv,
  94                                                            int *optind,
  95                                                            int *optarg,
  96                                                            void *data);
  97
  98                         typedef struct getarg_collect_info {
  99                             getarg_collect_func func;
 100                             void *data;
 101                         } getarg_collect_info;
 102
 103                         With the _\bf_\bu_\bn_\bc member set to a function to call, and
 104                         _\bd_\ba_\bt_\ba to some application specific data. The parameters
 105                         to the collect function are:
 106
 107                         _\bs_\bh_\bo_\br_\bt_\b__\bf_\bl_\ba_\bg non-zero if this call is via a short option
 108                         flag, zero otherwise
 109
 110                         _\ba_\br_\bg_\bc, _\ba_\br_\bg_\bv the whole argument list
 111
 112                         _\bo_\bp_\bt_\bi_\bn_\bd pointer to the index in argv where the flag is
 113
 114                         _\bo_\bp_\bt_\ba_\br_\bg pointer to the index in argv[*optind] where the
 115                         flag name starts
 116
 117                         _\bd_\ba_\bt_\ba application specific data
 118
 119                         You can modify _\b*_\bo_\bp_\bt_\bi_\bn_\bd, and _\b*_\bo_\bp_\bt_\ba_\br_\bg, but to do this
 120                         correct you (more or less) have to know about the in-
 121                         ner workings of getarg.
 122
 123                         You can skip parts of arguments by increasing _\b*_\bo_\bp_\bt_\ba_\br_\bg
 124                         (you could implement the -\b-z\bz_\b3 set of flags from g\bgz\bzi\bip\bp
 125                         with this), or whole argument strings by increasing
 126                         _\b*_\bo_\bp_\bt_\bi_\bn_\bd (let's say you want a flag -\b-c\bc _\bx _\by _\bz to specify
 127                         a coordinate); if you also have to set _\b*_\bo_\bp_\bt_\ba_\br_\bg to a
 128                         sane value.
 129
 130                         The collect function should return one of
 131                         ARG_ERR_NO_MATCH, ARG_ERR_BAD_ARG, ARG_ERR_NO_ARG on
 132                         error, zero otherwise.
 133
 134                         For your convenience there is a function,
 135                         g\bge\bet\bta\bar\brg\bg_\b_o\bop\bpt\bta\bar\brg\bg(), that returns the traditional argument
 136                         string, and you pass it all arguments, sans data, that
 137                         where given to the collection function.
 138
 139                         Don't use this more this unless you absolutely have
 140                         to.
 141
 142      Option parsing is similar to what getopt uses. Short options without ar-
 143      guments can be compressed (-\b-x\bxy\byz\bz is the same as -\b-x\bx -\b-y\by -\b-z\bz), and short op-
 144      tions with arguments take these as either the rest of the argv-string or
 145      as the next option (-\b-o\bo_\bf_\bo_\bo, or -\b-o\bo _\bf_\bo_\bo).
 146
 147      Long option names are prefixed with -- (double dash), and the value with
 148      a = (equal), -\b--\b-f\bfo\boo\bo=\b=_\bb_\ba_\br. Long option flags can either be specified as they
 149      are (-\b--\b-h\bhe\bel\blp\bp), or with an (boolean parsable) option (-\b--\b-h\bhe\bel\blp\bp=\b=_\by_\be_\bs,
 150      -\b--\b-h\bhe\bel\blp\bp=\b=_\bt_\br_\bu_\be, or similar), or they can also be negated (-\b--\b-n\bno\bo-\b-h\bhe\bel\blp\bp is the
 151      same as -\b--\b-h\bhe\bel\blp\bp=\b=no), and if you're really confused you can do it multiple
 152      times (-\b--\b-n\bno\bo-\b-n\bno\bo-\b-h\bhe\bel\blp\bp=\b=_\bf_\ba_\bl_\bs_\be, or even -\b--\b-n\bno\bo-\b-n\bno\bo-\b-h\bhe\bel\blp\bp=\b=_\bm_\ba_\by_\bb_\be).
 153
 154 E\bEX\bXA\bAM\bMP\bPL\bLE\bE
 155      #include <stdio.h>
 156      #include <string.h>
 157      #include <getarg.h>
 158
 159      char *source = "Ouagadougou";
 160      char *destination;
 161      int weight;
 162      int include_catalog = 1;
 163      int help_flag;
 164
 165      struct getargs args[] = {
 166          { "source",      's', arg_string,  &source,
 167            "source of shippment", "city" },
 168          { "destination", 'd', arg_string,  &destination,
 169            "destination of shippment", "city" },
 170          { "weight",      'w', arg_integer, &weight,
 171            "weight of shippment", "tons" },
 172          { "catalog",     'c', arg_negative_flag, &include_catalog,
 173            "include product catalog" },
 174          { "help",        'h', arg_flag, &help_flag }
 175      };
 176
 177      int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */
 178
 179      const char *progname = "ship++";
 180
 181      int
 182      main(int argc, char **argv)
 183      {
 184          int optind = 0;
 185          if (getarg(args, num_args, argc, argv, &optind)) {
 186              arg_printusage(args, num_args, progname, "stuff...");
 187              exit (1);
 188          }
 189          if (help_flag) {
 190              arg_printusage(args, num_args, progname, "stuff...");
 191              exit (0);
 192          }
 193          if (destination == NULL) {
 194              fprintf(stderr, "%s: must specify destination\n", progname);
 195              exit(1);
 196          }
 197          if (strcmp(source, destination) == 0) {
 198              fprintf(stderr, "%s: destination must be different from source\n");
 199              exit(1);
 200          }
 201          /* include more stuff here ... */
 202          exit(2);
 203      }
 204
 205      The output help output from this program looks like this:
 206
 207      $ ship++ --help
 208      Usage: ship++ [--source=city] [-s city] [--destination=city] [-d city]
 209         [--weight=tons] [-w tons] [--no-catalog] [-c] [--help] [-h] stuff...
 210      -s city, --source=city      source of shippment
 211      -d city, --destination=city destination of shippment
 212      -w tons, --weight=tons      weight of shippment
 213      -c, --no-catalog            include product catalog
 214
 215 B\bBU\bUG\bGS\bS
 216      It should be more flexible, so it would be possible to use other more
 217      complicated option syntaxes, such as what ps(1),  and tar(1),  uses, or
 218      the AFS model where you can skip the flag names as long as the options
 219      come in the correct order.
 220
 221      Options with multiple arguments should be handled better.
 222
 223      Should be integreated with SL.
 224
 225      It's very confusing that the struct you pass in is called getargS.
 226
 227 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
 228      getopt(3)
 229
 230  ROKEN                        September 24, 1999                             4