• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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  */
114 struct 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  */
131 struct 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@*/
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 
175 /*@-exportvar@*/
176 /*@unchecked@*/ /*@observer@*/
177 extern 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@*/
189 typedef /*@abstract@*/ struct poptContext_s * poptContext;
190 /*@=exporttype@*/
191 
192 /** \ingroup popt
193  */
194 #ifndef __cplusplus
195 /*@-exporttype -typeuse@*/
196 typedef struct poptOption * poptOption;
197 /*@=exporttype =typeuse@*/
198 #endif
199 
200 /*@-exportconst@*/
201 enum 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
209 extern "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  */
221 typedef 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@*/
239 poptContext 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@*/
251 void 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  */
259 int 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@*/
269 const 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@*/
278 const 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@*/
287 const 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@*/
296 const 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@*/
306 const 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@*/
315 poptContext 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@*/
325 int 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@*/
338 int 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  */
348 int 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  */
357 int 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@*/
369 int 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  */
385 int 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  */
401 int 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
413 aaa
414   bbb
415     ccc
416 bla=bla
417 
418 this_is   =   fdsafdas
419      bad_line=
420   reall bad line
421   reall bad line  = again
422 5555=   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@*/
452 int 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@*/
463 const 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@*/
473 void 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  */
482 void 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  */
492 void 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@*/
502 void 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@*/
513 const 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@*/
525 int 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@*/
539 int 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@*/
554 int 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