Commit | Line | Data |
---|---|---|
cc248aae WD |
1 | /** \file popt/popt.h |
2 | * \ingroup popt | |
3 | */ | |
4 | ||
5 | /* (C) 1998-2000 Red Hat, Inc. -- Licensing details are in the COPYING | |
62402cb1 | 6 | file accompanying popt source distributions, available from |
cc248aae | 7 | ftp://ftp.rpm.org/pub/rpm/dist. */ |
62402cb1 MP |
8 | |
9 | #ifndef H_POPT | |
10 | #define H_POPT | |
11 | ||
12 | #include <stdio.h> /* for FILE * */ | |
13 | ||
14 | #define POPT_OPTION_DEPTH 10 | |
15 | ||
cc248aae WD |
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 | |
62402cb1 MP |
26 | set first in table; arg points |
27 | to callback, descrip points to | |
28 | callback data to pass */ | |
cc248aae | 29 | #define POPT_ARG_INTL_DOMAIN 6 /*!< set the translation domain |
b348deae MP |
30 | for this table and any |
31 | included tables; arg points | |
32 | to the domain string */ | |
cc248aae WD |
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 | ||
62402cb1 | 37 | #define POPT_ARG_MASK 0x0000FFFF |
cc248aae WD |
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, | |
62402cb1 | 74 | not the subtable */ |
cc248aae WD |
75 | #define POPT_CBFLAG_SKIPOPTION 0x10000000 /*!< don't callback with option */ |
76 | #define POPT_CBFLAG_CONTINUE 0x08000000 /*!< continue callbacks with option */ | |
77 | /*@}*/ | |
62402cb1 | 78 | |
cc248aae WD |
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 paramter 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 | /*@}*/ | |
62402cb1 | 94 | |
cc248aae WD |
95 | /** \ingroup popt |
96 | * \name poptBadOption() flags | |
97 | */ | |
98 | /*@{*/ | |
99 | #define POPT_BADOPTION_NOALIAS (1 << 0) /*!< don't go into an alias */ | |
100 | /*@}*/ | |
62402cb1 | 101 | |
cc248aae WD |
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 | /*@}*/ | |
62402cb1 | 111 | |
cc248aae WD |
112 | /** \ingroup popt |
113 | */ | |
62402cb1 | 114 | struct poptOption { |
cc248aae WD |
115 | /*@observer@*/ /*@null@*/ const char * longName; /*!< may be NULL */ |
116 | char shortName; /*!< may be '\0' */ | |
62402cb1 | 117 | int argInfo; |
cc248aae WD |
118 | /*@shared@*/ /*@null@*/ void * arg; /*!< depends on argInfo */ |
119 | int val; /*!< 0 means don't return, just update flag */ | |
120 | /*@observer@*/ /*@null@*/ const char * descrip; /*!< description for autohelp -- may be NULL */ | |
121 | /*@observer@*/ /*@null@*/ const char * argDescrip; /*!< argument description for autohelp */ | |
62402cb1 MP |
122 | }; |
123 | ||
cc248aae WD |
124 | /** \ingroup popt |
125 | * A popt alias argument for poptAddAlias(). | |
126 | */ | |
62402cb1 | 127 | struct poptAlias { |
cc248aae WD |
128 | /*@owned@*/ /*@null@*/ const char * longName; /*!< may be NULL */ |
129 | char shortName; /*!< may be '\0' */ | |
62402cb1 | 130 | int argc; |
cc248aae | 131 | /*@owned@*/ const char ** argv; /*!< must be free()able */ |
62402cb1 MP |
132 | }; |
133 | ||
cc248aae WD |
134 | /** \ingroup popt |
135 | * A popt alias or exec argument for poptAddItem(). | |
136 | */ | |
137 | typedef struct poptItem_s { | |
138 | struct poptOption option; /*!< alias/exec name(s) and description. */ | |
139 | int argc; /*!< (alias) no. of args. */ | |
140 | /*@owned@*/ const char ** argv; /*!< (alias) args, must be free()able. */ | |
141 | } * poptItem; | |
142 | ||
143 | /** \ingroup popt | |
144 | * \name Auto-generated help/usage | |
145 | */ | |
146 | /*@{*/ | |
147 | ||
148 | /** | |
149 | * Empty table marker to enable displaying popt alias/exec options. | |
150 | */ | |
151 | /*@observer@*/ /*@checked@*/ | |
152 | extern struct poptOption poptAliasOptions[]; | |
153 | #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \ | |
154 | 0, "Options implemented via popt alias/exec:", NULL }, | |
155 | ||
156 | /** | |
157 | * Auto help table options. | |
158 | */ | |
159 | /*@observer@*/ /*@checked@*/ | |
62402cb1 MP |
160 | extern struct poptOption poptHelpOptions[]; |
161 | #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \ | |
cc248aae | 162 | 0, "Help options:", NULL }, |
62402cb1 | 163 | |
cc248aae WD |
164 | #define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL } |
165 | /*@}*/ | |
166 | ||
167 | /** \ingroup popt | |
168 | */ | |
169 | typedef /*@abstract@*/ struct poptContext_s * poptContext; | |
170 | ||
171 | /** \ingroup popt | |
172 | */ | |
62402cb1 | 173 | #ifndef __cplusplus |
cc248aae | 174 | /*@-typeuse@*/ |
62402cb1 | 175 | typedef struct poptOption * poptOption; |
cc248aae | 176 | /*@=typeuse@*/ |
62402cb1 MP |
177 | #endif |
178 | ||
179 | enum poptCallbackReason { POPT_CALLBACK_REASON_PRE, | |
180 | POPT_CALLBACK_REASON_POST, | |
181 | POPT_CALLBACK_REASON_OPTION }; | |
cc248aae WD |
182 | |
183 | #ifdef __cplusplus | |
184 | extern "C" { | |
185 | #endif | |
186 | /*@-type@*/ | |
187 | ||
188 | /** \ingroup popt | |
189 | * Table callback prototype. | |
190 | * @param con context | |
191 | * @param reason reason for callback | |
192 | * @param opt option that triggered callback | |
193 | * @param arg @todo Document. | |
194 | * @param data @todo Document. | |
195 | */ | |
196 | typedef void (*poptCallbackType) (poptContext con, | |
197 | enum poptCallbackReason reason, | |
198 | /*@null@*/ const struct poptOption * opt, | |
199 | /*@null@*/ const char * arg, | |
200 | /*@null@*/ const void * data) | |
201 | /*@*/; | |
202 | ||
203 | /** \ingroup popt | |
204 | * Initialize popt context. | |
205 | * @param name | |
206 | * @param argc no. of arguments | |
207 | * @param argv argument array | |
208 | * @param options address of popt option table | |
209 | * @param flags or'd POPT_CONTEXT_* bits | |
210 | * @return initialized popt context | |
211 | */ | |
212 | /*@only@*/ /*@null@*/ poptContext poptGetContext( | |
213 | /*@dependent@*/ /*@keep@*/ const char * name, | |
214 | int argc, /*@dependent@*/ /*@keep@*/ const char ** argv, | |
215 | /*@dependent@*/ /*@keep@*/ const struct poptOption * options, | |
216 | int flags) | |
217 | /*@*/; | |
218 | ||
219 | /** \ingroup popt | |
220 | * Reinitialize popt context. | |
221 | * @param con context | |
222 | */ | |
223 | void poptResetContext(/*@null@*/poptContext con) | |
224 | /*@modifies con @*/; | |
225 | ||
226 | /** \ingroup popt | |
227 | * Return value of next option found. | |
228 | * @param con context | |
229 | * @return next option val, -1 on last item, POPT_ERROR_* on error | |
230 | */ | |
231 | int poptGetNextOpt(/*@null@*/poptContext con) | |
232 | /*@globals fileSystem@*/ | |
233 | /*@modifies con, fileSystem @*/; | |
234 | ||
235 | /*@-redecl@*/ | |
236 | /** \ingroup popt | |
237 | * Return next option argument (if any). | |
238 | * @param con context | |
239 | * @return option argument, NULL if no more options are available | |
240 | */ | |
241 | /*@observer@*/ /*@null@*/ const char * poptGetOptArg(/*@null@*/poptContext con) | |
242 | /*@modifies con @*/; | |
243 | ||
244 | /** \ingroup popt | |
245 | * Return current option's argument. | |
246 | * @param con context | |
247 | * @return option argument, NULL if no more options are available | |
248 | */ | |
249 | /*@observer@*/ /*@null@*/ const char * poptGetArg(/*@null@*/poptContext con) | |
250 | /*@modifies con @*/; | |
251 | ||
252 | /** \ingroup popt | |
253 | * Peek at current option's argument. | |
254 | * @param con context | |
255 | * @return option argument | |
256 | */ | |
257 | /*@observer@*/ /*@null@*/ const char * poptPeekArg(/*@null@*/poptContext con) | |
258 | /*@*/; | |
259 | ||
260 | /** \ingroup popt | |
261 | * Return remaining arguments. | |
262 | * @param con context | |
263 | * @return argument array, terminated with NULL | |
264 | */ | |
265 | /*@observer@*/ /*@null@*/ const char ** poptGetArgs(/*@null@*/poptContext con) | |
266 | /*@modifies con @*/; | |
267 | ||
268 | /** \ingroup popt | |
269 | * Return the option which caused the most recent error. | |
270 | * @param con context | |
271 | * @return offending option | |
272 | */ | |
273 | /*@observer@*/ const char * poptBadOption(/*@null@*/poptContext con, int flags) | |
274 | /*@*/; | |
275 | /*@=redecl@*/ | |
276 | ||
277 | /** \ingroup popt | |
278 | * Destroy context. | |
279 | * @param con context | |
280 | * @return NULL always | |
281 | */ | |
282 | /*@null@*/ poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con) | |
283 | /*@modifies con @*/; | |
284 | ||
285 | /** \ingroup popt | |
286 | * Add arguments to context. | |
287 | * @param con context | |
288 | * @param argv argument array, NULL terminated | |
289 | * @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure | |
290 | */ | |
291 | int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv) | |
292 | /*@modifies con @*/; | |
293 | ||
294 | /** \ingroup popt | |
295 | * Add alias to context. | |
296 | * @todo Pass alias by reference, not value. | |
297 | * @deprecated Use poptAddItem instead. | |
298 | * @param con context | |
299 | * @param alias alias to add | |
300 | * @param flags (unused) | |
301 | * @return 0 on success | |
302 | */ | |
303 | /*@unused@*/ | |
304 | int poptAddAlias(poptContext con, struct poptAlias alias, int flags) | |
305 | /*@modifies con @*/; | |
306 | ||
307 | /** \ingroup popt | |
308 | * Add alias/exec item to context. | |
309 | * @param con context | |
310 | * @param item alias/exec item to add | |
311 | * @param flags 0 for alias, 1 for exec | |
312 | * @return 0 on success | |
313 | */ | |
314 | int poptAddItem(poptContext con, poptItem newItem, int flags) | |
315 | /*@modifies con @*/; | |
316 | ||
317 | /** \ingroup popt | |
318 | * Read configuration file. | |
319 | * @param con context | |
320 | * @param fn file name to read | |
321 | * @return 0 on success, POPT_ERROR_ERRNO on failure | |
322 | */ | |
323 | int poptReadConfigFile(poptContext con, const char * fn) | |
324 | /*@globals fileSystem@*/ | |
325 | /*@modifies fileSystem, | |
326 | con->execs, con->numExecs @*/; | |
327 | ||
328 | /** \ingroup popt | |
329 | * Read default configuration from /etc/popt and $HOME/.popt. | |
330 | * @param con context | |
331 | * @param useEnv (unused) | |
332 | * @return 0 on success, POPT_ERROR_ERRNO on failure | |
333 | */ | |
334 | int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv) | |
335 | /*@globals fileSystem@*/ | |
336 | /*@modifies fileSystem, | |
337 | con->execs, con->numExecs @*/; | |
338 | ||
339 | /** \ingroup popt | |
340 | * Duplicate an argument array. | |
341 | * @note: The argument array is malloc'd as a single area, so only argv must | |
342 | * be free'd. | |
343 | * | |
344 | * @param argc no. of arguments | |
345 | * @param argv argument array | |
346 | * @retval argcPtr address of returned no. of arguments | |
347 | * @retval argvPtr address of returned argument array | |
348 | * @return 0 on success, POPT_ERROR_NOARG on failure | |
349 | */ | |
350 | int poptDupArgv(int argc, /*@null@*/ const char **argv, | |
351 | /*@null@*/ /*@out@*/ int * argcPtr, | |
352 | /*@null@*/ /*@out@*/ const char *** argvPtr) | |
353 | /*@modifies *argcPtr, *argvPtr @*/; | |
354 | ||
355 | /** \ingroup popt | |
356 | * Parse a string into an argument array. | |
357 | * The parse allows ', ", and \ quoting, but ' is treated the same as " and | |
358 | * both may include \ quotes. | |
359 | * @note: The argument array is malloc'd as a single area, so only argv must | |
360 | * be free'd. | |
361 | * | |
362 | * @param s string to parse | |
363 | * @retval argcPtr address of returned no. of arguments | |
364 | * @retval argvPtr address of returned argument array | |
365 | */ | |
37101856 | 366 | int poptParseArgvString(const unsigned char * s, |
cc248aae WD |
367 | /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr) |
368 | /*@modifies *argcPtr, *argvPtr @*/; | |
369 | ||
370 | /** \ingroup popt | |
371 | * Return formatted error string for popt failure. | |
372 | * @param error popt error | |
373 | * @return error string | |
374 | */ | |
375 | /*@-redecl@*/ | |
376 | /*@observer@*/ const char *const poptStrerror(const int error) | |
377 | /*@*/; | |
378 | /*@=redecl@*/ | |
379 | ||
380 | /** \ingroup popt | |
381 | * Limit search for executables. | |
382 | * @param con context | |
383 | * @param path single path to search for executables | |
384 | * @param allowAbsolute absolute paths only? | |
385 | */ | |
386 | void poptSetExecPath(poptContext con, const char * path, int allowAbsolute) | |
387 | /*@modifies con @*/; | |
388 | ||
389 | /** \ingroup popt | |
390 | * Print detailed description of options. | |
391 | * @param con context | |
392 | * @param fp ouput file handle | |
393 | * @param flags (unused) | |
394 | */ | |
395 | void poptPrintHelp(poptContext con, FILE * fp, /*@unused@*/ int flags) | |
396 | /*@globals fileSystem @*/ | |
397 | /*@modifies *fp, fileSystem @*/; | |
398 | ||
399 | /** \ingroup popt | |
400 | * Print terse description of options. | |
401 | * @param con context | |
402 | * @param fp ouput file handle | |
403 | * @param flags (unused) | |
404 | */ | |
405 | void poptPrintUsage(poptContext con, FILE * fp, /*@unused@*/ int flags) | |
406 | /*@globals fileSystem @*/ | |
407 | /*@modifies *fp, fileSystem @*/; | |
408 | ||
409 | /** \ingroup popt | |
410 | * Provide text to replace default "[OPTION...]" in help/usage output. | |
411 | * @param con context | |
412 | * @param text replacement text | |
413 | */ | |
414 | /*@-fcnuse@*/ | |
415 | void poptSetOtherOptionHelp(poptContext con, const char * text) | |
416 | /*@modifies con @*/; | |
417 | /*@=fcnuse@*/ | |
418 | ||
419 | /** \ingroup popt | |
420 | * Return argv[0] from context. | |
421 | * @param con context | |
422 | * @return argv[0] | |
423 | */ | |
424 | /*@-redecl -fcnuse@*/ | |
425 | /*@observer@*/ const char * poptGetInvocationName(poptContext con) | |
426 | /*@*/; | |
427 | /*@=redecl =fcnuse@*/ | |
428 | ||
429 | /** \ingroup popt | |
430 | * Shuffle argv pointers to remove stripped args, returns new argc. | |
431 | * @param con context | |
432 | * @param argc no. of args | |
433 | * @param argv arg vector | |
434 | * @return new argc | |
435 | */ | |
436 | /*@-fcnuse@*/ | |
437 | int poptStrippedArgv(poptContext con, int argc, char ** argv) | |
438 | /*@modifies *argv @*/; | |
439 | /*@=fcnuse@*/ | |
b348deae | 440 | |
cc248aae | 441 | /*@=type@*/ |
b348deae MP |
442 | #ifdef __cplusplus |
443 | } | |
444 | #endif | |
62402cb1 MP |
445 | |
446 | #endif |