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