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