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