popt/popt.h

   1 /** @file
   2  */
   3
   4 /* (C) 1998-2000 Red Hat, Inc. -- Licensing details are in the COPYING
   5    file accompanying popt source distributions, available from
   6    ftp://ftp.rpm.org/pub/rpm/dist. */
   7
   8 #ifndef H_POPT
   9 #define H_POPT
  10
  11 #include <stdio.h>                      /* for FILE * */
  12
  13 #define POPT_OPTION_DEPTH       10
  14
  15 /**
  16  * \name Arg type identifiers
  17  */
  18 #define POPT_ARG_NONE            0U     /*!< no arg */
  19 #define POPT_ARG_STRING          1U     /*!< arg will be saved as string */
  20 #define POPT_ARG_INT             2U     /*!< arg ==> int */
  21 #define POPT_ARG_LONG            3U     /*!< arg ==> long */
  22 #define POPT_ARG_INCLUDE_TABLE   4U     /*!< arg points to table */
  23 #define POPT_ARG_CALLBACK        5U     /*!< table-wide callback... must be
  24                                            set first in table; arg points
  25                                            to callback, descrip points to
  26                                            callback data to pass */
  27 #define POPT_ARG_INTL_DOMAIN     6U     /*!< set the translation domain
  28                                            for this table and any
  29                                            included tables; arg points
  30                                            to the domain string */
  31 #define POPT_ARG_VAL             7U     /*!< arg should take value val */
  32 #define POPT_ARG_FLOAT           8U     /*!< arg ==> float */
  33 #define POPT_ARG_DOUBLE          9U     /*!< arg ==> double */
  34 #define POPT_ARG_LONGLONG        10U    /*!< arg ==> long long */
  35
  36 #define POPT_ARG_MAINCALL       (16U+11U)       /*!< EXPERIMENTAL: return (*arg) (argc, argv) */
  37 #define POPT_ARG_ARGV           12U     /*!< dupe'd arg appended to realloc'd argv array. */
  38 #define POPT_ARG_SHORT          13U     /*!< arg ==> short */
  39 #define POPT_ARG_BITSET         (16U+14U)       /*!< arg ==> bit set */
  40
  41 #define POPT_ARG_MASK           0x000000FFU
  42 #define POPT_GROUP_MASK         0x0000FF00U
  43
  44 /**
  45  * \name Arg modifiers
  46  */
  47 #define POPT_ARGFLAG_ONEDASH    0x80000000U  /*!< allow -longoption */
  48 #define POPT_ARGFLAG_DOC_HIDDEN 0x40000000U  /*!< don't show in help/usage */
  49 #define POPT_ARGFLAG_STRIP      0x20000000U  /*!< strip this arg from argv(only applies to long args) */
  50 #define POPT_ARGFLAG_OPTIONAL   0x10000000U  /*!< arg may be missing */
  51
  52 #define POPT_ARGFLAG_OR         0x08000000U  /*!< arg will be or'ed */
  53 #define POPT_ARGFLAG_NOR        0x09000000U  /*!< arg will be nor'ed */
  54 #define POPT_ARGFLAG_AND        0x04000000U  /*!< arg will be and'ed */
  55 #define POPT_ARGFLAG_NAND       0x05000000U  /*!< arg will be nand'ed */
  56 #define POPT_ARGFLAG_XOR        0x02000000U  /*!< arg will be xor'ed */
  57 #define POPT_ARGFLAG_NOT        0x01000000U  /*!< arg will be negated */
  58 #define POPT_ARGFLAG_LOGICALOPS \
  59         (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR)
  60
  61 #define POPT_BIT_SET    (POPT_ARG_VAL|POPT_ARGFLAG_OR)
  62                                         /*!< set arg bit(s) */
  63 #define POPT_BIT_CLR    (POPT_ARG_VAL|POPT_ARGFLAG_NAND)
  64                                         /*!< clear arg bit(s) */
  65
  66 #define POPT_ARGFLAG_SHOW_DEFAULT 0x00800000U /*!< show default value in --help */
  67 #define POPT_ARGFLAG_RANDOM     0x00400000U  /*!< random value in [1,arg] */
  68 #define POPT_ARGFLAG_TOGGLE     0x00200000U  /*!< permit --[no]opt prefix toggle */
  69
  70 /**
  71  * \name Callback modifiers
  72  */
  73 #define POPT_CBFLAG_PRE         0x80000000U  /*!< call the callback before parse */
  74 #define POPT_CBFLAG_POST        0x40000000U  /*!< call the callback after parse */
  75 #define POPT_CBFLAG_INC_DATA    0x20000000U  /*!< use data from the include line,
  76                                                not the subtable */
  77 #define POPT_CBFLAG_SKIPOPTION  0x10000000U  /*!< don't callback with option */
  78 #define POPT_CBFLAG_CONTINUE    0x08000000U  /*!< continue callbacks with option */
  79
  80 /**
  81  * \name Error return values
  82  */
  83 #define POPT_ERROR_NOARG        -10     /*!< missing argument */
  84 #define POPT_ERROR_BADOPT       -11     /*!< unknown option */
  85 #define POPT_ERROR_UNWANTEDARG  -12     /*!< option does not take an argument */
  86 #define POPT_ERROR_OPTSTOODEEP  -13     /*!< aliases nested too deeply */
  87 #define POPT_ERROR_BADQUOTE     -15     /*!< error in parameter quoting */
  88 #define POPT_ERROR_ERRNO        -16     /*!< errno set, use strerror(errno) */
  89 #define POPT_ERROR_BADNUMBER    -17     /*!< invalid numeric value */
  90 #define POPT_ERROR_OVERFLOW     -18     /*!< number too large or too small */
  91 #define POPT_ERROR_BADOPERATION -19     /*!< mutually exclusive logical operations requested */
  92 #define POPT_ERROR_NULLARG      -20     /*!< opt->arg should not be NULL */
  93 #define POPT_ERROR_MALLOC       -21     /*!< memory allocation failed */
  94 #define POPT_ERROR_BADCONFIG    -22     /*!< config file failed sanity test */
  95
  96 /**
  97  * \name poptBadOption() flags
  98  */
  99 #define POPT_BADOPTION_NOALIAS  (1U << 0)  /*!< don't go into an alias */
 100
 101 /**
 102  * \name poptGetContext() flags
 103  */
 104 #define POPT_CONTEXT_NO_EXEC    (1U << 0)  /*!< ignore exec expansions */
 105 #define POPT_CONTEXT_KEEP_FIRST (1U << 1)  /*!< pay attention to argv[0] */
 106 #define POPT_CONTEXT_POSIXMEHARDER (1U << 2) /*!< options can't follow args */
 107 #define POPT_CONTEXT_ARG_OPTS   (1U << 4) /*!< return args as options with value 0 */
 108
 109 /**
 110  */
 111 struct poptOption {
 112     const char * longName;      /*!< may be NULL */
 113     char shortName;             /*!< may be '\0' */
 114     unsigned int argInfo;       /*!< type of argument expected after the option */
 115     void * arg;                 /*!< depends on argInfo */
 116     int val;                    /*!< 0 means don't return, just update arg */
 117     const char * descrip;       /*!< description for autohelp -- may be NULL */
 118     const char * argDescrip;    /*!< argument description for autohelp -- may be NULL */
 119 };
 120
 121 /**
 122  * A popt alias argument for poptAddAlias().
 123  */
 124 struct poptAlias {
 125     const char * longName;      /*!< may be NULL */
 126     char shortName;             /*!< may be NUL */
 127     int argc;
 128     const char ** argv;         /*!< must be free()able */
 129 };
 130
 131 /**
 132  * A popt alias or exec argument for poptAddItem().
 133  */
 134 typedef struct poptItem_s {
 135     struct poptOption option;   /*!< alias/exec name(s) and description. */
 136     int argc;                   /*!< (alias) no. of args. */
 137     const char ** argv;         /*!< (alias) args, must be free()able. */
 138 } * poptItem;
 139
 140 /**
 141  * \name Auto-generated help/usage
 142  */
 143
 144 /**
 145  * Empty table marker to enable displaying popt alias/exec options.
 146  */
 147 extern struct poptOption poptAliasOptions[];
 148 #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
 149                         0, "Options implemented via popt alias/exec:", NULL },
 150
 151 /**
 152  * Auto help table options.
 153  */
 154 extern struct poptOption poptHelpOptions[];
 155
 156 extern struct poptOption * poptHelpOptionsI18N;
 157
 158 #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
 159                         0, "Help options:", NULL },
 160
 161 #define POPT_TABLEEND { NULL, '\0', 0, NULL, 0, NULL, NULL }
 162
 163 /**
 164  */
 165 typedef struct poptContext_s * poptContext;
 166
 167 /**
 168  */
 169 #ifndef __cplusplus
 170 typedef struct poptOption * poptOption;
 171 #endif
 172
 173 /**
 174  */
 175 enum poptCallbackReason {
 176     POPT_CALLBACK_REASON_PRE    = 0,
 177     POPT_CALLBACK_REASON_POST   = 1,
 178     POPT_CALLBACK_REASON_OPTION = 2
 179 };
 180
 181 #ifdef __cplusplus
 182 extern "C" {
 183 #endif
 184
 185 /**
 186  * Table callback prototype.
 187  * @param con           context
 188  * @param reason        reason for callback
 189  * @param opt           option that triggered callback
 190  * @param arg           @todo Document.
 191  * @param data          @todo Document.
 192  */
 193 typedef void (*poptCallbackType) (poptContext con,
 194                 enum poptCallbackReason reason,
 195                 const struct poptOption * opt,
 196                 const char * arg,
 197                 const void * data);
 198
 199 /**
 200  * Destroy context.
 201  * @param con           context
 202  * @return              NULL always
 203  */
 204 poptContext poptFreeContext( poptContext con);
 205
 206 /**
 207  * Initialize popt context.
 208  * @param name          context name (usually argv[0] program name)
 209  * @param argc          no. of arguments
 210  * @param argv          argument array
 211  * @param options       address of popt option table
 212  * @param flags         or'd POPT_CONTEXT_* bits
 213  * @return              initialized popt context
 214  */
 215 poptContext poptGetContext(
 216                 const char * name,
 217                 int argc, const char ** argv,
 218                 const struct poptOption * options,
 219                 unsigned int flags);
 220
 221 /**
 222  * Destroy context (alternative implementation).
 223  * @param con           context
 224  * @return              NULL always
 225  */
 226 poptContext poptFini( poptContext con);
 227
 228 /**
 229  * Initialize popt context (alternative implementation).
 230  * This routine does poptGetContext() and then poptReadConfigFiles().
 231  * @param argc          no. of arguments
 232  * @param argv          argument array
 233  * @param options       address of popt option table
 234  * @param configPaths   colon separated file path(s) to read.
 235  * @return              initialized popt context (NULL on error).
 236  */
 237 poptContext poptInit(int argc, const char ** argv,
 238                 const struct poptOption * options,
 239                 const char * configPaths);
 240
 241 /**
 242  * Reinitialize popt context.
 243  * @param con           context
 244  */
 245 void poptResetContext(poptContext con);
 246
 247 /**
 248  * Return value of next option found.
 249  * @param con           context
 250  * @return              next option val, -1 on last item, POPT_ERROR_* on error
 251  */
 252 int poptGetNextOpt(poptContext con);
 253
 254 /**
 255  * Return next option argument (if any).
 256  * @param con           context
 257  * @return              option argument, NULL if no argument is available
 258  */
 259 char * poptGetOptArg(poptContext con);
 260
 261 /**
 262  * Return next argument.
 263  * @param con           context
 264  * @return              next argument, NULL if no argument is available
 265  */
 266 const char * poptGetArg(poptContext con);
 267
 268 /**
 269  * Peek at current argument.
 270  * @param con           context
 271  * @return              current argument, NULL if no argument is available
 272  */
 273 const char * poptPeekArg(poptContext con);
 274
 275 /**
 276  * Return remaining arguments.
 277  * @param con           context
 278  * @return              argument array, NULL terminated
 279  */
 280 const char ** poptGetArgs(poptContext con);
 281
 282 /**
 283  * Return the option which caused the most recent error.
 284  * @param con           context
 285  * @param flags
 286  * @return              offending option
 287  */
 288 const char * poptBadOption(poptContext con, unsigned int flags);
 289
 290 /**
 291  * Add arguments to context.
 292  * @param con           context
 293  * @param argv          argument array, NULL terminated
 294  * @return              0 on success, POPT_ERROR_OPTSTOODEEP on failure
 295  */
 296 int poptStuffArgs(poptContext con, const char ** argv);
 297
 298 /**
 299  * Add alias to context.
 300  * @todo Pass alias by reference, not value.
 301  * @deprecated Use poptAddItem instead.
 302  * @param con           context
 303  * @param alias         alias to add
 304  * @param flags         (unused)
 305  * @return              0 on success
 306  */
 307 int poptAddAlias(poptContext con, struct poptAlias alias, int flags);
 308
 309 /**
 310  * Add alias/exec item to context.
 311  * @param con           context
 312  * @param newItem       alias/exec item to add
 313  * @param flags         0 for alias, 1 for exec
 314  * @return              0 on success
 315  */
 316 int poptAddItem(poptContext con, poptItem newItem, int flags);
 317
 318 /**
 319  * Test path/file for config file sanity (regular file, permissions etc)
 320  * @param fn            file name
 321  * @return              1 on OK, 0 on NOTOK.
 322  */
 323 int poptSaneFile(const char * fn);
 324
 325 /**
 326  * Read a file into a buffer.
 327  * @param fn            file name
 328  * @retval *bp          buffer (malloc'd) (or NULL)
 329  * @retval *nbp         no. of bytes in buffer (including final NUL) (or NULL)
 330  * @param flags         1 to trim escaped newlines
 331  * return               0 on success
 332  */
 333 int poptReadFile(const char * fn, char ** bp,
 334                 size_t * nbp, int flags);
 335 #define POPT_READFILE_TRIMNEWLINES      1
 336
 337 /**
 338  * Read configuration file.
 339  * @param con           context
 340  * @param fn            file name to read
 341  * @return              0 on success, POPT_ERROR_ERRNO on failure
 342  */
 343 int poptReadConfigFile(poptContext con, const char * fn);
 344
 345 /**
 346  * Read configuration file(s).
 347  * Colon separated files to read, looping over poptReadConfigFile().
 348  * Note that an '@' character preceding a path in the list will
 349  * also perform additional sanity checks on the file before reading.
 350  * @param con           context
 351  * @param paths         colon separated file name(s) to read
 352  * @return              0 on success, POPT_ERROR_BADCONFIG on failure
 353  */
 354 int poptReadConfigFiles(poptContext con, const char * paths);
 355
 356 /**
 357  * Read default configuration from /etc/popt and $HOME/.popt.
 358  * @param con           context
 359  * @param useEnv        (unused)
 360  * @return              0 on success, POPT_ERROR_ERRNO on failure
 361  */
 362 int poptReadDefaultConfig(poptContext con, int useEnv);
 363
 364 /**
 365  * Duplicate an argument array.
 366  * @note: The argument array is malloc'd as a single area, so only argv must
 367  * be free'd.
 368  *
 369  * @param argc          no. of arguments
 370  * @param argv          argument array
 371  * @retval argcPtr      address of returned no. of arguments
 372  * @retval argvPtr      address of returned argument array
 373  * @return              0 on success, POPT_ERROR_NOARG on failure
 374  */
 375 int poptDupArgv(int argc, const char **argv,
 376                 int * argcPtr,
 377                 const char *** argvPtr);
 378
 379 /**
 380  * Parse a string into an argument array.
 381  * The parse allows ', ", and \ quoting, but ' is treated the same as " and
 382  * both may include \ quotes.
 383  * @note: The argument array is malloc'd as a single area, so only argv must
 384  * be free'd.
 385  *
 386  * @param s             string to parse
 387  * @retval argcPtr      address of returned no. of arguments
 388  * @retval argvPtr      address of returned argument array
 389  */
 390 int poptParseArgvString(const char * s,
 391                 int * argcPtr, const char *** argvPtr);
 392
 393 /**
 394  * Parses an input configuration file and returns an string that is a
 395  * command line.  For use with popt.  You must free the return value when done.
 396  *
 397  * Given the file:
 398 \verbatim
 399 # this line is ignored
 400     #   this one too
 401 aaa
 402   bbb
 403     ccc
 404 bla=bla
 405
 406 this_is   =   fdsafdas
 407      bad_line=
 408   really bad line
 409   really bad line  = again
 410 5555=   55555
 411   test = with lots of spaces
 412 \endverbatim
 413 *
 414 * The result is:
 415 \verbatim
 416 --aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces"
 417 \endverbatim
 418 *
 419 * Passing this to poptParseArgvString() yields an argv of:
 420 \verbatim
 421 '--aaa'
 422 '--bbb'
 423 '--ccc'
 424 '--bla=bla'
 425 '--this_is=fdsafdas'
 426 '--5555=55555'
 427 '--test=with lots of spaces'
 428 \endverbatim
 429  *
 430  * @bug NULL is returned if file line is too long.
 431  * @bug Silently ignores invalid lines.
 432  *
 433  * @param fp            file handle to read
 434  * @param *argstrp      return string of options (malloc'd)
 435  * @param flags         unused
 436  * @return              0 on success
 437  * @see                 poptParseArgvString
 438  */
 439 int poptConfigFileToString(FILE *fp, char ** argstrp, int flags);
 440
 441 /**
 442  * Return formatted error string for popt failure.
 443  * @param error         popt error
 444  * @return              error string
 445  */
 446 const char * poptStrerror(const int error);
 447
 448 /**
 449  * Limit search for executables.
 450  * @param con           context
 451  * @param path          single path to search for executables
 452  * @param allowAbsolute absolute paths only?
 453  */
 454 void poptSetExecPath(poptContext con, const char * path, int allowAbsolute);
 455
 456 /**
 457  * Print detailed description of options.
 458  * @param con           context
 459  * @param fp            output file handle
 460  * @param flags         (unused)
 461  */
 462 void poptPrintHelp(poptContext con, FILE * fp, int flags);
 463
 464 /**
 465  * Print terse description of options.
 466  * @param con           context
 467  * @param fp            output file handle
 468  * @param flags         (unused)
 469  */
 470 void poptPrintUsage(poptContext con, FILE * fp, int flags);
 471
 472 /**
 473  * Provide text to replace default "[OPTION...]" in help/usage output.
 474  * @param con           context
 475  * @param text          replacement text
 476  */
 477 void poptSetOtherOptionHelp(poptContext con, const char * text);
 478
 479 /**
 480  * Return argv[0] from context.
 481  * @param con           context
 482  * @return              argv[0]
 483  */
 484 const char * poptGetInvocationName(poptContext con);
 485
 486 /**
 487  * Shuffle argv pointers to remove stripped args, returns new argc.
 488  * @param con           context
 489  * @param argc          no. of args
 490  * @param argv          arg vector
 491  * @return              new argc
 492  */
 493 int poptStrippedArgv(poptContext con, int argc, char ** argv);
 494
 495 /**
 496  * Add a string to an argv array.
 497  * @retval *argvp       argv array
 498  * @param argInfo       (unused)
 499  * @param val           string arg to add (using strdup)
 500  * @return              0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 501  */
 502 int poptSaveString(const char *** argvp, unsigned int argInfo,
 503                 const char * val);
 504
 505 /**
 506  * Save a long long, performing logical operation with value.
 507  * @warning Alignment check may be too strict on certain platorms.
 508  * @param arg           integer pointer, aligned on int boundary.
 509  * @param argInfo       logical operation (see POPT_ARGFLAG_*)
 510  * @param aLongLong     value to use
 511  * @return              0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 512  */
 513 int poptSaveLongLong(long long * arg, unsigned int argInfo,
 514                 long long aLongLong);
 515
 516 /**
 517  * Save a long, performing logical operation with value.
 518  * @warning Alignment check may be too strict on certain platorms.
 519  * @param arg           integer pointer, aligned on int boundary.
 520  * @param argInfo       logical operation (see POPT_ARGFLAG_*)
 521  * @param aLong         value to use
 522  * @return              0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 523  */
 524 int poptSaveLong(long * arg, unsigned int argInfo, long aLong);
 525
 526 /**
 527  * Save a short integer, performing logical operation with value.
 528  * @warning Alignment check may be too strict on certain platorms.
 529  * @param arg           short pointer, aligned on short boundary.
 530  * @param argInfo       logical operation (see POPT_ARGFLAG_*)
 531  * @param aLong         value to use
 532  * @return              0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 533  */
 534 int poptSaveShort(short * arg, unsigned int argInfo, long aLong);
 535
 536 /**
 537  * Save an integer, performing logical operation with value.
 538  * @warning Alignment check may be too strict on certain platorms.
 539  * @param arg           integer pointer, aligned on int boundary.
 540  * @param argInfo       logical operation (see POPT_ARGFLAG_*)
 541  * @param aLong         value to use
 542  * @return              0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 543  */
 544 int poptSaveInt(int * arg, unsigned int argInfo, long aLong);
 545
 546 /* The bit set typedef. */
 547 typedef struct poptBits_s {
 548     unsigned int bits[1];
 549 } * poptBits;
 550
 551 #define _POPT_BITS_N    1024U   /*!< estimated population */
 552 #define _POPT_BITS_M    ((3U * _POPT_BITS_N) / 2U)
 553 #define _POPT_BITS_K    16U     /*!< no. of linear hash combinations */
 554
 555 extern unsigned int _poptBitsN;
 556 extern  unsigned int _poptBitsM;
 557 extern  unsigned int _poptBitsK;
 558
 559 int poptBitsAdd(poptBits bits, const char * s);
 560 int poptBitsChk(poptBits bits, const char * s);
 561 int poptBitsClr(poptBits bits);
 562 int poptBitsDel(poptBits bits, const char * s);
 563 int poptBitsIntersect(poptBits * ap, const poptBits b);
 564 int poptBitsUnion(poptBits * ap, const poptBits b);
 565 int poptBitsArgs(poptContext con, poptBits * ap);
 566
 567 /**
 568  * Save a string into a bit set (experimental).
 569  * @retval *bits        bit set (lazily malloc'd if NULL)
 570  * @param argInfo       logical operation (see POPT_ARGFLAG_*)
 571  * @param s             string to add to bit set
 572  * @return              0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
 573  */
 574 int poptSaveBits(poptBits * bitsp, unsigned int argInfo,
 575                 const char * s);
 576
 577
 578 #ifdef  __cplusplus
 579 }
 580 #endif
 581
 582 #endif