popt/popt.h

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