1181834Sroberto/* -*- buffer-read-only: t -*- vi: set ro: 2280849Scy * 3181834Sroberto * DO NOT EDIT THIS FILE (options.h) 4280849Scy * 5285169Scy * It has been AutoGen-ed 6181834Sroberto * From the definitions funcs.def 7181834Sroberto * and the template file options_h 8181834Sroberto * 9181834Sroberto * This file defines all the global structures and special values 10181834Sroberto * used in the automated option processing library. 11181834Sroberto * 12285169Scy * Automated Options Copyright (C) 1992-2015 by Bruce Korb 13181834Sroberto * 14280849Scy * This file is part of AutoOpts, a companion to AutoGen. 15280849Scy * AutoOpts is free software. 16285169Scy * AutoOpts is Copyright (C) 1992-2015 by Bruce Korb - all rights reserved 17280849Scy * 18280849Scy * AutoOpts is available under any one of two licenses. The license 19280849Scy * in use must be one of these two and the choice is under the control 20280849Scy * of the user of the license. 21280849Scy * 22280849Scy * The GNU Lesser General Public License, version 3 or later 23280849Scy * See the files "COPYING.lgplv3" and "COPYING.gplv3" 24280849Scy * 25280849Scy * The Modified Berkeley Software Distribution License 26280849Scy * See the file "COPYING.mbsd" 27280849Scy * 28280849Scy * These files have the following sha256 sums: 29280849Scy * 30280849Scy * 8584710e9b04216a394078dc156b781d0b47e1729104d666658aecef8ee32e95 COPYING.gplv3 31280849Scy * 4379e7444a0e2ce2b12dd6f5a52a27a4d02d39d247901d3285c88cf0d37f477b COPYING.lgplv3 32280849Scy * 13aa749a5b0a454917a944ed8fffc530b784f5ead522b1aacaf4ec8aa55a6239 COPYING.mbsd 33181834Sroberto */ 34181834Sroberto#ifndef AUTOOPTS_OPTIONS_H_GUARD 35280849Scy#define AUTOOPTS_OPTIONS_H_GUARD 1 36280849Scy/** \file options.h 37280849Scy * 38280849Scy * @addtogroup autoopts 39280849Scy * @{ 40280849Scy */ 41181834Sroberto#include <sys/types.h> 42280849Scy#include <stdio.h> 43181834Sroberto 44280849Scy#ifndef COMPAT_H_GUARD 45280849Scy/* 46280849Scy * This is needed for test compilations where the "compat.h" 47280849Scy * header is not usually available. 48280849Scy */ 49280849Scy# if defined(HAVE_STDINT_H) 50280849Scy# include <stdint.h> 51280849Scy# elif defined(HAVE_INTTYPES_H) 52280849Scy# include <inttypes.h> 53280849Scy# endif /* HAVE_STDINT/INTTYPES_H */ 54181834Sroberto 55280849Scy# if defined(HAVE_LIMITS_H) 56280849Scy# include <limits.h> 57280849Scy# elif defined(HAVE_SYS_LIMITS_H) 58280849Scy# include <sys/limits.h> 59280849Scy# endif /* HAVE_LIMITS/SYS_LIMITS_H */ 60181834Sroberto 61280849Scy# if defined(HAVE_SYSEXITS_H) 62280849Scy# include <sysexits.h> 63280849Scy# endif /* HAVE_SYSEXITS_H */ 64181834Sroberto 65280849Scy# if defined(HAVE_STDBOOL_H) 66280849Scy# include <stdbool.h> 67280849Scy# else 68280849Scy typedef enum { false = 0, true = 1 } _Bool; 69280849Scy# define bool _Bool 70181834Sroberto 71280849Scy /* The other macros must be usable in preprocessor directives. */ 72280849Scy# define false 0 73280849Scy# define true 1 74280849Scy# endif /* HAVE_SYSEXITS_H */ 75280849Scy#endif /* COMPAT_H_GUARD */ 76280849Scy// END-CONFIGURED-HEADERS 77280849Scy 78280849Scy/** 79280849Scy * Defined to abnormal value of EX_USAGE. Used to indicate that paged usage 80280849Scy * was requested. It is used to distinguish a --usage from a --help request. 81280849Scy * --usage is abbreviated and --help gives as much help as possible. 82280849Scy */ 83280849Scy#define AO_EXIT_REQ_USAGE 10064 84280849Scy 85285169Scy#undef VOIDP 86280849Scy/** 87285169Scy * Coerce a value into a void pointer with no const or volatile attributes. 88285169Scy * Somewhere along the line, the above set of includes need to set up 89285169Scy * the "uintptr_t" type. 90285169Scy */ 91285169Scy#define VOIDP(_a) ((void *)(uintptr_t)(_a)) 92285169Scy 93285169Scy/** 94181834Sroberto * PUBLIC DEFINES 95181834Sroberto * 96181834Sroberto * The following defines may be used in applications that need to test the 97181834Sroberto * state of an option. To test against these masks and values, a pointer 98181834Sroberto * to an option descriptor must be obtained. There are two ways: 99181834Sroberto * 100181834Sroberto * 1. inside an option processing procedure, it is the second argument, 101285169Scy * conventionally "tOptDesc * pOD". 102181834Sroberto * 103280849Scy * 2. Outside of an option procedure (or to reference a different option 104280849Scy * descriptor), use either "&DESC( opt_name )" or "&pfx_DESC( opt_name )". 105181834Sroberto * 106181834Sroberto * See the relevant generated header file to determine which and what 107181834Sroberto * values for "opt_name" are available. 108280849Scy * @group version 109280849Scy * @{ 110181834Sroberto */ 111280849Scy/// autoopts structure version 112280849Scy#define OPTIONS_STRUCT_VERSION 167936 113280849Scy/// autoopts structure version string 114280849Scy#define OPTIONS_VERSION_STRING "41:0:16" 115280849Scy/// minimum version the autoopts library supports 116280849Scy#define OPTIONS_MINIMUM_VERSION 102400 117280849Scy/// minimum version the autoopts library supports as a string 118280849Scy#define OPTIONS_MIN_VER_STRING "25:0:0" 119280849Scy/// the display version of the autoopts library, as a string 120280849Scy#define OPTIONS_DOTTED_VERSION "41.0" 121280849Scy/// convert a version/release number pair to an integer value 122280849Scy#define OPTIONS_VER_TO_NUM(_v, _r) (((_v) * 4096) + (_r)) 123280849Scy/// @} 124181834Sroberto 125280849Scy/** 126280849Scy * Option argument types. This must fit in the OPTST_ARG_TYPE_MASK 127280849Scy * field of the fOptState field of an option descriptor (tOptDesc). 128280849Scy * It will be a problem to extend beyond 4 bits. 129280849Scy */ 130181834Srobertotypedef enum { 131280849Scy OPARG_TYPE_NONE = 0, ///< does not take an argument 132280849Scy OPARG_TYPE_STRING = 1, ///< default type/ vanilla string 133280849Scy OPARG_TYPE_ENUMERATION = 2, ///< opt arg is an enum (keyword list) 134280849Scy OPARG_TYPE_BOOLEAN = 3, ///< opt arg is boolean-valued 135280849Scy OPARG_TYPE_MEMBERSHIP = 4, ///< opt arg sets set membership bits 136280849Scy OPARG_TYPE_NUMERIC = 5, ///< opt arg is a long int 137280849Scy OPARG_TYPE_HIERARCHY = 6, ///< option arg is hierarchical value 138280849Scy OPARG_TYPE_FILE = 7, ///< option arg names a file 139280849Scy OPARG_TYPE_TIME = 8, ///< opt arg is a time duration 140280849Scy OPARG_TYPE_FLOAT = 9, ///< opt arg is a floating point num 141280849Scy OPARG_TYPE_DOUBLE = 10, ///< opt arg is a double prec. float 142280849Scy OPARG_TYPE_LONG_DOUBLE = 11, ///< opt arg is a long double prec. 143280849Scy OPARG_TYPE_LONG_LONG = 12 ///< opt arg is a long long int 144181834Sroberto} teOptArgType; 145181834Sroberto 146280849Scy/** 147280849Scy * value descriptor for sub options 148280849Scy */ 149181834Srobertotypedef struct optionValue { 150280849Scy teOptArgType valType; ///< which argument type 151280849Scy char * pzName; ///< name of the sub-option 152181834Sroberto union { 153280849Scy char strVal[1]; ///< OPARG_TYPE_STRING 154280849Scy unsigned int enumVal; ///< OPARG_TYPE_ENUMERATION 155280849Scy unsigned int boolVal; ///< OPARG_TYPE_BOOLEAN 156280849Scy unsigned long setVal; ///< OPARG_TYPE_MEMBERSHIP 157280849Scy long longVal; ///< OPARG_TYPE_NUMERIC 158285169Scy void * nestVal; ///< OPARG_TYPE_HIERARCHY 159181834Sroberto } v; 160181834Sroberto} tOptionValue; 161181834Sroberto 162280849Scy/** 163280849Scy * file argument state and handling. 164181834Sroberto */ 165181834Srobertotypedef enum { 166280849Scy FTYPE_MODE_MAY_EXIST = 0x00, ///< may or may not exist 167280849Scy FTYPE_MODE_MUST_EXIST = 0x01, ///< must pre-exist 168280849Scy FTYPE_MODE_MUST_NOT_EXIST = 0x02, ///< must *not* pre-exist 169280849Scy FTYPE_MODE_EXIST_MASK = 0x03, ///< mask for these bits 170280849Scy FTYPE_MODE_NO_OPEN = 0x00, ///< leave file closed 171280849Scy FTYPE_MODE_OPEN_FD = 0x10, ///< call open(2) 172280849Scy FTYPE_MODE_FOPEN_FP = 0x20, ///< call fopen(3) 173280849Scy FTYPE_MODE_OPEN_MASK = 0x30 ///< open/fopen/not open 174280849Scy} teOptFileType; 175181834Sroberto 176280849Scy/** 177280849Scy * the open flag bits or the mode string, depending on the open type. 178280849Scy */ 179280849Scytypedef union { 180280849Scy int file_flags; ///< open(2) flag bits 181280849Scy char const * file_mode; ///< fopen(3) mode string 182280849Scy} tuFileMode; 183181834Sroberto 184280849Scy/// initial number of option argument holders to allocate 185280849Scy#define MIN_ARG_ALLOC_CT 6 186280849Scy/// amount by which to increment the argument holder allocation. 187280849Scy#define INCR_ARG_ALLOC_CT 8 188280849Scy/** 189280849Scy * an argument list. When an option appears multiple times and 190280849Scy * the values get "stacked". \a apzArgs holds 8 pointers initially 191280849Scy * and is incremented by \a INCR_ARG_ALLOC_CT as needed. 192280849Scy */ 193280849Scytypedef struct { 194280849Scy int useCt; ///< elements in use 195181834Sroberto 196280849Scy /// allocated elements, mininum \a MIN_ARG_ALLOC_CT 197280849Scy /// steps by \a INCR_ARG_ALLOC_CT 198280849Scy int allocCt; 199280849Scy char const * apzArgs[MIN_ARG_ALLOC_CT]; ///< element array 200280849Scy} tArgList; 201181834Sroberto 202280849Scy/** 203280849Scy * Bits in the fOptState option descriptor field. 204280849Scy * @{ 205280849Scy */ 206181834Sroberto 207280849Scy/** integral type for holding opt_state masks */ 208280849Scytypedef uint32_t opt_state_mask_t; 209181834Sroberto 210280849Scy#define OPTST_ARG_TYPE_SHIFT 12 211280849Scy/** bits defined for opt_state_mask_t */ 212280849Scy/** Set via the "SET_OPT()" macro */ 213280849Scy#define OPTST_SET 0x0000001U 214280849Scy/** Set via an RC/INI file */ 215280849Scy#define OPTST_PRESET 0x0000002U 216280849Scy/** Set via a command line option */ 217280849Scy#define OPTST_DEFINED 0x0000004U 218280849Scy/** Reset via command line option */ 219280849Scy#define OPTST_RESET 0x0000008U 220280849Scy/** selected by equiv'ed option */ 221280849Scy#define OPTST_EQUIVALENCE 0x0000010U 222280849Scy/** option is in disabled state */ 223280849Scy#define OPTST_DISABLED 0x0000020U 224280849Scy/** pzOptArg was allocated */ 225280849Scy#define OPTST_ALLOC_ARG 0x0000040U 226280849Scy/** option cannot be preset */ 227280849Scy#define OPTST_NO_INIT 0x0000100U 228280849Scy/** opt value (flag) is any digit */ 229280849Scy#define OPTST_NUMBER_OPT 0x0000200U 230280849Scy/** opt uses optionStackArg proc */ 231280849Scy#define OPTST_STACKED 0x0000400U 232280849Scy/** option defaults to enabled */ 233280849Scy#define OPTST_INITENABLED 0x0000800U 234280849Scy/** bit 1 of arg type enum */ 235280849Scy#define OPTST_ARG_TYPE_1 0x0001000U 236280849Scy/** bit 2 of arg type enum */ 237280849Scy#define OPTST_ARG_TYPE_2 0x0002000U 238280849Scy/** bit 3 of arg type enum */ 239280849Scy#define OPTST_ARG_TYPE_3 0x0004000U 240280849Scy/** bit 4 of arg type enum */ 241280849Scy#define OPTST_ARG_TYPE_4 0x0008000U 242280849Scy/** the option arg not required */ 243280849Scy#define OPTST_ARG_OPTIONAL 0x0010000U 244280849Scy/** process opt on first pass */ 245280849Scy#define OPTST_IMM 0x0020000U 246280849Scy/** process disablement immed. */ 247280849Scy#define OPTST_DISABLE_IMM 0x0040000U 248280849Scy/** compiled out of program */ 249280849Scy#define OPTST_OMITTED 0x0080000U 250280849Scy/** must be set or pre-set */ 251280849Scy#define OPTST_MUST_SET 0x0100000U 252280849Scy/** opt is for doc only */ 253280849Scy#define OPTST_DOCUMENT 0x0200000U 254280849Scy/** process opt twice - imm + reg */ 255280849Scy#define OPTST_TWICE 0x0400000U 256280849Scy/** process disabled option twice */ 257280849Scy#define OPTST_DISABLE_TWICE 0x0800000U 258280849Scy/** scaled integer value */ 259280849Scy#define OPTST_SCALED_NUM 0x1000000U 260280849Scy/** disable from cmd line */ 261280849Scy#define OPTST_NO_COMMAND 0x2000000U 262280849Scy/** support is being removed */ 263280849Scy#define OPTST_DEPRECATED 0x4000000U 264280849Scy/** alias for other option */ 265280849Scy#define OPTST_ALIAS 0x8000000U 266280849Scy 267280849Scy/** bits in SET mask: 268280849Scy * set preset reset defined */ 269280849Scy#define OPTST_SET_MASK 0x000000FU 270280849Scy 271280849Scy/** bits in MUTABLE mask: 272280849Scy * set preset reset defined equivalence disabled 273280849Scy * alloc_arg */ 274280849Scy#define OPTST_MUTABLE_MASK 0x000007FU 275280849Scy 276280849Scy/** bits omitted from PERSISTENT mask: 277280849Scy * mutable_mask */ 278280849Scy#define OPTST_PERSISTENT_MASK 0xFFFFF00U 279280849Scy 280280849Scy/** bits in SELECTED mask: 281280849Scy * set defined */ 282280849Scy#define OPTST_SELECTED_MASK 0x0000005U 283280849Scy 284280849Scy/** bits in ARG_TYPE mask: 285280849Scy * arg_type_1 arg_type_2 arg_type_3 arg_type_4 */ 286280849Scy#define OPTST_ARG_TYPE_MASK 0x000F000U 287280849Scy 288280849Scy/** bits in NO_USAGE mask: 289280849Scy * omitted no_command deprecated */ 290280849Scy#define OPTST_NO_USAGE_MASK 0x6080000U 291280849Scy 292280849Scy/** bits in IMMUTABLE mask: 293280849Scy * document omitted */ 294280849Scy#define OPTST_IMMUTABLE_MASK 0x0280000U 295280849Scy 296280849Scy/** bits in DO_NOT_SAVE mask: 297280849Scy * document omitted no_init */ 298280849Scy#define OPTST_DO_NOT_SAVE_MASK 0x0280100U 299280849Scy 300280849Scy/** bits in NO_OUTPUT mask: 301280849Scy * document omitted alias */ 302280849Scy#define OPTST_NO_OUTPUT_MASK 0x8280000U 303280849Scy 304280849Scy/** all bits in opt_state_mask_t masks */ 305280849Scy#define OPTST_MASK_ALL 0xFFFFF7FU 306280849Scy 307280849Scy/** no bits in opt_state_mask_t */ 308280849Scy#define OPTST_INIT 0x0000000U 309280849Scy/** @} */ 310280849Scy 311181834Sroberto#ifdef NO_OPTIONAL_OPT_ARGS 312181834Sroberto# undef OPTST_ARG_OPTIONAL 313181834Sroberto# define OPTST_ARG_OPTIONAL 0 314181834Sroberto#endif 315181834Sroberto 316280849Scy#define VENDOR_OPTION_VALUE 'W' 317181834Sroberto 318280849Scy#define SELECTED_OPT(_od) ((_od)->fOptState & OPTST_SELECTED_MASK) 319280849Scy#define UNUSED_OPT( _od) (((_od)->fOptState & OPTST_SET_MASK) == 0) 320280849Scy#define DISABLED_OPT(_od) ((_od)->fOptState & OPTST_DISABLED) 321280849Scy#define OPTION_STATE(_od) ((_od)->fOptState) 322280849Scy#define OPTST_SET_ARGTYPE(_n) ((_n) << OPTST_ARG_TYPE_SHIFT) 323280849Scy#define OPTST_GET_ARGTYPE(_f) \ 324280849Scy (((_f)&OPTST_ARG_TYPE_MASK) >> OPTST_ARG_TYPE_SHIFT) 325181834Sroberto 326280849Scy/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 327280849Scy * 328181834Sroberto * PRIVATE INTERFACES 329181834Sroberto * 330181834Sroberto * The following values are used in the generated code to communicate 331181834Sroberto * with the option library procedures. They are not for public use 332181834Sroberto * and may be subject to change. 333181834Sroberto */ 334181834Sroberto 335280849Scy/** 336181834Sroberto * Define the processing state flags 337280849Scy * @{ 338181834Sroberto */ 339181834Sroberto 340280849Scy/** integral type for holding proc_state masks */ 341280849Scytypedef uint32_t proc_state_mask_t; 342181834Sroberto 343280849Scy/** bits defined for proc_state_mask_t */ 344280849Scy/** Process long style options */ 345280849Scy#define OPTPROC_LONGOPT 0x000001U 346280849Scy/** Process short style "flags" */ 347280849Scy#define OPTPROC_SHORTOPT 0x000002U 348280849Scy/** Stop on argument errors */ 349280849Scy#define OPTPROC_ERRSTOP 0x000004U 350280849Scy/** Current option is disabled */ 351280849Scy#define OPTPROC_DISABLEDOPT 0x000008U 352280849Scy/** no options are required */ 353280849Scy#define OPTPROC_NO_REQ_OPT 0x000010U 354280849Scy/** there is a number option */ 355280849Scy#define OPTPROC_NUM_OPT 0x000020U 356280849Scy/** have inits been done? */ 357280849Scy#define OPTPROC_INITDONE 0x000040U 358280849Scy/** any negation options? */ 359280849Scy#define OPTPROC_NEGATIONS 0x000080U 360280849Scy/** check environment? */ 361280849Scy#define OPTPROC_ENVIRON 0x000100U 362280849Scy/** Disallow remaining arguments */ 363280849Scy#define OPTPROC_NO_ARGS 0x000200U 364280849Scy/** Require args after options */ 365280849Scy#define OPTPROC_ARGS_REQ 0x000400U 366280849Scy/** reorder operands after opts */ 367280849Scy#define OPTPROC_REORDER 0x000800U 368280849Scy/** emit usage in GNU style */ 369280849Scy#define OPTPROC_GNUUSAGE 0x001000U 370280849Scy/** Translate strings in tOptions */ 371280849Scy#define OPTPROC_TRANSLATE 0x002000U 372280849Scy/** no usage on usage error */ 373280849Scy#define OPTPROC_MISUSE 0x004000U 374280849Scy/** immediate options active */ 375280849Scy#define OPTPROC_IMMEDIATE 0x008000U 376280849Scy/** suppress for config only */ 377280849Scy#define OPTPROC_NXLAT_OPT_CFG 0x010000U 378280849Scy/** suppress xlation always */ 379280849Scy#define OPTPROC_NXLAT_OPT 0x020000U 380280849Scy/** vendor options active */ 381280849Scy#define OPTPROC_VENDOR_OPT 0x040000U 382280849Scy/** opt processing in preset state */ 383280849Scy#define OPTPROC_PRESETTING 0x080000U 384280849Scy/** Ignore pzFullUsage, compute usage text */ 385280849Scy#define OPTPROC_COMPUTE 0x100000U 386280849Scy/** Program outputs digested option state for shell scripts. Usage text 387280849Scy * always written to stderr */ 388280849Scy#define OPTPROC_SHELL_OUTPUT 0x200000U 389181834Sroberto 390280849Scy/** bits in NO_XLAT mask: 391280849Scy * nxlat_opt_cfg nxlat_opt */ 392280849Scy#define OPTPROC_NO_XLAT_MASK 0x030000U 393280849Scy 394280849Scy/** all bits in proc_state_mask_t masks */ 395280849Scy#define OPTPROC_MASK_ALL 0x3FFFFFU 396280849Scy 397280849Scy/** no bits in proc_state_mask_t */ 398280849Scy#define OPTPROC_NONE 0x000000U 399280849Scy/** @} */ 400280849Scy 401280849Scy#define STMTS(s) do { s; } while (false) 402280849Scy 403280849Scy/** 404280849Scy * Abbreviation for const memory character. 405181834Sroberto */ 406181834Sroberto#define tCC char const 407181834Sroberto 408280849Scy/** 409280849Scy * Magical values for the program's option pointer 410280849Scy * @{ 411181834Sroberto */ 412280849Scytypedef enum { 413280849Scy OP_VAL_EMIT_USAGE = 1, ///< request for usage 414280849Scy OP_VAL_EMIT_SHELL = 2, ///< emit value for Bourne shell evaluation 415280849Scy OP_VAL_RETURN_VALNAME = 3, ///< return the value as a string 416280849Scy OP_VAL_EMIT_LIMIT = 15 ///< limit for magic values 417280849Scy} opt_proc_vals_t; 418181834Sroberto 419280849Scy/// \a OPT_VAL_EMIT_USAGE cast as a pointer 420280849Scy#define OPTPROC_EMIT_USAGE ((tOptions *)OP_VAL_EMIT_USAGE) 421280849Scy 422280849Scy/// \a OPT_VAL_EMIT_SHELL cast as a pointer 423280849Scy#define OPTPROC_EMIT_SHELL ((tOptions *)OP_VAL_EMIT_SHELL) 424280849Scy 425280849Scy/// \a OPT_VAL_RETURN_VALNAME cast as a pointer 426280849Scy#define OPTPROC_RETURN_VALNAME ((tOptions *)OP_VAL_RETURN_VALNAME) 427280849Scy 428280849Scy/// \a OPT_VAL_EMIT_LIMIT cast as a pointer 429280849Scy#define OPTPROC_EMIT_LIMIT ((tOptions *)OP_VAL_EMIT_LIMIT) 430280849Scy/** @} */ 431280849Scy 432280849Scy/** group option processing procedure types 433280849Scy * @{ 434181834Sroberto */ 435280849Scy/** forward declaration for tOptDesc */ 436280849Scytypedef struct opt_desc tOptDesc; 437280849Scy/** forward declaration for tOptiond */ 438181834Srobertotypedef struct options tOptions; 439181834Sroberto 440280849Scy/** 441181834Sroberto * The option procedures do the special processing for each 442181834Sroberto * option flag that needs it. 443181834Sroberto */ 444280849Scytypedef void (tOptProc)(tOptions * pOpts, tOptDesc * pOptDesc); 445181834Sroberto 446280849Scy/** 447280849Scy * a pointer to an option processing procedure 448280849Scy */ 449280849Scytypedef tOptProc * tpOptProc; 450280849Scy 451280849Scy/** 452181834Sroberto * The usage procedure will never return. It calls "exit(2)" 453181834Sroberto * with the "exitCode" argument passed to it. 454181834Sroberto */ 455280849Scy// coverity[+kill] 456285169Scytypedef void (tUsageProc)(tOptions * pOpts, int exitCode); 457181834Sroberto 458280849Scy/** 459280849Scy * a pointer to a procedure that prints usage and exits. 460280849Scy */ 461280849Scytypedef tUsageProc * tpUsageProc; 462280849Scy/** @} */ 463280849Scy 464280849Scy/** 465181834Sroberto * Special definitions. "NOLIMIT" is the 'max' value to use when 466181834Sroberto * a flag may appear multiple times without limit. "NO_EQUIVALENT" 467181834Sroberto * is an illegal value for 'optIndex' (option description index). 468280849Scy * @{ 469181834Sroberto */ 470280849Scy#define NOLIMIT USHRT_MAX ///< no occurrance count limit 471280849Scy#define OPTION_LIMIT SHRT_MAX ///< maximum number of option types 472280849Scy/// option index to indicate no equivalance or alias 473181834Sroberto#define NO_EQUIVALENT (OPTION_LIMIT+1) 474280849Scy/** @} */ 475181834Sroberto 476280849Scy/** 477280849Scy * Option argument value. Which is valid is determined by: 478280849Scy * (fOptState & OPTST_ARG_TYPE_MASK) >> OPTST_ARG_TYPE_SHIFT 479280849Scy * which will yield one of the teOptArgType values. 480181834Sroberto */ 481280849Scytypedef union { 482280849Scy char const * argString; ///< as a string 483280849Scy uintptr_t argEnum; ///< as an enumeration value 484280849Scy uintptr_t argIntptr; ///< as an integer big enough to hold pointer 485280849Scy long argInt; ///< as a long integer 486280849Scy unsigned long argUint; ///< as an unsigned long ingeger 487280849Scy unsigned int argBool; ///< as a boolean value 488280849Scy FILE * argFp; ///< as a FILE * pointer 489280849Scy int argFd; ///< as a file descriptor (int) 490280849Scy} opt_arg_union_t; 491181834Sroberto 492280849Scy/// Compatibility define: \a pzLastArg is now \a optArg.argString 493280849Scy#define pzLastArg optArg.argString 494280849Scy/// The old amorphous argument bucket is now the opt_arg_union_t union. 495280849Scy#define optArgBucket_t opt_arg_union_t 496181834Sroberto 497280849Scy/** 498280849Scy * Enumeration of AutoOpts defined options. The enumeration is used in 499280849Scy * marking each option that is defined by AutoOpts so libopts can find 500280849Scy * the correct descriptor. This renders \a option_spec_idx_t redundant. 501280849Scy */ 502280849Scytypedef enum { 503280849Scy AOUSE_USER_DEFINED = 0, ///< user specified option 504280849Scy AOUSE_RESET_OPTION, ///< reset option state option 505280849Scy AOUSE_VERSION, ///< request version 506280849Scy AOUSE_HELP, ///< request usage help 507280849Scy AOUSE_MORE_HELP, ///< request paged usage 508280849Scy AOUSE_USAGE, ///< request short usage 509280849Scy AOUSE_SAVE_OPTS, ///< save option state 510280849Scy AOUSE_LOAD_OPTS, ///< load options from file 511280849Scy AOUSE_VENDOR_OPT ///< specify a vendor option 512280849Scy} opt_usage_t; 513181834Sroberto 514280849Scy/** 515181834Sroberto * Descriptor structure for each option. 516181834Sroberto * Only the fields marked "PUBLIC" are for public use. 517181834Sroberto */ 518280849Scystruct opt_desc { 519280849Scy /// Public, the index of this descriptor 520280849Scy uint16_t const optIndex; 521280849Scy /// Public, the flag character (value) 522280849Scy uint16_t const optValue; 523280849Scy /// Public, the index of the option used to activate option 524280849Scy uint16_t optActualIndex; 525280849Scy /// Public, the flag character of the activating option 526280849Scy uint16_t optActualValue; 527181834Sroberto 528280849Scy /// Public, the index of the equivalenced-to option. 529280849Scy /// This is NO_EQUIVALENT unless activated. 530280849Scy uint16_t const optEquivIndex; 531280849Scy /// Private, the minimum occurrance count 532280849Scy uint16_t const optMinCt; 533280849Scy /// Private, the maximum occurrance count (NOLIMIT, if unlimited) 534280849Scy uint16_t const optMaxCt; 535280849Scy /// Public, the actual occurrance count 536280849Scy uint16_t optOccCt; 537181834Sroberto 538280849Scy /// Public, the option processing state 539280849Scy opt_state_mask_t fOptState; 540280849Scy /// Private, how the option is used (opt_usage_t) 541280849Scy uint32_t optUsage; 542280849Scy /// Public, The current option argument value 543280849Scy opt_arg_union_t optArg; 544280849Scy /// Public, data that is actually private to the code that handles 545280849Scy /// this particular option. It is public IFF you have your own 546280849Scy /// handling function. 547280849Scy void * optCookie; 548181834Sroberto 549280849Scy /// Private, a list of options that must be specified when this option 550280849Scy /// has been specified 551280849Scy int const * const pOptMust; 552181834Sroberto 553280849Scy /// Private, a list of options that cannot be specified when this option 554280849Scy /// has been specified 555280849Scy int const * const pOptCant; 556280849Scy 557280849Scy /// Private, the function to call for handling this option 558280849Scy tpOptProc const pOptProc; 559280849Scy 560280849Scy /// Private, usage information about this option 561280849Scy char const * const pzText; 562280849Scy 563280849Scy /// Public, the UPPER CASE, shell variable name syntax name of the option 564280849Scy char const * const pz_NAME; 565280849Scy 566280849Scy /// the unmodified name of the option 567280849Scy char const * const pz_Name; 568280849Scy 569280849Scy /// the option name to use to disable the option. Long options names 570280849Scy /// must be active. 571280849Scy char const * const pz_DisableName; 572280849Scy 573280849Scy /// the special prefix that makes the normal option name become the 574280849Scy /// disablement name. 575280849Scy char const * const pz_DisablePfx; 576181834Sroberto}; 577181834Sroberto 578280849Scy/** 579181834Sroberto * Some options need special processing, so we store their 580280849Scy * indexes in a known place. 581181834Sroberto */ 582280849Scytypedef struct { 583280849Scy uint16_t const more_help; ///< passes help text through pager 584280849Scy uint16_t const save_opts; ///< stores option state to a file 585280849Scy uint16_t const number_option; ///< the option "name" is an integer 586280849Scy /// all arguments are options, this is the default option that must 587280849Scy /// take an argument. That argument is the unrecognized option. 588280849Scy uint16_t const default_opt; 589280849Scy} option_spec_idx_t; 590181834Sroberto 591280849Scy/** 592181834Sroberto * The procedure generated for translating option text 593181834Sroberto */ 594181834Srobertotypedef void (tOptionXlateProc)(void); 595181834Sroberto 596280849Scy/** 597280849Scy * Everything marked "PUBLIC" is also marked "const". Public access is not 598280849Scy * a license to modify. Other fields are used and modified by the library. 599280849Scy * They are also subject to change without any notice. 600280849Scy * Do not even look at these outside of libopts. 601280849Scy */ 602181834Srobertostruct options { 603280849Scy int const structVersion; ///< The version of this struct 604280849Scy unsigned int origArgCt; ///< program argument count 605280849Scy char ** origArgVect; ///< program argument vector 606280849Scy proc_state_mask_t fOptSet; ///< option proc. state flags 607280849Scy unsigned int curOptIdx; ///< current option index 608280849Scy char * pzCurOpt; ///< current option text 609181834Sroberto 610280849Scy /// Public, the full path of the program 611280849Scy char const * const pzProgPath; 612280849Scy /// Public, the name of the executable, without any path 613280849Scy char const * const pzProgName; 614280849Scy /// Public, the upper-cased, shell variable syntax-ed program name 615280849Scy char const * const pzPROGNAME; 616280849Scy /// the name of the "rc file" (configuration file) 617280849Scy char const * const pzRcName; 618280849Scy /// the copyright text 619280849Scy char const * const pzCopyright; 620280849Scy /// the full copyright notice 621280849Scy char const * const pzCopyNotice; 622280849Scy /// a string with the program name, project name and version 623280849Scy char const * const pzFullVersion; 624280849Scy /// a list of pointers to directories to search for the config file 625280849Scy char const * const * const papzHomeList; 626280849Scy /// the title line for usage 627280849Scy char const * const pzUsageTitle; 628280849Scy /// some added explanation for what this program is trying to do 629280849Scy char const * const pzExplain; 630280849Scy /// a detailed explanation of the program's purpose, for use when 631280849Scy /// full help has been requested 632280849Scy char const * const pzDetail; 633280849Scy /// The public array of option descriptors 634280849Scy tOptDesc * const pOptDesc; 635280849Scy /// the email address for reporting bugs 636280849Scy char const * const pzBugAddr; 637181834Sroberto 638280849Scy /// Reserved for future use 639280849Scy void * pExtensions; 640280849Scy /// A copy of the option state when optionSaveState was called. 641280849Scy void * pSavedState; 642181834Sroberto 643280849Scy /// The procedure to call to print usage text 644280849Scy // coverity[+kill] 645280849Scy tpUsageProc pUsageProc; 646280849Scy /// The procedure to call to translate translatable option messages 647280849Scy tOptionXlateProc * pTransProc; 648181834Sroberto 649280849Scy /// Special option indexes. 650280849Scy option_spec_idx_t specOptIdx; 651280849Scy /// the total number of options for the program 652280849Scy int const optCt; 653280849Scy /// The number of "presettable" options, though some may be marked 654280849Scy /// "no-preset". Includes all user specified options, plus a few 655280849Scy /// that are specified by AutoOpts. 656280849Scy int const presetOptCt; 657280849Scy /// user specified full usage text 658280849Scy char const * pzFullUsage; 659280849Scy /// user specifed short usage (usage error triggered) message 660280849Scy char const * pzShortUsage; 661280849Scy /// The option argument settings active when optionSaveState was called 662280849Scy opt_arg_union_t const * const originalOptArgArray; 663280849Scy /// any saved cookie value 664280849Scy void * const * const originalOptArgCookie; 665280849Scy /// the package data directory (e.g. global configuration files) 666280849Scy char const * const pzPkgDataDir; 667280849Scy /// email address of the project packager 668280849Scy char const * const pzPackager; 669181834Sroberto}; 670181834Sroberto 671181834Sroberto/* 672280849Scy * Versions where in various fields first appear: 673280849Scy * ($AO_CURRENT * 4096 + $AO_REVISION, but $AO_REVISION must be zero) 674280849Scy */ 675280849Scy/** 676280849Scy * The version that first stored the original argument vector 677280849Scy */ 678280849Scy#define originalOptArgArray_STRUCT_VERSION 0x20000 /* AO_CURRENT = 32 */ 679280849Scy#define HAS_originalOptArgArray(_opt) \ 680280849Scy ((_opt)->structVersion >= originalOptArgArray_STRUCT_VERSION) 681280849Scy 682280849Scy/** 683280849Scy * The version that first stored the package data directory 684280849Scy */ 685280849Scy#define pzPkgDataDir_STRUCT_VERSION 0x22000 /* AO_CURRENT = 34 */ 686280849Scy#define HAS_pzPkgDataDir(_opt) \ 687280849Scy ((_opt)->structVersion >= pzPkgDataDir_STRUCT_VERSION) 688280849Scy 689280849Scy/** 690280849Scy * The version that first stored the option usage in each option descriptor 691280849Scy */ 692280849Scy#define opt_usage_t_STRUCT_VERSION 0x26000 /* AO_CURRENT = 38 */ 693280849Scy#define HAS_opt_usage_t(_opt) \ 694280849Scy ((_opt)->structVersion >= opt_usage_t_STRUCT_VERSION) 695280849Scy 696280849Scy/** 697181834Sroberto * "token list" structure returned by "string_tokenize()" 698181834Sroberto */ 699181834Srobertotypedef struct { 700280849Scy unsigned long tkn_ct; ///< number of tokens found 701285169Scy unsigned char * tkn_list[1]; ///< array of pointers to tokens 702181834Sroberto} token_list_t; 703181834Sroberto 704181834Sroberto/* 705181834Sroberto * Hide the interface - it pollutes a POSIX claim, but leave it for 706181834Sroberto * anyone #include-ing this header 707181834Sroberto */ 708181834Sroberto#define strneqvcmp option_strneqvcmp 709181834Sroberto#define streqvcmp option_streqvcmp 710181834Sroberto#define streqvmap option_streqvmap 711181834Sroberto#define strequate option_strequate 712181834Sroberto#define strtransform option_strtransform 713181834Sroberto 714280849Scy/** 715280849Scy * Everything needed to be known about an mmap-ed file. 716280849Scy * 717181834Sroberto * This is an output only structure used by text_mmap and text_munmap. 718181834Sroberto * Clients must not alter the contents and must provide it to both 719181834Sroberto * the text_mmap and text_munmap procedures. BE ADVISED: if you are 720181834Sroberto * mapping the file with PROT_WRITE the NUL byte at the end MIGHT NOT 721181834Sroberto * BE WRITABLE. In any event, that byte is not be written back 722181834Sroberto * to the source file. ALSO: if "txt_data" is valid and "txt_errno" 723181834Sroberto * is not zero, then there *may* not be a terminating NUL. 724181834Sroberto */ 725181834Srobertotypedef struct { 726280849Scy void * txt_data; ///< text file data 727280849Scy size_t txt_size; ///< actual file size 728280849Scy size_t txt_full_size; ///< mmaped mem size 729280849Scy int txt_fd; ///< file descriptor 730280849Scy int txt_zero_fd; ///< fd for /dev/zero 731280849Scy int txt_errno; ///< warning code 732280849Scy int txt_prot; ///< "prot" flags 733280849Scy int txt_flags; ///< mapping type 734181834Sroberto} tmap_info_t; 735181834Sroberto 736280849Scy/** 737280849Scy * mmap result wrapper that yields "true" when mmap has failed. 738280849Scy */ 739285169Scy#define TEXT_MMAP_FAILED_ADDR(a) (VOIDP(a) == VOIDP(MAP_FAILED)) 740181834Sroberto 741181834Sroberto#ifdef __cplusplus 742280849Scy#define CPLUSPLUS_OPENER extern "C" { 743280849ScyCPLUSPLUS_OPENER 744181834Sroberto#define CPLUSPLUS_CLOSER } 745181834Sroberto#else 746181834Sroberto#define CPLUSPLUS_CLOSER 747181834Sroberto#endif 748181834Sroberto 749280849Scy/** 750181834Sroberto * The following routines may be coded into AutoOpts client code: 751181834Sroberto */ 752181834Sroberto 753280849Scy/** 754181834Sroberto * ao_string_tokenize - tokenize an input string 755181834Sroberto * 756181834Sroberto * This function will convert one input string into a list of strings. 757181834Sroberto * The list of strings is derived by separating the input based on 758181834Sroberto * white space separation. However, if the input contains either single 759181834Sroberto * or double quote characters, then the text after that character up to 760181834Sroberto * a matching quote will become the string in the list. 761280849Scy * 762181834Sroberto * The returned pointer should be deallocated with @code{free(3C)} when 763181834Sroberto * are done using the data. The data are placed in a single block of 764181834Sroberto * allocated memory. Do not deallocate individual token/strings. 765280849Scy * 766181834Sroberto * The structure pointed to will contain at least these two fields: 767181834Sroberto * @table @samp 768181834Sroberto * @item tkn_ct 769181834Sroberto * The number of tokens found in the input string. 770181834Sroberto * @item tok_list 771181834Sroberto * An array of @code{tkn_ct + 1} pointers to substring tokens, with 772181834Sroberto * the last pointer set to NULL. 773181834Sroberto * @end table 774280849Scy * 775181834Sroberto * There are two types of quoted strings: single quoted (@code{'}) and 776181834Sroberto * double quoted (@code{"}). Singly quoted strings are fairly raw in that 777181834Sroberto * escape characters (@code{\\}) are simply another character, except when 778181834Sroberto * preceding the following characters: 779181834Sroberto * @example 780181834Sroberto * @code{\\} double backslashes reduce to one 781181834Sroberto * @code{'} incorporates the single quote into the string 782181834Sroberto * @code{\n} suppresses both the backslash and newline character 783181834Sroberto * @end example 784280849Scy * 785181834Sroberto * Double quote strings are formed according to the rules of string 786181834Sroberto * constants in ANSI-C programs. 787280849Scy * 788280849Scy * @param string string to be tokenized 789280849Scy * 790285169Scy * @return token_list_t * - pointer to a structure that lists each token 791181834Sroberto */ 792285169Scyextern token_list_t * ao_string_tokenize(char const *); 793181834Sroberto 794181834Sroberto 795280849Scy/** 796181834Sroberto * configFileLoad - parse a configuration file 797181834Sroberto * 798181834Sroberto * This routine will load a named configuration file and parse the 799181834Sroberto * text as a hierarchically valued option. The option descriptor 800181834Sroberto * created from an option definition file is not used via this interface. 801181834Sroberto * The returned value is "named" with the input file name and is of 802181834Sroberto * type "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to 803181834Sroberto * @code{optionGetValue()}, @code{optionNextValue()} and 804181834Sroberto * @code{optionUnloadNested()}. 805280849Scy * 806280849Scy * @param fname the file to load 807280849Scy * 808285169Scy * @return const tOptionValue * - An allocated, compound value structure 809181834Sroberto */ 810285169Scyextern const tOptionValue * configFileLoad(char const *); 811181834Sroberto 812181834Sroberto 813280849Scy/** 814181834Sroberto * optionFileLoad - Load the locatable config files, in order 815181834Sroberto * 816181834Sroberto * This function looks in all the specified directories for a configuration 817181834Sroberto * file ("rc" file or "ini" file) and processes any found twice. The first 818181834Sroberto * time through, they are processed in reverse order (last file first). At 819181834Sroberto * that time, only "immediate action" configurables are processed. For 820181834Sroberto * example, if the last named file specifies not processing any more 821181834Sroberto * configuration files, then no more configuration files will be processed. 822181834Sroberto * Such an option in the @strong{first} named directory will have no effect. 823280849Scy * 824181834Sroberto * Once the immediate action configurables have been handled, then the 825181834Sroberto * directories are handled in normal, forward order. In that way, later 826181834Sroberto * config files can override the settings of earlier config files. 827280849Scy * 828181834Sroberto * See the AutoOpts documentation for a thorough discussion of the 829181834Sroberto * config file format. 830280849Scy * 831181834Sroberto * Configuration files not found or not decipherable are simply ignored. 832280849Scy * 833280849Scy * @param opts program options descriptor 834280849Scy * @param prog program name 835280849Scy * 836280849Scy * @return int - 0 -> SUCCESS, -1 -> FAILURE 837181834Sroberto */ 838285169Scyextern int optionFileLoad(tOptions *, char const *); 839181834Sroberto 840181834Sroberto 841280849Scy/** 842181834Sroberto * optionFindNextValue - find a hierarcicaly valued option instance 843181834Sroberto * 844181834Sroberto * This routine will find the next entry in a nested value option or 845181834Sroberto * configurable. It will search through the list and return the next entry 846181834Sroberto * that matches the criteria. 847280849Scy * 848280849Scy * @param odesc an option with a nested arg type 849280849Scy * @param pPrevVal the last entry 850280849Scy * @param name name of value to find 851280849Scy * @param value the matching value 852280849Scy * 853285169Scy * @return const tOptionValue * - a compound value structure 854181834Sroberto */ 855285169Scyextern const tOptionValue * optionFindNextValue(const tOptDesc *, const tOptionValue *, char const *, char const *); 856181834Sroberto 857181834Sroberto 858280849Scy/** 859181834Sroberto * optionFindValue - find a hierarcicaly valued option instance 860181834Sroberto * 861280849Scy * This routine will find an entry in a nested value option or configurable. 862280849Scy * It will search through the list and return a matching entry. 863181834Sroberto * 864280849Scy * @param odesc an option with a nested arg type 865280849Scy * @param name name of value to find 866280849Scy * @param val the matching value 867181834Sroberto * 868285169Scy * @return const tOptionValue * - a compound value structure 869181834Sroberto */ 870285169Scyextern const tOptionValue * optionFindValue(const tOptDesc *, char const *, char const *); 871181834Sroberto 872181834Sroberto 873280849Scy/** 874181834Sroberto * optionFree - free allocated option processing memory 875181834Sroberto * 876181834Sroberto * AutoOpts sometimes allocates memory and puts pointers to it in the 877181834Sroberto * option state structures. This routine deallocates all such memory. 878280849Scy * 879280849Scy * @param pOpts program options descriptor 880181834Sroberto */ 881285169Scyextern void optionFree(tOptions *); 882181834Sroberto 883181834Sroberto 884280849Scy/** 885181834Sroberto * optionGetValue - get a specific value from a hierarcical list 886181834Sroberto * 887181834Sroberto * This routine will find an entry in a nested value option or configurable. 888181834Sroberto * If "valueName" is NULL, then the first entry is returned. Otherwise, 889181834Sroberto * the first entry with a name that exactly matches the argument will be 890280849Scy * returned. If there is no matching value, NULL is returned and errno is 891280849Scy * set to ENOENT. If the provided option value is not a hierarchical value, 892280849Scy * NULL is also returned and errno is set to EINVAL. 893280849Scy * 894280849Scy * @param pOptValue a hierarchcal value 895280849Scy * @param valueName name of value to get 896280849Scy * 897285169Scy * @return const tOptionValue * - a compound value structure 898181834Sroberto */ 899285169Scyextern const tOptionValue * optionGetValue(const tOptionValue *, char const *); 900181834Sroberto 901181834Sroberto 902280849Scy/** 903181834Sroberto * optionLoadLine - process a string for an option name and value 904181834Sroberto * 905181834Sroberto * This is a client program callable routine for setting options from, for 906181834Sroberto * example, the contents of a file that they read in. Only one option may 907181834Sroberto * appear in the text. It will be treated as a normal (non-preset) option. 908280849Scy * 909181834Sroberto * When passed a pointer to the option struct and a string, it will find 910181834Sroberto * the option named by the first token on the string and set the option 911181834Sroberto * argument to the remainder of the string. The caller must NUL terminate 912280849Scy * the string. The caller need not skip over any introductory hyphens. 913280849Scy * Any embedded new lines will be included in the option 914181834Sroberto * argument. If the input looks like one or more quoted strings, then the 915181834Sroberto * input will be "cooked". The "cooking" is identical to the string 916181834Sroberto * formation used in AutoGen definition files (@pxref{basic expression}), 917181834Sroberto * except that you may not use backquotes. 918280849Scy * 919280849Scy * @param opts program options descriptor 920280849Scy * @param line NUL-terminated text 921181834Sroberto */ 922285169Scyextern void optionLoadLine(tOptions *, char const *); 923181834Sroberto 924181834Sroberto 925280849Scy/** 926280849Scy * optionMemberList - Get the list of members of a bit mask set 927181834Sroberto * 928280849Scy * This converts the OPT_VALUE_name mask value to a allocated string. 929280849Scy * It is the caller's responsibility to free the string. 930181834Sroberto * 931280849Scy * @param od the set membership option description 932181834Sroberto * 933285169Scy * @return char * - the names of the set bits 934280849Scy */ 935285169Scyextern char * optionMemberList(tOptDesc *); 936280849Scy 937280849Scy 938280849Scy/** 939280849Scy * optionNextValue - get the next value from a hierarchical list 940181834Sroberto * 941181834Sroberto * This routine will return the next entry after the entry passed in. At the 942181834Sroberto * end of the list, NULL will be returned. If the entry is not found on the 943181834Sroberto * list, NULL will be returned and "@var{errno}" will be set to EINVAL. 944181834Sroberto * The "@var{pOldValue}" must have been gotten from a prior call to this 945181834Sroberto * routine or to "@code{opitonGetValue()}". 946280849Scy * 947280849Scy * @param pOptValue a hierarchcal list value 948280849Scy * @param pOldValue a value from this list 949280849Scy * 950285169Scy * @return const tOptionValue * - a compound value structure 951181834Sroberto */ 952285169Scyextern const tOptionValue * optionNextValue(const tOptionValue *, const tOptionValue *); 953181834Sroberto 954181834Sroberto 955280849Scy/** 956181834Sroberto * optionOnlyUsage - Print usage text for just the options 957181834Sroberto * 958181834Sroberto * This routine will print only the usage for each option. 959181834Sroberto * This function may be used when the emitted usage must incorporate 960181834Sroberto * information not available to AutoOpts. 961280849Scy * 962280849Scy * @param pOpts program options descriptor 963280849Scy * @param ex_code exit code for calling exit(3) 964181834Sroberto */ 965285169Scyextern void optionOnlyUsage(tOptions *, int); 966181834Sroberto 967181834Sroberto 968280849Scy/** 969280849Scy * optionPrintVersion - Print the program version 970181834Sroberto * 971280849Scy * This routine will print the version to stdout. 972181834Sroberto * 973280849Scy * @param opts program options descriptor 974280849Scy * @param od the descriptor for this arg 975280849Scy */ 976285169Scyextern void optionPrintVersion(tOptions *, tOptDesc *); 977280849Scy 978280849Scy 979280849Scy/** 980280849Scy * optionPrintVersionAndReturn - Print the program version 981181834Sroberto * 982280849Scy * This routine will print the version to stdout and return 983280849Scy * instead of exiting. Please see the source for the 984280849Scy * @code{print_ver} funtion for details on selecting how 985280849Scy * verbose to be after this function returns. 986181834Sroberto * 987280849Scy * @param opts program options descriptor 988280849Scy * @param od the descriptor for this arg 989280849Scy */ 990285169Scyextern void optionPrintVersionAndReturn(tOptions *, tOptDesc *); 991280849Scy 992280849Scy 993280849Scy/** 994280849Scy * optionProcess - this is the main option processing routine 995280849Scy * 996181834Sroberto * This is the main entry point for processing options. It is intended 997181834Sroberto * that this procedure be called once at the beginning of the execution of 998181834Sroberto * a program. Depending on options selected earlier, it is sometimes 999181834Sroberto * necessary to stop and restart option processing, or to select completely 1000181834Sroberto * different sets of options. This can be done easily, but you generally 1001181834Sroberto * do not want to do this. 1002280849Scy * 1003181834Sroberto * The number of arguments processed always includes the program name. 1004181834Sroberto * If one of the arguments is "--", then it is counted and the processing 1005181834Sroberto * stops. If an error was encountered and errors are to be tolerated, then 1006181834Sroberto * the returned value is the index of the argument causing the error. 1007181834Sroberto * A hyphen by itself ("-") will also cause processing to stop and will 1008181834Sroberto * @emph{not} be counted among the processed arguments. A hyphen by itself 1009181834Sroberto * is treated as an operand. Encountering an operand stops option 1010181834Sroberto * processing. 1011280849Scy * 1012280849Scy * @param opts program options descriptor 1013280849Scy * @param a_ct program arg count 1014280849Scy * @param a_v program arg vector 1015280849Scy * 1016280849Scy * @return int - the count of the arguments processed 1017181834Sroberto */ 1018285169Scyextern int optionProcess(tOptions *, int, char **); 1019181834Sroberto 1020181834Sroberto 1021280849Scy/** 1022181834Sroberto * optionRestore - restore option state from memory copy 1023181834Sroberto * 1024181834Sroberto * Copy back the option state from saved memory. 1025181834Sroberto * The allocated memory is left intact, so this routine can be 1026181834Sroberto * called repeatedly without having to call optionSaveState again. 1027181834Sroberto * If you are restoring a state that was saved before the first call 1028181834Sroberto * to optionProcess(3AO), then you may change the contents of the 1029181834Sroberto * argc/argv parameters to optionProcess. 1030280849Scy * 1031280849Scy * @param pOpts program options descriptor 1032181834Sroberto */ 1033285169Scyextern void optionRestore(tOptions *); 1034181834Sroberto 1035181834Sroberto 1036280849Scy/** 1037181834Sroberto * optionSaveFile - saves the option state to a file 1038181834Sroberto * 1039181834Sroberto * This routine will save the state of option processing to a file. The name 1040181834Sroberto * of that file can be specified with the argument to the @code{--save-opts} 1041181834Sroberto * option, or by appending the @code{rcfile} attribute to the last 1042181834Sroberto * @code{homerc} attribute. If no @code{rcfile} attribute was specified, it 1043181834Sroberto * will default to @code{.@i{programname}rc}. If you wish to specify another 1044280849Scy * file, you should invoke the @code{SET_OPT_SAVE_OPTS(@i{filename})} macro. 1045280849Scy * 1046280849Scy * The recommend usage is as follows: 1047280849Scy * @example 1048280849Scy * optionProcess(&progOptions, argc, argv); 1049280849Scy * if (i_want_a_non_standard_place_for_this) 1050280849Scy * SET_OPT_SAVE_OPTS("myfilename"); 1051280849Scy * optionSaveFile(&progOptions); 1052280849Scy * @end example 1053280849Scy * 1054280849Scy * @param opts program options descriptor 1055181834Sroberto */ 1056285169Scyextern void optionSaveFile(tOptions *); 1057181834Sroberto 1058181834Sroberto 1059280849Scy/** 1060181834Sroberto * optionSaveState - saves the option state to memory 1061181834Sroberto * 1062181834Sroberto * This routine will allocate enough memory to save the current option 1063181834Sroberto * processing state. If this routine has been called before, that memory 1064181834Sroberto * will be reused. You may only save one copy of the option state. This 1065181834Sroberto * routine may be called before optionProcess(3AO). If you do call it 1066181834Sroberto * before the first call to optionProcess, then you may also change the 1067181834Sroberto * contents of argc/argv after you call optionRestore(3AO) 1068280849Scy * 1069181834Sroberto * In fact, more strongly put: it is safest to only use this function 1070181834Sroberto * before having processed any options. In particular, the saving and 1071181834Sroberto * restoring of stacked string arguments and hierarchical values is 1072181834Sroberto * disabled. The values are not saved. 1073280849Scy * 1074280849Scy * @param pOpts program options descriptor 1075181834Sroberto */ 1076285169Scyextern void optionSaveState(tOptions *); 1077181834Sroberto 1078181834Sroberto 1079280849Scy/** 1080181834Sroberto * optionUnloadNested - Deallocate the memory for a nested value 1081181834Sroberto * 1082181834Sroberto * A nested value needs to be deallocated. The pointer passed in should 1083181834Sroberto * have been gotten from a call to @code{configFileLoad()} (See 1084181834Sroberto * @pxref{libopts-configFileLoad}). 1085280849Scy * 1086280849Scy * @param pOptVal the hierarchical value 1087181834Sroberto */ 1088280849Scyextern void optionUnloadNested(tOptionValue const *); 1089181834Sroberto 1090181834Sroberto 1091280849Scy/** 1092181834Sroberto * optionVersion - return the compiled AutoOpts version number 1093181834Sroberto * 1094181834Sroberto * Returns the full version string compiled into the library. 1095181834Sroberto * The returned string cannot be modified. 1096181834Sroberto * 1097285169Scy * @return char const * - the version string in constant memory 1098181834Sroberto */ 1099285169Scyextern char const * optionVersion(void); 1100181834Sroberto 1101181834Sroberto 1102280849Scy/** 1103181834Sroberto * strequate - map a list of characters to the same value 1104181834Sroberto * 1105181834Sroberto * Each character in the input string get mapped to the first character 1106181834Sroberto * in the string. 1107181834Sroberto * This function name is mapped to option_strequate so as to not conflict 1108181834Sroberto * with the POSIX name space. 1109280849Scy * 1110280849Scy * @param ch_list characters to equivalence 1111181834Sroberto */ 1112285169Scyextern void strequate(char const *); 1113181834Sroberto 1114181834Sroberto 1115280849Scy/** 1116181834Sroberto * streqvcmp - compare two strings with an equivalence mapping 1117181834Sroberto * 1118181834Sroberto * Using a character mapping, two strings are compared for "equivalence". 1119181834Sroberto * Each input character is mapped to a comparison character and the 1120181834Sroberto * mapped-to characters are compared for the two NUL terminated input strings. 1121181834Sroberto * This function name is mapped to option_streqvcmp so as to not conflict 1122181834Sroberto * with the POSIX name space. 1123280849Scy * 1124280849Scy * @param str1 first string 1125280849Scy * @param str2 second string 1126280849Scy * 1127280849Scy * @return int - the difference between two differing characters 1128181834Sroberto */ 1129285169Scyextern int streqvcmp(char const *, char const *); 1130181834Sroberto 1131181834Sroberto 1132280849Scy/** 1133181834Sroberto * streqvmap - Set the character mappings for the streqv functions 1134181834Sroberto * 1135181834Sroberto * Set the character mapping. If the count (@code{ct}) is set to zero, then 1136181834Sroberto * the map is cleared by setting all entries in the map to their index 1137181834Sroberto * value. Otherwise, the "@code{From}" character is mapped to the "@code{To}" 1138181834Sroberto * character. If @code{ct} is greater than 1, then @code{From} and @code{To} 1139181834Sroberto * are incremented and the process repeated until @code{ct} entries have been 1140181834Sroberto * set. For example, 1141181834Sroberto * @example 1142280849Scy * streqvmap('a', 'A', 26); 1143181834Sroberto * @end example 1144181834Sroberto * @noindent 1145181834Sroberto * will alter the mapping so that all English lower case letters 1146181834Sroberto * will map to upper case. 1147280849Scy * 1148181834Sroberto * This function name is mapped to option_streqvmap so as to not conflict 1149181834Sroberto * with the POSIX name space. 1150280849Scy * 1151280849Scy * @param from Input character 1152280849Scy * @param to Mapped-to character 1153280849Scy * @param ct compare length 1154181834Sroberto */ 1155280849Scyextern void streqvmap(char, char, int); 1156181834Sroberto 1157181834Sroberto 1158280849Scy/** 1159181834Sroberto * strneqvcmp - compare two strings with an equivalence mapping 1160181834Sroberto * 1161181834Sroberto * Using a character mapping, two strings are compared for "equivalence". 1162181834Sroberto * Each input character is mapped to a comparison character and the 1163181834Sroberto * mapped-to characters are compared for the two NUL terminated input strings. 1164181834Sroberto * The comparison is limited to @code{ct} bytes. 1165181834Sroberto * This function name is mapped to option_strneqvcmp so as to not conflict 1166181834Sroberto * with the POSIX name space. 1167280849Scy * 1168280849Scy * @param str1 first string 1169280849Scy * @param str2 second string 1170280849Scy * @param ct compare length 1171280849Scy * 1172280849Scy * @return int - the difference between two differing characters 1173181834Sroberto */ 1174285169Scyextern int strneqvcmp(char const *, char const *, int); 1175181834Sroberto 1176181834Sroberto 1177280849Scy/** 1178181834Sroberto * strtransform - convert a string into its mapped-to value 1179181834Sroberto * 1180181834Sroberto * Each character in the input string is mapped and the mapped-to 1181181834Sroberto * character is put into the output. 1182181834Sroberto * This function name is mapped to option_strtransform so as to not conflict 1183181834Sroberto * with the POSIX name space. 1184280849Scy * 1185280849Scy * The source and destination may be the same. 1186280849Scy * 1187280849Scy * @param dest output string 1188280849Scy * @param src input string 1189181834Sroberto */ 1190285169Scyextern void strtransform(char *, char const *); 1191181834Sroberto 1192181834Sroberto/* AutoOpts PRIVATE FUNCTIONS: */ 1193181834SrobertotOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal; 1194181834Sroberto 1195285169Scyextern char * ao_string_cook(char *, int *); 1196181834Sroberto 1197285169Scyextern unsigned int ao_string_cook_escape_char(char const *, char *, unsigned int); 1198181834Sroberto 1199285169Scyextern void genshelloptUsage(tOptions *, int); 1200181834Sroberto 1201280849Scyextern int optionAlias(tOptions *, tOptDesc *, unsigned int); 1202181834Sroberto 1203285169Scyextern void optionBooleanVal(tOptions *, tOptDesc *); 1204181834Sroberto 1205285169Scyextern uintptr_t optionEnumerationVal(tOptions *, tOptDesc *, char const * const *, unsigned int); 1206181834Sroberto 1207285169Scyextern void optionFileCheck(tOptions *, tOptDesc *, teOptFileType, tuFileMode); 1208181834Sroberto 1209285169Scyextern char const * optionKeywordName(tOptDesc *, unsigned int); 1210181834Sroberto 1211285169Scyextern void optionLoadOpt(tOptions *, tOptDesc *); 1212181834Sroberto 1213285169Scyextern bool optionMakePath(char *, int, char const *, char const *); 1214181834Sroberto 1215285169Scyextern void optionNestedVal(tOptions *, tOptDesc *); 1216181834Sroberto 1217285169Scyextern void optionNumericVal(tOptions *, tOptDesc *); 1218181834Sroberto 1219280849Scyextern void optionPagedUsage(tOptions *, tOptDesc *); 1220181834Sroberto 1221285169Scyextern void optionParseShell(tOptions *); 1222181834Sroberto 1223280849Scyextern void optionPrintParagraphs(char const *, bool, FILE *); 1224181834Sroberto 1225285169Scyextern void optionPutShell(tOptions *); 1226181834Sroberto 1227280849Scyextern char const * optionQuoteString(char const *, char const *); 1228181834Sroberto 1229285169Scyextern void optionResetOpt(tOptions *, tOptDesc *); 1230181834Sroberto 1231285169Scyextern void optionSetMembers(tOptions *, tOptDesc *, char const * const *, unsigned int); 1232181834Sroberto 1233285169Scyextern void optionShowRange(tOptions *, tOptDesc *, void *, int); 1234181834Sroberto 1235285169Scyextern void optionStackArg(tOptions *, tOptDesc *); 1236181834Sroberto 1237285169Scyextern void optionTimeDate(tOptions *, tOptDesc *); 1238181834Sroberto 1239285169Scyextern void optionTimeVal(tOptions *, tOptDesc *); 1240280849Scy 1241285169Scyextern void optionUnstackArg(tOptions *, tOptDesc *); 1242280849Scy 1243285169Scyextern void optionUsage(tOptions *, int); 1244280849Scy 1245280849Scyextern void optionVendorOption(tOptions *, tOptDesc *); 1246280849Scy 1247285169Scyextern void optionVersionStderr(tOptions *, tOptDesc *); 1248280849Scy 1249285169Scyextern void * text_mmap(char const *, int, int, tmap_info_t *); 1250280849Scy 1251285169Scyextern int text_munmap(tmap_info_t *); 1252280849Scy 1253181834SrobertoCPLUSPLUS_CLOSER 1254181834Sroberto#endif /* AUTOOPTS_OPTIONS_H_GUARD */ 1255280849Scy/** @} 1256280849Scy * 1257181834Sroberto * Local Variables: 1258181834Sroberto * c-file-style: "stroustrup" 1259181834Sroberto * indent-tabs-mode: nil 1260181834Sroberto * End: 1261181834Sroberto * options.h ends here */ 1262