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_OPTSTOODEEP  -13     /*!< aliases nested too deeply */
  86 #define POPT_ERROR_BADQUOTE     -15     /*!< error in paramter quoting */
  87 #define POPT_ERROR_ERRNO        -16     /*!< errno set, use strerror(errno) */
  88 #define POPT_ERROR_BADNUMBER    -17     /*!< invalid numeric value */
  89 #define POPT_ERROR_OVERFLOW     -18     /*!< number too large or too small */
  90 #define POPT_ERROR_BADOPERATION -19     /*!< mutually exclusive logical operations requested */
  91 #define POPT_ERROR_NULLARG      -20     /*!< opt->arg should not be NULL */
  92 #define POPT_ERROR_MALLOC       -21     /*!< memory allocation failed */
  93 /*@}*/
  94
  95 /** \ingroup popt
  96  * \name poptBadOption() flags
  97  */
  98 /*@{*/
  99 #define POPT_BADOPTION_NOALIAS  (1 << 0)  /*!< don't go into an alias */
 100 /*@}*/
 101
 102 /** \ingroup popt
 103  * \name poptGetContext() flags
 104  */
 105 /*@{*/
 106 #define POPT_CONTEXT_NO_EXEC    (1 << 0)  /*!< ignore exec expansions */
 107 #define POPT_CONTEXT_KEEP_FIRST (1 << 1)  /*!< pay attention to argv[0] */
 108 #define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /*!< options can't follow args */
 109 #define POPT_CONTEXT_ARG_OPTS   (1 << 4) /*!< return args as options with value 0 */
 110 /*@}*/
 111
 112 /** \ingroup popt
 113  */
 114 struct poptOption {
 115 /*@observer@*/ /*@null@*/ const char * longName; /*!< may be NULL */
 116     char shortName;                     /*!< may be '\0' */
 117     int argInfo;
 118 /*@shared@*/ /*@null@*/ void * arg;     /*!< depends on argInfo */
 119     int val;                    /*!< 0 means don't return, just update flag */
 120 /*@observer@*/ /*@null@*/ const char * descrip; /*!< description for autohelp -- may be NULL */
 121 /*@observer@*/ /*@null@*/ const char * argDescrip; /*!< argument description for autohelp */
 122 };
 123
 124 /** \ingroup popt
 125  * A popt alias argument for poptAddAlias().
 126  */
 127 struct poptAlias {
 128 /*@owned@*/ /*@null@*/ const char * longName;   /*!< may be NULL */
 129     char shortName;             /*!< may be '\0' */
 130     int argc;
 131 /*@owned@*/ const char ** argv; /*!< must be free()able */
 132 };
 133
 134 /** \ingroup popt
 135  * A popt alias or exec argument for poptAddItem().
 136  */
 137 typedef struct poptItem_s {
 138     struct poptOption option;   /*!< alias/exec name(s) and description. */
 139     int argc;                   /*!< (alias) no. of args. */
 140 /*@owned@*/ const char ** argv; /*!< (alias) args, must be free()able. */
 141 } * poptItem;
 142
 143 /** \ingroup popt
 144  * \name Auto-generated help/usage
 145  */
 146 /*@{*/
 147
 148 /**
 149  * Empty table marker to enable displaying popt alias/exec options.
 150  */
 151 /*@observer@*/ /*@checked@*/
 152 extern struct poptOption poptAliasOptions[];
 153 #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
 154                         0, "Options implemented via popt alias/exec:", NULL },
 155
 156 /**
 157  * Auto help table options.
 158  */
 159 /*@observer@*/ /*@checked@*/
 160 extern struct poptOption poptHelpOptions[];
 161 #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
 162                         0, "Help options:", NULL },
 163
 164 #define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
 165 /*@}*/
 166
 167 /** \ingroup popt
 168  */
 169 typedef /*@abstract@*/ struct poptContext_s * poptContext;
 170
 171 /** \ingroup popt
 172  */
 173 #ifndef __cplusplus
 174 /*@-typeuse@*/
 175 typedef struct poptOption * poptOption;
 176 /*@=typeuse@*/
 177 #endif
 178
 179 enum poptCallbackReason { POPT_CALLBACK_REASON_PRE,
 180                           POPT_CALLBACK_REASON_POST,
 181                           POPT_CALLBACK_REASON_OPTION };
 182
 183 #ifdef __cplusplus
 184 extern "C" {
 185 #endif
 186 /*@-type@*/
 187
 188 /** \ingroup popt
 189  * Table callback prototype.
 190  * @param con           context
 191  * @param reason        reason for callback
 192  * @param opt           option that triggered callback
 193  * @param arg           @todo Document.
 194  * @param data          @todo Document.
 195  */
 196 typedef void (*poptCallbackType) (poptContext con,
 197                 enum poptCallbackReason reason,
 198                 /*@null@*/ const struct poptOption * opt,
 199                 /*@null@*/ const char * arg,
 200                 /*@null@*/ const void * data)
 201         /*@*/;
 202
 203 /** \ingroup popt
 204  * Initialize popt context.
 205  * @param name
 206  * @param argc          no. of arguments
 207  * @param argv          argument array
 208  * @param options       address of popt option table
 209  * @param flags         or'd POPT_CONTEXT_* bits
 210  * @return              initialized popt context
 211  */
 212 /*@only@*/ /*@null@*/ poptContext poptGetContext(
 213                 /*@dependent@*/ /*@keep@*/ const char * name,
 214                 int argc, /*@dependent@*/ /*@keep@*/ const char ** argv,
 215                 /*@dependent@*/ /*@keep@*/ const struct poptOption * options,
 216                 int flags)
 217         /*@*/;
 218
 219 /** \ingroup popt
 220  * Reinitialize popt context.
 221  * @param con           context
 222  */
 223 void poptResetContext(/*@null@*/poptContext con)
 224         /*@modifies con @*/;
 225
 226 /** \ingroup popt
 227  * Return value of next option found.
 228  * @param con           context
 229  * @return              next option val, -1 on last item, POPT_ERROR_* on error
 230  */
 231 int poptGetNextOpt(/*@null@*/poptContext con)
 232         /*@globals fileSystem@*/
 233         /*@modifies con, fileSystem @*/;
 234
 235 /*@-redecl@*/
 236 /** \ingroup popt
 237  * Return next option argument (if any).
 238  * @param con           context
 239  * @return              option argument, NULL if no more options are available
 240  */
 241 /*@observer@*/ /*@null@*/ const char * poptGetOptArg(/*@null@*/poptContext con)
 242         /*@modifies con @*/;
 243
 244 /** \ingroup popt
 245  * Return current option's argument.
 246  * @param con           context
 247  * @return              option argument, NULL if no more options are available
 248  */
 249 /*@observer@*/ /*@null@*/ const char * poptGetArg(/*@null@*/poptContext con)
 250         /*@modifies con @*/;
 251
 252 /** \ingroup popt
 253  * Peek at current option's argument.
 254  * @param con           context
 255  * @return              option argument
 256  */
 257 /*@observer@*/ /*@null@*/ const char * poptPeekArg(/*@null@*/poptContext con)
 258         /*@*/;
 259
 260 /** \ingroup popt
 261  * Return remaining arguments.
 262  * @param con           context
 263  * @return              argument array, terminated with NULL
 264  */
 265 /*@observer@*/ /*@null@*/ const char ** poptGetArgs(/*@null@*/poptContext con)
 266         /*@modifies con @*/;
 267
 268 /** \ingroup popt
 269  * Return the option which caused the most recent error.
 270  * @param con           context
 271  * @return              offending option
 272  */
 273 /*@observer@*/ const char * poptBadOption(/*@null@*/poptContext con, int flags)
 274         /*@*/;
 275 /*@=redecl@*/
 276
 277 /** \ingroup popt
 278  * Destroy context.
 279  * @param con           context
 280  * @return              NULL always
 281  */
 282 /*@null@*/ poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con)
 283         /*@modifies con @*/;
 284
 285 /** \ingroup popt
 286  * Add arguments to context.
 287  * @param con           context
 288  * @param argv          argument array, NULL terminated
 289  * @return              0 on success, POPT_ERROR_OPTSTOODEEP on failure
 290  */
 291 int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv)
 292         /*@modifies con @*/;
 293
 294 /** \ingroup popt
 295  * Add alias to context.
 296  * @todo Pass alias by reference, not value.
 297  * @deprecated Use poptAddItem instead.
 298  * @param con           context
 299  * @param alias         alias to add
 300  * @param flags         (unused)
 301  * @return              0 on success
 302  */
 303 /*@unused@*/
 304 int poptAddAlias(poptContext con, struct poptAlias alias, int flags)
 305         /*@modifies con @*/;
 306
 307 /** \ingroup popt
 308  * Add alias/exec item to context.
 309  * @param con           context
 310  * @param item          alias/exec item to add
 311  * @param flags         0 for alias, 1 for exec
 312  * @return              0 on success
 313  */
 314 int poptAddItem(poptContext con, poptItem newItem, int flags)
 315         /*@modifies con @*/;
 316
 317 /** \ingroup popt
 318  * Read configuration file.
 319  * @param con           context
 320  * @param fn            file name to read
 321  * @return              0 on success, POPT_ERROR_ERRNO on failure
 322  */
 323 int poptReadConfigFile(poptContext con, const char * fn)
 324         /*@globals fileSystem@*/
 325         /*@modifies fileSystem,
 326                 con->execs, con->numExecs @*/;
 327
 328 /** \ingroup popt
 329  * Read default configuration from /etc/popt and $HOME/.popt.
 330  * @param con           context
 331  * @param useEnv        (unused)
 332  * @return              0 on success, POPT_ERROR_ERRNO on failure
 333  */
 334 int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv)
 335         /*@globals fileSystem@*/
 336         /*@modifies fileSystem,
 337                 con->execs, con->numExecs @*/;
 338
 339 /** \ingroup popt
 340  * Duplicate an argument array.
 341  * @note: The argument array is malloc'd as a single area, so only argv must
 342  * be free'd.
 343  *
 344  * @param argc          no. of arguments
 345  * @param argv          argument array
 346  * @retval argcPtr      address of returned no. of arguments
 347  * @retval argvPtr      address of returned argument array
 348  * @return              0 on success, POPT_ERROR_NOARG on failure
 349  */
 350 int poptDupArgv(int argc, /*@null@*/ const char **argv,
 351                 /*@null@*/ /*@out@*/ int * argcPtr,
 352                 /*@null@*/ /*@out@*/ const char *** argvPtr)
 353         /*@modifies *argcPtr, *argvPtr @*/;
 354
 355 /** \ingroup popt
 356  * Parse a string into an argument array.
 357  * The parse allows ', ", and \ quoting, but ' is treated the same as " and
 358  * both may include \ quotes.
 359  * @note: The argument array is malloc'd as a single area, so only argv must
 360  * be free'd.
 361  *
 362  * @param s             string to parse
 363  * @retval argcPtr      address of returned no. of arguments
 364  * @retval argvPtr      address of returned argument array
 365  */
 366 int poptParseArgvString(const unsigned char * s,
 367                 /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr)
 368         /*@modifies *argcPtr, *argvPtr @*/;
 369
 370 /** \ingroup popt
 371  * Return formatted error string for popt failure.
 372  * @param error         popt error
 373  * @return              error string
 374  */
 375 /*@-redecl@*/
 376 /*@observer@*/ const char * poptStrerror(const int error)
 377         /*@*/;
 378 /*@=redecl@*/
 379
 380 /** \ingroup popt
 381  * Limit search for executables.
 382  * @param con           context
 383  * @param path          single path to search for executables
 384  * @param allowAbsolute absolute paths only?
 385  */
 386 void poptSetExecPath(poptContext con, const char * path, int allowAbsolute)
 387         /*@modifies con @*/;
 388
 389 /** \ingroup popt
 390  * Print detailed description of options.
 391  * @param con           context
 392  * @param fp            ouput file handle
 393  * @param flags         (unused)
 394  */
 395 void poptPrintHelp(poptContext con, FILE * fp, /*@unused@*/ int flags)
 396         /*@globals fileSystem @*/
 397         /*@modifies *fp, fileSystem @*/;
 398
 399 /** \ingroup popt
 400  * Print terse description of options.
 401  * @param con           context
 402  * @param fp            ouput file handle
 403  * @param flags         (unused)
 404  */
 405 void poptPrintUsage(poptContext con, FILE * fp, /*@unused@*/ int flags)
 406         /*@globals fileSystem @*/
 407         /*@modifies *fp, fileSystem @*/;
 408
 409 /** \ingroup popt
 410  * Provide text to replace default "[OPTION...]" in help/usage output.
 411  * @param con           context
 412  * @param text          replacement text
 413  */
 414 /*@-fcnuse@*/
 415 void poptSetOtherOptionHelp(poptContext con, const char * text)
 416         /*@modifies con @*/;
 417 /*@=fcnuse@*/
 418
 419 /** \ingroup popt
 420  * Return argv[0] from context.
 421  * @param con           context
 422  * @return              argv[0]
 423  */
 424 /*@-redecl -fcnuse@*/
 425 /*@observer@*/ const char * poptGetInvocationName(poptContext con)
 426         /*@*/;
 427 /*@=redecl =fcnuse@*/
 428
 429 /** \ingroup popt
 430  * Shuffle argv pointers to remove stripped args, returns new argc.
 431  * @param con           context
 432  * @param argc          no. of args
 433  * @param argv          arg vector
 434  * @return              new argc
 435  */
 436 /*@-fcnuse@*/
 437 int poptStrippedArgv(poptContext con, int argc, char ** argv)
 438         /*@modifies *argv @*/;
 439 /*@=fcnuse@*/
 440
 441 /*@=type@*/
 442 #ifdef  __cplusplus
 443 }
 444 #endif
 445
 446 #endif