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