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