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@*/ 116 const char * longName; /*!< may be NULL */ 117 char shortName; /*!< may be NUL */ 118 int argInfo; 119 /*@shared@*/ /*@null@*/ 120 void * arg; /*!< depends on argInfo */ 121 int val; /*!< 0 means don't return, just update flag */ 122 /*@observer@*/ /*@null@*/ 123 const char * descrip; /*!< description for autohelp -- may be NULL */ 124 /*@observer@*/ /*@null@*/ 125 const char * argDescrip; /*!< argument description for autohelp */ 126 }; 127 128 /** \ingroup popt 129 * A popt alias argument for poptAddAlias(). 130 */ 131 struct poptAlias { 132 /*@owned@*/ /*@null@*/ 133 const char * longName; /*!< may be NULL */ 134 char shortName; /*!< may be NUL */ 135 int argc; 136 /*@owned@*/ 137 const char ** argv; /*!< must be free()able */ 138 }; 139 140 /** \ingroup popt 141 * A popt alias or exec argument for poptAddItem(). 142 */ 143 /*@-exporttype@*/ 144 typedef struct poptItem_s { 145 struct poptOption option; /*!< alias/exec name(s) and description. */ 146 int argc; /*!< (alias) no. of args. */ 147 /*@owned@*/ 148 const char ** argv; /*!< (alias) args, must be free()able. */ 149 } * poptItem; 150 /*@=exporttype@*/ 151 152 /** \ingroup popt 153 * \name Auto-generated help/usage 154 */ 155 /*@{*/ 156 157 /** 158 * Empty table marker to enable displaying popt alias/exec options. 159 */ 160 /*@-exportvar@*/ 161 /*@unchecked@*/ /*@observer@*/ 162 extern struct poptOption poptAliasOptions[]; 163 /*@=exportvar@*/ 164 #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \ 165 0, "Options implemented via popt alias/exec:", NULL }, 166 167 /** 168 * Auto help table options. 169 */ 170 /*@-exportvar@*/ 171 /*@unchecked@*/ /*@observer@*/ 172 extern struct poptOption poptHelpOptions[]; 173 /*@=exportvar@*/ 174 175 /*@-exportvar@*/ 176 /*@unchecked@*/ /*@observer@*/ 177 extern struct poptOption * poptHelpOptionsI18N; 178 /*@=exportvar@*/ 179 180 #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \ 181 0, "Help options:", NULL }, 182 183 #define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL } 184 /*@}*/ 185 186 /** \ingroup popt 187 */ 188 /*@-exporttype@*/ 189 typedef /*@abstract@*/ struct poptContext_s * poptContext; 190 /*@=exporttype@*/ 191 192 /** \ingroup popt 193 */ 194 #ifndef __cplusplus 195 /*@-exporttype -typeuse@*/ 196 typedef struct poptOption * poptOption; 197 /*@=exporttype =typeuse@*/ 198 #endif 199 200 /*@-exportconst@*/ 201 enum poptCallbackReason { 202 POPT_CALLBACK_REASON_PRE = 0, 203 POPT_CALLBACK_REASON_POST = 1, 204 POPT_CALLBACK_REASON_OPTION = 2 205 }; 206 /*@=exportconst@*/ 207 208 #ifdef __cplusplus 209 extern "C" { 210 #endif 211 /*@-type@*/ 212 213 /** \ingroup popt 214 * Table callback prototype. 215 * @param con context 216 * @param reason reason for callback 217 * @param opt option that triggered callback 218 * @param arg @todo Document. 219 * @param data @todo Document. 220 */ 221 typedef void (*poptCallbackType) (poptContext con, 222 enum poptCallbackReason reason, 223 /*@null@*/ const struct poptOption * opt, 224 /*@null@*/ const char * arg, 225 /*@null@*/ const void * data) 226 /*@globals internalState @*/ 227 /*@modifies internalState @*/; 228 229 /** \ingroup popt 230 * Initialize popt context. 231 * @param name context name (usually argv[0] program name) 232 * @param argc no. of arguments 233 * @param argv argument array 234 * @param options address of popt option table 235 * @param flags or'd POPT_CONTEXT_* bits 236 * @return initialized popt context 237 */ 238 /*@only@*/ /*@null@*/ 239 poptContext poptGetContext( 240 /*@dependent@*/ /*@keep@*/ const char * name, 241 int argc, /*@dependent@*/ /*@keep@*/ const char ** argv, 242 /*@dependent@*/ /*@keep@*/ const struct poptOption * options, 243 int flags) 244 /*@*/; 245 246 /** \ingroup popt 247 * Reinitialize popt context. 248 * @param con context 249 */ 250 /*@unused@*/ 251 void poptResetContext(/*@null@*/poptContext con) 252 /*@modifies con @*/; 253 254 /** \ingroup popt 255 * Return value of next option found. 256 * @param con context 257 * @return next option val, -1 on last item, POPT_ERROR_* on error 258 */ 259 int poptGetNextOpt(/*@null@*/poptContext con) 260 /*@globals fileSystem, internalState @*/ 261 /*@modifies con, fileSystem, internalState @*/; 262 263 /** \ingroup popt 264 * Return next option argument (if any). 265 * @param con context 266 * @return option argument, NULL if no argument is available 267 */ 268 /*@observer@*/ /*@null@*/ /*@unused@*/ 269 const char * poptGetOptArg(/*@null@*/poptContext con) 270 /*@modifies con @*/; 271 272 /** \ingroup popt 273 * Return next argument. 274 * @param con context 275 * @return next argument, NULL if no argument is available 276 */ 277 /*@observer@*/ /*@null@*/ /*@unused@*/ 278 const char * poptGetArg(/*@null@*/poptContext con) 279 /*@modifies con @*/; 280 281 /** \ingroup popt 282 * Peek at current argument. 283 * @param con context 284 * @return current argument, NULL if no argument is available 285 */ 286 /*@observer@*/ /*@null@*/ /*@unused@*/ 287 const char * poptPeekArg(/*@null@*/poptContext con) 288 /*@*/; 289 290 /** \ingroup popt 291 * Return remaining arguments. 292 * @param con context 293 * @return argument array, NULL terminated 294 */ 295 /*@observer@*/ /*@null@*/ 296 const char ** poptGetArgs(/*@null@*/poptContext con) 297 /*@modifies con @*/; 298 299 /** \ingroup popt 300 * Return the option which caused the most recent error. 301 * @param con context 302 * @param flags 303 * @return offending option 304 */ 305 /*@observer@*/ 306 const char * poptBadOption(/*@null@*/poptContext con, int flags) 307 /*@*/; 308 309 /** \ingroup popt 310 * Destroy context. 311 * @param con context 312 * @return NULL always 313 */ 314 /*@null@*/ 315 poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con) 316 /*@modifies con @*/; 317 318 /** \ingroup popt 319 * Add arguments to context. 320 * @param con context 321 * @param argv argument array, NULL terminated 322 * @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure 323 */ 324 /*@unused@*/ 325 int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv) 326 /*@modifies con @*/; 327 328 /** \ingroup popt 329 * Add alias to context. 330 * @todo Pass alias by reference, not value. 331 * @deprecated Use poptAddItem instead. 332 * @param con context 333 * @param alias alias to add 334 * @param flags (unused) 335 * @return 0 on success 336 */ 337 /*@unused@*/ 338 int poptAddAlias(poptContext con, struct poptAlias alias, int flags) 339 /*@modifies con @*/; 340 341 /** \ingroup popt 342 * Add alias/exec item to context. 343 * @param con context 344 * @param newItem alias/exec item to add 345 * @param flags 0 for alias, 1 for exec 346 * @return 0 on success 347 */ 348 int poptAddItem(poptContext con, poptItem newItem, int flags) 349 /*@modifies con @*/; 350 351 /** \ingroup popt 352 * Read configuration file. 353 * @param con context 354 * @param fn file name to read 355 * @return 0 on success, POPT_ERROR_ERRNO on failure 356 */ 357 int poptReadConfigFile(poptContext con, const char * fn) 358 /*@globals errno, fileSystem, internalState @*/ 359 /*@modifies con->execs, con->numExecs, 360 errno, fileSystem, internalState @*/; 361 362 /** \ingroup popt 363 * Read default configuration from /etc/popt and $HOME/.popt. 364 * @param con context 365 * @param useEnv (unused) 366 * @return 0 on success, POPT_ERROR_ERRNO on failure 367 */ 368 /*@unused@*/ 369 int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv) 370 /*@globals fileSystem, internalState @*/ 371 /*@modifies con->execs, con->numExecs, 372 fileSystem, internalState @*/; 373 374 /** \ingroup popt 375 * Duplicate an argument array. 376 * @note: The argument array is malloc'd as a single area, so only argv must 377 * be free'd. 378 * 379 * @param argc no. of arguments 380 * @param argv argument array 381 * @retval argcPtr address of returned no. of arguments 382 * @retval argvPtr address of returned argument array 383 * @return 0 on success, POPT_ERROR_NOARG on failure 384 */ 385 int poptDupArgv(int argc, /*@null@*/ const char **argv, 386 /*@null@*/ /*@out@*/ int * argcPtr, 387 /*@null@*/ /*@out@*/ const char *** argvPtr) 388 /*@modifies *argcPtr, *argvPtr @*/; 389 390 /** \ingroup popt 391 * Parse a string into an argument array. 392 * The parse allows ', ", and \ quoting, but ' is treated the same as " and 393 * both may include \ quotes. 394 * @note: The argument array is malloc'd as a single area, so only argv must 395 * be free'd. 396 * 397 * @param s string to parse 398 * @retval argcPtr address of returned no. of arguments 399 * @retval argvPtr address of returned argument array 400 */ 401 int poptParseArgvString(const char * s, 402 /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr) 403 /*@modifies *argcPtr, *argvPtr @*/; 404 405 /** \ingroup popt 406 * Parses an input configuration file and returns an string that is a 407 * command line. For use with popt. You must free the return value when done. 408 * 409 * Given the file: 410 \verbatim 411 # this line is ignored 412 # this one too 413 aaa 414 bbb 415 ccc 416 bla=bla 417 418 this_is = fdsafdas 419 bad_line= 420 reall bad line 421 reall bad line = again 422 5555= 55555 423 test = with lots of spaces 424 \endverbatim 425 * 426 * The result is: 427 \verbatim 428 --aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces" 429 \endverbatim 430 * 431 * Passing this to poptParseArgvString() yields an argv of: 432 \verbatim 433 '--aaa' 434 '--bbb' 435 '--ccc' 436 '--bla=bla' 437 '--this_is=fdsafdas' 438 '--5555=55555' 439 '--test=with lots of spaces' 440 \endverbatim 441 * 442 * @bug NULL is returned if file line is too long. 443 * @bug Silently ignores invalid lines. 444 * 445 * @param fp file handle to read 446 * @param *argstrp return string of options (malloc'd) 447 * @param flags unused 448 * @return 0 on success 449 * @see poptParseArgvString 450 */ 451 /*@-fcnuse@*/ 452 int poptConfigFileToString(FILE *fp, /*@out@*/ char ** argstrp, int flags) 453 /*@globals fileSystem @*/ 454 /*@modifies *fp, *argstrp, fileSystem @*/; 455 /*@=fcnuse@*/ 456 457 /** \ingroup popt 458 * Return formatted error string for popt failure. 459 * @param error popt error 460 * @return error string 461 */ 462 /*@observer@*/ 463 const char * poptStrerror(const int error) 464 /*@*/; 465 466 /** \ingroup popt 467 * Limit search for executables. 468 * @param con context 469 * @param path single path to search for executables 470 * @param allowAbsolute absolute paths only? 471 */ 472 /*@unused@*/ 473 void poptSetExecPath(poptContext con, const char * path, int allowAbsolute) 474 /*@modifies con @*/; 475 476 /** \ingroup popt 477 * Print detailed description of options. 478 * @param con context 479 * @param fp ouput file handle 480 * @param flags (unused) 481 */ 482 void poptPrintHelp(poptContext con, FILE * fp, /*@unused@*/ int flags) 483 /*@globals fileSystem @*/ 484 /*@modifies *fp, fileSystem @*/; 485 486 /** \ingroup popt 487 * Print terse description of options. 488 * @param con context 489 * @param fp ouput file handle 490 * @param flags (unused) 491 */ 492 void poptPrintUsage(poptContext con, FILE * fp, /*@unused@*/ int flags) 493 /*@globals fileSystem @*/ 494 /*@modifies *fp, fileSystem @*/; 495 496 /** \ingroup popt 497 * Provide text to replace default "[OPTION...]" in help/usage output. 498 * @param con context 499 * @param text replacement text 500 */ 501 /*@-fcnuse@*/ 502 void poptSetOtherOptionHelp(poptContext con, const char * text) 503 /*@modifies con @*/; 504 /*@=fcnuse@*/ 505 506 /** \ingroup popt 507 * Return argv[0] from context. 508 * @param con context 509 * @return argv[0] 510 */ 511 /*@-fcnuse@*/ 512 /*@observer@*/ 513 const char * poptGetInvocationName(poptContext con) 514 /*@*/; 515 /*@=fcnuse@*/ 516 517 /** \ingroup popt 518 * Shuffle argv pointers to remove stripped args, returns new argc. 519 * @param con context 520 * @param argc no. of args 521 * @param argv arg vector 522 * @return new argc 523 */ 524 /*@-fcnuse@*/ 525 int poptStrippedArgv(poptContext con, int argc, char ** argv) 526 /*@modifies *argv @*/; 527 /*@=fcnuse@*/ 528 529 /** 530 * Save a long, performing logical operation with value. 531 * @warning Alignment check may be too strict on certain platorms. 532 * @param arg integer pointer, aligned on int boundary. 533 * @param argInfo logical operation (see POPT_ARGFLAG_*) 534 * @param aLong value to use 535 * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION 536 */ 537 /*@-incondefs@*/ 538 /*@unused@*/ 539 int poptSaveLong(/*@null@*/ long * arg, int argInfo, long aLong) 540 /*@modifies *arg @*/ 541 /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/; 542 /*@=incondefs@*/ 543 544 /** 545 * Save an integer, performing logical operation with value. 546 * @warning Alignment check may be too strict on certain platorms. 547 * @param arg integer pointer, aligned on int boundary. 548 * @param argInfo logical operation (see POPT_ARGFLAG_*) 549 * @param aLong value to use 550 * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION 551 */ 552 /*@-incondefs@*/ 553 /*@unused@*/ 554 int poptSaveInt(/*@null@*/ int * arg, int argInfo, long aLong) 555 /*@modifies *arg @*/ 556 /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/; 557 /*@=incondefs@*/ 558 559 /*@=type@*/ 560 #ifdef __cplusplus 561 } 562 #endif 563 564 #endif 565
