Reject passing an arg to an option that doesn't take one (bug 6915).
[rsync.git] / 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_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