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