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