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