dist/ntp/libopts/autoopts/options.h

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