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@*/ const char * longName; /*!< may be NULL */
116    char shortName;			/*!< may be '\0' */
117    int argInfo;
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 */
122};
123
124/** \ingroup popt
125 * A popt alias argument for poptAddAlias().
126 */
127struct poptAlias {
128/*@owned@*/ /*@null@*/ const char * longName;	/*!< may be NULL */
129    char shortName;		/*!< may be '\0' */
130    int argc;
131/*@owned@*/ const char ** argv;	/*!< must be free()able */
132};
133
134/** \ingroup popt
135 * A popt alias or exec argument for poptAddItem().
136 */
137typedef 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@*/
152extern 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@*/
160extern struct poptOption poptHelpOptions[];
161#define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
162			0, "Help options:", NULL },
163
164#define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
165/*@}*/
166
167/** \ingroup popt
168 */
169typedef /*@abstract@*/ struct poptContext_s * poptContext;
170
171/** \ingroup popt
172 */
173#ifndef __cplusplus
174/*@-typeuse@*/
175typedef struct poptOption * poptOption;
176/*@=typeuse@*/
177#endif
178
179enum poptCallbackReason { POPT_CALLBACK_REASON_PRE,
180			  POPT_CALLBACK_REASON_POST,
181			  POPT_CALLBACK_REASON_OPTION };
182
183#ifdef __cplusplus
184extern "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 */
196typedef 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 */
223void 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 */
231int 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 */
291int 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@*/
304int 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 */
314int 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 */
323int 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 */
334int 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 */
350int 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 */
366int poptParseArgvString(const unsigned char * s,
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 * 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 */
386void 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 */
395void 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 */
405void 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@*/
415void 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@*/
437int poptStrippedArgv(poptContext con, int argc, char ** argv)
438	/*@modifies *argv @*/;
439/*@=fcnuse@*/
440
441/*@=type@*/
442#ifdef  __cplusplus
443}
444#endif
445
446#endif
447