From d98232a0fadf69e07af267f964957da467bf9def Mon Sep 17 00:00:00 2001 From: Sebastian Schuberth Date: Tue, 29 Dec 2009 01:50:30 +0100 Subject: [PATCH] Install popt-1.15.tar.gz Signed-off-by: Sebastian Schuberth --- mingw/include/popt.h | 669 ++++++++++++++++++++++++++++++++++++++ mingw/lib/libpopt.a | Bin 0 -> 41550 bytes mingw/lib/libpopt.la | 41 +++ mingw/share/man/man3/popt.3 | 771 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 1481 insertions(+) create mode 100644 mingw/include/popt.h create mode 100644 mingw/lib/libpopt.a create mode 100644 mingw/lib/libpopt.la create mode 100644 mingw/share/man/man3/popt.3 diff --git a/mingw/include/popt.h b/mingw/include/popt.h new file mode 100644 index 00000000..bd991a20 --- /dev/null +++ b/mingw/include/popt.h @@ -0,0 +1,669 @@ +/** \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.rpm.org/pub/rpm/dist. */ + +#ifndef H_POPT +#define H_POPT + +#include /* for FILE * */ + +#define POPT_OPTION_DEPTH 10 + +/** \ingroup popt + * \name Arg type identifiers + */ +/*@{*/ +#define POPT_ARG_NONE 0U /*!< no arg */ +#define POPT_ARG_STRING 1U /*!< arg will be saved as string */ +#define POPT_ARG_INT 2U /*!< arg ==> int */ +#define POPT_ARG_LONG 3U /*!< arg ==> long */ +#define POPT_ARG_INCLUDE_TABLE 4U /*!< arg points to table */ +#define POPT_ARG_CALLBACK 5U /*!< 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 6U /*!< set the translation domain + for this table and any + included tables; arg points + to the domain string */ +#define POPT_ARG_VAL 7U /*!< arg should take value val */ +#define POPT_ARG_FLOAT 8U /*!< arg ==> float */ +#define POPT_ARG_DOUBLE 9U /*!< arg ==> double */ +#define POPT_ARG_LONGLONG 10U /*!< arg ==> long long */ + +#define POPT_ARG_MAINCALL 16U+11U /*!< EXPERIMENTAL: return (*arg) (argc, argv) */ +#define POPT_ARG_ARGV 12U /*!< dupe'd arg appended to realloc'd argv array. */ + +#define POPT_ARG_MASK 0x000000FFU +#define POPT_GROUP_MASK 0x0000FF00U + +/*@}*/ + +/** \ingroup popt + * \name Arg modifiers + */ +/*@{*/ +#define POPT_ARGFLAG_ONEDASH 0x80000000U /*!< allow -longoption */ +#define POPT_ARGFLAG_DOC_HIDDEN 0x40000000U /*!< don't show in help/usage */ +#define POPT_ARGFLAG_STRIP 0x20000000U /*!< strip this arg from argv(only applies to long args) */ +#define POPT_ARGFLAG_OPTIONAL 0x10000000U /*!< arg may be missing */ + +#define POPT_ARGFLAG_OR 0x08000000U /*!< arg will be or'ed */ +#define POPT_ARGFLAG_NOR 0x09000000U /*!< arg will be nor'ed */ +#define POPT_ARGFLAG_AND 0x04000000U /*!< arg will be and'ed */ +#define POPT_ARGFLAG_NAND 0x05000000U /*!< arg will be nand'ed */ +#define POPT_ARGFLAG_XOR 0x02000000U /*!< arg will be xor'ed */ +#define POPT_ARGFLAG_NOT 0x01000000U /*!< 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 0x00800000U /*!< show default value in --help */ +#define POPT_ARGFLAG_RANDOM 0x00400000U /*!< random value in [1,arg] */ +#define POPT_ARGFLAG_TOGGLE 0x00200000U /*!< permit --[no]opt prefix toggle */ + +/*@}*/ + +/** \ingroup popt + * \name Callback modifiers + */ +/*@{*/ +#define POPT_CBFLAG_PRE 0x80000000U /*!< call the callback before parse */ +#define POPT_CBFLAG_POST 0x40000000U /*!< call the callback after parse */ +#define POPT_CBFLAG_INC_DATA 0x20000000U /*!< use data from the include line, + not the subtable */ +#define POPT_CBFLAG_SKIPOPTION 0x10000000U /*!< don't callback with option */ +#define POPT_CBFLAG_CONTINUE 0x08000000U /*!< continue callbacks with option */ +/*@}*/ + +/** \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 */ +#define POPT_ERROR_BADCONFIG -22 /*!< config file failed sanity test */ +/*@}*/ + +/** \ingroup popt + * \name poptBadOption() flags + */ +/*@{*/ +#define POPT_BADOPTION_NOALIAS (1U << 0) /*!< don't go into an alias */ +/*@}*/ + +/** \ingroup popt + * \name poptGetContext() flags + */ +/*@{*/ +#define POPT_CONTEXT_NO_EXEC (1U << 0) /*!< ignore exec expansions */ +#define POPT_CONTEXT_KEEP_FIRST (1U << 1) /*!< pay attention to argv[0] */ +#define POPT_CONTEXT_POSIXMEHARDER (1U << 2) /*!< options can't follow args */ +#define POPT_CONTEXT_ARG_OPTS (1U << 4) /*!< return args as options with value 0 */ +/*@}*/ + +/** \ingroup popt + */ +struct poptOption { +/*@observer@*/ /*@null@*/ + const char * longName; /*!< may be NULL */ + char shortName; /*!< may be NUL */ + unsigned int 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 */ +}; + +/** \ingroup popt + * A popt alias argument for poptAddAlias(). + */ +struct poptAlias { +/*@owned@*/ /*@null@*/ + const char * longName; /*!< may be NULL */ + char shortName; /*!< may be NUL */ + int argc; +/*@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. */ +} * poptItem; +/*@=exporttype@*/ + +/** \ingroup popt + * \name Auto-generated help/usage + */ +/*@{*/ + +/** + * Empty table marker to enable displaying popt alias/exec options. + */ +/*@-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. + */ +/*@-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 }, + +#define POPT_TABLEEND { NULL, '\0', 0, NULL, 0, NULL, NULL } +/*@}*/ + +/** \ingroup popt + */ +/*@-exporttype@*/ +typedef /*@abstract@*/ struct poptContext_s * poptContext; +/*@=exporttype@*/ + +/** \ingroup popt + */ +#ifndef __cplusplus +/*@-exporttype -typeuse@*/ +typedef struct poptOption * poptOption; +/*@=exporttype =typeuse@*/ +#endif + +/** \ingroup popt + */ +/*@-exportconst@*/ +enum poptCallbackReason { + POPT_CALLBACK_REASON_PRE = 0, + POPT_CALLBACK_REASON_POST = 1, + POPT_CALLBACK_REASON_OPTION = 2 +}; +/*@=exportconst@*/ + +#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) + /*@globals internalState @*/ + /*@modifies internalState @*/; + +/** \ingroup popt + * Destroy context. + * @param con context + * @return NULL always + */ +/*@null@*/ +poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Initialize popt context. + * @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( + /*@dependent@*/ /*@keep@*/ const char * name, + int argc, /*@dependent@*/ /*@keep@*/ const char ** argv, + /*@dependent@*/ /*@keep@*/ const struct poptOption * options, + unsigned int flags) + /*@globals internalState @*/ + /*@modifies internalState @*/; + +/** \ingroup popt + * Destroy context (alternative implementation). + * @param con context + * @return NULL always + */ +/*@null@*/ +poptContext poptFini( /*@only@*/ /*@null@*/ poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Initialize popt context (alternative implementation). + * This routine does poptGetContext() and then poptReadConfigFiles(). + * @param argc no. of arguments + * @param argv argument array + * @param options address of popt option table + * @param configPaths colon separated file path(s) to read. + * @return initialized popt context (NULL on error). + */ +/*@only@*/ /*@null@*/ /*@unused@*/ +poptContext poptInit(int argc, /*@dependent@*/ /*@keep@*/ const char ** argv, + /*@dependent@*/ /*@keep@*/ const struct poptOption * options, + /*@null@*/ const char * configPaths) + /*@globals fileSystem, internalState @*/ + /*@modifies fileSystem, internalState @*/; + +/** \ingroup popt + * Reinitialize popt context. + * @param con context + */ +/*@unused@*/ +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, internalState @*/ + /*@modifies con, fileSystem, internalState @*/; + +/** \ingroup popt + * Return next option argument (if any). + * @param con context + * @return option argument, NULL if no argument is available + */ +/*@observer@*/ /*@null@*/ /*@unused@*/ +char * poptGetOptArg(/*@null@*/poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Return next argument. + * @param con context + * @return next argument, NULL if no argument is available + */ +/*@observer@*/ /*@null@*/ /*@unused@*/ +const char * poptGetArg(/*@null@*/poptContext con) + /*@modifies con @*/; + +/** \ingroup popt + * Peek at current argument. + * @param con context + * @return current argument, NULL if no argument is available + */ +/*@observer@*/ /*@null@*/ /*@unused@*/ +const char * poptPeekArg(/*@null@*/poptContext con) + /*@*/; + +/** \ingroup popt + * Return remaining arguments. + * @param con context + * @return argument array, NULL terminated + */ +/*@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, unsigned int flags) + /*@*/; + +/** \ingroup popt + * Add arguments to context. + * @param con context + * @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 @*/; + +/** \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 newItem 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 + * Perform sanity checks on a file path. + * @param fn file name + * @return 0 on OK, 1 on NOTOK. + */ +int poptSaneFile(const char * fn) + /*@globals errno, internalState @*/ + /*@modifies errno, internalState @*/; + +/** + * Read a file into a buffer. + * @param fn file name + * @retval *bp buffer (malloc'd) (or NULL) + * @retval *nbp no. of bytes in buffer (including final NUL) (or NULL) + * @param flags 1 to trim escaped newlines + * return 0 on success + */ +int poptReadFile(const char * fn, /*@null@*/ /*@out@*/ char ** bp, + /*@null@*/ /*@out@*/ size_t * nbp, int flags) + /*@globals errno, fileSystem, internalState @*/ + /*@modifies *bp, *nbp, errno, fileSystem, internalState @*/; +#define POPT_READFILE_TRIMNEWLINES 1 + +/** \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 errno, fileSystem, internalState @*/ + /*@modifies con->execs, con->numExecs, + errno, fileSystem, internalState @*/; + +/** \ingroup popt + * Read configuration file(s). + * Colon separated files to read, looping over poptReadConfigFile(). + * Note that an '@' character preceeding a path in the list will + * also perform additional sanity checks on the file before reading. + * @param con context + * @param paths colon separated file name(s) to read + * @return 0 on success, POPT_ERROR_BADCONFIG on failure + */ +int poptReadConfigFiles(poptContext con, /*@null@*/ const char * paths) + /*@globals errno, fileSystem, internalState @*/ + /*@modifies con->execs, con->numExecs, + errno, fileSystem, internalState @*/; + +/** \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 + */ +/*@unused@*/ +int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv) + /*@globals fileSystem, internalState @*/ + /*@modifies con->execs, con->numExecs, + fileSystem, internalState @*/; + +/** \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) + /*@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 + */ +/*@observer@*/ +const char * poptStrerror(const int error) + /*@*/; + +/** \ingroup popt + * Limit search for executables. + * @param con context + * @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 @*/; + +/** \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] + */ +/*@-fcnuse@*/ +/*@observer@*/ +const char * poptGetInvocationName(poptContext con) + /*@*/; +/*@=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@*/ + +/** + * Add a string to an argv array. + * @retval *argvp argv array + * @param argInfo (unused) + * @param val string arg to add (using strdup) + * @return 0 always + */ +/*@unused@*/ +int poptSaveString(/*@null@*/ const char *** argvp, unsigned int argInfo, + const char * val) + /*@modifies *argvp @*/; + +/** + * Save a long 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 aLongLong value to use + * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION + */ +/*@-incondefs@*/ +/*@unused@*/ +int poptSaveLongLong(/*@null@*/ long long * arg, unsigned int argInfo, + long long aLongLong) + /*@globals internalState @*/ + /*@modifies *arg, internalState @*/ + /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/; +/*@=incondefs@*/ + +/** + * 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, unsigned int argInfo, long aLong) + /*@globals internalState @*/ + /*@modifies *arg, internalState @*/ + /*@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, unsigned int argInfo, long aLong) + /*@globals internalState @*/ + /*@modifies *arg, internalState @*/ + /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/; +/*@=incondefs@*/ + +/*@=type@*/ +#ifdef __cplusplus +} +#endif + +#endif diff --git a/mingw/lib/libpopt.a b/mingw/lib/libpopt.a new file mode 100644 index 0000000000000000000000000000000000000000..65556bed001eb7de45e862cefdbc4d003dca3ae2 GIT binary patch literal 41550 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 +.sp +.BI "poptContext poptGetContext(const char * " name ", int " argc , +.BI " const char ** "argv , +.BI " const struct poptOption * " options , +.BI " int " flags ); +.sp +.BI "void poptFreeContext(poptContext " con ); +.sp +.BI "void poptResetContext(poptContext " con ); +.sp +.BI "int poptGetNextOpt(poptContext " con ); +.sp +.BI "const char * poptGetOptArg(poptContext " con ); +.sp +.BI "const char * poptGetArg(poptContext " con ); +.sp +.BI "const char * poptPeekArg(poptContext " con ); +.sp +.BI "const char ** poptGetArgs(poptContext " con ); +.sp +.BI "const char *const poptStrerror(const int " error ); +.sp +.BI "const char * poptBadOption(poptContext " con ", int " flags ); +.sp +.BI "int poptReadDefaultConfig(poptContext " con ", int " flags ); +.sp +.BI "int poptReadConfigFile(poptContext " con ", char * " fn ); +.sp +.BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias , +.BI " int " flags ); +.sp +.BI "int poptParseArgvString(char * " s ", int * " argcPtr , +.BI " const char *** " argvPtr ); +.sp +.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ", +.BI " const char *** " argvPtr ");" +.sp +.BI "int poptStuffArgs(poptContext " con ", const char ** " argv ); +.sp +.fi +.SH DESCRIPTION +The popt library exists essentially for parsing command-line +options. It is found superior in many ways when compared to +parsing the argv array by hand or using the getopt functions +.B getopt() +and +.B getopt_long() +[see +.BR getopt "(3)]." +Some specific advantages of popt are: it does not utilize global +.RI "variables, thus enabling multiple passes in parsing " argv +.RI "; it can parse an arbitrary array of " argv "-style elements, " +allowing parsing of command-line-strings from any source; +it provides a standard method of option aliasing (to be +discussed at length below.); it can exec external option filters; and, +finally, it can automatically generate help and usage messages for +the application. +.sp +Like +.BR getopt_long() , +the popt library supports short and long style options. Recall +that a +.B short option +consists of a - character followed by a single alphanumeric character. +A +.BR "long option" , +common in GNU utilities, consists of two - characters followed by a +string made up of letters, numbers and hyphens. Long options are +optionally allowed to begin with a single -, primarily to allow command-line +compatibility between popt applications and X toolkit applications. +Either type of option may be followed by an argument. A space separates a +short option from its arguments; either a space or an = separates a long +option from an argument. +.sp +The popt library is highly portable and should work on any POSIX +platform. The latest version is distributed with rpm and is always available +from: ftp://ftp.rpm.org/pub/rpm/dist. +.sp +It may be redistributed under the X consortium license, see the file COPYING +in the popt source distribution for details. +.SH "BASIC POPT USAGE" +.SS "1. THE OPTION TABLE" +Applications provide popt with information on their command-line +options by means of an "option table," i.e., an array of +.B struct poptOption +structures: +.sp +#include +.sp +.nf +struct poptOption { + const char * longName; /* may be NULL */ + char shortName; /* may be '\\0' */ + int argInfo; + void * arg; /* depends on argInfo */ + int val; /* 0 means don't return, just update flag */ + char * descrip; /* description for autohelp -- may be NULL */ + char * argDescrip; /* argument description for autohelp */ +}; +.fi +.sp +Each member of the table defines a single option that may be +passed to the program. Long and short options are considered +a single option that may occur in two different forms. The +first two members, +.IR longName " and " shortName ", define the names of the option;" +the first is a long name, while the latter is a single character. +.sp +The +.IR argInfo " member tells popt what type of argument is expected" +after the option. If no argument is expected, +.B POPT_ARG_NONE +should be used. +The rest of the valid values are shown in the following table: +.sp +.TS +lfB lfB lfB +lfB lfR lfR. +Value Description arg Type +POPT_ARG_NONE No argument expected int +POPT_ARG_STRING No type checking to be performed char * +POPT_ARG_ARGV No type checking to be performed char ** +POPT_ARG_INT An integer argument is expected int +POPT_ARG_LONG A long integer is expected long +POPT_ARG_LONGLONG A long long integer is expected long long +POPT_ARG_VAL Integer value taken from \f(CWval\fR int +POPT_ARG_FLOAT An float argument is expected float +POPT_ARG_DOUBLE A double argument is expected double +.TE +.sp +For numeric values, if the \fIargInfo\fR value is bitwise or'd with one of +\fBPOPT_ARGFLAG_OR\fR, \fBPOPT_ARGFLAG_AND\fR, or \fBPOPT_ARGFLAG_XOR\fR, +the value is saved by performing an OR, AND, or XOR. +If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_NOT\fR, +the value will be negated before saving. For the common operations of +setting and/or clearing bits, \fBPOPT_BIT_SET\fR and \fBPOPT_BIT_CLR\fR +have the appropriate flags set to perform bit operations. +.sp +If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_ONEDASH\fR, +the long argument may be given with a single - instead of two. For example, +if \fB--longopt\fR is an option with \fBPOPT_ARGFLAG_ONEDASH\fR, is +specified, \fB-longopt\fR is accepted as well. +.sp +.RI "The next element, " arg ", allows popt to automatically update " +.RI "program variables when the option is used. If " arg " is " +.BR NULL ", it is ignored and popt takes no special action. " +Otherwise it should point to a variable of the type indicated in the +.RB "right-most column of the table above. A " POPT_ARG_ARGV " arg will +(re-)allocate an array of char * string pointers, append the string argument, and add a +.BR NULL " sentinel at the end of the array as needed." +.RB "The target char ** address of a " POPT_ARG_ARGV " arg should be initialized to " NULL "." +.sp +.RI "If the option takes no argument (" argInfo " is " +.BR POPT_ARG_NONE "), the variable pointed to by " +.IR arg " is set to 1 when the option is used. (Incidentally, it " +will perhaps not escape the attention of hunt-and-peck typists that +.RB "the value of " POPT_ARG_NONE " is 0.) If the option does take " +an argument, the variable that +.IR arg " points to is updated to reflect the value of the argument." +.RB "Any string is acceptable for " POPT_ARG_STRING " and " POPT_ARG_ARGV " arguments, but " +.BR POPT_ARG_INT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", " POPT_ARG_FLOAT ", and " +.BR POPT_ARG_DOUBLE " are converted to the appropriate type, and an " +error returned if the conversion fails. +.sp +\fBPOPT_ARG_VAL\fR causes \fIarg\fP to be set to the (integer) value of +\fIval\fP when the argument is found. This is most often useful for +mutually-exclusive arguments in cases where it is not an error for +multiple arguments to occur and where you want the last argument +specified to win; for example, "rm -i -f". \fBPOPT_ARG_VAL\fP causes +the parsing function not to return a value, since the value of \fIval\fP +has already been used. +.sp +If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_OPTIONAL\fR, +the argument to the long option may be omitted. If the long option +is used without an argument, a default value of zero or NULL will be saved +(if the arg pointer is present), otherwise behavior will be identical to +a long option with argument. +.sp +.RI "The next option, " val ", is the value popt's parsing function +should return when the option is encountered. If it is 0, the parsing +function does not return a value, instead parsing the next +command-line argument. +.sp +.RI "The last two options, " descrip " and " argDescrip " are only required +if automatic help messages are desired (automatic usage messages can +.RI "be generated without them). " descrip " is a text description of the +.RI "argument and " argdescrip " is a short summary of the type of arguments +.RI "the option expects, or NULL if the option doesn't require any +arguments. +.sp +.RB "If popt should automatically provide " --usage " and " --help " (" -? ") +.RB "options, one line in the table should be the macro " POPT_AUTOHELP ". +.RB "This macro includes another option table (via " POPT_ARG_INCLUDE_TABLE +; see below) in the main one which provides the table entries for these +.RB "arguments. When " --usage " or " --help " are passed to programs which +use popt's automatical help, popt displays the appropriate message on +stderr as soon as it finds the option, and exits the program with a +return code of 0. If you want to use popt's automatic help generation in +a different way, you need to explicitly add the option entries to your programs +.RB "option table instead of using " POPT_AUTOHELP ". +.sp +If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_DOC_HIDDEN\fR, +the argument will not be shown in help output. +.sp +If the \fIargInfo\fR value is bitwise or'd with \fBPOPT_ARGFLAG_SHOW_DEFAULT\fR, +the inital value of the arg will be shown in help output. +.sp +The final structure in the table should have all the pointer values set +.RB "to " NULL " and all the arithmetic values set to 0, marking the " +.RB "end of the table. The macro " POPT_TABLEEND " is provided to do that. +.sp +There are two types of option table entries which do not specify command +line options. When either of these types of entries are used, the +\fIlongName\fR element must be \fBNULL\fR and the \fBshortName\fR element +must be \fB'\\0'\fR. +.sp +The first of these special entry types allows the application to nest +another option table in the current one; such nesting may extend quite +deeply (the actual depth is limited by the program's stack). Including +other option tables allows a library to provide a standard set of +command-line options to every program which uses it (this is often done +in graphical programming toolkits, for example). To do this, set +the \fIargInfo\fR field to \fBPOPT_ARG_INCLUDE_TABLE\fR and the +\fRarg\fR field to point to the table which is being included. If +automatic help generation is being used, the \fIdescrip\fR field should +contain a overall description of the option table being included. +.sp +The other special option table entry type tells popt to call a function (a +callback) when any option in that table is found. This is especially usefull +when included option tables are being used, as the program which provides +the top-level option table doesn't need to be aware of the other options +which are provided by the included table. When a callback is set for +a table, the parsing function never returns information on an option in +the table. Instead, options information must be retained via the callback +or by having popt set a variable through the option's \fIarg\fR field. +Option callbacks should match the following prototype: +.sp +.nf +.BI "void poptCallbackType(poptContext con, +.BI " const struct poptOption * opt, +.BI " const char * arg, void * data); +.fi +.sp +The first parameter is the context which is being parsed (see the next +section for information on contexts), \fIopt\fR points to the option +which triggered this callback, and \fIarg\fR is the option's argument. +If the option does not take an argument, \fIarg\fR is \fBNULL\fR. The +final parameter, \fIdata\fR is taken from the \fIdescrip\fR field +of the option table entry which defined the callback. As \fIdescrip\fR +is a pointer, this allows callback functions to be passed an arbitrary +set of data (though a typecast will have to be used). +.sp +The option table entry which defines a callback has an \fIargInfo\fR of +\fBPOPT_ARG_CALLBACK\fR, an \fIarg\fR which points to the callback +function, and a \fIdescrip\fR field which specifies an arbitrary pointer +to be passed to the callback. +.SS "2. CREATING A CONTEXT" +popt can interleave the parsing of multiple command-line sets. It allows +this by keeping all the state information for a particular set of +command-line arguments in a +.BR poptContext " data structure, an opaque type that should not be " +modified outside the popt library. +.sp +.RB "New popt contexts are created by " poptGetContext() ":" +.sp +.nf +.BI "poptContext poptGetContext(const char * " name ", int "argc ", +.BI " const char ** "argv ", +.BI " const struct poptOption * "options ", +.BI " int "flags ");" +.fi +.sp +The first parameter, +.IR name ", is used only for alias handling (discussed later). It " +should be the name of the application whose options are being parsed, +.RB "or should be " NULL " if no option aliasing is desired. The next " +two arguments specify the command-line arguments to parse. These are +.RB "generally passed to " poptGetContext() " exactly as they were " +.RB "passed to the program's " main() " function. The " +.IR options " parameter points to the table of command-line options, " +which was described in the previous section. The final parameter, +.IR flags , +can take one of three values: +.br +.TS +lfB lfB +lfB lfR. +Value Description +POPT_CONTEXT_NO_EXEC Ignore exec expansions +POPT_CONTEXT_KEEP_FIRST Do not ignore argv[0] +POPT_CONTEXT_POSIXMEHARDER Options cannot follow arguments +.TE +.sp +.RB "A " poptContext " keeps track of which options have already been " +parsed and which remain, among other things. If a program wishes to +restart option processing of a set of arguments, it can reset the +.BR poptContext " by passing the context as the sole argument to " +.BR poptResetContext() . +.sp +When argument processing is complete, the process should free the +.BR poptContext " as it contains dynamically allocated components. The " +.BR poptFreeContext() " function takes a " +.BR poptContext " as its sole argument and frees the resources the " +context is using. +.sp +.RB "Here are the prototypes of both " poptResetContext() " and " +.BR poptFreeContext() : +.sp +.nf +.B #include +.BI "void poptFreeContext(poptContext " con ");" +.BI "void poptResetContext(poptContext " con ");" +.fi +.sp +.SS "3. PARSING THE COMMAND LINE" +.RB "After an application has created a " poptContext ", it may begin " +.RB "parsing arguments. " poptGetNextOpt() " performs the actual " +argument parsing. +.sp +.nf +.B #include +.BI "int poptGetNextOpt(poptContext " con ");" +.fi +.sp +Taking the context as its sole argument, this function parses the next +command-line argument found. After finding the next argument in the +option table, the function fills in the object pointed to by the option +.RI "table entry's " arg +.RB "pointer if it is not " NULL ". If the val entry for the option is " +non-0, the function then returns that value. Otherwise, +.BR poptGetNextOpt() " continues on to the next argument." +.sp +.BR poptGetNextOpt() " returns -1 when the final argument has been " +parsed, and other negative values when errors occur. This makes it a +good idea to +.RI "keep the " val " elements in the options table greater than 0." +.sp +.RI "If all of the command-line options are handled through " arg +pointers, command-line parsing is reduced to the following line of code: +.sp +.nf +rc = poptGetNextOpt(poptcon); +.fi +.sp +Many applications require more complex command-line parsing than this, +however, and use the following structure: +.sp +.nf +while ((rc = poptGetNextOpt(poptcon)) > 0) { + switch (rc) { + /* specific arguments are handled here */ + } +} +.fi +.sp +When returned options are handled, the application needs to know the +value of any arguments that were specified after the option. There are two +ways to discover them. One is to ask popt to fill in a variable with the +.RI "value of the option through the option table's " arg " elements. The " +.RB "other is to use " poptGetOptArg() ":" +.sp +.nf +.B #include +.BI "char * poptGetOptArg(poptContext " con ");" +.fi +.sp +This function returns the argument given for the final option returned by +.BR poptGetNextOpt() ", or it returns " NULL " if no argument was specified." +The calling function is responsible for deallocating this string. +.sp +.SS "4. LEFTOVER ARGUMENTS" +Many applications take an arbitrary number of command-line arguments, +such as a list of file names. When popt encounters an argument that does +not begin with a -, it assumes it is such an argument and adds it to a list +of leftover arguments. Three functions allow applications to access such +arguments: +.nf +.HP +.BI "const char * poptGetArg(poptContext " con ");" +.fi +This function returns the next leftover argument and marks it as +processed. +.PP +.nf +.HP +.BI "const char * poptPeekArg(poptContext " con ");" +.fi +The next leftover argument is returned but not marked as processed. +This allows an application to look ahead into the argument list, +without modifying the list. +.PP +.nf +.HP +.BI "const char ** poptGetArgs(poptContext " con ");" +.fi +All the leftover arguments are returned in a manner identical to +.IR argv ". The final element in the returned array points to " +.BR NULL ", indicating the end of the arguments. +.sp +.SS "5. AUTOMATIC HELP MESSAGES" +The \fBpopt\fR library can automatically generate help messages which +describe the options a program accepts. There are two types of help +messages which can be generated. Usage messages are a short messages +which lists valid options, but does not describe them. Help messages +describe each option on one (or more) lines, resulting in a longer, but +more useful, message. Whenever automatic help messages are used, the +\fBdescrip\fR and \fBargDescrip\fR fields \fBstruct poptOption\fR members +should be filled in for each option. +.sp +The \fBPOPT_AUTOHELP\fR macro makes it easy to add \fB--usage\fR and +\fB--help\fR messages to your program, and is described in part 1 +of this man page. If more control is needed over your help messages, +the following two functions are available: +.sp +.nf +.B #include +.BI "void poptPrintHelp(poptContext " con ", FILE * " f ", int " flags "); +.BI "void poptPrintUsage(poptContext " con ", FILE * " f ", int " flags "); +.fi +.sp +\fBpoptPrintHelp()\fR displays the standard help message to the stdio file +descriptor f, while \fBpoptPrintUsage()\fR displays the shorter usage +message. Both functions currently ignore the \fBflags\fR argument; it is +there to allow future changes. +.sp +.SH "ERROR HANDLING" +All of the popt functions that can return errors return integers. +When an error occurs, a negative error code is returned. The +following table summarizes the error codes that occur: +.sp +.nf +.B " Error Description" +.BR "POPT_ERROR_NOARG " "Argument missing for an option." +.BR "POPT_ERROR_BADOPT " "Option's argument couldn't be parsed." +.BR "POPT_ERROR_OPTSTOODEEP " "Option aliasing nested too deeply." +.BR "POPT_ERROR_BADQUOTE " "Quotations do not match." +.BR "POPT_ERROR_BADNUMBER " "Option couldn't be converted to number." +.BR "POPT_ERROR_OVERFLOW " "A given number was too big or small." +.fi +.sp +Here is a more detailed discussion of each error: +.sp +.TP +.B POPT_ERROR_NOARG +An option that requires an argument was specified on the command +line, but no argument was given. This can be returned only by +.BR poptGetNextOpt() . +.sp +.TP +.B POPT_ERROR_BADOPT +.RI "An option was specified in " argv " but is not in the option +.RB "table. This error can be returned only from " poptGetNextOpt() . +.sp +.TP +.B POPT_ERROR_OPTSTOODEEP +A set of option aliases is nested too deeply. Currently, popt +follows options only 10 levels to prevent infinite recursion. Only +.BR poptGetNextOpt() " can return this error." +.sp +.TP +.B POPT_ERROR_BADQUOTE +A parsed string has a quotation mismatch (such as a single quotation +.RB "mark). " poptParseArgvString() ", " poptReadConfigFile() ", or " +.BR poptReadDefaultConfig() " can return this error." +.sp +.TP +.B POPT_ERROR_BADNUMBER +A conversion from a string to a number (int or long) failed due +to the string containing nonnumeric characters. This occurs when +.BR poptGetNextOpt() " is processing an argument of type " +.BR POPT_ARG_INT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", " +.RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "." +.sp +.TP +.B POPT_ERROR_OVERFLOW +A string-to-number conversion failed because the number was too +.RB "large or too small. Like " POPT_ERROR_BADNUMBER ", this error +.RB "can occur only when " poptGetNextOpt() " is processing an " +.RB "argument of type " POPT_ARG_INT ", " POPT_ARG_LONG ", " POPT_ARG_LONGLONG ", " +.RB POPT_ARG_FLOAT ", or " POPT_ARG_DOUBLE "." +.sp +.TP +.B POPT_ERROR_ERRNO +.RI "A system call returned with an error, and " errno " still +contains the error from the system call. Both +.BR poptReadConfigFile() " and " poptReadDefaultConfig() " can " +return this error. +.sp +.PP +Two functions are available to make it easy for applications to provide +good error messages. +.HP +.nf +.BI "const char *const poptStrerror(const int " error ");" +.fi +This function takes a popt error code and returns a string describing +.RB "the error, just as with the standard " strerror() " function." +.PP +.HP +.nf +.BI "const char * poptBadOption(poptContext " con ", int " flags ");" +.fi +.RB "If an error occurred during " poptGetNextOpt() ", this function " +.RI "returns the option that caused the error. If the " flags " argument" +.RB "is set to " POPT_BADOPTION_NOALIAS ", the outermost option is " +.RI "returned. Otherwise, " flags " should be 0, and the option that is " +returned may have been specified through an alias. +.PP +These two functions make popt error handling trivial for most +applications. When an error is detected from most of the functions, +an error message is printed along with the error string from +.BR poptStrerror() ". When an error occurs during argument parsing, " +code similiar to the following displays a useful error message: +.sp +.nf +fprintf(stderr, "%s: %s\\n", + poptBadOption(optCon, POPT_BADOPTION_NOALIAS), + poptStrerror(rc)); +.fi +.sp +.SH "OPTION ALIASING" +.RB "One of the primary benefits of using popt over " getopt() " is the " +ability to use option aliasing. This lets the user specify options that +popt expands into other options when they are specified. If the standard +.RB "grep program made use of popt, users could add a " --text " option " +.RB "that expanded to " "-i -n -E -2" " to let them more easily find " +information in text files. +.sp +.SS "1. SPECIFYING ALIASES" +.RI "Aliases are normally specified in two places: " /etc/popt +.RB "and the " .popt " file in the user's home directory (found through " +.RB "the " HOME " environment variable). Both files have the same format, " +an arbitrary number of lines formatted like this: +.sp +.IB appname " alias " newoption "" " expansion" +.sp +.RI "The " appname " is the name of the application, which must be the " +.RI "same as the " name " parameter passed to " +.BR poptGetContext() ". This allows each file to specify aliases for " +.RB "multiple programs. The " alias " keyword specifies that an alias is " +being defined; currently popt configuration files support only aliases, but +other abilities may be added in the future. The next option is the option +that should be aliased, and it may be either a short or a long option. The +rest of the line specifies the expansion for the alias. It is parsed +similarly to a shell command, which allows \\, ", and ' to be used for +quoting. If a backslash is the final character on a line, the next line +in the file is assumed to be a logical continuation of the line containing +the backslash, just as in shell. +.sp +.RB "The following entry would add a " --text " option to the grep command, " +as suggested at the beginning of this section. +.sp +.B "grep alias --text -i -n -E -2" +.SS "2. ENABLING ALIASES" +.RB "An application must enable alias expansion for a " poptContext +.RB "before calling " poptGetNextArg() " for the first time. There are " +three functions that define aliases for a context: +.HP +.nf +.BI "int poptReadDefaultConfig(poptContext " con ", int " flags ");" +.fi +.RI "This function reads aliases from " /etc/popt " and the " +.BR .popt " file in the user's home directory. Currently, " +.IR flags " should be " +.BR NULL ", as it is provided only for future expansion." +.PP +.HP +.nf +.BI "int poptReadConfigFile(poptContext " con ", char * " fn ");" +.fi +.RI "The file specified by " fn " is opened and parsed as a popt " +configuration file. This allows programs to use program-specific +configuration files. +.PP +.HP +.nf +.BI "int poptAddAlias(poptContext " con ", struct poptAlias " alias ", +.BI " int " flags ");" +.fi +Occasionally, processes want to specify aliases without having to +read them from a configuration file. This function adds a new alias +.RI "to a context. The " flags " argument should be 0, as it is " +currently reserved for future expansion. The new alias is specified +.RB "as a " "struct poptAlias" ", which is defined as:" +.sp +.nf +struct poptAlias { + const char * longName; /* may be NULL */ + char shortName; /* may be '\\0' */ + int argc; + const char ** argv; /* must be free()able */ +}; +.fi +.sp +.RI "The first two elements, " longName " and " shortName ", specify " +.RI "the option that is aliased. The final two, " argc " and " argv "," +define the expansion to use when the aliases option is encountered. +.PP +.SH "PARSING ARGUMENT STRINGS" +Although popt is usually used for parsing arguments already divided into +.RI "an " argv "-style array, some programs need to parse strings that " +are formatted identically to command lines. To facilitate this, popt +provides a function that parses a string into an array of strings, +using rules similiar to normal shell parsing. +.sp +.nf +.B "#include " +.BI "int poptParseArgvString(char * " s ", int * " argcPtr ", +.BI " char *** " argvPtr ");" +.BI "int poptDupArgv(int " argc ", const char ** " argv ", int * " argcPtr ", +.BI " const char *** " argvPtr ");" +.fi +.sp +.RI "The string s is parsed into an " argv "-style array. The integer " +.RI "pointed to by the " argcPtr " parameter contains the number of elements " +.RI "parsed, and the final " argvPtr " parameter contains the address of the" +newly created array. +.RB "The routine " poptDupArgv() " can be used to make a copy of an existing " +argument array. +.sp +.RI "The " argvPtr +.RB "created by " poptParseArgvString() " or " poptDupArgv() " is suitable to pass directly " +.RB "to " poptGetContext() . +Both routines return a single dynamically allocated contiguous +.RB "block of storage and should be " free() "ed when the application is" +finished with the storage. +.SH "HANDLING EXTRA ARGUMENTS" +Some applications implement the equivalent of option aliasing but need +.RB "to do so through special logic. The " poptStuffArgs() " function " +allows an application to insert new arguments into the current +.BR poptContext . +.sp +.nf +.B "#include " +.BI "int poptStuffArgs(poptContext "con ", const char ** " argv ");" +.fi +.sp +.RI "The passed " argv +.RB "must have a " NULL " pointer as its final element. When " +.BR poptGetNextOpt() " is next called, the " +"stuffed" arguments are the first to be parsed. popt returns to the +normal arguments once all the stuffed arguments have been exhausted. +.SH "EXAMPLE" +The following example is a simplified version of the program "robin" +which appears in Chapter 15 of the text cited below. Robin has +been stripped of everything but its argument-parsing logic, slightly +reworked, and renamed "parse." It may prove useful in illustrating +at least some of the features of the extremely rich popt library. +.sp +.nf +#include +#include + +void usage(poptContext optCon, int exitcode, char *error, char *addl) { + poptPrintUsage(optCon, stderr, 0); + if (error) fprintf(stderr, "%s: %s\n", error, addl); + exit(exitcode); +} + +int main(int argc, char *argv[]) { + char c; /* used for argument parsing */ + int i = 0; /* used for tracking options */ + char *portname; + int speed = 0; /* used in argument parsing to set speed */ + int raw = 0; /* raw mode? */ + int j; + char buf[BUFSIZ+1]; + poptContext optCon; /* context for parsing command-line options */ + + struct poptOption optionsTable[] = { + { "bps", 'b', POPT_ARG_INT, &speed, 0, + "signaling rate in bits-per-second", "BPS" }, + { "crnl", 'c', 0, 0, 'c', + "expand cr characters to cr/lf sequences", NULL }, + { "hwflow", 'h', 0, 0, 'h', + "use hardware (RTS/CTS) flow control", NULL }, + { "noflow", 'n', 0, 0, 'n', + "use no flow control", NULL }, + { "raw", 'r', 0, &raw, 0, + "don't perform any character conversions", NULL }, + { "swflow", 's', 0, 0, 's', + "use software (XON/XOF) flow control", NULL } , + POPT_AUTOHELP + { NULL, 0, 0, NULL, 0 } + }; + + optCon = poptGetContext(NULL, argc, argv, optionsTable, 0); + poptSetOtherOptionHelp(optCon, "[OPTIONS]* "); + + if (argc < 2) { + poptPrintUsage(optCon, stderr, 0); + exit(1); + } + + /* Now do options processing, get portname */ + while ((c = poptGetNextOpt(optCon)) >= 0) { + switch (c) { + case 'c': + buf[i++] = 'c'; + break; + case 'h': + buf[i++] = 'h'; + break; + case 's': + buf[i++] = 's'; + break; + case 'n': + buf[i++] = 'n'; + break; + } + } + portname = poptGetArg(optCon); + if((portname == NULL) || !(poptPeekArg(optCon) == NULL)) + usage(optCon, 1, "Specify a single port", ".e.g., /dev/cua0"); + + if (c < -1) { + /* an error occurred during option processing */ + fprintf(stderr, "%s: %s\\n", + poptBadOption(optCon, POPT_BADOPTION_NOALIAS), + poptStrerror(c)); + return 1; + } + + /* Print out options, portname chosen */ + printf("Options chosen: "); + for(j = 0; j < i ; j++) + printf("-%c ", buf[j]); + if(raw) printf("-r "); + if(speed) printf("-b %d ", speed); + printf("\\nPortname chosen: %s\\n", portname); + + poptFreeContext(optCon); + exit(0); +} +.fi +.sp +RPM, a popular Linux package management program, makes heavy use +of popt's features. Many of its command-line arguments are implemented +through popt aliases, which makes RPM an excellent example of how to +take advantage of the popt library. For more information on RPM, see +http://www.rpm.org. The popt source code distribution includes test +program(s) which use all of the features of the popt libraries in +various ways. If a feature isn't working for you, the popt test code +is the first place to look. +.SH BUGS +None presently known. +.SH AUTHOR +Erik W. Troan +.PP +This man page is derived in part from +.IR "Linux Application Development" +by Michael K. Johnson and Erik W. Troan, Copyright (c) 1998 by Addison +Wesley Longman, Inc., and included in the popt documentation with the +permission of the Publisher and the appreciation of the Authors. +.PP +Thanks to Robert Lynch for his extensive work on this man page. +.SH "SEE ALSO" +.BR getopt (3) +.sp +.IR "Linux Application Development" ", by Michael K. Johnson and " +Erik W. Troan (Addison-Wesley, 1998; ISBN 0-201-30821-5), Chapter 24. +.sp +.BR popt.ps " is a Postscript version of the above cited book " +chapter. It can be found in the source archive for popt available at: +ftp://ftp.rpm.org/pub/rpm. -- 2.11.4.GIT