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 */ 978