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 */ 114struct 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 */ 127struct 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 */ 137typedef 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@*/ 152extern 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@*/ 160extern 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 */ 169typedef /*@abstract@*/ struct poptContext_s * poptContext; 170 171/** \ingroup popt 172 */ 173#ifndef __cplusplus 174/*@-typeuse@*/ 175typedef struct poptOption * poptOption; 176/*@=typeuse@*/ 177#endif 178 179enum poptCallbackReason { POPT_CALLBACK_REASON_PRE, 180 POPT_CALLBACK_REASON_POST, 181 POPT_CALLBACK_REASON_OPTION }; 182 183#ifdef __cplusplus 184extern "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 */ 196typedef 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 */ 223void 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 */ 231int 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 */ 291int 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@*/ 304int 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 */ 314int 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 */ 323int 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 */ 334int 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 */ 350int 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 */ 366int 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 */ 386void 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 */ 395void 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 */ 405void 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@*/ 415void 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@*/ 437int poptStrippedArgv(poptContext con, int argc, char ** argv) 438 /*@modifies *argv @*/; 439/*@=fcnuse@*/ 440 441/*@=type@*/ 442#ifdef __cplusplus 443} 444#endif 445 446#endif 447