PageRenderTime 11ms CodeModel.GetById 12ms app.highlight 18ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/ntp/sntp/libopts/autoopts/options.h

https://bitbucket.org/freebsd/freebsd-head/
C++ Header | 977 lines | 329 code | 116 blank | 532 comment | 3 complexity | b9e534c35e65b16bb04480bc139209f1 MD5 | raw file
  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
 76typedef 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
 86typedef 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 */
102typedef 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 */
201typedef 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 */
258typedef 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 */
265typedef struct options  tOptions;
266typedef struct optDesc  tOptDesc;
267typedef struct optNames tOptNames;
268
269/*
270 *  The option procedures do the special processing for each
271 *  option flag that needs it.
272 */
273typedef void (tOptProc)( tOptions*  pOpts, tOptDesc* pOptDesc );
274typedef tOptProc*  tpOptProc;
275
276/*
277 *  The usage procedure will never return.  It calls "exit(2)"
278 *  with the "exitCode" argument passed to it.
279 */
280typedef void (tUsageProc)( tOptions* pOpts, int exitCode );
281typedef 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
298typedef struct argList tArgList;
299#define MIN_ARG_ALLOC_CT   6
300#define INCR_ARG_ALLOC_CT  8
301struct argList {
302    int             useCt;
303    int             allocCt;
304    tCC*            apzArgs[ MIN_ARG_ALLOC_CT ];
305};
306
307typedef 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 */
320struct 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 */
352typedef struct optSpecIndex tOptSpecIndex;
353struct 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 */
363typedef void (tOptionXlateProc)(void);
364
365struct 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 */
401typedef 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 */
425typedef 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
440extern "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 */
491extern 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 */
511extern 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 */
541extern 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 */
560extern 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 */
577extern 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 */
590extern 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 */
608extern 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 */
632extern 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 */
651extern 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 */
666extern 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 */
696extern 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 */
713extern 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 */
730extern 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 */
752extern 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 */
766extern 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 */
778extern 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
821extern 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 */
837extern 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 */
856extern 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 */
884extern 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 */
905extern 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 */
921extern void strtransform( char*, char const* );
922
923/*  AutoOpts PRIVATE FUNCTIONS:  */
924tOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal;
925
926extern char* ao_string_cook( char*, int* );
927
928extern unsigned int ao_string_cook_escape_char( char const*, char*, unsigned int );
929
930extern void export_options_to_guile( tOptions* );
931
932extern void genshelloptUsage( tOptions*, int );
933
934extern void optionBooleanVal( tOptions*, tOptDesc* );
935
936extern uintptr_t optionEnumerationVal( tOptions*, tOptDesc*, char const * const *, unsigned int );
937
938extern char const* optionKeywordName( tOptDesc*, unsigned int );
939
940extern void optionLoadOpt( tOptions*, tOptDesc* );
941
942extern ag_bool optionMakePath( char*, int, char const*, char const* );
943
944extern void optionNestedVal( tOptions*, tOptDesc* );
945
946extern void optionNumericVal( tOptions*, tOptDesc* );
947
948extern void optionPagedUsage( tOptions*, tOptDesc* );
949
950extern void optionParseShell( tOptions* );
951
952extern void optionPrintVersion( tOptions*, tOptDesc* );
953
954extern void optionPutShell( tOptions* );
955
956extern void optionSetMembers( tOptions*, tOptDesc*, char const * const *, unsigned int );
957
958extern void optionStackArg( tOptions*, tOptDesc* );
959
960extern void optionUnstackArg( tOptions*, tOptDesc* );
961
962extern void optionUsage( tOptions*, int );
963
964extern void optionVersionStderr( tOptions*, tOptDesc* );
965
966extern void* text_mmap( char const*, int, int, tmap_info_t* );
967
968extern int text_munmap( tmap_info_t* );
969
970CPLUSPLUS_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 */