1/* -*- buffer-read-only: t -*- vi: set ro: 2 * 3 * DO NOT EDIT THIS FILE (options.h) 4 * 5 * It has been AutoGen-ed 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-2015 by Bruce Korb 13 * 14 * This file is part of AutoOpts, a companion to AutoGen. 15 * AutoOpts is free software. 16 * AutoOpts is Copyright (C) 1992-2015 by Bruce Korb - all rights reserved 17 * 18 * AutoOpts is available under any one of two licenses. The license 19 * in use must be one of these two and the choice is under the control 20 * of the user of the license. 21 * 22 * The GNU Lesser General Public License, version 3 or later 23 * See the files "COPYING.lgplv3" and "COPYING.gplv3" 24 * 25 * The Modified Berkeley Software Distribution License 26 * See the file "COPYING.mbsd" 27 * 28 * These files have the following sha256 sums: 29 * 30 * 8584710e9b04216a394078dc156b781d0b47e1729104d666658aecef8ee32e95 COPYING.gplv3 31 * 4379e7444a0e2ce2b12dd6f5a52a27a4d02d39d247901d3285c88cf0d37f477b COPYING.lgplv3 32 * 13aa749a5b0a454917a944ed8fffc530b784f5ead522b1aacaf4ec8aa55a6239 COPYING.mbsd 33 */ 34#ifndef AUTOOPTS_OPTIONS_H_GUARD 35#define AUTOOPTS_OPTIONS_H_GUARD 1 36/** \file options.h 37 * 38 * @addtogroup autoopts 39 * @{ 40 */ 41#include <sys/types.h> 42#include <stdio.h> 43 44#ifndef COMPAT_H_GUARD 45/* 46 * This is needed for test compilations where the "compat.h" 47 * header is not usually available. 48 */ 49# if defined(HAVE_STDINT_H) 50# include <stdint.h> 51# elif defined(HAVE_INTTYPES_H) 52# include <inttypes.h> 53# endif /* HAVE_STDINT/INTTYPES_H */ 54 55# if defined(HAVE_LIMITS_H) 56# include <limits.h> 57# elif defined(HAVE_SYS_LIMITS_H) 58# include <sys/limits.h> 59# endif /* HAVE_LIMITS/SYS_LIMITS_H */ 60 61# if defined(HAVE_SYSEXITS_H) 62# include <sysexits.h> 63# endif /* HAVE_SYSEXITS_H */ 64 65# if defined(HAVE_STDBOOL_H) 66# include <stdbool.h> 67# else 68 typedef enum { false = 0, true = 1 } _Bool; 69# define bool _Bool 70 71 /* The other macros must be usable in preprocessor directives. */ 72# define false 0 73# define true 1 74# endif /* HAVE_SYSEXITS_H */ 75#endif /* COMPAT_H_GUARD */ 76// END-CONFIGURED-HEADERS 77 78/** 79 * Defined to abnormal value of EX_USAGE. Used to indicate that paged usage 80 * was requested. It is used to distinguish a --usage from a --help request. 81 * --usage is abbreviated and --help gives as much help as possible. 82 */ 83#define AO_EXIT_REQ_USAGE 10064 84 85#undef VOIDP 86/** 87 * Coerce a value into a void pointer with no const or volatile attributes. 88 * Somewhere along the line, the above set of includes need to set up 89 * the "uintptr_t" type. 90 */ 91#define VOIDP(_a) ((void *)(uintptr_t)(_a)) 92 93/** 94 * PUBLIC DEFINES 95 * 96 * The following defines may be used in applications that need to test the 97 * state of an option. To test against these masks and values, a pointer 98 * to an option descriptor must be obtained. There are two ways: 99 * 100 * 1. inside an option processing procedure, it is the second argument, 101 * conventionally "tOptDesc * pOD". 102 * 103 * 2. Outside of an option procedure (or to reference a different option 104 * descriptor), use either "&DESC( opt_name )" or "&pfx_DESC( opt_name )". 105 * 106 * See the relevant generated header file to determine which and what 107 * values for "opt_name" are available. 108 * @group version 109 * @{ 110 */ 111/// autoopts structure version 112#define OPTIONS_STRUCT_VERSION 167936 113/// autoopts structure version string 114#define OPTIONS_VERSION_STRING "41:0:16" 115/// minimum version the autoopts library supports 116#define OPTIONS_MINIMUM_VERSION 102400 117/// minimum version the autoopts library supports as a string 118#define OPTIONS_MIN_VER_STRING "25:0:0" 119/// the display version of the autoopts library, as a string 120#define OPTIONS_DOTTED_VERSION "41.0" 121/// convert a version/release number pair to an integer value 122#define OPTIONS_VER_TO_NUM(_v, _r) (((_v) * 4096) + (_r)) 123/// @} 124 125/** 126 * Option argument types. This must fit in the OPTST_ARG_TYPE_MASK 127 * field of the fOptState field of an option descriptor (tOptDesc). 128 * It will be a problem to extend beyond 4 bits. 129 */ 130typedef enum { 131 OPARG_TYPE_NONE = 0, ///< does not take an argument 132 OPARG_TYPE_STRING = 1, ///< default type/ vanilla string 133 OPARG_TYPE_ENUMERATION = 2, ///< opt arg is an enum (keyword list) 134 OPARG_TYPE_BOOLEAN = 3, ///< opt arg is boolean-valued 135 OPARG_TYPE_MEMBERSHIP = 4, ///< opt arg sets set membership bits 136 OPARG_TYPE_NUMERIC = 5, ///< opt arg is a long int 137 OPARG_TYPE_HIERARCHY = 6, ///< option arg is hierarchical value 138 OPARG_TYPE_FILE = 7, ///< option arg names a file 139 OPARG_TYPE_TIME = 8, ///< opt arg is a time duration 140 OPARG_TYPE_FLOAT = 9, ///< opt arg is a floating point num 141 OPARG_TYPE_DOUBLE = 10, ///< opt arg is a double prec. float 142 OPARG_TYPE_LONG_DOUBLE = 11, ///< opt arg is a long double prec. 143 OPARG_TYPE_LONG_LONG = 12 ///< opt arg is a long long int 144} teOptArgType; 145 146/** 147 * value descriptor for sub options 148 */ 149typedef struct optionValue { 150 teOptArgType valType; ///< which argument type 151 char * pzName; ///< name of the sub-option 152 union { 153 char strVal[1]; ///< OPARG_TYPE_STRING 154 unsigned int enumVal; ///< OPARG_TYPE_ENUMERATION 155 unsigned int boolVal; ///< OPARG_TYPE_BOOLEAN 156 unsigned long setVal; ///< OPARG_TYPE_MEMBERSHIP 157 long longVal; ///< OPARG_TYPE_NUMERIC 158 void * nestVal; ///< OPARG_TYPE_HIERARCHY 159 } v; 160} tOptionValue; 161 162/** 163 * file argument state and handling. 164 */ 165typedef enum { 166 FTYPE_MODE_MAY_EXIST = 0x00, ///< may or may not exist 167 FTYPE_MODE_MUST_EXIST = 0x01, ///< must pre-exist 168 FTYPE_MODE_MUST_NOT_EXIST = 0x02, ///< must *not* pre-exist 169 FTYPE_MODE_EXIST_MASK = 0x03, ///< mask for these bits 170 FTYPE_MODE_NO_OPEN = 0x00, ///< leave file closed 171 FTYPE_MODE_OPEN_FD = 0x10, ///< call open(2) 172 FTYPE_MODE_FOPEN_FP = 0x20, ///< call fopen(3) 173 FTYPE_MODE_OPEN_MASK = 0x30 ///< open/fopen/not open 174} teOptFileType; 175 176/** 177 * the open flag bits or the mode string, depending on the open type. 178 */ 179typedef union { 180 int file_flags; ///< open(2) flag bits 181 char const * file_mode; ///< fopen(3) mode string 182} tuFileMode; 183 184/// initial number of option argument holders to allocate 185#define MIN_ARG_ALLOC_CT 6 186/// amount by which to increment the argument holder allocation. 187#define INCR_ARG_ALLOC_CT 8 188/** 189 * an argument list. When an option appears multiple times and 190 * the values get "stacked". \a apzArgs holds 8 pointers initially 191 * and is incremented by \a INCR_ARG_ALLOC_CT as needed. 192 */ 193typedef struct { 194 int useCt; ///< elements in use 195 196 /// allocated elements, mininum \a MIN_ARG_ALLOC_CT 197 /// steps by \a INCR_ARG_ALLOC_CT 198 int allocCt; 199 char const * apzArgs[MIN_ARG_ALLOC_CT]; ///< element array 200} tArgList; 201 202/** 203 * Bits in the fOptState option descriptor field. 204 * @{ 205 */ 206 207/** integral type for holding opt_state masks */ 208typedef uint32_t opt_state_mask_t; 209 210#define OPTST_ARG_TYPE_SHIFT 12 211/** bits defined for opt_state_mask_t */ 212/** Set via the "SET_OPT()" macro */ 213#define OPTST_SET 0x0000001U 214/** Set via an RC/INI file */ 215#define OPTST_PRESET 0x0000002U 216/** Set via a command line option */ 217#define OPTST_DEFINED 0x0000004U 218/** Reset via command line option */ 219#define OPTST_RESET 0x0000008U 220/** selected by equiv'ed option */ 221#define OPTST_EQUIVALENCE 0x0000010U 222/** option is in disabled state */ 223#define OPTST_DISABLED 0x0000020U 224/** pzOptArg was allocated */ 225#define OPTST_ALLOC_ARG 0x0000040U 226/** option cannot be preset */ 227#define OPTST_NO_INIT 0x0000100U 228/** opt value (flag) is any digit */ 229#define OPTST_NUMBER_OPT 0x0000200U 230/** opt uses optionStackArg proc */ 231#define OPTST_STACKED 0x0000400U 232/** option defaults to enabled */ 233#define OPTST_INITENABLED 0x0000800U 234/** bit 1 of arg type enum */ 235#define OPTST_ARG_TYPE_1 0x0001000U 236/** bit 2 of arg type enum */ 237#define OPTST_ARG_TYPE_2 0x0002000U 238/** bit 3 of arg type enum */ 239#define OPTST_ARG_TYPE_3 0x0004000U 240/** bit 4 of arg type enum */ 241#define OPTST_ARG_TYPE_4 0x0008000U 242/** the option arg not required */ 243#define OPTST_ARG_OPTIONAL 0x0010000U 244/** process opt on first pass */ 245#define OPTST_IMM 0x0020000U 246/** process disablement immed. */ 247#define OPTST_DISABLE_IMM 0x0040000U 248/** compiled out of program */ 249#define OPTST_OMITTED 0x0080000U 250/** must be set or pre-set */ 251#define OPTST_MUST_SET 0x0100000U 252/** opt is for doc only */ 253#define OPTST_DOCUMENT 0x0200000U 254/** process opt twice - imm + reg */ 255#define OPTST_TWICE 0x0400000U 256/** process disabled option twice */ 257#define OPTST_DISABLE_TWICE 0x0800000U 258/** scaled integer value */ 259#define OPTST_SCALED_NUM 0x1000000U 260/** disable from cmd line */ 261#define OPTST_NO_COMMAND 0x2000000U 262/** support is being removed */ 263#define OPTST_DEPRECATED 0x4000000U 264/** alias for other option */ 265#define OPTST_ALIAS 0x8000000U 266 267/** bits in SET mask: 268 * set preset reset defined */ 269#define OPTST_SET_MASK 0x000000FU 270 271/** bits in MUTABLE mask: 272 * set preset reset defined equivalence disabled 273 * alloc_arg */ 274#define OPTST_MUTABLE_MASK 0x000007FU 275 276/** bits omitted from PERSISTENT mask: 277 * mutable_mask */ 278#define OPTST_PERSISTENT_MASK 0xFFFFF00U 279 280/** bits in SELECTED mask: 281 * set defined */ 282#define OPTST_SELECTED_MASK 0x0000005U 283 284/** bits in ARG_TYPE mask: 285 * arg_type_1 arg_type_2 arg_type_3 arg_type_4 */ 286#define OPTST_ARG_TYPE_MASK 0x000F000U 287 288/** bits in NO_USAGE mask: 289 * omitted no_command deprecated */ 290#define OPTST_NO_USAGE_MASK 0x6080000U 291 292/** bits in IMMUTABLE mask: 293 * document omitted */ 294#define OPTST_IMMUTABLE_MASK 0x0280000U 295 296/** bits in DO_NOT_SAVE mask: 297 * document omitted no_init */ 298#define OPTST_DO_NOT_SAVE_MASK 0x0280100U 299 300/** bits in NO_OUTPUT mask: 301 * document omitted alias */ 302#define OPTST_NO_OUTPUT_MASK 0x8280000U 303 304/** all bits in opt_state_mask_t masks */ 305#define OPTST_MASK_ALL 0xFFFFF7FU 306 307/** no bits in opt_state_mask_t */ 308#define OPTST_INIT 0x0000000U 309/** @} */ 310 311#ifdef NO_OPTIONAL_OPT_ARGS 312# undef OPTST_ARG_OPTIONAL 313# define OPTST_ARG_OPTIONAL 0 314#endif 315 316#define VENDOR_OPTION_VALUE 'W' 317 318#define SELECTED_OPT(_od) ((_od)->fOptState & OPTST_SELECTED_MASK) 319#define UNUSED_OPT( _od) (((_od)->fOptState & OPTST_SET_MASK) == 0) 320#define DISABLED_OPT(_od) ((_od)->fOptState & OPTST_DISABLED) 321#define OPTION_STATE(_od) ((_od)->fOptState) 322#define OPTST_SET_ARGTYPE(_n) ((_n) << OPTST_ARG_TYPE_SHIFT) 323#define OPTST_GET_ARGTYPE(_f) \ 324 (((_f)&OPTST_ARG_TYPE_MASK) >> OPTST_ARG_TYPE_SHIFT) 325 326/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 327 * 328 * PRIVATE INTERFACES 329 * 330 * The following values are used in the generated code to communicate 331 * with the option library procedures. They are not for public use 332 * and may be subject to change. 333 */ 334 335/** 336 * Define the processing state flags 337 * @{ 338 */ 339 340/** integral type for holding proc_state masks */ 341typedef uint32_t proc_state_mask_t; 342 343/** bits defined for proc_state_mask_t */ 344/** Process long style options */ 345#define OPTPROC_LONGOPT 0x000001U 346/** Process short style "flags" */ 347#define OPTPROC_SHORTOPT 0x000002U 348/** Stop on argument errors */ 349#define OPTPROC_ERRSTOP 0x000004U 350/** Current option is disabled */ 351#define OPTPROC_DISABLEDOPT 0x000008U 352/** no options are required */ 353#define OPTPROC_NO_REQ_OPT 0x000010U 354/** there is a number option */ 355#define OPTPROC_NUM_OPT 0x000020U 356/** have inits been done? */ 357#define OPTPROC_INITDONE 0x000040U 358/** any negation options? */ 359#define OPTPROC_NEGATIONS 0x000080U 360/** check environment? */ 361#define OPTPROC_ENVIRON 0x000100U 362/** Disallow remaining arguments */ 363#define OPTPROC_NO_ARGS 0x000200U 364/** Require args after options */ 365#define OPTPROC_ARGS_REQ 0x000400U 366/** reorder operands after opts */ 367#define OPTPROC_REORDER 0x000800U 368/** emit usage in GNU style */ 369#define OPTPROC_GNUUSAGE 0x001000U 370/** Translate strings in tOptions */ 371#define OPTPROC_TRANSLATE 0x002000U 372/** no usage on usage error */ 373#define OPTPROC_MISUSE 0x004000U 374/** immediate options active */ 375#define OPTPROC_IMMEDIATE 0x008000U 376/** suppress for config only */ 377#define OPTPROC_NXLAT_OPT_CFG 0x010000U 378/** suppress xlation always */ 379#define OPTPROC_NXLAT_OPT 0x020000U 380/** vendor options active */ 381#define OPTPROC_VENDOR_OPT 0x040000U 382/** opt processing in preset state */ 383#define OPTPROC_PRESETTING 0x080000U 384/** Ignore pzFullUsage, compute usage text */ 385#define OPTPROC_COMPUTE 0x100000U 386/** Program outputs digested option state for shell scripts. Usage text 387 * always written to stderr */ 388#define OPTPROC_SHELL_OUTPUT 0x200000U 389 390/** bits in NO_XLAT mask: 391 * nxlat_opt_cfg nxlat_opt */ 392#define OPTPROC_NO_XLAT_MASK 0x030000U 393 394/** all bits in proc_state_mask_t masks */ 395#define OPTPROC_MASK_ALL 0x3FFFFFU 396 397/** no bits in proc_state_mask_t */ 398#define OPTPROC_NONE 0x000000U 399/** @} */ 400 401#define STMTS(s) do { s; } while (false) 402 403/** 404 * Abbreviation for const memory character. 405 */ 406#define tCC char const 407 408/** 409 * Magical values for the program's option pointer 410 * @{ 411 */ 412typedef enum { 413 OP_VAL_EMIT_USAGE = 1, ///< request for usage 414 OP_VAL_EMIT_SHELL = 2, ///< emit value for Bourne shell evaluation 415 OP_VAL_RETURN_VALNAME = 3, ///< return the value as a string 416 OP_VAL_EMIT_LIMIT = 15 ///< limit for magic values 417} opt_proc_vals_t; 418 419/// \a OPT_VAL_EMIT_USAGE cast as a pointer 420#define OPTPROC_EMIT_USAGE ((tOptions *)OP_VAL_EMIT_USAGE) 421 422/// \a OPT_VAL_EMIT_SHELL cast as a pointer 423#define OPTPROC_EMIT_SHELL ((tOptions *)OP_VAL_EMIT_SHELL) 424 425/// \a OPT_VAL_RETURN_VALNAME cast as a pointer 426#define OPTPROC_RETURN_VALNAME ((tOptions *)OP_VAL_RETURN_VALNAME) 427 428/// \a OPT_VAL_EMIT_LIMIT cast as a pointer 429#define OPTPROC_EMIT_LIMIT ((tOptions *)OP_VAL_EMIT_LIMIT) 430/** @} */ 431 432/** group option processing procedure types 433 * @{ 434 */ 435/** forward declaration for tOptDesc */ 436typedef struct opt_desc tOptDesc; 437/** forward declaration for tOptiond */ 438typedef struct options tOptions; 439 440/** 441 * The option procedures do the special processing for each 442 * option flag that needs it. 443 */ 444typedef void (tOptProc)(tOptions * pOpts, tOptDesc * pOptDesc); 445 446/** 447 * a pointer to an option processing procedure 448 */ 449typedef tOptProc * tpOptProc; 450 451/** 452 * The usage procedure will never return. It calls "exit(2)" 453 * with the "exitCode" argument passed to it. 454 */ 455// coverity[+kill] 456typedef void (tUsageProc)(tOptions * pOpts, int exitCode); 457 458/** 459 * a pointer to a procedure that prints usage and exits. 460 */ 461typedef tUsageProc * tpUsageProc; 462/** @} */ 463 464/** 465 * Special definitions. "NOLIMIT" is the 'max' value to use when 466 * a flag may appear multiple times without limit. "NO_EQUIVALENT" 467 * is an illegal value for 'optIndex' (option description index). 468 * @{ 469 */ 470#define NOLIMIT USHRT_MAX ///< no occurrance count limit 471#define OPTION_LIMIT SHRT_MAX ///< maximum number of option types 472/// option index to indicate no equivalance or alias 473#define NO_EQUIVALENT (OPTION_LIMIT+1) 474/** @} */ 475 476/** 477 * Option argument value. Which is valid is determined by: 478 * (fOptState & OPTST_ARG_TYPE_MASK) >> OPTST_ARG_TYPE_SHIFT 479 * which will yield one of the teOptArgType values. 480 */ 481typedef union { 482 char const * argString; ///< as a string 483 uintptr_t argEnum; ///< as an enumeration value 484 uintptr_t argIntptr; ///< as an integer big enough to hold pointer 485 long argInt; ///< as a long integer 486 unsigned long argUint; ///< as an unsigned long ingeger 487 unsigned int argBool; ///< as a boolean value 488 FILE * argFp; ///< as a FILE * pointer 489 int argFd; ///< as a file descriptor (int) 490} opt_arg_union_t; 491 492/// Compatibility define: \a pzLastArg is now \a optArg.argString 493#define pzLastArg optArg.argString 494/// The old amorphous argument bucket is now the opt_arg_union_t union. 495#define optArgBucket_t opt_arg_union_t 496 497/** 498 * Enumeration of AutoOpts defined options. The enumeration is used in 499 * marking each option that is defined by AutoOpts so libopts can find 500 * the correct descriptor. This renders \a option_spec_idx_t redundant. 501 */ 502typedef enum { 503 AOUSE_USER_DEFINED = 0, ///< user specified option 504 AOUSE_RESET_OPTION, ///< reset option state option 505 AOUSE_VERSION, ///< request version 506 AOUSE_HELP, ///< request usage help 507 AOUSE_MORE_HELP, ///< request paged usage 508 AOUSE_USAGE, ///< request short usage 509 AOUSE_SAVE_OPTS, ///< save option state 510 AOUSE_LOAD_OPTS, ///< load options from file 511 AOUSE_VENDOR_OPT ///< specify a vendor option 512} opt_usage_t; 513 514/** 515 * Descriptor structure for each option. 516 * Only the fields marked "PUBLIC" are for public use. 517 */ 518struct opt_desc { 519 /// Public, the index of this descriptor 520 uint16_t const optIndex; 521 /// Public, the flag character (value) 522 uint16_t const optValue; 523 /// Public, the index of the option used to activate option 524 uint16_t optActualIndex; 525 /// Public, the flag character of the activating option 526 uint16_t optActualValue; 527 528 /// Public, the index of the equivalenced-to option. 529 /// This is NO_EQUIVALENT unless activated. 530 uint16_t const optEquivIndex; 531 /// Private, the minimum occurrance count 532 uint16_t const optMinCt; 533 /// Private, the maximum occurrance count (NOLIMIT, if unlimited) 534 uint16_t const optMaxCt; 535 /// Public, the actual occurrance count 536 uint16_t optOccCt; 537 538 /// Public, the option processing state 539 opt_state_mask_t fOptState; 540 /// Private, how the option is used (opt_usage_t) 541 uint32_t optUsage; 542 /// Public, The current option argument value 543 opt_arg_union_t optArg; 544 /// Public, data that is actually private to the code that handles 545 /// this particular option. It is public IFF you have your own 546 /// handling function. 547 void * optCookie; 548 549 /// Private, a list of options that must be specified when this option 550 /// has been specified 551 int const * const pOptMust; 552 553 /// Private, a list of options that cannot be specified when this option 554 /// has been specified 555 int const * const pOptCant; 556 557 /// Private, the function to call for handling this option 558 tpOptProc const pOptProc; 559 560 /// Private, usage information about this option 561 char const * const pzText; 562 563 /// Public, the UPPER CASE, shell variable name syntax name of the option 564 char const * const pz_NAME; 565 566 /// the unmodified name of the option 567 char const * const pz_Name; 568 569 /// the option name to use to disable the option. Long options names 570 /// must be active. 571 char const * const pz_DisableName; 572 573 /// the special prefix that makes the normal option name become the 574 /// disablement name. 575 char const * const pz_DisablePfx; 576}; 577 578/** 579 * Some options need special processing, so we store their 580 * indexes in a known place. 581 */ 582typedef struct { 583 uint16_t const more_help; ///< passes help text through pager 584 uint16_t const save_opts; ///< stores option state to a file 585 uint16_t const number_option; ///< the option "name" is an integer 586 /// all arguments are options, this is the default option that must 587 /// take an argument. That argument is the unrecognized option. 588 uint16_t const default_opt; 589} option_spec_idx_t; 590 591/** 592 * The procedure generated for translating option text 593 */ 594typedef void (tOptionXlateProc)(void); 595 596/** 597 * Everything marked "PUBLIC" is also marked "const". Public access is not 598 * a license to modify. Other fields are used and modified by the library. 599 * They are also subject to change without any notice. 600 * Do not even look at these outside of libopts. 601 */ 602struct options { 603 int const structVersion; ///< The version of this struct 604 unsigned int origArgCt; ///< program argument count 605 char ** origArgVect; ///< program argument vector 606 proc_state_mask_t fOptSet; ///< option proc. state flags 607 unsigned int curOptIdx; ///< current option index 608 char * pzCurOpt; ///< current option text 609 610 /// Public, the full path of the program 611 char const * const pzProgPath; 612 /// Public, the name of the executable, without any path 613 char const * const pzProgName; 614 /// Public, the upper-cased, shell variable syntax-ed program name 615 char const * const pzPROGNAME; 616 /// the name of the "rc file" (configuration file) 617 char const * const pzRcName; 618 /// the copyright text 619 char const * const pzCopyright; 620 /// the full copyright notice 621 char const * const pzCopyNotice; 622 /// a string with the program name, project name and version 623 char const * const pzFullVersion; 624 /// a list of pointers to directories to search for the config file 625 char const * const * const papzHomeList; 626 /// the title line for usage 627 char const * const pzUsageTitle; 628 /// some added explanation for what this program is trying to do 629 char const * const pzExplain; 630 /// a detailed explanation of the program's purpose, for use when 631 /// full help has been requested 632 char const * const pzDetail; 633 /// The public array of option descriptors 634 tOptDesc * const pOptDesc; 635 /// the email address for reporting bugs 636 char const * const pzBugAddr; 637 638 /// Reserved for future use 639 void * pExtensions; 640 /// A copy of the option state when optionSaveState was called. 641 void * pSavedState; 642 643 /// The procedure to call to print usage text 644 // coverity[+kill] 645 tpUsageProc pUsageProc; 646 /// The procedure to call to translate translatable option messages 647 tOptionXlateProc * pTransProc; 648 649 /// Special option indexes. 650 option_spec_idx_t specOptIdx; 651 /// the total number of options for the program 652 int const optCt; 653 /// The number of "presettable" options, though some may be marked 654 /// "no-preset". Includes all user specified options, plus a few 655 /// that are specified by AutoOpts. 656 int const presetOptCt; 657 /// user specified full usage text 658 char const * pzFullUsage; 659 /// user specifed short usage (usage error triggered) message 660 char const * pzShortUsage; 661 /// The option argument settings active when optionSaveState was called 662 opt_arg_union_t const * const originalOptArgArray; 663 /// any saved cookie value 664 void * const * const originalOptArgCookie; 665 /// the package data directory (e.g. global configuration files) 666 char const * const pzPkgDataDir; 667 /// email address of the project packager 668 char const * const pzPackager; 669}; 670 671/* 672 * Versions where in various fields first appear: 673 * ($AO_CURRENT * 4096 + $AO_REVISION, but $AO_REVISION must be zero) 674 */ 675/** 676 * The version that first stored the original argument vector 677 */ 678#define originalOptArgArray_STRUCT_VERSION 0x20000 /* AO_CURRENT = 32 */ 679#define HAS_originalOptArgArray(_opt) \ 680 ((_opt)->structVersion >= originalOptArgArray_STRUCT_VERSION) 681 682/** 683 * The version that first stored the package data directory 684 */ 685#define pzPkgDataDir_STRUCT_VERSION 0x22000 /* AO_CURRENT = 34 */ 686#define HAS_pzPkgDataDir(_opt) \ 687 ((_opt)->structVersion >= pzPkgDataDir_STRUCT_VERSION) 688 689/** 690 * The version that first stored the option usage in each option descriptor 691 */ 692#define opt_usage_t_STRUCT_VERSION 0x26000 /* AO_CURRENT = 38 */ 693#define HAS_opt_usage_t(_opt) \ 694 ((_opt)->structVersion >= opt_usage_t_STRUCT_VERSION) 695 696/** 697 * "token list" structure returned by "string_tokenize()" 698 */ 699typedef struct { 700 unsigned long tkn_ct; ///< number of tokens found 701 unsigned char * tkn_list[1]; ///< array of pointers to tokens 702} token_list_t; 703 704/* 705 * Hide the interface - it pollutes a POSIX claim, but leave it for 706 * anyone #include-ing this header 707 */ 708#define strneqvcmp option_strneqvcmp 709#define streqvcmp option_streqvcmp 710#define streqvmap option_streqvmap 711#define strequate option_strequate 712#define strtransform option_strtransform 713 714/** 715 * Everything needed to be known about an mmap-ed file. 716 * 717 * This is an output only structure used by text_mmap and text_munmap. 718 * Clients must not alter the contents and must provide it to both 719 * the text_mmap and text_munmap procedures. BE ADVISED: if you are 720 * mapping the file with PROT_WRITE the NUL byte at the end MIGHT NOT 721 * BE WRITABLE. In any event, that byte is not be written back 722 * to the source file. ALSO: if "txt_data" is valid and "txt_errno" 723 * is not zero, then there *may* not be a terminating NUL. 724 */ 725typedef struct { 726 void * txt_data; ///< text file data 727 size_t txt_size; ///< actual file size 728 size_t txt_full_size; ///< mmaped mem size 729 int txt_fd; ///< file descriptor 730 int txt_zero_fd; ///< fd for /dev/zero 731 int txt_errno; ///< warning code 732 int txt_prot; ///< "prot" flags 733 int txt_flags; ///< mapping type 734} tmap_info_t; 735 736/** 737 * mmap result wrapper that yields "true" when mmap has failed. 738 */ 739#define TEXT_MMAP_FAILED_ADDR(a) (VOIDP(a) == VOIDP(MAP_FAILED)) 740 741#ifdef __cplusplus 742#define CPLUSPLUS_OPENER extern "C" { 743CPLUSPLUS_OPENER 744#define CPLUSPLUS_CLOSER } 745#else 746#define CPLUSPLUS_CLOSER 747#endif 748 749/** 750 * The following routines may be coded into AutoOpts client code: 751 */ 752 753/** 754 * ao_string_tokenize - tokenize an input string 755 * 756 * This function will convert one input string into a list of strings. 757 * The list of strings is derived by separating the input based on 758 * white space separation. However, if the input contains either single 759 * or double quote characters, then the text after that character up to 760 * a matching quote will become the string in the list. 761 * 762 * The returned pointer should be deallocated with @code{free(3C)} when 763 * are done using the data. The data are placed in a single block of 764 * allocated memory. Do not deallocate individual token/strings. 765 * 766 * The structure pointed to will contain at least these two fields: 767 * @table @samp 768 * @item tkn_ct 769 * The number of tokens found in the input string. 770 * @item tok_list 771 * An array of @code{tkn_ct + 1} pointers to substring tokens, with 772 * the last pointer set to NULL. 773 * @end table 774 * 775 * There are two types of quoted strings: single quoted (@code{'}) and 776 * double quoted (@code{"}). Singly quoted strings are fairly raw in that 777 * escape characters (@code{\\}) are simply another character, except when 778 * preceding the following characters: 779 * @example 780 * @code{\\} double backslashes reduce to one 781 * @code{'} incorporates the single quote into the string 782 * @code{\n} suppresses both the backslash and newline character 783 * @end example 784 * 785 * Double quote strings are formed according to the rules of string 786 * constants in ANSI-C programs. 787 * 788 * @param string string to be tokenized 789 * 790 * @return token_list_t * - pointer to a structure that lists each token 791 */ 792extern token_list_t * ao_string_tokenize(char const *); 793 794 795/** 796 * configFileLoad - parse a configuration file 797 * 798 * This routine will load a named configuration file and parse the 799 * text as a hierarchically valued option. The option descriptor 800 * created from an option definition file is not used via this interface. 801 * The returned value is "named" with the input file name and is of 802 * type "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to 803 * @code{optionGetValue()}, @code{optionNextValue()} and 804 * @code{optionUnloadNested()}. 805 * 806 * @param fname the file to load 807 * 808 * @return const tOptionValue * - An allocated, compound value structure 809 */ 810extern const tOptionValue * configFileLoad(char const *); 811 812 813/** 814 * optionFileLoad - Load the locatable config files, in order 815 * 816 * This function looks in all the specified directories for a configuration 817 * file ("rc" file or "ini" file) and processes any found twice. The first 818 * time through, they are processed in reverse order (last file first). At 819 * that time, only "immediate action" configurables are processed. For 820 * example, if the last named file specifies not processing any more 821 * configuration files, then no more configuration files will be processed. 822 * Such an option in the @strong{first} named directory will have no effect. 823 * 824 * Once the immediate action configurables have been handled, then the 825 * directories are handled in normal, forward order. In that way, later 826 * config files can override the settings of earlier config files. 827 * 828 * See the AutoOpts documentation for a thorough discussion of the 829 * config file format. 830 * 831 * Configuration files not found or not decipherable are simply ignored. 832 * 833 * @param opts program options descriptor 834 * @param prog program name 835 * 836 * @return int - 0 -> SUCCESS, -1 -> FAILURE 837 */ 838extern int optionFileLoad(tOptions *, char const *); 839 840 841/** 842 * optionFindNextValue - find a hierarcicaly valued option instance 843 * 844 * This routine will find the next entry in a nested value option or 845 * configurable. It will search through the list and return the next entry 846 * that matches the criteria. 847 * 848 * @param odesc an option with a nested arg type 849 * @param pPrevVal the last entry 850 * @param name name of value to find 851 * @param value the matching value 852 * 853 * @return const tOptionValue * - a compound value structure 854 */ 855extern const tOptionValue * optionFindNextValue(const tOptDesc *, const tOptionValue *, char const *, char const *); 856 857 858/** 859 * optionFindValue - find a hierarcicaly valued option instance 860 * 861 * This routine will find an entry in a nested value option or configurable. 862 * It will search through the list and return a matching entry. 863 * 864 * @param odesc an option with a nested arg type 865 * @param name name of value to find 866 * @param val the matching value 867 * 868 * @return const tOptionValue * - a compound value structure 869 */ 870extern const tOptionValue * optionFindValue(const tOptDesc *, char const *, char const *); 871 872 873/** 874 * optionFree - free allocated option processing memory 875 * 876 * AutoOpts sometimes allocates memory and puts pointers to it in the 877 * option state structures. This routine deallocates all such memory. 878 * 879 * @param pOpts program options descriptor 880 */ 881extern void optionFree(tOptions *); 882 883 884/** 885 * optionGetValue - get a specific value from a hierarcical list 886 * 887 * This routine will find an entry in a nested value option or configurable. 888 * If "valueName" is NULL, then the first entry is returned. Otherwise, 889 * the first entry with a name that exactly matches the argument will be 890 * returned. If there is no matching value, NULL is returned and errno is 891 * set to ENOENT. If the provided option value is not a hierarchical value, 892 * NULL is also returned and errno is set to EINVAL. 893 * 894 * @param pOptValue a hierarchcal value 895 * @param valueName name of value to get 896 * 897 * @return const tOptionValue * - a compound value structure 898 */ 899extern const tOptionValue * optionGetValue(const tOptionValue *, char const *); 900 901 902/** 903 * optionLoadLine - process a string for an option name and value 904 * 905 * This is a client program callable routine for setting options from, for 906 * example, the contents of a file that they read in. Only one option may 907 * appear in the text. It will be treated as a normal (non-preset) option. 908 * 909 * When passed a pointer to the option struct and a string, it will find 910 * the option named by the first token on the string and set the option 911 * argument to the remainder of the string. The caller must NUL terminate 912 * the string. The caller need not skip over any introductory hyphens. 913 * Any embedded new lines will be included in the option 914 * argument. If the input looks like one or more quoted strings, then the 915 * input will be "cooked". The "cooking" is identical to the string 916 * formation used in AutoGen definition files (@pxref{basic expression}), 917 * except that you may not use backquotes. 918 * 919 * @param opts program options descriptor 920 * @param line NUL-terminated text 921 */ 922extern void optionLoadLine(tOptions *, char const *); 923 924 925/** 926 * optionMemberList - Get the list of members of a bit mask set 927 * 928 * This converts the OPT_VALUE_name mask value to a allocated string. 929 * It is the caller's responsibility to free the string. 930 * 931 * @param od the set membership option description 932 * 933 * @return char * - the names of the set bits 934 */ 935extern char * optionMemberList(tOptDesc *); 936 937 938/** 939 * optionNextValue - get the next value from a hierarchical list 940 * 941 * This routine will return the next entry after the entry passed in. At the 942 * end of the list, NULL will be returned. If the entry is not found on the 943 * list, NULL will be returned and "@var{errno}" will be set to EINVAL. 944 * The "@var{pOldValue}" must have been gotten from a prior call to this 945 * routine or to "@code{opitonGetValue()}". 946 * 947 * @param pOptValue a hierarchcal list value 948 * @param pOldValue a value from this list 949 * 950 * @return const tOptionValue * - a compound value structure 951 */ 952extern const tOptionValue * optionNextValue(const tOptionValue *, const tOptionValue *); 953 954 955/** 956 * optionOnlyUsage - Print usage text for just the options 957 * 958 * This routine will print only the usage for each option. 959 * This function may be used when the emitted usage must incorporate 960 * information not available to AutoOpts. 961 * 962 * @param pOpts program options descriptor 963 * @param ex_code exit code for calling exit(3) 964 */ 965extern void optionOnlyUsage(tOptions *, int); 966 967 968/** 969 * optionPrintVersion - Print the program version 970 * 971 * This routine will print the version to stdout. 972 * 973 * @param opts program options descriptor 974 * @param od the descriptor for this arg 975 */ 976extern void optionPrintVersion(tOptions *, tOptDesc *); 977 978 979/** 980 * optionPrintVersionAndReturn - Print the program version 981 * 982 * This routine will print the version to stdout and return 983 * instead of exiting. Please see the source for the 984 * @code{print_ver} funtion for details on selecting how 985 * verbose to be after this function returns. 986 * 987 * @param opts program options descriptor 988 * @param od the descriptor for this arg 989 */ 990extern void optionPrintVersionAndReturn(tOptions *, tOptDesc *); 991 992 993/** 994 * optionProcess - this is the main option processing routine 995 * 996 * This is the main entry point for processing options. It is intended 997 * that this procedure be called once at the beginning of the execution of 998 * a program. Depending on options selected earlier, it is sometimes 999 * necessary to stop and restart option processing, or to select completely 1000 * different sets of options. This can be done easily, but you generally 1001 * do not want to do this. 1002 * 1003 * The number of arguments processed always includes the program name. 1004 * If one of the arguments is "--", then it is counted and the processing 1005 * stops. If an error was encountered and errors are to be tolerated, then 1006 * the returned value is the index of the argument causing the error. 1007 * A hyphen by itself ("-") will also cause processing to stop and will 1008 * @emph{not} be counted among the processed arguments. A hyphen by itself 1009 * is treated as an operand. Encountering an operand stops option 1010 * processing. 1011 * 1012 * @param opts program options descriptor 1013 * @param a_ct program arg count 1014 * @param a_v program arg vector 1015 * 1016 * @return int - the count of the arguments processed 1017 */ 1018extern int optionProcess(tOptions *, int, char **); 1019 1020 1021/** 1022 * optionRestore - restore option state from memory copy 1023 * 1024 * Copy back the option state from saved memory. 1025 * The allocated memory is left intact, so this routine can be 1026 * called repeatedly without having to call optionSaveState again. 1027 * If you are restoring a state that was saved before the first call 1028 * to optionProcess(3AO), then you may change the contents of the 1029 * argc/argv parameters to optionProcess. 1030 * 1031 * @param pOpts program options descriptor 1032 */ 1033extern void optionRestore(tOptions *); 1034 1035 1036/** 1037 * optionSaveFile - saves the option state to a file 1038 * 1039 * This routine will save the state of option processing to a file. The name 1040 * of that file can be specified with the argument to the @code{--save-opts} 1041 * option, or by appending the @code{rcfile} attribute to the last 1042 * @code{homerc} attribute. If no @code{rcfile} attribute was specified, it 1043 * will default to @code{.@i{programname}rc}. If you wish to specify another 1044 * file, you should invoke the @code{SET_OPT_SAVE_OPTS(@i{filename})} macro. 1045 * 1046 * The recommend usage is as follows: 1047 * @example 1048 * optionProcess(&progOptions, argc, argv); 1049 * if (i_want_a_non_standard_place_for_this) 1050 * SET_OPT_SAVE_OPTS("myfilename"); 1051 * optionSaveFile(&progOptions); 1052 * @end example 1053 * 1054 * @param opts program options descriptor 1055 */ 1056extern void optionSaveFile(tOptions *); 1057 1058 1059/** 1060 * optionSaveState - saves the option state to memory 1061 * 1062 * This routine will allocate enough memory to save the current option 1063 * processing state. If this routine has been called before, that memory 1064 * will be reused. You may only save one copy of the option state. This 1065 * routine may be called before optionProcess(3AO). If you do call it 1066 * before the first call to optionProcess, then you may also change the 1067 * contents of argc/argv after you call optionRestore(3AO) 1068 * 1069 * In fact, more strongly put: it is safest to only use this function 1070 * before having processed any options. In particular, the saving and 1071 * restoring of stacked string arguments and hierarchical values is 1072 * disabled. The values are not saved. 1073 * 1074 * @param pOpts program options descriptor 1075 */ 1076extern void optionSaveState(tOptions *); 1077 1078 1079/** 1080 * optionUnloadNested - Deallocate the memory for a nested value 1081 * 1082 * A nested value needs to be deallocated. The pointer passed in should 1083 * have been gotten from a call to @code{configFileLoad()} (See 1084 * @pxref{libopts-configFileLoad}). 1085 * 1086 * @param pOptVal the hierarchical value 1087 */ 1088extern void optionUnloadNested(tOptionValue const *); 1089 1090 1091/** 1092 * optionVersion - return the compiled AutoOpts version number 1093 * 1094 * Returns the full version string compiled into the library. 1095 * The returned string cannot be modified. 1096 * 1097 * @return char const * - the version string in constant memory 1098 */ 1099extern char const * optionVersion(void); 1100 1101 1102/** 1103 * strequate - map a list of characters to the same value 1104 * 1105 * Each character in the input string get mapped to the first character 1106 * in the string. 1107 * This function name is mapped to option_strequate so as to not conflict 1108 * with the POSIX name space. 1109 * 1110 * @param ch_list characters to equivalence 1111 */ 1112extern void strequate(char const *); 1113 1114 1115/** 1116 * streqvcmp - compare two strings with an equivalence mapping 1117 * 1118 * Using a character mapping, two strings are compared for "equivalence". 1119 * Each input character is mapped to a comparison character and the 1120 * mapped-to characters are compared for the two NUL terminated input strings. 1121 * This function name is mapped to option_streqvcmp so as to not conflict 1122 * with the POSIX name space. 1123 * 1124 * @param str1 first string 1125 * @param str2 second string 1126 * 1127 * @return int - the difference between two differing characters 1128 */ 1129extern int streqvcmp(char const *, char const *); 1130 1131 1132/** 1133 * streqvmap - Set the character mappings for the streqv functions 1134 * 1135 * Set the character mapping. If the count (@code{ct}) is set to zero, then 1136 * the map is cleared by setting all entries in the map to their index 1137 * value. Otherwise, the "@code{From}" character is mapped to the "@code{To}" 1138 * character. If @code{ct} is greater than 1, then @code{From} and @code{To} 1139 * are incremented and the process repeated until @code{ct} entries have been 1140 * set. For example, 1141 * @example 1142 * streqvmap('a', 'A', 26); 1143 * @end example 1144 * @noindent 1145 * will alter the mapping so that all English lower case letters 1146 * will map to upper case. 1147 * 1148 * This function name is mapped to option_streqvmap so as to not conflict 1149 * with the POSIX name space. 1150 * 1151 * @param from Input character 1152 * @param to Mapped-to character 1153 * @param ct compare length 1154 */ 1155extern void streqvmap(char, char, int); 1156 1157 1158/** 1159 * strneqvcmp - compare two strings with an equivalence mapping 1160 * 1161 * Using a character mapping, two strings are compared for "equivalence". 1162 * Each input character is mapped to a comparison character and the 1163 * mapped-to characters are compared for the two NUL terminated input strings. 1164 * The comparison is limited to @code{ct} bytes. 1165 * This function name is mapped to option_strneqvcmp so as to not conflict 1166 * with the POSIX name space. 1167 * 1168 * @param str1 first string 1169 * @param str2 second string 1170 * @param ct compare length 1171 * 1172 * @return int - the difference between two differing characters 1173 */ 1174extern int strneqvcmp(char const *, char const *, int); 1175 1176 1177/** 1178 * strtransform - convert a string into its mapped-to value 1179 * 1180 * Each character in the input string is mapped and the mapped-to 1181 * character is put into the output. 1182 * This function name is mapped to option_strtransform so as to not conflict 1183 * with the POSIX name space. 1184 * 1185 * The source and destination may be the same. 1186 * 1187 * @param dest output string 1188 * @param src input string 1189 */ 1190extern void strtransform(char *, char const *); 1191 1192/* AutoOpts PRIVATE FUNCTIONS: */ 1193tOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal; 1194 1195extern char * ao_string_cook(char *, int *); 1196 1197extern unsigned int ao_string_cook_escape_char(char const *, char *, unsigned int); 1198 1199extern void genshelloptUsage(tOptions *, int); 1200 1201extern int optionAlias(tOptions *, tOptDesc *, unsigned int); 1202 1203extern void optionBooleanVal(tOptions *, tOptDesc *); 1204 1205extern uintptr_t optionEnumerationVal(tOptions *, tOptDesc *, char const * const *, unsigned int); 1206 1207extern void optionFileCheck(tOptions *, tOptDesc *, teOptFileType, tuFileMode); 1208 1209extern char const * optionKeywordName(tOptDesc *, unsigned int); 1210 1211extern void optionLoadOpt(tOptions *, tOptDesc *); 1212 1213extern bool optionMakePath(char *, int, char const *, char const *); 1214 1215extern void optionNestedVal(tOptions *, tOptDesc *); 1216 1217extern void optionNumericVal(tOptions *, tOptDesc *); 1218 1219extern void optionPagedUsage(tOptions *, tOptDesc *); 1220 1221extern void optionParseShell(tOptions *); 1222 1223extern void optionPrintParagraphs(char const *, bool, FILE *); 1224 1225extern void optionPutShell(tOptions *); 1226 1227extern char const * optionQuoteString(char const *, char const *); 1228 1229extern void optionResetOpt(tOptions *, tOptDesc *); 1230 1231extern void optionSetMembers(tOptions *, tOptDesc *, char const * const *, unsigned int); 1232 1233extern void optionShowRange(tOptions *, tOptDesc *, void *, int); 1234 1235extern void optionStackArg(tOptions *, tOptDesc *); 1236 1237extern void optionTimeDate(tOptions *, tOptDesc *); 1238 1239extern void optionTimeVal(tOptions *, tOptDesc *); 1240 1241extern void optionUnstackArg(tOptions *, tOptDesc *); 1242 1243extern void optionUsage(tOptions *, int); 1244 1245extern void optionVendorOption(tOptions *, tOptDesc *); 1246 1247extern void optionVersionStderr(tOptions *, tOptDesc *); 1248 1249extern void * text_mmap(char const *, int, int, tmap_info_t *); 1250 1251extern int text_munmap(tmap_info_t *); 1252 1253CPLUSPLUS_CLOSER 1254#endif /* AUTOOPTS_OPTIONS_H_GUARD */ 1255/** @} 1256 * 1257 * Local Variables: 1258 * c-file-style: "stroustrup" 1259 * indent-tabs-mode: nil 1260 * End: 1261 * options.h ends here */ 1262