diff options
Diffstat (limited to 'popt/popt.h')
| -rw-r--r-- | popt/popt.h | 484 |
1 files changed, 400 insertions, 84 deletions
diff --git a/popt/popt.h b/popt/popt.h index e6fa8bdf..bb6a867b 100644 --- a/popt/popt.h +++ b/popt/popt.h @@ -1,128 +1,444 @@ -/* (C) 1998 Red Hat Software, Inc. -- Licensing details are in the COPYING +/** \file popt/popt.h + * \ingroup popt + */ + +/* (C) 1998-2000 Red Hat, Inc. -- Licensing details are in the COPYING file accompanying popt source distributions, available from - ftp://ftp.redhat.com/pub/code/popt */ + ftp://ftp.rpm.org/pub/rpm/dist. */ #ifndef H_POPT #define H_POPT -#ifdef __cplusplus -extern "C" { -#endif - #include <stdio.h> /* for FILE * */ #define POPT_OPTION_DEPTH 10 -#define POPT_ARG_NONE 0 -#define POPT_ARG_STRING 1 -#define POPT_ARG_INT 2 -#define POPT_ARG_LONG 3 -#define POPT_ARG_INCLUDE_TABLE 4 /* arg points to table */ -#define POPT_ARG_CALLBACK 5 /* table-wide callback... must be +/** \ingroup popt + * \name Arg type identifiers + */ +/*@{*/ +#define POPT_ARG_NONE 0 /*!< no arg */ +#define POPT_ARG_STRING 1 /*!< arg will be saved as string */ +#define POPT_ARG_INT 2 /*!< arg will be converted to int */ +#define POPT_ARG_LONG 3 /*!< arg will be converted to long */ +#define POPT_ARG_INCLUDE_TABLE 4 /*!< arg points to table */ +#define POPT_ARG_CALLBACK 5 /*!< table-wide callback... must be set first in table; arg points to callback, descrip points to callback data to pass */ -#define POPT_ARG_INTL_DOMAIN 6 /* set the translation domain +#define POPT_ARG_INTL_DOMAIN 6 /*!< set the translation domain for this table and any included tables; arg points to the domain string */ -#define POPT_ARG_VAL 7 /* arg should take value val */ +#define POPT_ARG_VAL 7 /*!< arg should take value val */ +#define POPT_ARG_FLOAT 8 /*!< arg will be converted to float */ +#define POPT_ARG_DOUBLE 9 /*!< arg will be converted to double */ + #define POPT_ARG_MASK 0x0000FFFF -#define POPT_ARGFLAG_ONEDASH 0x80000000 /* allow -longoption */ -#define POPT_ARGFLAG_DOC_HIDDEN 0x40000000 /* don't show in help/usage */ -#define POPT_ARGFLAG_STRIP 0x20000000 /* strip this arg from argv (only applies to long args) */ -#define POPT_CBFLAG_PRE 0x80000000 /* call the callback before parse */ -#define POPT_CBFLAG_POST 0x40000000 /* call the callback after parse */ -#define POPT_CBFLAG_INC_DATA 0x20000000 /* use data from the include line, +/*@}*/ + +/** \ingroup popt + * \name Arg modifiers + */ +/*@{*/ +#define POPT_ARGFLAG_ONEDASH 0x80000000 /*!< allow -longoption */ +#define POPT_ARGFLAG_DOC_HIDDEN 0x40000000 /*!< don't show in help/usage */ +#define POPT_ARGFLAG_STRIP 0x20000000 /*!< strip this arg from argv(only applies to long args) */ +#define POPT_ARGFLAG_OPTIONAL 0x10000000 /*!< arg may be missing */ + +#define POPT_ARGFLAG_OR 0x08000000 /*!< arg will be or'ed */ +#define POPT_ARGFLAG_NOR 0x09000000 /*!< arg will be nor'ed */ +#define POPT_ARGFLAG_AND 0x04000000 /*!< arg will be and'ed */ +#define POPT_ARGFLAG_NAND 0x05000000 /*!< arg will be nand'ed */ +#define POPT_ARGFLAG_XOR 0x02000000 /*!< arg will be xor'ed */ +#define POPT_ARGFLAG_NOT 0x01000000 /*!< arg will be negated */ +#define POPT_ARGFLAG_LOGICALOPS \ + (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR) + +#define POPT_BIT_SET (POPT_ARG_VAL|POPT_ARGFLAG_OR) + /*!< set arg bit(s) */ +#define POPT_BIT_CLR (POPT_ARG_VAL|POPT_ARGFLAG_NAND) + /*!< clear arg bit(s) */ + +#define POPT_ARGFLAG_SHOW_DEFAULT 0x00800000 /*!< show default value in --help */ + +/*@}*/ + +/** \ingroup popt + * \name Callback modifiers + */ +/*@{*/ +#define POPT_CBFLAG_PRE 0x80000000 /*!< call the callback before parse */ +#define POPT_CBFLAG_POST 0x40000000 /*!< call the callback after parse */ +#define POPT_CBFLAG_INC_DATA 0x20000000 /*!< use data from the include line, not the subtable */ +#define POPT_CBFLAG_SKIPOPTION 0x10000000 /*!< don't callback with option */ +#define POPT_CBFLAG_CONTINUE 0x08000000 /*!< continue callbacks with option */ +/*@}*/ -#define POPT_ERROR_NOARG -10 -#define POPT_ERROR_BADOPT -11 -#define POPT_ERROR_OPTSTOODEEP -13 -#define POPT_ERROR_BADQUOTE -15 /* only from poptParseArgString() */ -#define POPT_ERROR_ERRNO -16 /* only from poptParseArgString() */ -#define POPT_ERROR_BADNUMBER -17 -#define POPT_ERROR_OVERFLOW -18 +/** \ingroup popt + * \name Error return values + */ +/*@{*/ +#define POPT_ERROR_NOARG -10 /*!< missing argument */ +#define POPT_ERROR_BADOPT -11 /*!< unknown option */ +#define POPT_ERROR_OPTSTOODEEP -13 /*!< aliases nested too deeply */ +#define POPT_ERROR_BADQUOTE -15 /*!< error in paramter quoting */ +#define POPT_ERROR_ERRNO -16 /*!< errno set, use strerror(errno) */ +#define POPT_ERROR_BADNUMBER -17 /*!< invalid numeric value */ +#define POPT_ERROR_OVERFLOW -18 /*!< number too large or too small */ +#define POPT_ERROR_BADOPERATION -19 /*!< mutually exclusive logical operations requested */ +#define POPT_ERROR_NULLARG -20 /*!< opt->arg should not be NULL */ +#define POPT_ERROR_MALLOC -21 /*!< memory allocation failed */ +/*@}*/ -/* poptBadOption() flags */ -#define POPT_BADOPTION_NOALIAS (1 << 0) /* don't go into an alias */ +/** \ingroup popt + * \name poptBadOption() flags + */ +/*@{*/ +#define POPT_BADOPTION_NOALIAS (1 << 0) /*!< don't go into an alias */ +/*@}*/ -/* poptGetContext() flags */ -#define POPT_CONTEXT_NO_EXEC (1 << 0) /* ignore exec expansions */ -#define POPT_CONTEXT_KEEP_FIRST (1 << 1) /* pay attention to argv[0] */ -#define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /* options can't follow args */ +/** \ingroup popt + * \name poptGetContext() flags + */ +/*@{*/ +#define POPT_CONTEXT_NO_EXEC (1 << 0) /*!< ignore exec expansions */ +#define POPT_CONTEXT_KEEP_FIRST (1 << 1) /*!< pay attention to argv[0] */ +#define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /*!< options can't follow args */ +#define POPT_CONTEXT_ARG_OPTS (1 << 4) /*!< return args as options with value 0 */ +/*@}*/ +/** \ingroup popt + */ struct poptOption { - /*@observer@*/ /*@null@*/ const char * longName; /* may be NULL */ - char shortName; /* may be '\0' */ +/*@observer@*/ /*@null@*/ const char * longName; /*!< may be NULL */ + char shortName; /*!< may be '\0' */ int argInfo; - /*@shared@*/ /*@null@*/ void * arg; /* depends on argInfo */ - int val; /* 0 means don't return, just update flag */ - /*@shared@*/ /*@null@*/ const char * descrip; /* description for autohelp -- may be NULL */ - /*@shared@*/ /*@null@*/ const char * argDescrip; /* argument description for autohelp */ +/*@shared@*/ /*@null@*/ void * arg; /*!< depends on argInfo */ + int val; /*!< 0 means don't return, just update flag */ +/*@observer@*/ /*@null@*/ const char * descrip; /*!< description for autohelp -- may be NULL */ +/*@observer@*/ /*@null@*/ const char * argDescrip; /*!< argument description for autohelp */ }; +/** \ingroup popt + * A popt alias argument for poptAddAlias(). + */ struct poptAlias { - /*@owned@*/ /*@null@*/ const char * longName; /* may be NULL */ - char shortName; /* may be '\0' */ +/*@owned@*/ /*@null@*/ const char * longName; /*!< may be NULL */ + char shortName; /*!< may be '\0' */ int argc; - /*@owned@*/ const char ** argv; /* must be free()able */ +/*@owned@*/ const char ** argv; /*!< must be free()able */ }; +/** \ingroup popt + * A popt alias or exec argument for poptAddItem(). + */ +typedef struct poptItem_s { + struct poptOption option; /*!< alias/exec name(s) and description. */ + int argc; /*!< (alias) no. of args. */ +/*@owned@*/ const char ** argv; /*!< (alias) args, must be free()able. */ +} * poptItem; + +/** \ingroup popt + * \name Auto-generated help/usage + */ +/*@{*/ + +/** + * Empty table marker to enable displaying popt alias/exec options. + */ +/*@observer@*/ /*@checked@*/ +extern struct poptOption poptAliasOptions[]; +#define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \ + 0, "Options implemented via popt alias/exec:", NULL }, + +/** + * Auto help table options. + */ +/*@observer@*/ /*@checked@*/ extern struct poptOption poptHelpOptions[]; #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \ - 0, "Help options", NULL }, + 0, "Help options:", NULL }, -typedef struct poptContext_s * poptContext; +#define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL } +/*@}*/ + +/** \ingroup popt + */ +typedef /*@abstract@*/ struct poptContext_s * poptContext; + +/** \ingroup popt + */ #ifndef __cplusplus +/*@-typeuse@*/ typedef struct poptOption * poptOption; +/*@=typeuse@*/ #endif enum poptCallbackReason { POPT_CALLBACK_REASON_PRE, POPT_CALLBACK_REASON_POST, POPT_CALLBACK_REASON_OPTION }; -typedef void (*poptCallbackType)(poptContext con, - enum poptCallbackReason reason, - const struct poptOption * opt, - const char * arg, const void * data); - -/*@only@*/ poptContext poptGetContext(/*@keep@*/ const char * name, - int argc, /*@keep@*/ const char ** argv, - /*@keep@*/ const struct poptOption * options, int flags); -void poptResetContext(poptContext con); - -/* returns 'val' element, -1 on last item, POPT_ERROR_* on error */ -int poptGetNextOpt(poptContext con); -/* returns NULL if no argument is available */ -/*@observer@*/ /*@null@*/ const char * poptGetOptArg(poptContext con); -/* returns NULL if no more options are available */ -/*@observer@*/ /*@null@*/ const char * poptGetArg(poptContext con); -/*@observer@*/ /*@null@*/ const char * poptPeekArg(poptContext con); -/*@observer@*/ /*@null@*/ const char ** poptGetArgs(poptContext con); -/* returns the option which caused the most recent error */ -/*@observer@*/ const char * poptBadOption(poptContext con, int flags); -void poptFreeContext( /*@only@*/ poptContext con); -int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv); -int poptAddAlias(poptContext con, struct poptAlias alias, int flags); -int poptReadConfigFile(poptContext con, const char * fn); -/* like above, but reads /etc/popt and $HOME/.popt along with environment - vars */ -int poptReadDefaultConfig(poptContext con, int useEnv); -/* argv should be freed -- this allows ', ", and \ quoting, but ' is treated - the same as " and both may include \ quotes */ -int poptDupArgv(int argc, const char **argv, - /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr); + +#ifdef __cplusplus +extern "C" { +#endif +/*@-type@*/ + +/** \ingroup popt + * Table callback prototype. + * @param con context + * @param reason reason for callback + * @param opt option that triggered callback + * @param arg @todo Document. + * @param data @todo Document. + */ +typedef void (*poptCallbackType) (poptContext con, + enum poptCallbackReason reason, + /*@null@*/ const struct poptOption * opt, + /*@null@*/ const char * arg, + /*@null@*/ const void * data) + /*@*/; + +/** \ingroup popt + * Initialize popt context. + * @param name + * @param argc no. of arguments + * @param argv argument array + * @param options address of popt option table + * @param flags or'd POPT_CONTEXT_* bits + * @return initialized popt context + */ +/*@only@*/ /*@null@*/ poptContext poptGetContext( + /*@dependent@*/ /*@keep@*/ const char * name, + int argc, /*@dependent@*/ /*@keep@*/ const char ** argv, + /*@dependent@*/ /*@keep@*/ const struct poptOption * options, + int flags) + /*@*/; + +/** \ingroup popt + * Reinitialize popt context. + * @param con context + */ +void poptResetContext(/*@null@*/poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Return value of next option found. + * @param con context + * @return next option val, -1 on last item, POPT_ERROR_* on error + */ +int poptGetNextOpt(/*@null@*/poptContext con) + /*@globals fileSystem@*/ + /*@modifies con, fileSystem @*/; + +/*@-redecl@*/ +/** \ingroup popt + * Return next option argument (if any). + * @param con context + * @return option argument, NULL if no more options are available + */ +/*@observer@*/ /*@null@*/ const char * poptGetOptArg(/*@null@*/poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Return current option's argument. + * @param con context + * @return option argument, NULL if no more options are available + */ +/*@observer@*/ /*@null@*/ const char * poptGetArg(/*@null@*/poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Peek at current option's argument. + * @param con context + * @return option argument + */ +/*@observer@*/ /*@null@*/ const char * poptPeekArg(/*@null@*/poptContext con) + /*@*/; + +/** \ingroup popt + * Return remaining arguments. + * @param con context + * @return argument array, terminated with NULL + */ +/*@observer@*/ /*@null@*/ const char ** poptGetArgs(/*@null@*/poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Return the option which caused the most recent error. + * @param con context + * @return offending option + */ +/*@observer@*/ const char * poptBadOption(/*@null@*/poptContext con, int flags) + /*@*/; +/*@=redecl@*/ + +/** \ingroup popt + * Destroy context. + * @param con context + * @return NULL always + */ +/*@null@*/ poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Add arguments to context. + * @param con context + * @param argv argument array, NULL terminated + * @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure + */ +int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv) + /*@modifies con @*/; + +/** \ingroup popt + * Add alias to context. + * @todo Pass alias by reference, not value. + * @deprecated Use poptAddItem instead. + * @param con context + * @param alias alias to add + * @param flags (unused) + * @return 0 on success + */ +/*@unused@*/ +int poptAddAlias(poptContext con, struct poptAlias alias, int flags) + /*@modifies con @*/; + +/** \ingroup popt + * Add alias/exec item to context. + * @param con context + * @param item alias/exec item to add + * @param flags 0 for alias, 1 for exec + * @return 0 on success + */ +int poptAddItem(poptContext con, poptItem newItem, int flags) + /*@modifies con @*/; + +/** \ingroup popt + * Read configuration file. + * @param con context + * @param fn file name to read + * @return 0 on success, POPT_ERROR_ERRNO on failure + */ +int poptReadConfigFile(poptContext con, const char * fn) + /*@globals fileSystem@*/ + /*@modifies fileSystem, + con->execs, con->numExecs @*/; + +/** \ingroup popt + * Read default configuration from /etc/popt and $HOME/.popt. + * @param con context + * @param useEnv (unused) + * @return 0 on success, POPT_ERROR_ERRNO on failure + */ +int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv) + /*@globals fileSystem@*/ + /*@modifies fileSystem, + con->execs, con->numExecs @*/; + +/** \ingroup popt + * Duplicate an argument array. + * @note: The argument array is malloc'd as a single area, so only argv must + * be free'd. + * + * @param argc no. of arguments + * @param argv argument array + * @retval argcPtr address of returned no. of arguments + * @retval argvPtr address of returned argument array + * @return 0 on success, POPT_ERROR_NOARG on failure + */ +int poptDupArgv(int argc, /*@null@*/ const char **argv, + /*@null@*/ /*@out@*/ int * argcPtr, + /*@null@*/ /*@out@*/ const char *** argvPtr) + /*@modifies *argcPtr, *argvPtr @*/; + +/** \ingroup popt + * Parse a string into an argument array. + * The parse allows ', ", and \ quoting, but ' is treated the same as " and + * both may include \ quotes. + * @note: The argument array is malloc'd as a single area, so only argv must + * be free'd. + * + * @param s string to parse + * @retval argcPtr address of returned no. of arguments + * @retval argvPtr address of returned argument array + */ int poptParseArgvString(const char * s, - /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr); -/*@observer@*/ const char *const poptStrerror(const int error); -void poptSetExecPath(poptContext con, const char * path, int allowAbsolute); -void poptPrintHelp(poptContext con, FILE * f, int flags); -void poptPrintUsage(poptContext con, FILE * f, int flags); -void poptSetOtherOptionHelp(poptContext con, const char * text); -/*@observer@*/ const char * poptGetInvocationName(poptContext con); -/* shuffles argv pointers to remove stripped args, returns new argc */ -int poptStrippedArgv(poptContext con, int argc, char **argv); + /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr) + /*@modifies *argcPtr, *argvPtr @*/; + +/** \ingroup popt + * Return formatted error string for popt failure. + * @param error popt error + * @return error string + */ +/*@-redecl@*/ +/*@observer@*/ const char *const poptStrerror(const int error) + /*@*/; +/*@=redecl@*/ + +/** \ingroup popt + * Limit search for executables. + * @param con context + * @param path single path to search for executables + * @param allowAbsolute absolute paths only? + */ +void poptSetExecPath(poptContext con, const char * path, int allowAbsolute) + /*@modifies con @*/; + +/** \ingroup popt + * Print detailed description of options. + * @param con context + * @param fp ouput file handle + * @param flags (unused) + */ +void poptPrintHelp(poptContext con, FILE * fp, /*@unused@*/ int flags) + /*@globals fileSystem @*/ + /*@modifies *fp, fileSystem @*/; + +/** \ingroup popt + * Print terse description of options. + * @param con context + * @param fp ouput file handle + * @param flags (unused) + */ +void poptPrintUsage(poptContext con, FILE * fp, /*@unused@*/ int flags) + /*@globals fileSystem @*/ + /*@modifies *fp, fileSystem @*/; + +/** \ingroup popt + * Provide text to replace default "[OPTION...]" in help/usage output. + * @param con context + * @param text replacement text + */ +/*@-fcnuse@*/ +void poptSetOtherOptionHelp(poptContext con, const char * text) + /*@modifies con @*/; +/*@=fcnuse@*/ + +/** \ingroup popt + * Return argv[0] from context. + * @param con context + * @return argv[0] + */ +/*@-redecl -fcnuse@*/ +/*@observer@*/ const char * poptGetInvocationName(poptContext con) + /*@*/; +/*@=redecl =fcnuse@*/ + +/** \ingroup popt + * Shuffle argv pointers to remove stripped args, returns new argc. + * @param con context + * @param argc no. of args + * @param argv arg vector + * @return new argc + */ +/*@-fcnuse@*/ +int poptStrippedArgv(poptContext con, int argc, char ** argv) + /*@modifies *argv @*/; +/*@=fcnuse@*/ +/*@=type@*/ #ifdef __cplusplus } #endif |