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_UNWANTEDARG -12 /*!< option does not take an argument */
86: #define POPT_ERROR_OPTSTOODEEP -13 /*!< aliases nested too deeply */
87: #define POPT_ERROR_BADQUOTE -15 /*!< error in paramter quoting */
88: #define POPT_ERROR_ERRNO -16 /*!< errno set, use strerror(errno) */
89: #define POPT_ERROR_BADNUMBER -17 /*!< invalid numeric value */
90: #define POPT_ERROR_OVERFLOW -18 /*!< number too large or too small */
91: #define POPT_ERROR_BADOPERATION -19 /*!< mutually exclusive logical operations requested */
92: #define POPT_ERROR_NULLARG -20 /*!< opt->arg should not be NULL */
93: #define POPT_ERROR_MALLOC -21 /*!< memory allocation failed */
94: /*@}*/
95:
96: /** \ingroup popt
97: * \name poptBadOption() flags
98: */
99: /*@{*/
100: #define POPT_BADOPTION_NOALIAS (1 << 0) /*!< don't go into an alias */
101: /*@}*/
102:
103: /** \ingroup popt
104: * \name poptGetContext() flags
105: */
106: /*@{*/
107: #define POPT_CONTEXT_NO_EXEC (1 << 0) /*!< ignore exec expansions */
108: #define POPT_CONTEXT_KEEP_FIRST (1 << 1) /*!< pay attention to argv[0] */
109: #define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /*!< options can't follow args */
110: #define POPT_CONTEXT_ARG_OPTS (1 << 4) /*!< return args as options with value 0 */
111: /*@}*/
112:
113: /** \ingroup popt
114: */
115: struct poptOption {
116: /*@observer@*/ /*@null@*/
117: const char * longName; /*!< may be NULL */
118: char shortName; /*!< may be NUL */
119: int argInfo;
120: /*@shared@*/ /*@null@*/
121: void * arg; /*!< depends on argInfo */
122: int val; /*!< 0 means don't return, just update flag */
123: /*@observer@*/ /*@null@*/
124: const char * descrip; /*!< description for autohelp -- may be NULL */
125: /*@observer@*/ /*@null@*/
126: const char * argDescrip; /*!< argument description for autohelp */
127: };
128:
129: /** \ingroup popt
130: * A popt alias argument for poptAddAlias().
131: */
132: struct poptAlias {
133: /*@owned@*/ /*@null@*/
134: const char * longName; /*!< may be NULL */
135: char shortName; /*!< may be NUL */
136: int argc;
137: /*@owned@*/
138: const char ** argv; /*!< must be free()able */
139: };
140:
141: /** \ingroup popt
142: * A popt alias or exec argument for poptAddItem().
143: */
144: /*@-exporttype@*/
145: typedef struct poptItem_s {
146: struct poptOption option; /*!< alias/exec name(s) and description. */
147: int argc; /*!< (alias) no. of args. */
148: /*@owned@*/
149: const char ** argv; /*!< (alias) args, must be free()able. */
150: } * poptItem;
151: /*@=exporttype@*/
152:
153: /** \ingroup popt
154: * \name Auto-generated help/usage
155: */
156: /*@{*/
157:
158: /**
159: * Empty table marker to enable displaying popt alias/exec options.
160: */
161: /*@-exportvar@*/
162: /*@unchecked@*/ /*@observer@*/
163: extern struct poptOption poptAliasOptions[];
164: /*@=exportvar@*/
165: #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
166: 0, "Options implemented via popt alias/exec:", NULL },
167:
168: /**
169: * Auto help table options.
170: */
171: /*@-exportvar@*/
172: /*@unchecked@*/ /*@observer@*/
173: extern struct poptOption poptHelpOptions[];
174: /*@=exportvar@*/
175:
176: /*@-exportvar@*/
177: /*@unchecked@*/ /*@observer@*/
178: extern struct poptOption * poptHelpOptionsI18N;
179: /*@=exportvar@*/
180:
181: #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
182: 0, "Help options:", NULL },
183:
184: #define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
185: /*@}*/
186:
187: /** \ingroup popt
188: */
189: /*@-exporttype@*/
190: typedef /*@abstract@*/ struct poptContext_s * poptContext;
191: /*@=exporttype@*/
192:
193: /** \ingroup popt
194: */
195: #ifndef __cplusplus
196: /*@-exporttype -typeuse@*/
197: typedef struct poptOption * poptOption;
198: /*@=exporttype =typeuse@*/
199: #endif
200:
201: /*@-exportconst@*/
202: enum poptCallbackReason {
203: POPT_CALLBACK_REASON_PRE = 0,
204: POPT_CALLBACK_REASON_POST = 1,
205: POPT_CALLBACK_REASON_OPTION = 2
206: };
207: /*@=exportconst@*/
208:
209: #ifdef __cplusplus
210: extern "C" {
211: #endif
212: /*@-type@*/
213:
214: /** \ingroup popt
215: * Table callback prototype.
216: * @param con context
217: * @param reason reason for callback
218: * @param opt option that triggered callback
219: * @param arg @todo Document.
220: * @param data @todo Document.
221: */
222: typedef void (*poptCallbackType) (poptContext con,
223: enum poptCallbackReason reason,
224: /*@null@*/ const struct poptOption * opt,
225: /*@null@*/ const char * arg,
226: /*@null@*/ const void * data)
227: /*@globals internalState @*/
228: /*@modifies internalState @*/;
229:
230: /** \ingroup popt
231: * Initialize popt context.
232: * @param name context name (usually argv[0] program name)
233: * @param argc no. of arguments
234: * @param argv argument array
235: * @param options address of popt option table
236: * @param flags or'd POPT_CONTEXT_* bits
237: * @return initialized popt context
238: */
239: /*@only@*/ /*@null@*/
240: poptContext poptGetContext(
241: /*@dependent@*/ /*@keep@*/ const char * name,
242: int argc, /*@dependent@*/ /*@keep@*/ const char ** argv,
243: /*@dependent@*/ /*@keep@*/ const struct poptOption * options,
244: int flags)
245: /*@*/;
246:
247: /** \ingroup popt
248: * Reinitialize popt context.
249: * @param con context
250: */
251: /*@unused@*/
252: void poptResetContext(/*@null@*/poptContext con)
253: /*@modifies con @*/;
254:
255: /** \ingroup popt
256: * Return value of next option found.
257: * @param con context
258: * @return next option val, -1 on last item, POPT_ERROR_* on error
259: */
260: int poptGetNextOpt(/*@null@*/poptContext con)
261: /*@globals fileSystem, internalState @*/
262: /*@modifies con, fileSystem, internalState @*/;
263:
264: /** \ingroup popt
265: * Return next option argument (if any).
266: * @param con context
267: * @return option argument, NULL if no argument is available
268: */
269: /*@observer@*/ /*@null@*/ /*@unused@*/
270: const char * poptGetOptArg(/*@null@*/poptContext con)
271: /*@modifies con @*/;
272:
273: /** \ingroup popt
274: * Return next argument.
275: * @param con context
276: * @return next argument, NULL if no argument is available
277: */
278: /*@observer@*/ /*@null@*/ /*@unused@*/
279: const char * poptGetArg(/*@null@*/poptContext con)
280: /*@modifies con @*/;
281:
282: /** \ingroup popt
283: * Peek at current argument.
284: * @param con context
285: * @return current argument, NULL if no argument is available
286: */
287: /*@observer@*/ /*@null@*/ /*@unused@*/
288: const char * poptPeekArg(/*@null@*/poptContext con)
289: /*@*/;
290:
291: /** \ingroup popt
292: * Return remaining arguments.
293: * @param con context
294: * @return argument array, NULL terminated
295: */
296: /*@observer@*/ /*@null@*/
297: const char ** poptGetArgs(/*@null@*/poptContext con)
298: /*@modifies con @*/;
299:
300: /** \ingroup popt
301: * Return the option which caused the most recent error.
302: * @param con context
303: * @param flags
304: * @return offending option
305: */
306: /*@observer@*/
307: const char * poptBadOption(/*@null@*/poptContext con, int flags)
308: /*@*/;
309:
310: /** \ingroup popt
311: * Destroy context.
312: * @param con context
313: * @return NULL always
314: */
315: /*@null@*/
316: poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con)
317: /*@modifies con @*/;
318:
319: /** \ingroup popt
320: * Add arguments to context.
321: * @param con context
322: * @param argv argument array, NULL terminated
323: * @return 0 on success, POPT_ERROR_OPTSTOODEEP on failure
324: */
325: /*@unused@*/
326: int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv)
327: /*@modifies con @*/;
328:
329: /** \ingroup popt
330: * Add alias to context.
331: * @todo Pass alias by reference, not value.
332: * @deprecated Use poptAddItem instead.
333: * @param con context
334: * @param alias alias to add
335: * @param flags (unused)
336: * @return 0 on success
337: */
338: /*@unused@*/
339: int poptAddAlias(poptContext con, struct poptAlias alias, int flags)
340: /*@modifies con @*/;
341:
342: /** \ingroup popt
343: * Add alias/exec item to context.
344: * @param con context
345: * @param newItem alias/exec item to add
346: * @param flags 0 for alias, 1 for exec
347: * @return 0 on success
348: */
349: int poptAddItem(poptContext con, poptItem newItem, int flags)
350: /*@modifies con @*/;
351:
352: /** \ingroup popt
353: * Read configuration file.
354: * @param con context
355: * @param fn file name to read
356: * @return 0 on success, POPT_ERROR_ERRNO on failure
357: */
358: int poptReadConfigFile(poptContext con, const char * fn)
359: /*@globals errno, fileSystem, internalState @*/
360: /*@modifies con->execs, con->numExecs,
361: errno, fileSystem, internalState @*/;
362:
363: /** \ingroup popt
364: * Read default configuration from /etc/popt and $HOME/.popt.
365: * @param con context
366: * @param useEnv (unused)
367: * @return 0 on success, POPT_ERROR_ERRNO on failure
368: */
369: /*@unused@*/
370: int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv)
371: /*@globals fileSystem, internalState @*/
372: /*@modifies con->execs, con->numExecs,
373: fileSystem, internalState @*/;
374:
375: /** \ingroup popt
376: * Duplicate an argument array.
377: * @note: The argument array is malloc'd as a single area, so only argv must
378: * be free'd.
379: *
380: * @param argc no. of arguments
381: * @param argv argument array
382: * @retval argcPtr address of returned no. of arguments
383: * @retval argvPtr address of returned argument array
384: * @return 0 on success, POPT_ERROR_NOARG on failure
385: */
386: int poptDupArgv(int argc, /*@null@*/ const char **argv,
387: /*@null@*/ /*@out@*/ int * argcPtr,
388: /*@null@*/ /*@out@*/ const char *** argvPtr)
389: /*@modifies *argcPtr, *argvPtr @*/;
390:
391: /** \ingroup popt
392: * Parse a string into an argument array.
393: * The parse allows ', ", and \ quoting, but ' is treated the same as " and
394: * both may include \ quotes.
395: * @note: The argument array is malloc'd as a single area, so only argv must
396: * be free'd.
397: *
398: * @param s string to parse
399: * @retval argcPtr address of returned no. of arguments
400: * @retval argvPtr address of returned argument array
401: */
402: int poptParseArgvString(const char * s,
403: /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr)
404: /*@modifies *argcPtr, *argvPtr @*/;
405:
406: /** \ingroup popt
407: * Parses an input configuration file and returns an string that is a
408: * command line. For use with popt. You must free the return value when done.
409: *
410: * Given the file:
411: \verbatim
412: # this line is ignored
413: # this one too
414: aaa
415: bbb
416: ccc
417: bla=bla
418:
419: this_is = fdsafdas
420: bad_line=
421: reall bad line
422: reall bad line = again
423: 5555= 55555
424: test = with lots of spaces
425: \endverbatim
426: *
427: * The result is:
428: \verbatim
429: --aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces"
430: \endverbatim
431: *
432: * Passing this to poptParseArgvString() yields an argv of:
433: \verbatim
434: '--aaa'
435: '--bbb'
436: '--ccc'
437: '--bla=bla'
438: '--this_is=fdsafdas'
439: '--5555=55555'
440: '--test=with lots of spaces'
441: \endverbatim
442: *
443: * @bug NULL is returned if file line is too long.
444: * @bug Silently ignores invalid lines.
445: *
446: * @param fp file handle to read
447: * @param *argstrp return string of options (malloc'd)
448: * @param flags unused
449: * @return 0 on success
450: * @see poptParseArgvString
451: */
452: /*@-fcnuse@*/
453: int poptConfigFileToString(FILE *fp, /*@out@*/ char ** argstrp, int flags)
454: /*@globals fileSystem @*/
455: /*@modifies *fp, *argstrp, fileSystem @*/;
456: /*@=fcnuse@*/
457:
458: /** \ingroup popt
459: * Return formatted error string for popt failure.
460: * @param error popt error
461: * @return error string
462: */
463: /*@observer@*/
464: const char * poptStrerror(const int error)
465: /*@*/;
466:
467: /** \ingroup popt
468: * Limit search for executables.
469: * @param con context
470: * @param path single path to search for executables
471: * @param allowAbsolute absolute paths only?
472: */
473: /*@unused@*/
474: void poptSetExecPath(poptContext con, const char * path, int allowAbsolute)
475: /*@modifies con @*/;
476:
477: /** \ingroup popt
478: * Print detailed description of options.
479: * @param con context
480: * @param fp ouput file handle
481: * @param flags (unused)
482: */
483: void poptPrintHelp(poptContext con, FILE * fp, /*@unused@*/ int flags)
484: /*@globals fileSystem @*/
485: /*@modifies *fp, fileSystem @*/;
486:
487: /** \ingroup popt
488: * Print terse description of options.
489: * @param con context
490: * @param fp ouput file handle
491: * @param flags (unused)
492: */
493: void poptPrintUsage(poptContext con, FILE * fp, /*@unused@*/ int flags)
494: /*@globals fileSystem @*/
495: /*@modifies *fp, fileSystem @*/;
496:
497: /** \ingroup popt
498: * Provide text to replace default "[OPTION...]" in help/usage output.
499: * @param con context
500: * @param text replacement text
501: */
502: /*@-fcnuse@*/
503: void poptSetOtherOptionHelp(poptContext con, const char * text)
504: /*@modifies con @*/;
505: /*@=fcnuse@*/
506:
507: /** \ingroup popt
508: * Return argv[0] from context.
509: * @param con context
510: * @return argv[0]
511: */
512: /*@-fcnuse@*/
513: /*@observer@*/
514: const char * poptGetInvocationName(poptContext con)
515: /*@*/;
516: /*@=fcnuse@*/
517:
518: /** \ingroup popt
519: * Shuffle argv pointers to remove stripped args, returns new argc.
520: * @param con context
521: * @param argc no. of args
522: * @param argv arg vector
523: * @return new argc
524: */
525: /*@-fcnuse@*/
526: int poptStrippedArgv(poptContext con, int argc, char ** argv)
527: /*@modifies *argv @*/;
528: /*@=fcnuse@*/
529:
530: /**
531: * Save a long, performing logical operation with value.
532: * @warning Alignment check may be too strict on certain platorms.
533: * @param arg integer pointer, aligned on int boundary.
534: * @param argInfo logical operation (see POPT_ARGFLAG_*)
535: * @param aLong value to use
536: * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
537: */
538: /*@-incondefs@*/
539: /*@unused@*/
540: int poptSaveLong(/*@null@*/ long * arg, int argInfo, long aLong)
541: /*@modifies *arg @*/
542: /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/;
543: /*@=incondefs@*/
544:
545: /**
546: * Save an integer, performing logical operation with value.
547: * @warning Alignment check may be too strict on certain platorms.
548: * @param arg integer pointer, aligned on int boundary.
549: * @param argInfo logical operation (see POPT_ARGFLAG_*)
550: * @param aLong value to use
551: * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
552: */
553: /*@-incondefs@*/
554: /*@unused@*/
555: int poptSaveInt(/*@null@*/ int * arg, int argInfo, long aLong)
556: /*@modifies *arg @*/
557: /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/;
558: /*@=incondefs@*/
559:
560: /*@=type@*/
561: #ifdef __cplusplus
562: }
563: #endif
564:
565: #endif
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to popt.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / popt