X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/37101856a6968452bdbcfefcc997738be98fafd9..25082d1ef6712a15c52a1dacb36b7f0642c23ac8:/popt/popt.h diff --git a/popt/popt.h b/popt/popt.h index d4ba4911..8d85f731 100644 --- a/popt/popt.h +++ b/popt/popt.h @@ -82,6 +82,7 @@ /*@{*/ #define POPT_ERROR_NOARG -10 /*!< missing argument */ #define POPT_ERROR_BADOPT -11 /*!< unknown option */ +#define POPT_ERROR_UNWANTEDARG -12 /*!< option does not take an argument */ #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) */ @@ -112,33 +113,42 @@ /** \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 NUL */ int argInfo; -/*@shared@*/ /*@null@*/ void * arg; /*!< depends on argInfo */ +/*@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 */ +/*@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 NUL */ 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(). */ +/*@-exporttype@*/ 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. */ +/*@owned@*/ + const char ** argv; /*!< (alias) args, must be free()able. */ } * poptItem; +/*@=exporttype@*/ /** \ingroup popt * \name Auto-generated help/usage @@ -148,16 +158,26 @@ typedef struct poptItem_s { /** * Empty table marker to enable displaying popt alias/exec options. */ -/*@observer@*/ /*@checked@*/ +/*@-exportvar@*/ +/*@unchecked@*/ /*@observer@*/ extern struct poptOption poptAliasOptions[]; +/*@=exportvar@*/ #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \ 0, "Options implemented via popt alias/exec:", NULL }, /** * Auto help table options. */ -/*@observer@*/ /*@checked@*/ +/*@-exportvar@*/ +/*@unchecked@*/ /*@observer@*/ extern struct poptOption poptHelpOptions[]; +/*@=exportvar@*/ + +/*@-exportvar@*/ +/*@unchecked@*/ /*@observer@*/ +extern struct poptOption * poptHelpOptionsI18N; +/*@=exportvar@*/ + #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \ 0, "Help options:", NULL }, @@ -166,19 +186,25 @@ extern struct poptOption poptHelpOptions[]; /** \ingroup popt */ +/*@-exporttype@*/ typedef /*@abstract@*/ struct poptContext_s * poptContext; +/*@=exporttype@*/ /** \ingroup popt */ #ifndef __cplusplus -/*@-typeuse@*/ +/*@-exporttype -typeuse@*/ typedef struct poptOption * poptOption; -/*@=typeuse@*/ +/*@=exporttype =typeuse@*/ #endif -enum poptCallbackReason { POPT_CALLBACK_REASON_PRE, - POPT_CALLBACK_REASON_POST, - POPT_CALLBACK_REASON_OPTION }; +/*@-exportconst@*/ +enum poptCallbackReason { + POPT_CALLBACK_REASON_PRE = 0, + POPT_CALLBACK_REASON_POST = 1, + POPT_CALLBACK_REASON_OPTION = 2 +}; +/*@=exportconst@*/ #ifdef __cplusplus extern "C" { @@ -198,18 +224,20 @@ typedef void (*poptCallbackType) (poptContext con, /*@null@*/ const struct poptOption * opt, /*@null@*/ const char * arg, /*@null@*/ const void * data) - /*@*/; + /*@globals internalState @*/ + /*@modifies internalState @*/; /** \ingroup popt * Initialize popt context. - * @param name + * @param name context name (usually argv[0] program 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( +/*@only@*/ /*@null@*/ +poptContext poptGetContext( /*@dependent@*/ /*@keep@*/ const char * name, int argc, /*@dependent@*/ /*@keep@*/ const char ** argv, /*@dependent@*/ /*@keep@*/ const struct poptOption * options, @@ -220,6 +248,7 @@ typedef void (*poptCallbackType) (poptContext con, * Reinitialize popt context. * @param con context */ +/*@unused@*/ void poptResetContext(/*@null@*/poptContext con) /*@modifies con @*/; @@ -229,57 +258,62 @@ void poptResetContext(/*@null@*/poptContext con) * @return next option val, -1 on last item, POPT_ERROR_* on error */ int poptGetNextOpt(/*@null@*/poptContext con) - /*@globals fileSystem@*/ - /*@modifies con, fileSystem @*/; + /*@globals fileSystem, internalState @*/ + /*@modifies con, fileSystem, internalState @*/; -/*@-redecl@*/ /** \ingroup popt * Return next option argument (if any). * @param con context - * @return option argument, NULL if no more options are available + * @return option argument, NULL if no argument is available */ -/*@observer@*/ /*@null@*/ const char * poptGetOptArg(/*@null@*/poptContext con) +/*@observer@*/ /*@null@*/ /*@unused@*/ +const char * poptGetOptArg(/*@null@*/poptContext con) /*@modifies con @*/; /** \ingroup popt - * Return current option's argument. + * Return next argument. * @param con context - * @return option argument, NULL if no more options are available + * @return next argument, NULL if no argument is available */ -/*@observer@*/ /*@null@*/ const char * poptGetArg(/*@null@*/poptContext con) +/*@observer@*/ /*@null@*/ /*@unused@*/ +const char * poptGetArg(/*@null@*/poptContext con) /*@modifies con @*/; /** \ingroup popt - * Peek at current option's argument. + * Peek at current argument. * @param con context - * @return option argument + * @return current argument, NULL if no argument is available */ -/*@observer@*/ /*@null@*/ const char * poptPeekArg(/*@null@*/poptContext con) +/*@observer@*/ /*@null@*/ /*@unused@*/ +const char * poptPeekArg(/*@null@*/poptContext con) /*@*/; /** \ingroup popt * Return remaining arguments. * @param con context - * @return argument array, terminated with NULL + * @return argument array, NULL terminated */ -/*@observer@*/ /*@null@*/ const char ** poptGetArgs(/*@null@*/poptContext con) +/*@observer@*/ /*@null@*/ +const char ** poptGetArgs(/*@null@*/poptContext con) /*@modifies con @*/; /** \ingroup popt * Return the option which caused the most recent error. * @param con context + * @param flags * @return offending option */ -/*@observer@*/ const char * poptBadOption(/*@null@*/poptContext con, int flags) +/*@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) +/*@null@*/ +poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con) /*@modifies con @*/; /** \ingroup popt @@ -288,6 +322,7 @@ int poptGetNextOpt(/*@null@*/poptContext con) * @param argv argument array, NULL terminated * @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure */ +/*@unused@*/ int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv) /*@modifies con @*/; @@ -307,7 +342,7 @@ int poptAddAlias(poptContext con, struct poptAlias alias, int flags) /** \ingroup popt * Add alias/exec item to context. * @param con context - * @param item alias/exec item to add + * @param newItem alias/exec item to add * @param flags 0 for alias, 1 for exec * @return 0 on success */ @@ -321,9 +356,9 @@ int poptAddItem(poptContext con, poptItem newItem, int flags) * @return 0 on success, POPT_ERROR_ERRNO on failure */ int poptReadConfigFile(poptContext con, const char * fn) - /*@globals fileSystem@*/ - /*@modifies fileSystem, - con->execs, con->numExecs @*/; + /*@globals errno, fileSystem, internalState @*/ + /*@modifies con->execs, con->numExecs, + errno, fileSystem, internalState @*/; /** \ingroup popt * Read default configuration from /etc/popt and $HOME/.popt. @@ -331,10 +366,11 @@ int poptReadConfigFile(poptContext con, const char * fn) * @param useEnv (unused) * @return 0 on success, POPT_ERROR_ERRNO on failure */ +/*@unused@*/ int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv) - /*@globals fileSystem@*/ - /*@modifies fileSystem, - con->execs, con->numExecs @*/; + /*@globals fileSystem, internalState @*/ + /*@modifies con->execs, con->numExecs, + fileSystem, internalState @*/; /** \ingroup popt * Duplicate an argument array. @@ -363,19 +399,70 @@ int poptDupArgv(int argc, /*@null@*/ const char **argv, * @retval argcPtr address of returned no. of arguments * @retval argvPtr address of returned argument array */ -int poptParseArgvString(const unsigned char * s, +int poptParseArgvString(const char * s, /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr) /*@modifies *argcPtr, *argvPtr @*/; +/** \ingroup popt + * Parses an input configuration file and returns an string that is a + * command line. For use with popt. You must free the return value when done. + * + * Given the file: +\verbatim +# this line is ignored + # this one too +aaa + bbb + ccc +bla=bla + +this_is = fdsafdas + bad_line= + reall bad line + reall bad line = again +5555= 55555 + test = with lots of spaces +\endverbatim +* +* The result is: +\verbatim +--aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces" +\endverbatim +* +* Passing this to poptParseArgvString() yields an argv of: +\verbatim +'--aaa' +'--bbb' +'--ccc' +'--bla=bla' +'--this_is=fdsafdas' +'--5555=55555' +'--test=with lots of spaces' +\endverbatim + * + * @bug NULL is returned if file line is too long. + * @bug Silently ignores invalid lines. + * + * @param fp file handle to read + * @param *argstrp return string of options (malloc'd) + * @param flags unused + * @return 0 on success + * @see poptParseArgvString + */ +/*@-fcnuse@*/ +int poptConfigFileToString(FILE *fp, /*@out@*/ char ** argstrp, int flags) + /*@globals fileSystem @*/ + /*@modifies *fp, *argstrp, fileSystem @*/; +/*@=fcnuse@*/ + /** \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) +/*@observer@*/ +const char * poptStrerror(const int error) /*@*/; -/*@=redecl@*/ /** \ingroup popt * Limit search for executables. @@ -383,6 +470,7 @@ int poptParseArgvString(const unsigned char * s, * @param path single path to search for executables * @param allowAbsolute absolute paths only? */ +/*@unused@*/ void poptSetExecPath(poptContext con, const char * path, int allowAbsolute) /*@modifies con @*/; @@ -421,10 +509,11 @@ void poptSetOtherOptionHelp(poptContext con, const char * text) * @param con context * @return argv[0] */ -/*@-redecl -fcnuse@*/ -/*@observer@*/ const char * poptGetInvocationName(poptContext con) +/*@-fcnuse@*/ +/*@observer@*/ +const char * poptGetInvocationName(poptContext con) /*@*/; -/*@=redecl =fcnuse@*/ +/*@=fcnuse@*/ /** \ingroup popt * Shuffle argv pointers to remove stripped args, returns new argc. @@ -438,6 +527,36 @@ int poptStrippedArgv(poptContext con, int argc, char ** argv) /*@modifies *argv @*/; /*@=fcnuse@*/ +/** + * Save a long, performing logical operation with value. + * @warning Alignment check may be too strict on certain platorms. + * @param arg integer pointer, aligned on int boundary. + * @param argInfo logical operation (see POPT_ARGFLAG_*) + * @param aLong value to use + * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION + */ +/*@-incondefs@*/ +/*@unused@*/ +int poptSaveLong(/*@null@*/ long * arg, int argInfo, long aLong) + /*@modifies *arg @*/ + /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/; +/*@=incondefs@*/ + +/** + * Save an integer, performing logical operation with value. + * @warning Alignment check may be too strict on certain platorms. + * @param arg integer pointer, aligned on int boundary. + * @param argInfo logical operation (see POPT_ARGFLAG_*) + * @param aLong value to use + * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION + */ +/*@-incondefs@*/ +/*@unused@*/ +int poptSaveInt(/*@null@*/ int * arg, int argInfo, long aLong) + /*@modifies *arg @*/ + /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/; +/*@=incondefs@*/ + /*@=type@*/ #ifdef __cplusplus }