| 1 | /** \file popt/popt.h
|
|---|
| 2 | * \ingroup popt
|
|---|
| 3 | */
|
|---|
| 4 |
|
|---|
| 5 | /* (C) 1998-2000 Red Hat, Inc. -- Licensing details are in the COPYING
|
|---|
| 6 | file accompanying popt source distributions, available from
|
|---|
| 7 | ftp://ftp.rpm.org/pub/rpm/dist. */
|
|---|
| 8 |
|
|---|
| 9 | #ifndef H_POPT
|
|---|
| 10 | #define H_POPT
|
|---|
| 11 |
|
|---|
| 12 | #include <stdio.h> /* for FILE * */
|
|---|
| 13 |
|
|---|
| 14 | #define POPT_OPTION_DEPTH 10
|
|---|
| 15 |
|
|---|
| 16 | /** \ingroup popt
|
|---|
| 17 | * \name Arg type identifiers
|
|---|
| 18 | */
|
|---|
| 19 | /*@{*/
|
|---|
| 20 | #define POPT_ARG_NONE 0 /*!< no arg */
|
|---|
| 21 | #define POPT_ARG_STRING 1 /*!< arg will be saved as string */
|
|---|
| 22 | #define POPT_ARG_INT 2 /*!< arg will be converted to int */
|
|---|
| 23 | #define POPT_ARG_LONG 3 /*!< arg will be converted to long */
|
|---|
| 24 | #define POPT_ARG_INCLUDE_TABLE 4 /*!< arg points to table */
|
|---|
| 25 | #define POPT_ARG_CALLBACK 5 /*!< table-wide callback... must be
|
|---|
| 26 | set first in table; arg points
|
|---|
| 27 | to callback, descrip points to
|
|---|
| 28 | callback data to pass */
|
|---|
| 29 | #define POPT_ARG_INTL_DOMAIN 6 /*!< set the translation domain
|
|---|
| 30 | for this table and any
|
|---|
| 31 | included tables; arg points
|
|---|
| 32 | to the domain string */
|
|---|
| 33 | #define POPT_ARG_VAL 7 /*!< arg should take value val */
|
|---|
| 34 | #define POPT_ARG_FLOAT 8 /*!< arg will be converted to float */
|
|---|
| 35 | #define POPT_ARG_DOUBLE 9 /*!< arg will be converted to double */
|
|---|
| 36 |
|
|---|
| 37 | #define POPT_ARG_MASK 0x0000FFFF
|
|---|
| 38 | /*@}*/
|
|---|
| 39 |
|
|---|
| 40 | /** \ingroup popt
|
|---|
| 41 | * \name Arg modifiers
|
|---|
| 42 | */
|
|---|
| 43 | /*@{*/
|
|---|
| 44 | #define POPT_ARGFLAG_ONEDASH 0x80000000 /*!< allow -longoption */
|
|---|
| 45 | #define POPT_ARGFLAG_DOC_HIDDEN 0x40000000 /*!< don't show in help/usage */
|
|---|
| 46 | #define POPT_ARGFLAG_STRIP 0x20000000 /*!< strip this arg from argv(only applies to long args) */
|
|---|
| 47 | #define POPT_ARGFLAG_OPTIONAL 0x10000000 /*!< arg may be missing */
|
|---|
| 48 |
|
|---|
| 49 | #define POPT_ARGFLAG_OR 0x08000000 /*!< arg will be or'ed */
|
|---|
| 50 | #define POPT_ARGFLAG_NOR 0x09000000 /*!< arg will be nor'ed */
|
|---|
| 51 | #define POPT_ARGFLAG_AND 0x04000000 /*!< arg will be and'ed */
|
|---|
| 52 | #define POPT_ARGFLAG_NAND 0x05000000 /*!< arg will be nand'ed */
|
|---|
| 53 | #define POPT_ARGFLAG_XOR 0x02000000 /*!< arg will be xor'ed */
|
|---|
| 54 | #define POPT_ARGFLAG_NOT 0x01000000 /*!< arg will be negated */
|
|---|
| 55 | #define POPT_ARGFLAG_LOGICALOPS \
|
|---|
| 56 | (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR)
|
|---|
| 57 |
|
|---|
| 58 | #define POPT_BIT_SET (POPT_ARG_VAL|POPT_ARGFLAG_OR)
|
|---|
| 59 | /*!< set arg bit(s) */
|
|---|
| 60 | #define POPT_BIT_CLR (POPT_ARG_VAL|POPT_ARGFLAG_NAND)
|
|---|
| 61 | /*!< clear arg bit(s) */
|
|---|
| 62 |
|
|---|
| 63 | #define POPT_ARGFLAG_SHOW_DEFAULT 0x00800000 /*!< show default value in --help */
|
|---|
| 64 |
|
|---|
| 65 | /*@}*/
|
|---|
| 66 |
|
|---|
| 67 | /** \ingroup popt
|
|---|
| 68 | * \name Callback modifiers
|
|---|
| 69 | */
|
|---|
| 70 | /*@{*/
|
|---|
| 71 | #define POPT_CBFLAG_PRE 0x80000000 /*!< call the callback before parse */
|
|---|
| 72 | #define POPT_CBFLAG_POST 0x40000000 /*!< call the callback after parse */
|
|---|
| 73 | #define POPT_CBFLAG_INC_DATA 0x20000000 /*!< use data from the include line,
|
|---|
| 74 | not the subtable */
|
|---|
| 75 | #define POPT_CBFLAG_SKIPOPTION 0x10000000 /*!< don't callback with option */
|
|---|
| 76 | #define POPT_CBFLAG_CONTINUE 0x08000000 /*!< continue callbacks with option */
|
|---|
| 77 | /*@}*/
|
|---|
| 78 |
|
|---|
| 79 | /** \ingroup popt
|
|---|
| 80 | * \name Error return values
|
|---|
| 81 | */
|
|---|
| 82 | /*@{*/
|
|---|
| 83 | #define POPT_ERROR_NOARG -10 /*!< missing argument */
|
|---|
| 84 | #define POPT_ERROR_BADOPT -11 /*!< unknown option */
|
|---|
| 85 | #define POPT_ERROR_OPTSTOODEEP -13 /*!< aliases nested too deeply */
|
|---|
| 86 | #define POPT_ERROR_BADQUOTE -15 /*!< error in parameter quoting */
|
|---|
| 87 | #define POPT_ERROR_ERRNO -16 /*!< errno set, use strerror(errno) */
|
|---|
| 88 | #define POPT_ERROR_BADNUMBER -17 /*!< invalid numeric value */
|
|---|
| 89 | #define POPT_ERROR_OVERFLOW -18 /*!< number too large or too small */
|
|---|
| 90 | #define POPT_ERROR_BADOPERATION -19 /*!< mutually exclusive logical operations requested */
|
|---|
| 91 | #define POPT_ERROR_NULLARG -20 /*!< opt->arg should not be NULL */
|
|---|
| 92 | #define POPT_ERROR_MALLOC -21 /*!< memory allocation failed */
|
|---|
| 93 | /*@}*/
|
|---|
| 94 |
|
|---|
| 95 | /** \ingroup popt
|
|---|
| 96 | * \name poptBadOption() flags
|
|---|
| 97 | */
|
|---|
| 98 | /*@{*/
|
|---|
| 99 | #define POPT_BADOPTION_NOALIAS (1 << 0) /*!< don't go into an alias */
|
|---|
| 100 | /*@}*/
|
|---|
| 101 |
|
|---|
| 102 | /** \ingroup popt
|
|---|
| 103 | * \name poptGetContext() flags
|
|---|
| 104 | */
|
|---|
| 105 | /*@{*/
|
|---|
| 106 | #define POPT_CONTEXT_NO_EXEC (1 << 0) /*!< ignore exec expansions */
|
|---|
| 107 | #define POPT_CONTEXT_KEEP_FIRST (1 << 1) /*!< pay attention to argv[0] */
|
|---|
| 108 | #define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /*!< options can't follow args */
|
|---|
| 109 | #define POPT_CONTEXT_ARG_OPTS (1 << 4) /*!< return args as options with value 0 */
|
|---|
| 110 | /*@}*/
|
|---|
| 111 |
|
|---|
| 112 | /** \ingroup popt
|
|---|
| 113 | */
|
|---|
| 114 | struct poptOption {
|
|---|
| 115 | /*@observer@*/ /*@null@*/
|
|---|
| 116 | const char * longName; /*!< may be NULL */
|
|---|
| 117 | char shortName; /*!< may be '\0' */
|
|---|
| 118 | int argInfo;
|
|---|
| 119 | /*@shared@*/ /*@null@*/
|
|---|
| 120 | void * arg; /*!< depends on argInfo */
|
|---|
| 121 | int val; /*!< 0 means don't return, just update flag */
|
|---|
| 122 | /*@observer@*/ /*@null@*/
|
|---|
| 123 | const char * descrip; /*!< description for autohelp -- may be NULL */
|
|---|
| 124 | /*@observer@*/ /*@null@*/
|
|---|
| 125 | const char * argDescrip; /*!< argument description for autohelp */
|
|---|
| 126 | };
|
|---|
| 127 |
|
|---|
| 128 | /** \ingroup popt
|
|---|
| 129 | * A popt alias argument for poptAddAlias().
|
|---|
| 130 | */
|
|---|
| 131 | struct poptAlias {
|
|---|
| 132 | /*@owned@*/ /*@null@*/
|
|---|
| 133 | const char * longName; /*!< may be NULL */
|
|---|
| 134 | char shortName; /*!< may be '\0' */
|
|---|
| 135 | int argc;
|
|---|
| 136 | /*@owned@*/
|
|---|
| 137 | const char ** argv; /*!< must be free()able */
|
|---|
| 138 | };
|
|---|
| 139 |
|
|---|
| 140 | /** \ingroup popt
|
|---|
| 141 | * A popt alias or exec argument for poptAddItem().
|
|---|
| 142 | */
|
|---|
| 143 | /*@-exporttype@*/
|
|---|
| 144 | typedef struct poptItem_s {
|
|---|
| 145 | struct poptOption option; /*!< alias/exec name(s) and description. */
|
|---|
| 146 | int argc; /*!< (alias) no. of args. */
|
|---|
| 147 | /*@owned@*/
|
|---|
| 148 | const char ** argv; /*!< (alias) args, must be free()able. */
|
|---|
| 149 | } * poptItem;
|
|---|
| 150 | /*@=exporttype@*/
|
|---|
| 151 |
|
|---|
| 152 | /** \ingroup popt
|
|---|
| 153 | * \name Auto-generated help/usage
|
|---|
| 154 | */
|
|---|
| 155 | /*@{*/
|
|---|
| 156 |
|
|---|
| 157 | /**
|
|---|
| 158 | * Empty table marker to enable displaying popt alias/exec options.
|
|---|
| 159 | */
|
|---|
| 160 | /*@-exportvar@*/
|
|---|
| 161 | /*@unchecked@*/ /*@observer@*/
|
|---|
| 162 | extern struct poptOption poptAliasOptions[];
|
|---|
| 163 | /*@=exportvar@*/
|
|---|
| 164 | #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
|
|---|
| 165 | 0, "Options implemented via popt alias/exec:", NULL },
|
|---|
| 166 |
|
|---|
| 167 | /**
|
|---|
| 168 | * Auto help table options.
|
|---|
| 169 | */
|
|---|
| 170 | /*@-exportvar@*/
|
|---|
| 171 | /*@unchecked@*/ /*@observer@*/
|
|---|
| 172 | extern struct poptOption poptHelpOptions[];
|
|---|
| 173 | /*@=exportvar@*/
|
|---|
| 174 | #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
|
|---|
| 175 | 0, "Help options:", NULL },
|
|---|
| 176 |
|
|---|
| 177 | #define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
|
|---|
| 178 | /*@}*/
|
|---|
| 179 |
|
|---|
| 180 | /** \ingroup popt
|
|---|
| 181 | */
|
|---|
| 182 | /*@-exporttype@*/
|
|---|
| 183 | typedef /*@abstract@*/ struct poptContext_s * poptContext;
|
|---|
| 184 | /*@=exporttype@*/
|
|---|
| 185 |
|
|---|
| 186 | /** \ingroup popt
|
|---|
| 187 | */
|
|---|
| 188 | #ifndef __cplusplus
|
|---|
| 189 | /*@-exporttype -typeuse@*/
|
|---|
| 190 | typedef struct poptOption * poptOption;
|
|---|
| 191 | /*@=exporttype =typeuse@*/
|
|---|
| 192 | #endif
|
|---|
| 193 |
|
|---|
| 194 | /*@-exportconst@*/
|
|---|
| 195 | enum poptCallbackReason {
|
|---|
| 196 | POPT_CALLBACK_REASON_PRE = 0,
|
|---|
| 197 | POPT_CALLBACK_REASON_POST = 1,
|
|---|
| 198 | POPT_CALLBACK_REASON_OPTION = 2
|
|---|
| 199 | };
|
|---|
| 200 | /*@=exportconst@*/
|
|---|
| 201 |
|
|---|
| 202 | #ifdef __cplusplus
|
|---|
| 203 | extern "C" {
|
|---|
| 204 | #endif
|
|---|
| 205 | /*@-type@*/
|
|---|
| 206 |
|
|---|
| 207 | /** \ingroup popt
|
|---|
| 208 | * Table callback prototype.
|
|---|
| 209 | * @param con context
|
|---|
| 210 | * @param reason reason for callback
|
|---|
| 211 | * @param opt option that triggered callback
|
|---|
| 212 | * @param arg @todo Document.
|
|---|
| 213 | * @param data @todo Document.
|
|---|
| 214 | */
|
|---|
| 215 | typedef void (*poptCallbackType) (poptContext con,
|
|---|
| 216 | enum poptCallbackReason reason,
|
|---|
| 217 | /*@null@*/ const struct poptOption * opt,
|
|---|
| 218 | /*@null@*/ const char * arg,
|
|---|
| 219 | /*@null@*/ const void * data)
|
|---|
| 220 | /*@*/;
|
|---|
| 221 |
|
|---|
| 222 | /** \ingroup popt
|
|---|
| 223 | * Initialize popt context.
|
|---|
| 224 | * @param name context name (usually argv[0] program name)
|
|---|
| 225 | * @param argc no. of arguments
|
|---|
| 226 | * @param argv argument array
|
|---|
| 227 | * @param options address of popt option table
|
|---|
| 228 | * @param flags or'd POPT_CONTEXT_* bits
|
|---|
| 229 | * @return initialized popt context
|
|---|
| 230 | */
|
|---|
| 231 | /*@only@*/ /*@null@*/ poptContext poptGetContext(
|
|---|
| 232 | /*@dependent@*/ /*@keep@*/ const char * name,
|
|---|
| 233 | int argc, /*@dependent@*/ /*@keep@*/ const char ** argv,
|
|---|
| 234 | /*@dependent@*/ /*@keep@*/ const struct poptOption * options,
|
|---|
| 235 | int flags)
|
|---|
| 236 | /*@*/;
|
|---|
| 237 |
|
|---|
| 238 | /** \ingroup popt
|
|---|
| 239 | * Reinitialize popt context.
|
|---|
| 240 | * @param con context
|
|---|
| 241 | */
|
|---|
| 242 | /*@unused@*/
|
|---|
| 243 | void poptResetContext(/*@null@*/poptContext con)
|
|---|
| 244 | /*@modifies con @*/;
|
|---|
| 245 |
|
|---|
| 246 | /** \ingroup popt
|
|---|
| 247 | * Return value of next option found.
|
|---|
| 248 | * @param con context
|
|---|
| 249 | * @return next option val, -1 on last item, POPT_ERROR_* on error
|
|---|
| 250 | */
|
|---|
| 251 | int poptGetNextOpt(/*@null@*/poptContext con)
|
|---|
| 252 | /*@globals fileSystem, internalState @*/
|
|---|
| 253 | /*@modifies con, fileSystem, internalState @*/;
|
|---|
| 254 |
|
|---|
| 255 | /** \ingroup popt
|
|---|
| 256 | * Return next option argument (if any).
|
|---|
| 257 | * @param con context
|
|---|
| 258 | * @return option argument, NULL if no argument is available
|
|---|
| 259 | */
|
|---|
| 260 | /*@observer@*/ /*@null@*/ const char * poptGetOptArg(/*@null@*/poptContext con)
|
|---|
| 261 | /*@modifies con @*/;
|
|---|
| 262 |
|
|---|
| 263 | /** \ingroup popt
|
|---|
| 264 | * Return next argument.
|
|---|
| 265 | * @param con context
|
|---|
| 266 | * @return next argument, NULL if no argument is available
|
|---|
| 267 | */
|
|---|
| 268 | /*@observer@*/ /*@null@*/ const char * poptGetArg(/*@null@*/poptContext con)
|
|---|
| 269 | /*@modifies con @*/;
|
|---|
| 270 |
|
|---|
| 271 | /** \ingroup popt
|
|---|
| 272 | * Peek at current argument.
|
|---|
| 273 | * @param con context
|
|---|
| 274 | * @return current argument, NULL if no argument is available
|
|---|
| 275 | */
|
|---|
| 276 | /*@observer@*/ /*@null@*/ const char * poptPeekArg(/*@null@*/poptContext con)
|
|---|
| 277 | /*@*/;
|
|---|
| 278 |
|
|---|
| 279 | /** \ingroup popt
|
|---|
| 280 | * Return remaining arguments.
|
|---|
| 281 | * @param con context
|
|---|
| 282 | * @return argument array, NULL terminated
|
|---|
| 283 | */
|
|---|
| 284 | /*@observer@*/ /*@null@*/ const char ** poptGetArgs(/*@null@*/poptContext con)
|
|---|
| 285 | /*@modifies con @*/;
|
|---|
| 286 |
|
|---|
| 287 | /** \ingroup popt
|
|---|
| 288 | * Return the option which caused the most recent error.
|
|---|
| 289 | * @param con context
|
|---|
| 290 | * @param flags
|
|---|
| 291 | * @return offending option
|
|---|
| 292 | */
|
|---|
| 293 | /*@observer@*/ const char * poptBadOption(/*@null@*/poptContext con, int flags)
|
|---|
| 294 | /*@*/;
|
|---|
| 295 |
|
|---|
| 296 | /** \ingroup popt
|
|---|
| 297 | * Destroy context.
|
|---|
| 298 | * @param con context
|
|---|
| 299 | * @return NULL always
|
|---|
| 300 | */
|
|---|
| 301 | /*@null@*/ poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con)
|
|---|
| 302 | /*@modifies con @*/;
|
|---|
| 303 |
|
|---|
| 304 | /** \ingroup popt
|
|---|
| 305 | * Add arguments to context.
|
|---|
| 306 | * @param con context
|
|---|
| 307 | * @param argv argument array, NULL terminated
|
|---|
| 308 | * @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure
|
|---|
| 309 | */
|
|---|
| 310 | int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv)
|
|---|
| 311 | /*@modifies con @*/;
|
|---|
| 312 |
|
|---|
| 313 | /** \ingroup popt
|
|---|
| 314 | * Add alias to context.
|
|---|
| 315 | * @todo Pass alias by reference, not value.
|
|---|
| 316 | * @deprecated Use poptAddItem instead.
|
|---|
| 317 | * @param con context
|
|---|
| 318 | * @param alias alias to add
|
|---|
| 319 | * @param flags (unused)
|
|---|
| 320 | * @return 0 on success
|
|---|
| 321 | */
|
|---|
| 322 | /*@unused@*/
|
|---|
| 323 | int poptAddAlias(poptContext con, struct poptAlias alias, int flags)
|
|---|
| 324 | /*@modifies con @*/;
|
|---|
| 325 |
|
|---|
| 326 | /** \ingroup popt
|
|---|
| 327 | * Add alias/exec item to context.
|
|---|
| 328 | * @param con context
|
|---|
|
|---|
