xref: /freebsd/contrib/ntp/sntp/libopts/autoopts/options.h (revision 271c3a9060f2ee55607ebe146523f888e1db2654)
1 /*   -*- buffer-read-only: t -*- vi: set ro:
2  *
3  *  DO NOT EDIT THIS FILE   (options.h)
4  *
5  *  It has been AutoGen-ed  Saturday May  5, 2007 at 12:02:34 PM PDT
6  *  From the definitions    funcs.def
7  *  and the template file   options_h
8  *
9  *  This file defines all the global structures and special values
10  *  used in the automated option processing library.
11  *
12  *  Automated Options copyright 1992-Y Bruce Korb
13  *
14  *  AutoOpts is free software; you can redistribute it and/or
15  *  modify it under the terms of the GNU Lesser General Public
16  *  License as published by the Free Software Foundation; either
17  *  version 2.1 of the License, or (at your option) any later version.
18  *
19  *  AutoOpts is distributed in the hope that it will be useful,
20  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
22  *  Lesser General Public License for more details.
23  *
24  *  You should have received a copy of the GNU Lesser General Public
25  *  License along with AutoOpts.  If not, write to:
26  *  	The Free Software Foundation, Inc.,
27  *  	51 Franklin Street, Fifth Floor
28  *  	Boston, MA  02110-1301, USA.
29  */
30 #ifndef AUTOOPTS_OPTIONS_H_GUARD
31 #define AUTOOPTS_OPTIONS_H_GUARD
32 #include <sys/types.h>
33 
34 #if defined(HAVE_STDINT_H)
35 # include <stdint.h>
36 #elif defined(HAVE_INTTYPES_H)
37 # include <inttypes.h>
38 #endif /* HAVE_STDINT/INTTYPES_H */
39 
40 #if defined(HAVE_LIMITS_H)
41 # include <limits.h>
42 #elif defined(HAVE_SYS_LIMITS_H)
43 # include <sys/limits.h>
44 #endif /* HAVE_LIMITS/SYS_LIMITS_H */
45 
46 #if defined(HAVE_SYSEXITS_H)
47 #  include <sysexits.h>
48 #endif /* HAVE_SYSEXITS_H */
49 
50 #ifndef EX_USAGE
51 #  define EX_USAGE              64
52 #endif
53 
54 /*
55  *  PUBLIC DEFINES
56  *
57  *  The following defines may be used in applications that need to test the
58  *  state of an option.  To test against these masks and values, a pointer
59  *  to an option descriptor must be obtained.  There are two ways:
60  *
61  *  1. inside an option processing procedure, it is the second argument,
62  *  conventionally "tOptDesc* pOD".
63  *
64  *  2.  Outside of an option procedure (or to reference a different option
65  *  descriptor), use either "&DESC( opt_name )" or "&pfx_DESC( opt_name )".
66  *
67  *  See the relevant generated header file to determine which and what
68  *  values for "opt_name" are available.
69  */
70 
71 #define  OPTIONS_STRUCT_VERSION  118784
72 #define  OPTIONS_VERSION_STRING  "29:0:4"
73 #define  OPTIONS_MINIMUM_VERSION 102400
74 #define  OPTIONS_MIN_VER_STRING  "25:0:0"
75 
76 typedef enum {
77     OPARG_TYPE_NONE             = 0,
78     OPARG_TYPE_STRING           = 1,    /* default type/ vanilla string      */
79     OPARG_TYPE_ENUMERATION      = 2,    /* opt arg is an enum (keyword list) */
80     OPARG_TYPE_BOOLEAN          = 3,    /* opt arg is boolean-valued         */
81     OPARG_TYPE_MEMBERSHIP       = 4,    /* opt arg sets set membership bits  */
82     OPARG_TYPE_NUMERIC          = 5,    /* opt arg has numeric value         */
83     OPARG_TYPE_HIERARCHY        = 6     /* option arg is hierarchical value  */
84 } teOptArgType;
85 
86 typedef struct optionValue {
87     teOptArgType        valType;
88     char*               pzName;
89     union {
90         char            strVal[1];      /* OPARG_TYPE_STRING      */
91         unsigned int    enumVal;        /* OPARG_TYPE_ENUMERATION */
92         unsigned int    boolVal;        /* OPARG_TYPE_BOOLEAN     */
93         unsigned long   setVal;         /* OPARG_TYPE_MEMBERSHIP  */
94         long            longVal;        /* OPARG_TYPE_NUMERIC     */
95         void*           nestVal;        /* OPARG_TYPE_HIERARCHY   */
96     } v;
97 } tOptionValue;
98 
99 /*
100  *  Bits in the fOptState option descriptor field.
101  */
102 typedef enum {
103     OPTST_SET_ID             =   0, /* Set via the "SET_OPT()" macro */
104     OPTST_PRESET_ID          =   1, /* Set via an RC/INI file        */
105     OPTST_DEFINED_ID         =   2, /* Set via a command line option */
106     OPTST_EQUIVALENCE_ID     =   4, /* selected by equiv'ed option   */
107     OPTST_DISABLED_ID        =   5, /* option is in disabled state   */
108     OPTST_ALLOC_ARG_ID       =   6, /* pzOptArg was allocated        */
109     OPTST_NO_INIT_ID         =   8, /* option cannot be preset       */
110     OPTST_NUMBER_OPT_ID      =   9, /* opt value (flag) is any digit */
111     OPTST_STACKED_ID         =  10, /* opt uses optionStackArg proc  */
112     OPTST_INITENABLED_ID     =  11, /* option defaults to enabled    */
113     OPTST_ARG_TYPE_1_ID      =  12, /* bit 1 of arg type enum        */
114     OPTST_ARG_TYPE_2_ID      =  13, /* bit 2 of arg type enum        */
115     OPTST_ARG_TYPE_3_ID      =  14, /* bit 3 of arg type enum        */
116     OPTST_ARG_TYPE_4_ID      =  15, /* bit 4 of arg type enum        */
117     OPTST_ARG_OPTIONAL_ID    =  16, /* the option arg not required   */
118     OPTST_IMM_ID             =  17, /* process opt on first pass     */
119     OPTST_DISABLE_IMM_ID     =  18, /* process disablement immed.    */
120     OPTST_OMITTED_ID         =  19, /* compiled out of program       */
121     OPTST_MUST_SET_ID        =  20, /* must be set or pre-set        */
122     OPTST_DOCUMENT_ID        =  21, /* opt is for doc only           */
123     OPTST_TWICE_ID           =  22, /* process opt twice - imm + reg */
124     OPTST_DISABLE_TWICE_ID   =  23  /* process disabled option twice */
125 } opt_state_enum_t;
126 
127 #define OPTST_INIT           0U
128 #define OPTST_SET            (1U << OPTST_SET_ID)
129 #define OPTST_PRESET         (1U << OPTST_PRESET_ID)
130 #define OPTST_DEFINED        (1U << OPTST_DEFINED_ID)
131 #define OPTST_EQUIVALENCE    (1U << OPTST_EQUIVALENCE_ID)
132 #define OPTST_DISABLED       (1U << OPTST_DISABLED_ID)
133 #define OPTST_ALLOC_ARG      (1U << OPTST_ALLOC_ARG_ID)
134 #define OPTST_NO_INIT        (1U << OPTST_NO_INIT_ID)
135 #define OPTST_NUMBER_OPT     (1U << OPTST_NUMBER_OPT_ID)
136 #define OPTST_STACKED        (1U << OPTST_STACKED_ID)
137 #define OPTST_INITENABLED    (1U << OPTST_INITENABLED_ID)
138 #define OPTST_ARG_TYPE_1     (1U << OPTST_ARG_TYPE_1_ID)
139 #define OPTST_ARG_TYPE_2     (1U << OPTST_ARG_TYPE_2_ID)
140 #define OPTST_ARG_TYPE_3     (1U << OPTST_ARG_TYPE_3_ID)
141 #define OPTST_ARG_TYPE_4     (1U << OPTST_ARG_TYPE_4_ID)
142 #define OPTST_ARG_OPTIONAL   (1U << OPTST_ARG_OPTIONAL_ID)
143 #define OPTST_IMM            (1U << OPTST_IMM_ID)
144 #define OPTST_DISABLE_IMM    (1U << OPTST_DISABLE_IMM_ID)
145 #define OPTST_OMITTED        (1U << OPTST_OMITTED_ID)
146 #define OPTST_MUST_SET       (1U << OPTST_MUST_SET_ID)
147 #define OPTST_DOCUMENT       (1U << OPTST_DOCUMENT_ID)
148 #define OPTST_TWICE          (1U << OPTST_TWICE_ID)
149 #define OPTST_DISABLE_TWICE  (1U << OPTST_DISABLE_TWICE_ID)
150 #define OPT_STATE_MASK       0x00FFFF77U
151 
152 #define OPTST_SET_MASK       (  \
153         OPTST_SET | \
154         OPTST_PRESET | \
155         OPTST_DEFINED )
156 
157 #define OPTST_MUTABLE_MASK   (  \
158         OPTST_SET | \
159         OPTST_PRESET | \
160         OPTST_DEFINED | \
161         OPTST_EQUIVALENCE | \
162         OPTST_DISABLED | \
163         OPTST_ALLOC_ARG )
164 
165 #define OPTST_SELECTED_MASK  (  \
166         OPTST_SET | \
167         OPTST_DEFINED )
168 
169 #define OPTST_ARG_TYPE_MASK  (  \
170         OPTST_ARG_TYPE_1 | \
171         OPTST_ARG_TYPE_2 | \
172         OPTST_ARG_TYPE_3 | \
173         OPTST_ARG_TYPE_4 )
174 
175 #ifdef NO_OPTIONAL_OPT_ARGS
176 # undef  OPTST_ARG_OPTIONAL
177 # define OPTST_ARG_OPTIONAL   0
178 #endif
179 
180 #define OPTST_PERSISTENT_MASK (~OPTST_MUTABLE_MASK)
181 
182 #define SELECTED_OPT( pod )   ((pod)->fOptState  & OPTST_SELECTED_MASK)
183 #define UNUSED_OPT(   pod )   (((pod)->fOptState & OPTST_SET_MASK) == 0)
184 #define DISABLED_OPT( pod )   ((pod)->fOptState  & OPTST_DISABLED)
185 #define OPTION_STATE( pod )   ((pod)->fOptState)
186 
187 #define OPTST_SET_ARGTYPE(n)  ((n) << OPTST_ARG_TYPE_1_ID)
188 #define OPTST_GET_ARGTYPE(f)  (((f) & OPTST_ARG_TYPE_MASK)>>OPTST_ARG_TYPE_1_ID)
189 
190 /*
191  *  PRIVATE INTERFACES
192  *
193  *  The following values are used in the generated code to communicate
194  *  with the option library procedures.  They are not for public use
195  *  and may be subject to change.
196  */
197 
198 /*
199  *  Define the processing state flags
200  */
201 typedef enum {
202     OPTPROC_LONGOPT_ID       =   0, /* Process long style options      */
203     OPTPROC_SHORTOPT_ID      =   1, /* Process short style "flags"     */
204     OPTPROC_ERRSTOP_ID       =   2, /* Stop on argument errors         */
205     OPTPROC_DISABLEDOPT_ID   =   3, /* Current option is disabled      */
206     OPTPROC_NO_REQ_OPT_ID    =   4, /* no options are required         */
207     OPTPROC_NUM_OPT_ID       =   5, /* there is a number option        */
208     OPTPROC_INITDONE_ID      =   6, /* have initializations been done? */
209     OPTPROC_NEGATIONS_ID     =   7, /* any negation options?           */
210     OPTPROC_ENVIRON_ID       =   8, /* check environment?              */
211     OPTPROC_NO_ARGS_ID       =   9, /* Disallow remaining arguments    */
212     OPTPROC_ARGS_REQ_ID      =  10, /* Require arguments after options */
213     OPTPROC_REORDER_ID       =  11, /* reorder operands after options  */
214     OPTPROC_GNUUSAGE_ID      =  12, /* emit usage in GNU style         */
215     OPTPROC_TRANSLATE_ID     =  13, /* Translate strings in tOptions   */
216     OPTPROC_HAS_IMMED_ID     =  14, /* program defines immed options   */
217     OPTPROC_PRESETTING_ID    =  19  /* opt processing in preset state  */
218 } optproc_state_enum_t;
219 
220 #define OPTPROC_NONE         0U
221 #define OPTPROC_LONGOPT      (1U << OPTPROC_LONGOPT_ID)
222 #define OPTPROC_SHORTOPT     (1U << OPTPROC_SHORTOPT_ID)
223 #define OPTPROC_ERRSTOP      (1U << OPTPROC_ERRSTOP_ID)
224 #define OPTPROC_DISABLEDOPT  (1U << OPTPROC_DISABLEDOPT_ID)
225 #define OPTPROC_NO_REQ_OPT   (1U << OPTPROC_NO_REQ_OPT_ID)
226 #define OPTPROC_NUM_OPT      (1U << OPTPROC_NUM_OPT_ID)
227 #define OPTPROC_INITDONE     (1U << OPTPROC_INITDONE_ID)
228 #define OPTPROC_NEGATIONS    (1U << OPTPROC_NEGATIONS_ID)
229 #define OPTPROC_ENVIRON      (1U << OPTPROC_ENVIRON_ID)
230 #define OPTPROC_NO_ARGS      (1U << OPTPROC_NO_ARGS_ID)
231 #define OPTPROC_ARGS_REQ     (1U << OPTPROC_ARGS_REQ_ID)
232 #define OPTPROC_REORDER      (1U << OPTPROC_REORDER_ID)
233 #define OPTPROC_GNUUSAGE     (1U << OPTPROC_GNUUSAGE_ID)
234 #define OPTPROC_TRANSLATE    (1U << OPTPROC_TRANSLATE_ID)
235 #define OPTPROC_HAS_IMMED    (1U << OPTPROC_HAS_IMMED_ID)
236 #define OPTPROC_PRESETTING   (1U << OPTPROC_PRESETTING_ID)
237 #define OPTPROC_STATE_MASK   0x00087FFFU
238 
239 #define STMTS(s)  do { s; } while (0)
240 
241 /*
242  *  The following must be #defined instead of typedef-ed
243  *  because "static const" cannot both be applied to a type,
244  *  tho each individually can...so they all are
245  */
246 #define tSCC        static char const
247 #define tCC         char const
248 #define tAoSC       static char
249 #define tAoUC       unsigned char
250 #define tAoUI       unsigned int
251 #define tAoUL       unsigned long
252 #define tAoUS       unsigned short
253 
254 /*
255  *  It is so disgusting that there must be so many ways
256  *  of specifying TRUE and FALSE.
257  */
258 typedef enum { AG_FALSE = 0, AG_TRUE } ag_bool;
259 
260 /*
261  *  Define a structure that describes each option and
262  *  a pointer to the procedure that handles it.
263  *  The argument is the count of this flag previously seen.
264  */
265 typedef struct options  tOptions;
266 typedef struct optDesc  tOptDesc;
267 typedef struct optNames tOptNames;
268 
269 /*
270  *  The option procedures do the special processing for each
271  *  option flag that needs it.
272  */
273 typedef void (tOptProc)( tOptions*  pOpts, tOptDesc* pOptDesc );
274 typedef tOptProc*  tpOptProc;
275 
276 /*
277  *  The usage procedure will never return.  It calls "exit(2)"
278  *  with the "exitCode" argument passed to it.
279  */
280 typedef void (tUsageProc)( tOptions* pOpts, int exitCode );
281 typedef tUsageProc* tpUsageProc;
282 
283 /*
284  *  Special definitions.  "NOLIMIT" is the 'max' value to use when
285  *  a flag may appear multiple times without limit.  "NO_EQUIVALENT"
286  *  is an illegal value for 'optIndex' (option description index).
287  */
288 #define NOLIMIT          USHRT_MAX
289 #define OPTION_LIMIT     SHRT_MAX
290 #define NO_EQUIVALENT    (OPTION_LIMIT+1)
291 
292 /*
293  *  Special values for optValue.  It must not be generatable from the
294  *  computation "optIndex +96".  Since "optIndex" is limited to 100, ...
295  */
296 #define NUMBER_OPTION    '#'
297 
298 typedef struct argList tArgList;
299 #define MIN_ARG_ALLOC_CT   6
300 #define INCR_ARG_ALLOC_CT  8
301 struct argList {
302     int             useCt;
303     int             allocCt;
304     tCC*            apzArgs[ MIN_ARG_ALLOC_CT ];
305 };
306 
307 typedef union {
308     char const *    argString;
309     uintptr_t       argEnum;
310     uintptr_t       argIntptr;
311     long            argInt;
312     unsigned long   argUint;
313     unsigned int    argBool;
314 } optArgBucket_t;
315 
316 /*
317  *  Descriptor structure for each option.
318  *  Only the fields marked "PUBLIC" are for public use.
319  */
320 struct optDesc {
321     tAoUS const     optIndex;         /* PUBLIC */
322     tAoUS const     optValue;         /* PUBLIC */
323     tAoUS           optActualIndex;   /* PUBLIC */
324     tAoUS           optActualValue;   /* PUBLIC */
325 
326     tAoUS const     optEquivIndex;    /* PUBLIC */
327     tAoUS const     optMinCt;
328     tAoUS const     optMaxCt;
329     tAoUS           optOccCt;         /* PUBLIC */
330 
331     tAoUI           fOptState;        /* PUBLIC */
332     tAoUI           reserved;
333     optArgBucket_t  optArg;           /* PUBLIC */
334 #   define          pzLastArg   optArg.argString
335     void*           optCookie;        /* PUBLIC */
336 
337     const int *     pOptMust;
338     const int *     pOptCant;
339     tpOptProc       pOptProc;
340     char const*     pzText;
341 
342     char const*     pz_NAME;
343     char const*     pz_Name;
344     char const*     pz_DisableName;
345     char const*     pz_DisablePfx;
346 };
347 
348 /*
349  *  Some options need special processing, so we store their
350  *  indexes in a known place:
351  */
352 typedef struct optSpecIndex tOptSpecIndex;
353 struct optSpecIndex {
354     const tAoUS         more_help;
355     const tAoUS         save_opts;
356     const tAoUS         number_option;
357     const tAoUS         default_opt;
358 };
359 
360 /*
361  *  The procedure generated for translating option text
362  */
363 typedef void (tOptionXlateProc)(void);
364 
365 struct options {
366     int const           structVersion;
367     int                 origArgCt;
368     char**              origArgVect;
369     unsigned int        fOptSet;
370     unsigned int        curOptIdx;
371     char*               pzCurOpt;
372 
373     char const*         pzProgPath;
374     char const*         pzProgName;
375     char const* const   pzPROGNAME;
376     char const* const   pzRcName;
377     char const* const   pzCopyright;
378     char const* const   pzCopyNotice;
379     char const* const   pzFullVersion;
380     char const* const* const papzHomeList;
381     char const* const   pzUsageTitle;
382     char const* const   pzExplain;
383     char const* const   pzDetail;
384     tOptDesc*   const   pOptDesc;
385     char const* const   pzBugAddr;
386 
387     void*               pExtensions;
388     void*               pSavedState;
389 
390     tpUsageProc         pUsageProc;
391     tOptionXlateProc*   pTransProc;
392 
393     tOptSpecIndex       specOptIdx;
394     int const           optCt;
395     int const           presetOptCt;
396 };
397 
398 /*
399  *  "token list" structure returned by "string_tokenize()"
400  */
401 typedef struct {
402     unsigned long   tkn_ct;
403     unsigned char*  tkn_list[1];
404 } token_list_t;
405 
406 /*
407  *  Hide the interface - it pollutes a POSIX claim, but leave it for
408  *  anyone #include-ing this header
409  */
410 #define strneqvcmp      option_strneqvcmp
411 #define streqvcmp       option_streqvcmp
412 #define streqvmap       option_streqvmap
413 #define strequate       option_strequate
414 #define strtransform    option_strtransform
415 
416 /*
417  *  This is an output only structure used by text_mmap and text_munmap.
418  *  Clients must not alter the contents and must provide it to both
419  *  the text_mmap and text_munmap procedures.  BE ADVISED: if you are
420  *  mapping the file with PROT_WRITE the NUL byte at the end MIGHT NOT
421  *  BE WRITABLE.  In any event, that byte is not be written back
422  *  to the source file.  ALSO: if "txt_data" is valid and "txt_errno"
423  *  is not zero, then there *may* not be a terminating NUL.
424  */
425 typedef struct {
426     void*       txt_data;      /* text file data   */
427     size_t      txt_size;      /* actual file size */
428     size_t      txt_full_size; /* mmaped mem size  */
429     int         txt_fd;        /* file descriptor  */
430     int         txt_zero_fd;   /* fd for /dev/zero */
431     int         txt_errno;     /* warning code     */
432     int         txt_prot;      /* "prot" flags     */
433     int         txt_flags;     /* mapping type     */
434     int         txt_alloc;     /* if we malloced memory */
435 } tmap_info_t;
436 
437 #define TEXT_MMAP_FAILED_ADDR(a)  ((void*)(a) ==  (void*)MAP_FAILED)
438 
439 #ifdef  __cplusplus
440 extern "C" {
441 #define CPLUSPLUS_CLOSER }
442 #else
443 #define CPLUSPLUS_CLOSER
444 #endif
445 
446 /*
447  *  The following routines may be coded into AutoOpts client code:
448  */
449 
450 /* From: tokenize.c line 115
451  *
452  * ao_string_tokenize - tokenize an input string
453  *
454  * Arguments:
455  *   string       string to be tokenized
456  *
457  * Returns: token_list_t* - pointer to a structure that lists each token
458  *
459  *  This function will convert one input string into a list of strings.
460  *  The list of strings is derived by separating the input based on
461  *  white space separation.  However, if the input contains either single
462  *  or double quote characters, then the text after that character up to
463  *  a matching quote will become the string in the list.
464  *
465  *  The returned pointer should be deallocated with @code{free(3C)} when
466  *  are done using the data.  The data are placed in a single block of
467  *  allocated memory.  Do not deallocate individual token/strings.
468  *
469  *  The structure pointed to will contain at least these two fields:
470  *  @table @samp
471  *  @item tkn_ct
472  *  The number of tokens found in the input string.
473  *  @item tok_list
474  *  An array of @code{tkn_ct + 1} pointers to substring tokens, with
475  *  the last pointer set to NULL.
476  *  @end table
477  *
478  *  There are two types of quoted strings: single quoted (@code{'}) and
479  *  double quoted (@code{"}).  Singly quoted strings are fairly raw in that
480  *  escape characters (@code{\\}) are simply another character, except when
481  *  preceding the following characters:
482  *  @example
483  *  @code{\\}  double backslashes reduce to one
484  *  @code{'}   incorporates the single quote into the string
485  *  @code{\n}  suppresses both the backslash and newline character
486  *  @end example
487  *
488  *  Double quote strings are formed according to the rules of string
489  *  constants in ANSI-C programs.
490  */
491 extern token_list_t* ao_string_tokenize( char const* );
492 
493 
494 /* From: configfile.c line 113
495  *
496  * configFileLoad - parse a configuration file
497  *
498  * Arguments:
499  *   pzFile       the file to load
500  *
501  * Returns: const tOptionValue* - An allocated, compound value structure
502  *
503  *  This routine will load a named configuration file and parse the
504  *  text as a hierarchically valued option.  The option descriptor
505  *  created from an option definition file is not used via this interface.
506  *  The returned value is "named" with the input file name and is of
507  *  type "@code{OPARG_TYPE_HIERARCHY}".  It may be used in calls to
508  *  @code{optionGetValue()}, @code{optionNextValue()} and
509  *  @code{optionUnloadNested()}.
510  */
511 extern const tOptionValue* configFileLoad( char const* );
512 
513 
514 /* From: configfile.c line 883
515  *
516  * optionFileLoad - Load the locatable config files, in order
517  *
518  * Arguments:
519  *   pOpts        program options descriptor
520  *   pzProg       program name
521  *
522  * Returns: int - 0 -> SUCCESS, -1 -> FAILURE
523  *
524  *  This function looks in all the specified directories for a configuration
525  *  file ("rc" file or "ini" file) and processes any found twice.  The first
526  *  time through, they are processed in reverse order (last file first).  At
527  *  that time, only "immediate action" configurables are processed.  For
528  *  example, if the last named file specifies not processing any more
529  *  configuration files, then no more configuration files will be processed.
530  *  Such an option in the @strong{first} named directory will have no effect.
531  *
532  *  Once the immediate action configurables have been handled, then the
533  *  directories are handled in normal, forward order.  In that way, later
534  *  config files can override the settings of earlier config files.
535  *
536  *  See the AutoOpts documentation for a thorough discussion of the
537  *  config file format.
538  *
539  *  Configuration files not found or not decipherable are simply ignored.
540  */
541 extern int optionFileLoad( tOptions*, char const* );
542 
543 
544 /* From: configfile.c line 245
545  *
546  * optionFindNextValue - find a hierarcicaly valued option instance
547  *
548  * Arguments:
549  *   pOptDesc     an option with a nested arg type
550  *   pPrevVal     the last entry
551  *   name         name of value to find
552  *   value        the matching value
553  *
554  * Returns: const tOptionValue* - a compound value structure
555  *
556  *  This routine will find the next entry in a nested value option or
557  *  configurable.  It will search through the list and return the next entry
558  *  that matches the criteria.
559  */
560 extern const tOptionValue* optionFindNextValue( const tOptDesc*, const tOptionValue*, char const*, char const* );
561 
562 
563 /* From: configfile.c line 171
564  *
565  * optionFindValue - find a hierarcicaly valued option instance
566  *
567  * Arguments:
568  *   pOptDesc     an option with a nested arg type
569  *   name         name of value to find
570  *   value        the matching value
571  *
572  * Returns: const tOptionValue* - a compound value structure
573  *
574  *  This routine will find an entry in a nested value option or configurable.
575  *  It will search through the list and return a matching entry.
576  */
577 extern const tOptionValue* optionFindValue( const tOptDesc*, char const*, char const* );
578 
579 
580 /* From: restore.c line 188
581  *
582  * optionFree - free allocated option processing memory
583  *
584  * Arguments:
585  *   pOpts        program options descriptor
586  *
587  *  AutoOpts sometimes allocates memory and puts pointers to it in the
588  *  option state structures.  This routine deallocates all such memory.
589  */
590 extern void optionFree( tOptions* );
591 
592 
593 /* From: configfile.c line 314
594  *
595  * optionGetValue - get a specific value from a hierarcical list
596  *
597  * Arguments:
598  *   pOptValue    a hierarchcal value
599  *   valueName    name of value to get
600  *
601  * Returns: const tOptionValue* - a compound value structure
602  *
603  *  This routine will find an entry in a nested value option or configurable.
604  *  If "valueName" is NULL, then the first entry is returned.  Otherwise,
605  *  the first entry with a name that exactly matches the argument will be
606  *  returned.
607  */
608 extern const tOptionValue* optionGetValue( const tOptionValue*, char const* );
609 
610 
611 /* From: load.c line 521
612  *
613  * optionLoadLine - process a string for an option name and value
614  *
615  * Arguments:
616  *   pOpts        program options descriptor
617  *   pzLine       NUL-terminated text
618  *
619  *  This is a client program callable routine for setting options from, for
620  *  example, the contents of a file that they read in.  Only one option may
621  *  appear in the text.  It will be treated as a normal (non-preset) option.
622  *
623  *  When passed a pointer to the option struct and a string, it will find
624  *  the option named by the first token on the string and set the option
625  *  argument to the remainder of the string.  The caller must NUL terminate
626  *  the string.  Any embedded new lines will be included in the option
627  *  argument.  If the input looks like one or more quoted strings, then the
628  *  input will be "cooked".  The "cooking" is identical to the string
629  *  formation used in AutoGen definition files (@pxref{basic expression}),
630  *  except that you may not use backquotes.
631  */
632 extern void optionLoadLine( tOptions*, char const* );
633 
634 
635 /* From: configfile.c line 373
636  *
637  * optionNextValue - get the next value from a hierarchical list
638  *
639  * Arguments:
640  *   pOptValue    a hierarchcal list value
641  *   pOldValue    a value from this list
642  *
643  * Returns: const tOptionValue* - a compound value structure
644  *
645  *  This routine will return the next entry after the entry passed in.  At the
646  *  end of the list, NULL will be returned.  If the entry is not found on the
647  *  list, NULL will be returned and "@var{errno}" will be set to EINVAL.
648  *  The "@var{pOldValue}" must have been gotten from a prior call to this
649  *  routine or to "@code{opitonGetValue()}".
650  */
651 extern const tOptionValue* optionNextValue( const tOptionValue*, const tOptionValue* );
652 
653 
654 /* From: usage.c line 128
655  *
656  * optionOnlyUsage - Print usage text for just the options
657  *
658  * Arguments:
659  *   pOpts        program options descriptor
660  *   ex_code      exit code for calling exit(3)
661  *
662  *  This routine will print only the usage for each option.
663  *  This function may be used when the emitted usage must incorporate
664  *  information not available to AutoOpts.
665  */
666 extern void optionOnlyUsage( tOptions*, int );
667 
668 
669 /* From: autoopts.c line 1012
670  *
671  * optionProcess - this is the main option processing routine
672  *
673  * Arguments:
674  *   pOpts        program options descriptor
675  *   argc         program arg count
676  *   argv         program arg vector
677  *
678  * Returns: int - the count of the arguments processed
679  *
680  *  This is the main entry point for processing options.  It is intended
681  *  that this procedure be called once at the beginning of the execution of
682  *  a program.  Depending on options selected earlier, it is sometimes
683  *  necessary to stop and restart option processing, or to select completely
684  *  different sets of options.  This can be done easily, but you generally
685  *  do not want to do this.
686  *
687  *  The number of arguments processed always includes the program name.
688  *  If one of the arguments is "--", then it is counted and the processing
689  *  stops.  If an error was encountered and errors are to be tolerated, then
690  *  the returned value is the index of the argument causing the error.
691  *  A hyphen by itself ("-") will also cause processing to stop and will
692  *  @emph{not} be counted among the processed arguments.  A hyphen by itself
693  *  is treated as an operand.  Encountering an operand stops option
694  *  processing.
695  */
696 extern int optionProcess( tOptions*, int, char** );
697 
698 
699 /* From: restore.c line 145
700  *
701  * optionRestore - restore option state from memory copy
702  *
703  * Arguments:
704  *   pOpts        program options descriptor
705  *
706  *  Copy back the option state from saved memory.
707  *  The allocated memory is left intact, so this routine can be
708  *  called repeatedly without having to call optionSaveState again.
709  *  If you are restoring a state that was saved before the first call
710  *  to optionProcess(3AO), then you may change the contents of the
711  *  argc/argv parameters to optionProcess.
712  */
713 extern void optionRestore( tOptions* );
714 
715 
716 /* From: save.c line 334
717  *
718  * optionSaveFile - saves the option state to a file
719  *
720  * Arguments:
721  *   pOpts        program options descriptor
722  *
723  *  This routine will save the state of option processing to a file.  The name
724  *  of that file can be specified with the argument to the @code{--save-opts}
725  *  option, or by appending the @code{rcfile} attribute to the last
726  *  @code{homerc} attribute.  If no @code{rcfile} attribute was specified, it
727  *  will default to @code{.@i{programname}rc}.  If you wish to specify another
728  *  file, you should invoke the @code{SET_OPT_SAVE_OPTS( @i{filename} )} macro.
729  */
730 extern void optionSaveFile( tOptions* );
731 
732 
733 /* From: restore.c line 93
734  *
735  * optionSaveState - saves the option state to memory
736  *
737  * Arguments:
738  *   pOpts        program options descriptor
739  *
740  *  This routine will allocate enough memory to save the current option
741  *  processing state.  If this routine has been called before, that memory
742  *  will be reused.  You may only save one copy of the option state.  This
743  *  routine may be called before optionProcess(3AO).  If you do call it
744  *  before the first call to optionProcess, then you may also change the
745  *  contents of argc/argv after you call optionRestore(3AO)
746  *
747  *  In fact, more strongly put: it is safest to only use this function
748  *  before having processed any options.  In particular, the saving and
749  *  restoring of stacked string arguments and hierarchical values is
750  *  disabled.  The values are not saved.
751  */
752 extern void optionSaveState( tOptions* );
753 
754 
755 /* From: nested.c line 559
756  *
757  * optionUnloadNested - Deallocate the memory for a nested value
758  *
759  * Arguments:
760  *   pOptVal      the hierarchical value
761  *
762  *  A nested value needs to be deallocated.  The pointer passed in should
763  *  have been gotten from a call to @code{configFileLoad()} (See
764  *  @pxref{libopts-configFileLoad}).
765  */
766 extern void optionUnloadNested( tOptionValue const * );
767 
768 
769 /* From: version.c line 58
770  *
771  * optionVersion - return the compiled AutoOpts version number
772  *
773  * Returns: char const* - the version string in constant memory
774  *
775  *  Returns the full version string compiled into the library.
776  *  The returned string cannot be modified.
777  */
778 extern char const* optionVersion( void );
779 
780 
781 /* From: ../compat/pathfind.c line 34
782  *
783  * pathfind - fild a file in a list of directories
784  *
785  * Arguments:
786  *   path         colon separated list of search directories
787  *   file         the name of the file to look for
788  *   mode         the mode bits that must be set to match
789  *
790  * Returns: char* - the path to the located file
791  *
792  * the pathfind function is available only if HAVE_PATHFIND is not defined
793  *
794  *  pathfind looks for a a file with name "FILE" and "MODE" access
795  *  along colon delimited "PATH", and returns the full pathname as a
796  *  string, or NULL if not found.  If "FILE" contains a slash, then
797  *  it is treated as a relative or absolute path and "PATH" is ignored.
798  *
799  *  @strong{NOTE}: this function is compiled into @file{libopts} only if
800  *  it is not natively supplied.
801  *
802  *  The "MODE" argument is a string of option letters chosen from the
803  *  list below:
804  *  @example
805  *  Letter    Meaning
806  *  r         readable
807  *  w         writable
808  *  x         executable
809  *  f         normal file       (NOT IMPLEMENTED)
810  *  b         block special     (NOT IMPLEMENTED)
811  *  c         character special (NOT IMPLEMENTED)
812  *  d         directory         (NOT IMPLEMENTED)
813  *  p         FIFO (pipe)       (NOT IMPLEMENTED)
814  *  u         set user ID bit   (NOT IMPLEMENTED)
815  *  g         set group ID bit  (NOT IMPLEMENTED)
816  *  k         sticky bit        (NOT IMPLEMENTED)
817  *  s         size nonzero      (NOT IMPLEMENTED)
818  *  @end example
819  */
820 #ifndef HAVE_PATHFIND
821 extern char* pathfind( char const*, char const*, char const* );
822 #endif /* HAVE_PATHFIND */
823 
824 
825 /* From: streqvcmp.c line 233
826  *
827  * strequate - map a list of characters to the same value
828  *
829  * Arguments:
830  *   ch_list      characters to equivalence
831  *
832  *  Each character in the input string get mapped to the first character
833  *  in the string.
834  *  This function name is mapped to option_strequate so as to not conflict
835  *  with the POSIX name space.
836  */
837 extern void strequate( char const* );
838 
839 
840 /* From: streqvcmp.c line 143
841  *
842  * streqvcmp - compare two strings with an equivalence mapping
843  *
844  * Arguments:
845  *   str1         first string
846  *   str2         second string
847  *
848  * Returns: int - the difference between two differing characters
849  *
850  *  Using a character mapping, two strings are compared for "equivalence".
851  *  Each input character is mapped to a comparison character and the
852  *  mapped-to characters are compared for the two NUL terminated input strings.
853  *  This function name is mapped to option_streqvcmp so as to not conflict
854  *  with the POSIX name space.
855  */
856 extern int streqvcmp( char const*, char const* );
857 
858 
859 /* From: streqvcmp.c line 180
860  *
861  * streqvmap - Set the character mappings for the streqv functions
862  *
863  * Arguments:
864  *   From         Input character
865  *   To           Mapped-to character
866  *   ct           compare length
867  *
868  *  Set the character mapping.  If the count (@code{ct}) is set to zero, then
869  *  the map is cleared by setting all entries in the map to their index
870  *  value.  Otherwise, the "@code{From}" character is mapped to the "@code{To}"
871  *  character.  If @code{ct} is greater than 1, then @code{From} and @code{To}
872  *  are incremented and the process repeated until @code{ct} entries have been
873  *  set. For example,
874  *  @example
875  *  streqvmap( 'a', 'A', 26 );
876  *  @end example
877  *  @noindent
878  *  will alter the mapping so that all English lower case letters
879  *  will map to upper case.
880  *
881  *  This function name is mapped to option_streqvmap so as to not conflict
882  *  with the POSIX name space.
883  */
884 extern void streqvmap( char, char, int );
885 
886 
887 /* From: streqvcmp.c line 102
888  *
889  * strneqvcmp - compare two strings with an equivalence mapping
890  *
891  * Arguments:
892  *   str1         first string
893  *   str2         second string
894  *   ct           compare length
895  *
896  * Returns: int - the difference between two differing characters
897  *
898  *  Using a character mapping, two strings are compared for "equivalence".
899  *  Each input character is mapped to a comparison character and the
900  *  mapped-to characters are compared for the two NUL terminated input strings.
901  *  The comparison is limited to @code{ct} bytes.
902  *  This function name is mapped to option_strneqvcmp so as to not conflict
903  *  with the POSIX name space.
904  */
905 extern int strneqvcmp( char const*, char const*, int );
906 
907 
908 /* From: streqvcmp.c line 259
909  *
910  * strtransform - convert a string into its mapped-to value
911  *
912  * Arguments:
913  *   dest         output string
914  *   src          input string
915  *
916  *  Each character in the input string is mapped and the mapped-to
917  *  character is put into the output.
918  *  This function name is mapped to option_strtransform so as to not conflict
919  *  with the POSIX name space.
920  */
921 extern void strtransform( char*, char const* );
922 
923 /*  AutoOpts PRIVATE FUNCTIONS:  */
924 tOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal;
925 
926 extern char* ao_string_cook( char*, int* );
927 
928 extern unsigned int ao_string_cook_escape_char( char const*, char*, unsigned int );
929 
930 extern void export_options_to_guile( tOptions* );
931 
932 extern void genshelloptUsage( tOptions*, int );
933 
934 extern void optionBooleanVal( tOptions*, tOptDesc* );
935 
936 extern uintptr_t optionEnumerationVal( tOptions*, tOptDesc*, char const * const *, unsigned int );
937 
938 extern char const* optionKeywordName( tOptDesc*, unsigned int );
939 
940 extern void optionLoadOpt( tOptions*, tOptDesc* );
941 
942 extern ag_bool optionMakePath( char*, int, char const*, char const* );
943 
944 extern void optionNestedVal( tOptions*, tOptDesc* );
945 
946 extern void optionNumericVal( tOptions*, tOptDesc* );
947 
948 extern void optionPagedUsage( tOptions*, tOptDesc* );
949 
950 extern void optionParseShell( tOptions* );
951 
952 extern void optionPrintVersion( tOptions*, tOptDesc* );
953 
954 extern void optionPutShell( tOptions* );
955 
956 extern void optionSetMembers( tOptions*, tOptDesc*, char const * const *, unsigned int );
957 
958 extern void optionStackArg( tOptions*, tOptDesc* );
959 
960 extern void optionUnstackArg( tOptions*, tOptDesc* );
961 
962 extern void optionUsage( tOptions*, int );
963 
964 extern void optionVersionStderr( tOptions*, tOptDesc* );
965 
966 extern void* text_mmap( char const*, int, int, tmap_info_t* );
967 
968 extern int text_munmap( tmap_info_t* );
969 
970 CPLUSPLUS_CLOSER
971 #endif /* AUTOOPTS_OPTIONS_H_GUARD */
972 /*
973  * Local Variables:
974  * c-file-style: "stroustrup"
975  * indent-tabs-mode: nil
976  * End:
977  * options.h ends here */
978