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 583