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