1181834Sroberto/* -*- buffer-read-only: t -*- vi: set ro: 2285612Sdelphij * 3181834Sroberto * DO NOT EDIT THIS FILE (options.h) 4285612Sdelphij * 5285612Sdelphij * 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 * 12285612Sdelphij * Automated Options Copyright (C) 1992-2015 by Bruce Korb 13181834Sroberto * 14285612Sdelphij * This file is part of AutoOpts, a companion to AutoGen. 15285612Sdelphij * AutoOpts is free software. 16285612Sdelphij * AutoOpts is Copyright (C) 1992-2015 by Bruce Korb - all rights reserved 17285612Sdelphij * 18285612Sdelphij * AutoOpts is available under any one of two licenses. The license 19285612Sdelphij * in use must be one of these two and the choice is under the control 20285612Sdelphij * of the user of the license. 21285612Sdelphij * 22285612Sdelphij * The GNU Lesser General Public License, version 3 or later 23285612Sdelphij * See the files "COPYING.lgplv3" and "COPYING.gplv3" 24285612Sdelphij * 25285612Sdelphij * The Modified Berkeley Software Distribution License 26285612Sdelphij * See the file "COPYING.mbsd" 27285612Sdelphij * 28285612Sdelphij * These files have the following sha256 sums: 29285612Sdelphij * 30285612Sdelphij * 8584710e9b04216a394078dc156b781d0b47e1729104d666658aecef8ee32e95 COPYING.gplv3 31285612Sdelphij * 4379e7444a0e2ce2b12dd6f5a52a27a4d02d39d247901d3285c88cf0d37f477b COPYING.lgplv3 32285612Sdelphij * 13aa749a5b0a454917a944ed8fffc530b784f5ead522b1aacaf4ec8aa55a6239 COPYING.mbsd 33181834Sroberto */ 34181834Sroberto#ifndef AUTOOPTS_OPTIONS_H_GUARD 35285612Sdelphij#define AUTOOPTS_OPTIONS_H_GUARD 1 36285612Sdelphij/** \file options.h 37285612Sdelphij * 38285612Sdelphij * @addtogroup autoopts 39285612Sdelphij * @{ 40285612Sdelphij */ 41181834Sroberto#include <sys/types.h> 42285612Sdelphij#include <stdio.h> 43181834Sroberto 44285612Sdelphij#ifndef COMPAT_H_GUARD 45285612Sdelphij/* 46285612Sdelphij * This is needed for test compilations where the "compat.h" 47285612Sdelphij * header is not usually available. 48285612Sdelphij */ 49285612Sdelphij# if defined(HAVE_STDINT_H) 50285612Sdelphij# include <stdint.h> 51285612Sdelphij# elif defined(HAVE_INTTYPES_H) 52285612Sdelphij# include <inttypes.h> 53285612Sdelphij# endif /* HAVE_STDINT/INTTYPES_H */ 54181834Sroberto 55285612Sdelphij# if defined(HAVE_LIMITS_H) 56285612Sdelphij# include <limits.h> 57285612Sdelphij# elif defined(HAVE_SYS_LIMITS_H) 58285612Sdelphij# include <sys/limits.h> 59285612Sdelphij# endif /* HAVE_LIMITS/SYS_LIMITS_H */ 60181834Sroberto 61285612Sdelphij# if defined(HAVE_SYSEXITS_H) 62285612Sdelphij# include <sysexits.h> 63285612Sdelphij# endif /* HAVE_SYSEXITS_H */ 64181834Sroberto 65285612Sdelphij# if defined(HAVE_STDBOOL_H) 66285612Sdelphij# include <stdbool.h> 67285612Sdelphij# else 68285612Sdelphij typedef enum { false = 0, true = 1 } _Bool; 69285612Sdelphij# define bool _Bool 70181834Sroberto 71285612Sdelphij /* The other macros must be usable in preprocessor directives. */ 72285612Sdelphij# define false 0 73285612Sdelphij# define true 1 74285612Sdelphij# endif /* HAVE_SYSEXITS_H */ 75285612Sdelphij#endif /* COMPAT_H_GUARD */ 76285612Sdelphij// END-CONFIGURED-HEADERS 77285612Sdelphij 78285612Sdelphij/** 79285612Sdelphij * Defined to abnormal value of EX_USAGE. Used to indicate that paged usage 80285612Sdelphij * was requested. It is used to distinguish a --usage from a --help request. 81285612Sdelphij * --usage is abbreviated and --help gives as much help as possible. 82285612Sdelphij */ 83285612Sdelphij#define AO_EXIT_REQ_USAGE 10064 84285612Sdelphij 85285612Sdelphij#undef VOIDP 86285612Sdelphij/** 87285612Sdelphij * Coerce a value into a void pointer with no const or volatile attributes. 88285612Sdelphij * Somewhere along the line, the above set of includes need to set up 89285612Sdelphij * the "uintptr_t" type. 90285612Sdelphij */ 91285612Sdelphij#define VOIDP(_a) ((void *)(uintptr_t)(_a)) 92285612Sdelphij 93285612Sdelphij/** 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, 101285612Sdelphij * conventionally "tOptDesc * pOD". 102181834Sroberto * 103285612Sdelphij * 2. Outside of an option procedure (or to reference a different option 104285612Sdelphij * 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. 108285612Sdelphij * @group version 109285612Sdelphij * @{ 110181834Sroberto */ 111285612Sdelphij/// autoopts structure version 112285612Sdelphij#define OPTIONS_STRUCT_VERSION 167936 113285612Sdelphij/// autoopts structure version string 114285612Sdelphij#define OPTIONS_VERSION_STRING "41:0:16" 115285612Sdelphij/// minimum version the autoopts library supports 116285612Sdelphij#define OPTIONS_MINIMUM_VERSION 102400 117285612Sdelphij/// minimum version the autoopts library supports as a string 118285612Sdelphij#define OPTIONS_MIN_VER_STRING "25:0:0" 119285612Sdelphij/// the display version of the autoopts library, as a string 120285612Sdelphij#define OPTIONS_DOTTED_VERSION "41.0" 121285612Sdelphij/// convert a version/release number pair to an integer value 122285612Sdelphij#define OPTIONS_VER_TO_NUM(_v, _r) (((_v) * 4096) + (_r)) 123285612Sdelphij/// @} 124181834Sroberto 125285612Sdelphij/** 126285612Sdelphij * Option argument types. This must fit in the OPTST_ARG_TYPE_MASK 127285612Sdelphij * field of the fOptState field of an option descriptor (tOptDesc). 128285612Sdelphij * It will be a problem to extend beyond 4 bits. 129285612Sdelphij */ 130181834Srobertotypedef enum { 131285612Sdelphij OPARG_TYPE_NONE = 0, ///< does not take an argument 132285612Sdelphij OPARG_TYPE_STRING = 1, ///< default type/ vanilla string 133285612Sdelphij OPARG_TYPE_ENUMERATION = 2, ///< opt arg is an enum (keyword list) 134285612Sdelphij OPARG_TYPE_BOOLEAN = 3, ///< opt arg is boolean-valued 135285612Sdelphij OPARG_TYPE_MEMBERSHIP = 4, ///< opt arg sets set membership bits 136285612Sdelphij OPARG_TYPE_NUMERIC = 5, ///< opt arg is a long int 137285612Sdelphij OPARG_TYPE_HIERARCHY = 6, ///< option arg is hierarchical value 138285612Sdelphij OPARG_TYPE_FILE = 7, ///< option arg names a file 139285612Sdelphij OPARG_TYPE_TIME = 8, ///< opt arg is a time duration 140285612Sdelphij OPARG_TYPE_FLOAT = 9, ///< opt arg is a floating point num 141285612Sdelphij OPARG_TYPE_DOUBLE = 10, ///< opt arg is a double prec. float 142285612Sdelphij OPARG_TYPE_LONG_DOUBLE = 11, ///< opt arg is a long double prec. 143285612Sdelphij OPARG_TYPE_LONG_LONG = 12 ///< opt arg is a long long int 144181834Sroberto} teOptArgType; 145181834Sroberto 146285612Sdelphij/** 147285612Sdelphij * value descriptor for sub options 148285612Sdelphij */ 149181834Srobertotypedef struct optionValue { 150285612Sdelphij teOptArgType valType; ///< which argument type 151285612Sdelphij char * pzName; ///< name of the sub-option 152181834Sroberto union { 153285612Sdelphij char strVal[1]; ///< OPARG_TYPE_STRING 154285612Sdelphij unsigned int enumVal; ///< OPARG_TYPE_ENUMERATION 155285612Sdelphij unsigned int boolVal; ///< OPARG_TYPE_BOOLEAN 156285612Sdelphij unsigned long setVal; ///< OPARG_TYPE_MEMBERSHIP 157285612Sdelphij long longVal; ///< OPARG_TYPE_NUMERIC 158285612Sdelphij void * nestVal; ///< OPARG_TYPE_HIERARCHY 159181834Sroberto } v; 160181834Sroberto} tOptionValue; 161181834Sroberto 162285612Sdelphij/** 163285612Sdelphij * file argument state and handling. 164181834Sroberto */ 165181834Srobertotypedef enum { 166285612Sdelphij FTYPE_MODE_MAY_EXIST = 0x00, ///< may or may not exist 167285612Sdelphij FTYPE_MODE_MUST_EXIST = 0x01, ///< must pre-exist 168285612Sdelphij FTYPE_MODE_MUST_NOT_EXIST = 0x02, ///< must *not* pre-exist 169285612Sdelphij FTYPE_MODE_EXIST_MASK = 0x03, ///< mask for these bits 170285612Sdelphij FTYPE_MODE_NO_OPEN = 0x00, ///< leave file closed 171285612Sdelphij FTYPE_MODE_OPEN_FD = 0x10, ///< call open(2) 172285612Sdelphij FTYPE_MODE_FOPEN_FP = 0x20, ///< call fopen(3) 173285612Sdelphij FTYPE_MODE_OPEN_MASK = 0x30 ///< open/fopen/not open 174285612Sdelphij} teOptFileType; 175181834Sroberto 176285612Sdelphij/** 177285612Sdelphij * the open flag bits or the mode string, depending on the open type. 178285612Sdelphij */ 179285612Sdelphijtypedef union { 180285612Sdelphij int file_flags; ///< open(2) flag bits 181285612Sdelphij char const * file_mode; ///< fopen(3) mode string 182285612Sdelphij} tuFileMode; 183181834Sroberto 184285612Sdelphij/// initial number of option argument holders to allocate 185285612Sdelphij#define MIN_ARG_ALLOC_CT 6 186285612Sdelphij/// amount by which to increment the argument holder allocation. 187285612Sdelphij#define INCR_ARG_ALLOC_CT 8 188285612Sdelphij/** 189285612Sdelphij * an argument list. When an option appears multiple times and 190285612Sdelphij * the values get "stacked". \a apzArgs holds 8 pointers initially 191285612Sdelphij * and is incremented by \a INCR_ARG_ALLOC_CT as needed. 192285612Sdelphij */ 193285612Sdelphijtypedef struct { 194285612Sdelphij int useCt; ///< elements in use 195181834Sroberto 196285612Sdelphij /// allocated elements, mininum \a MIN_ARG_ALLOC_CT 197285612Sdelphij /// steps by \a INCR_ARG_ALLOC_CT 198285612Sdelphij int allocCt; 199285612Sdelphij char const * apzArgs[MIN_ARG_ALLOC_CT]; ///< element array 200285612Sdelphij} tArgList; 201181834Sroberto 202285612Sdelphij/** 203285612Sdelphij * Bits in the fOptState option descriptor field. 204285612Sdelphij * @{ 205285612Sdelphij */ 206181834Sroberto 207285612Sdelphij/** integral type for holding opt_state masks */ 208285612Sdelphijtypedef uint32_t opt_state_mask_t; 209181834Sroberto 210285612Sdelphij#define OPTST_ARG_TYPE_SHIFT 12 211285612Sdelphij/** bits defined for opt_state_mask_t */ 212285612Sdelphij/** Set via the "SET_OPT()" macro */ 213285612Sdelphij#define OPTST_SET 0x0000001U 214285612Sdelphij/** Set via an RC/INI file */ 215285612Sdelphij#define OPTST_PRESET 0x0000002U 216285612Sdelphij/** Set via a command line option */ 217285612Sdelphij#define OPTST_DEFINED 0x0000004U 218285612Sdelphij/** Reset via command line option */ 219285612Sdelphij#define OPTST_RESET 0x0000008U 220285612Sdelphij/** selected by equiv'ed option */ 221285612Sdelphij#define OPTST_EQUIVALENCE 0x0000010U 222285612Sdelphij/** option is in disabled state */ 223285612Sdelphij#define OPTST_DISABLED 0x0000020U 224285612Sdelphij/** pzOptArg was allocated */ 225285612Sdelphij#define OPTST_ALLOC_ARG 0x0000040U 226285612Sdelphij/** option cannot be preset */ 227285612Sdelphij#define OPTST_NO_INIT 0x0000100U 228285612Sdelphij/** opt value (flag) is any digit */ 229285612Sdelphij#define OPTST_NUMBER_OPT 0x0000200U 230285612Sdelphij/** opt uses optionStackArg proc */ 231285612Sdelphij#define OPTST_STACKED 0x0000400U 232285612Sdelphij/** option defaults to enabled */ 233285612Sdelphij#define OPTST_INITENABLED 0x0000800U 234285612Sdelphij/** bit 1 of arg type enum */ 235285612Sdelphij#define OPTST_ARG_TYPE_1 0x0001000U 236285612Sdelphij/** bit 2 of arg type enum */ 237285612Sdelphij#define OPTST_ARG_TYPE_2 0x0002000U 238285612Sdelphij/** bit 3 of arg type enum */ 239285612Sdelphij#define OPTST_ARG_TYPE_3 0x0004000U 240285612Sdelphij/** bit 4 of arg type enum */ 241285612Sdelphij#define OPTST_ARG_TYPE_4 0x0008000U 242285612Sdelphij/** the option arg not required */ 243285612Sdelphij#define OPTST_ARG_OPTIONAL 0x0010000U 244285612Sdelphij/** process opt on first pass */ 245285612Sdelphij#define OPTST_IMM 0x0020000U 246285612Sdelphij/** process disablement immed. */ 247285612Sdelphij#define OPTST_DISABLE_IMM 0x0040000U 248285612Sdelphij/** compiled out of program */ 249285612Sdelphij#define OPTST_OMITTED 0x0080000U 250285612Sdelphij/** must be set or pre-set */ 251285612Sdelphij#define OPTST_MUST_SET 0x0100000U 252285612Sdelphij/** opt is for doc only */ 253285612Sdelphij#define OPTST_DOCUMENT 0x0200000U 254285612Sdelphij/** process opt twice - imm + reg */ 255285612Sdelphij#define OPTST_TWICE 0x0400000U 256285612Sdelphij/** process disabled option twice */ 257285612Sdelphij#define OPTST_DISABLE_TWICE 0x0800000U 258285612Sdelphij/** scaled integer value */ 259285612Sdelphij#define OPTST_SCALED_NUM 0x1000000U 260285612Sdelphij/** disable from cmd line */ 261285612Sdelphij#define OPTST_NO_COMMAND 0x2000000U 262285612Sdelphij/** support is being removed */ 263285612Sdelphij#define OPTST_DEPRECATED 0x4000000U 264285612Sdelphij/** alias for other option */ 265285612Sdelphij#define OPTST_ALIAS 0x8000000U 266285612Sdelphij 267285612Sdelphij/** bits in SET mask: 268285612Sdelphij * set preset reset defined */ 269285612Sdelphij#define OPTST_SET_MASK 0x000000FU 270285612Sdelphij 271285612Sdelphij/** bits in MUTABLE mask: 272285612Sdelphij * set preset reset defined equivalence disabled 273285612Sdelphij * alloc_arg */ 274285612Sdelphij#define OPTST_MUTABLE_MASK 0x000007FU 275285612Sdelphij 276285612Sdelphij/** bits omitted from PERSISTENT mask: 277285612Sdelphij * mutable_mask */ 278285612Sdelphij#define OPTST_PERSISTENT_MASK 0xFFFFF00U 279285612Sdelphij 280285612Sdelphij/** bits in SELECTED mask: 281285612Sdelphij * set defined */ 282285612Sdelphij#define OPTST_SELECTED_MASK 0x0000005U 283285612Sdelphij 284285612Sdelphij/** bits in ARG_TYPE mask: 285285612Sdelphij * arg_type_1 arg_type_2 arg_type_3 arg_type_4 */ 286285612Sdelphij#define OPTST_ARG_TYPE_MASK 0x000F000U 287285612Sdelphij 288285612Sdelphij/** bits in NO_USAGE mask: 289285612Sdelphij * omitted no_command deprecated */ 290285612Sdelphij#define OPTST_NO_USAGE_MASK 0x6080000U 291285612Sdelphij 292285612Sdelphij/** bits in IMMUTABLE mask: 293285612Sdelphij * document omitted */ 294285612Sdelphij#define OPTST_IMMUTABLE_MASK 0x0280000U 295285612Sdelphij 296285612Sdelphij/** bits in DO_NOT_SAVE mask: 297285612Sdelphij * document omitted no_init */ 298285612Sdelphij#define OPTST_DO_NOT_SAVE_MASK 0x0280100U 299285612Sdelphij 300285612Sdelphij/** bits in NO_OUTPUT mask: 301285612Sdelphij * document omitted alias */ 302285612Sdelphij#define OPTST_NO_OUTPUT_MASK 0x8280000U 303285612Sdelphij 304285612Sdelphij/** all bits in opt_state_mask_t masks */ 305285612Sdelphij#define OPTST_MASK_ALL 0xFFFFF7FU 306285612Sdelphij 307285612Sdelphij/** no bits in opt_state_mask_t */ 308285612Sdelphij#define OPTST_INIT 0x0000000U 309285612Sdelphij/** @} */ 310285612Sdelphij 311181834Sroberto#ifdef NO_OPTIONAL_OPT_ARGS 312181834Sroberto# undef OPTST_ARG_OPTIONAL 313181834Sroberto# define OPTST_ARG_OPTIONAL 0 314181834Sroberto#endif 315181834Sroberto 316285612Sdelphij#define VENDOR_OPTION_VALUE 'W' 317181834Sroberto 318285612Sdelphij#define SELECTED_OPT(_od) ((_od)->fOptState & OPTST_SELECTED_MASK) 319285612Sdelphij#define UNUSED_OPT( _od) (((_od)->fOptState & OPTST_SET_MASK) == 0) 320285612Sdelphij#define DISABLED_OPT(_od) ((_od)->fOptState & OPTST_DISABLED) 321285612Sdelphij#define OPTION_STATE(_od) ((_od)->fOptState) 322285612Sdelphij#define OPTST_SET_ARGTYPE(_n) ((_n) << OPTST_ARG_TYPE_SHIFT) 323285612Sdelphij#define OPTST_GET_ARGTYPE(_f) \ 324285612Sdelphij (((_f)&OPTST_ARG_TYPE_MASK) >> OPTST_ARG_TYPE_SHIFT) 325181834Sroberto 326285612Sdelphij/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 327285612Sdelphij * 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 335285612Sdelphij/** 336181834Sroberto * Define the processing state flags 337285612Sdelphij * @{ 338181834Sroberto */ 339181834Sroberto 340285612Sdelphij/** integral type for holding proc_state masks */ 341285612Sdelphijtypedef uint32_t proc_state_mask_t; 342181834Sroberto 343285612Sdelphij/** bits defined for proc_state_mask_t */ 344285612Sdelphij/** Process long style options */ 345285612Sdelphij#define OPTPROC_LONGOPT 0x000001U 346285612Sdelphij/** Process short style "flags" */ 347285612Sdelphij#define OPTPROC_SHORTOPT 0x000002U 348285612Sdelphij/** Stop on argument errors */ 349285612Sdelphij#define OPTPROC_ERRSTOP 0x000004U 350285612Sdelphij/** Current option is disabled */ 351285612Sdelphij#define OPTPROC_DISABLEDOPT 0x000008U 352285612Sdelphij/** no options are required */ 353285612Sdelphij#define OPTPROC_NO_REQ_OPT 0x000010U 354285612Sdelphij/** there is a number option */ 355285612Sdelphij#define OPTPROC_NUM_OPT 0x000020U 356285612Sdelphij/** have inits been done? */ 357285612Sdelphij#define OPTPROC_INITDONE 0x000040U 358285612Sdelphij/** any negation options? */ 359285612Sdelphij#define OPTPROC_NEGATIONS 0x000080U 360285612Sdelphij/** check environment? */ 361285612Sdelphij#define OPTPROC_ENVIRON 0x000100U 362285612Sdelphij/** Disallow remaining arguments */ 363285612Sdelphij#define OPTPROC_NO_ARGS 0x000200U 364285612Sdelphij/** Require args after options */ 365285612Sdelphij#define OPTPROC_ARGS_REQ 0x000400U 366285612Sdelphij/** reorder operands after opts */ 367285612Sdelphij#define OPTPROC_REORDER 0x000800U 368285612Sdelphij/** emit usage in GNU style */ 369285612Sdelphij#define OPTPROC_GNUUSAGE 0x001000U 370285612Sdelphij/** Translate strings in tOptions */ 371285612Sdelphij#define OPTPROC_TRANSLATE 0x002000U 372285612Sdelphij/** no usage on usage error */ 373285612Sdelphij#define OPTPROC_MISUSE 0x004000U 374285612Sdelphij/** immediate options active */ 375285612Sdelphij#define OPTPROC_IMMEDIATE 0x008000U 376285612Sdelphij/** suppress for config only */ 377285612Sdelphij#define OPTPROC_NXLAT_OPT_CFG 0x010000U 378285612Sdelphij/** suppress xlation always */ 379285612Sdelphij#define OPTPROC_NXLAT_OPT 0x020000U 380285612Sdelphij/** vendor options active */ 381285612Sdelphij#define OPTPROC_VENDOR_OPT 0x040000U 382285612Sdelphij/** opt processing in preset state */ 383285612Sdelphij#define OPTPROC_PRESETTING 0x080000U 384285612Sdelphij/** Ignore pzFullUsage, compute usage text */ 385285612Sdelphij#define OPTPROC_COMPUTE 0x100000U 386285612Sdelphij/** Program outputs digested option state for shell scripts. Usage text 387285612Sdelphij * always written to stderr */ 388285612Sdelphij#define OPTPROC_SHELL_OUTPUT 0x200000U 389181834Sroberto 390285612Sdelphij/** bits in NO_XLAT mask: 391285612Sdelphij * nxlat_opt_cfg nxlat_opt */ 392285612Sdelphij#define OPTPROC_NO_XLAT_MASK 0x030000U 393285612Sdelphij 394285612Sdelphij/** all bits in proc_state_mask_t masks */ 395285612Sdelphij#define OPTPROC_MASK_ALL 0x3FFFFFU 396285612Sdelphij 397285612Sdelphij/** no bits in proc_state_mask_t */ 398285612Sdelphij#define OPTPROC_NONE 0x000000U 399285612Sdelphij/** @} */ 400285612Sdelphij 401285612Sdelphij#define STMTS(s) do { s; } while (false) 402285612Sdelphij 403285612Sdelphij/** 404285612Sdelphij * Abbreviation for const memory character. 405181834Sroberto */ 406181834Sroberto#define tCC char const 407181834Sroberto 408285612Sdelphij/** 409285612Sdelphij * Magical values for the program's option pointer 410285612Sdelphij * @{ 411181834Sroberto */ 412285612Sdelphijtypedef enum { 413285612Sdelphij OP_VAL_EMIT_USAGE = 1, ///< request for usage 414285612Sdelphij OP_VAL_EMIT_SHELL = 2, ///< emit value for Bourne shell evaluation 415285612Sdelphij OP_VAL_RETURN_VALNAME = 3, ///< return the value as a string 416285612Sdelphij OP_VAL_EMIT_LIMIT = 15 ///< limit for magic values 417285612Sdelphij} opt_proc_vals_t; 418181834Sroberto 419285612Sdelphij/// \a OPT_VAL_EMIT_USAGE cast as a pointer 420285612Sdelphij#define OPTPROC_EMIT_USAGE ((tOptions *)OP_VAL_EMIT_USAGE) 421285612Sdelphij 422285612Sdelphij/// \a OPT_VAL_EMIT_SHELL cast as a pointer 423285612Sdelphij#define OPTPROC_EMIT_SHELL ((tOptions *)OP_VAL_EMIT_SHELL) 424285612Sdelphij 425285612Sdelphij/// \a OPT_VAL_RETURN_VALNAME cast as a pointer 426285612Sdelphij#define OPTPROC_RETURN_VALNAME ((tOptions *)OP_VAL_RETURN_VALNAME) 427285612Sdelphij 428285612Sdelphij/// \a OPT_VAL_EMIT_LIMIT cast as a pointer 429285612Sdelphij#define OPTPROC_EMIT_LIMIT ((tOptions *)OP_VAL_EMIT_LIMIT) 430285612Sdelphij/** @} */ 431285612Sdelphij 432285612Sdelphij/** group option processing procedure types 433285612Sdelphij * @{ 434181834Sroberto */ 435285612Sdelphij/** forward declaration for tOptDesc */ 436285612Sdelphijtypedef struct opt_desc tOptDesc; 437285612Sdelphij/** forward declaration for tOptiond */ 438181834Srobertotypedef struct options tOptions; 439181834Sroberto 440285612Sdelphij/** 441181834Sroberto * The option procedures do the special processing for each 442181834Sroberto * option flag that needs it. 443181834Sroberto */ 444285612Sdelphijtypedef void (tOptProc)(tOptions * pOpts, tOptDesc * pOptDesc); 445181834Sroberto 446285612Sdelphij/** 447285612Sdelphij * a pointer to an option processing procedure 448285612Sdelphij */ 449285612Sdelphijtypedef tOptProc * tpOptProc; 450285612Sdelphij 451285612Sdelphij/** 452181834Sroberto * The usage procedure will never return. It calls "exit(2)" 453181834Sroberto * with the "exitCode" argument passed to it. 454181834Sroberto */ 455285612Sdelphij// coverity[+kill] 456285612Sdelphijtypedef void (tUsageProc)(tOptions * pOpts, int exitCode); 457181834Sroberto 458285612Sdelphij/** 459285612Sdelphij * a pointer to a procedure that prints usage and exits. 460285612Sdelphij */ 461285612Sdelphijtypedef tUsageProc * tpUsageProc; 462285612Sdelphij/** @} */ 463285612Sdelphij 464285612Sdelphij/** 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). 468285612Sdelphij * @{ 469181834Sroberto */ 470285612Sdelphij#define NOLIMIT USHRT_MAX ///< no occurrance count limit 471285612Sdelphij#define OPTION_LIMIT SHRT_MAX ///< maximum number of option types 472285612Sdelphij/// option index to indicate no equivalance or alias 473181834Sroberto#define NO_EQUIVALENT (OPTION_LIMIT+1) 474285612Sdelphij/** @} */ 475181834Sroberto 476285612Sdelphij/** 477285612Sdelphij * Option argument value. Which is valid is determined by: 478285612Sdelphij * (fOptState & OPTST_ARG_TYPE_MASK) >> OPTST_ARG_TYPE_SHIFT 479285612Sdelphij * which will yield one of the teOptArgType values. 480181834Sroberto */ 481285612Sdelphijtypedef union { 482285612Sdelphij char const * argString; ///< as a string 483285612Sdelphij uintptr_t argEnum; ///< as an enumeration value 484285612Sdelphij uintptr_t argIntptr; ///< as an integer big enough to hold pointer 485285612Sdelphij long argInt; ///< as a long integer 486285612Sdelphij unsigned long argUint; ///< as an unsigned long ingeger 487285612Sdelphij unsigned int argBool; ///< as a boolean value 488285612Sdelphij FILE * argFp; ///< as a FILE * pointer 489285612Sdelphij int argFd; ///< as a file descriptor (int) 490285612Sdelphij} opt_arg_union_t; 491181834Sroberto 492285612Sdelphij/// Compatibility define: \a pzLastArg is now \a optArg.argString 493285612Sdelphij#define pzLastArg optArg.argString 494285612Sdelphij/// The old amorphous argument bucket is now the opt_arg_union_t union. 495285612Sdelphij#define optArgBucket_t opt_arg_union_t 496181834Sroberto 497285612Sdelphij/** 498285612Sdelphij * Enumeration of AutoOpts defined options. The enumeration is used in 499285612Sdelphij * marking each option that is defined by AutoOpts so libopts can find 500285612Sdelphij * the correct descriptor. This renders \a option_spec_idx_t redundant. 501285612Sdelphij */ 502285612Sdelphijtypedef enum { 503285612Sdelphij AOUSE_USER_DEFINED = 0, ///< user specified option 504285612Sdelphij AOUSE_RESET_OPTION, ///< reset option state option 505285612Sdelphij AOUSE_VERSION, ///< request version 506285612Sdelphij AOUSE_HELP, ///< request usage help 507285612Sdelphij AOUSE_MORE_HELP, ///< request paged usage 508285612Sdelphij AOUSE_USAGE, ///< request short usage 509285612Sdelphij AOUSE_SAVE_OPTS, ///< save option state 510285612Sdelphij AOUSE_LOAD_OPTS, ///< load options from file 511285612Sdelphij AOUSE_VENDOR_OPT ///< specify a vendor option 512285612Sdelphij} opt_usage_t; 513181834Sroberto 514285612Sdelphij/** 515181834Sroberto * Descriptor structure for each option. 516181834Sroberto * Only the fields marked "PUBLIC" are for public use. 517181834Sroberto */ 518285612Sdelphijstruct opt_desc { 519285612Sdelphij /// Public, the index of this descriptor 520285612Sdelphij uint16_t const optIndex; 521285612Sdelphij /// Public, the flag character (value) 522285612Sdelphij uint16_t const optValue; 523285612Sdelphij /// Public, the index of the option used to activate option 524285612Sdelphij uint16_t optActualIndex; 525285612Sdelphij /// Public, the flag character of the activating option 526285612Sdelphij uint16_t optActualValue; 527181834Sroberto 528285612Sdelphij /// Public, the index of the equivalenced-to option. 529285612Sdelphij /// This is NO_EQUIVALENT unless activated. 530285612Sdelphij uint16_t const optEquivIndex; 531285612Sdelphij /// Private, the minimum occurrance count 532285612Sdelphij uint16_t const optMinCt; 533285612Sdelphij /// Private, the maximum occurrance count (NOLIMIT, if unlimited) 534285612Sdelphij uint16_t const optMaxCt; 535285612Sdelphij /// Public, the actual occurrance count 536285612Sdelphij uint16_t optOccCt; 537181834Sroberto 538285612Sdelphij /// Public, the option processing state 539285612Sdelphij opt_state_mask_t fOptState; 540285612Sdelphij /// Private, how the option is used (opt_usage_t) 541285612Sdelphij uint32_t optUsage; 542285612Sdelphij /// Public, The current option argument value 543285612Sdelphij opt_arg_union_t optArg; 544285612Sdelphij /// Public, data that is actually private to the code that handles 545285612Sdelphij /// this particular option. It is public IFF you have your own 546285612Sdelphij /// handling function. 547285612Sdelphij void * optCookie; 548181834Sroberto 549285612Sdelphij /// Private, a list of options that must be specified when this option 550285612Sdelphij /// has been specified 551285612Sdelphij int const * const pOptMust; 552181834Sroberto 553285612Sdelphij /// Private, a list of options that cannot be specified when this option 554285612Sdelphij /// has been specified 555285612Sdelphij int const * const pOptCant; 556285612Sdelphij 557285612Sdelphij /// Private, the function to call for handling this option 558285612Sdelphij tpOptProc const pOptProc; 559285612Sdelphij 560285612Sdelphij /// Private, usage information about this option 561285612Sdelphij char const * const pzText; 562285612Sdelphij 563285612Sdelphij /// Public, the UPPER CASE, shell variable name syntax name of the option 564285612Sdelphij char const * const pz_NAME; 565285612Sdelphij 566285612Sdelphij /// the unmodified name of the option 567285612Sdelphij char const * const pz_Name; 568285612Sdelphij 569285612Sdelphij /// the option name to use to disable the option. Long options names 570285612Sdelphij /// must be active. 571285612Sdelphij char const * const pz_DisableName; 572285612Sdelphij 573285612Sdelphij /// the special prefix that makes the normal option name become the 574285612Sdelphij /// disablement name. 575285612Sdelphij char const * const pz_DisablePfx; 576181834Sroberto}; 577181834Sroberto 578285612Sdelphij/** 579181834Sroberto * Some options need special processing, so we store their 580285612Sdelphij * indexes in a known place. 581181834Sroberto */ 582285612Sdelphijtypedef struct { 583285612Sdelphij uint16_t const more_help; ///< passes help text through pager 584285612Sdelphij uint16_t const save_opts; ///< stores option state to a file 585285612Sdelphij uint16_t const number_option; ///< the option "name" is an integer 586285612Sdelphij /// all arguments are options, this is the default option that must 587285612Sdelphij /// take an argument. That argument is the unrecognized option. 588285612Sdelphij uint16_t const default_opt; 589285612Sdelphij} option_spec_idx_t; 590181834Sroberto 591285612Sdelphij/** 592181834Sroberto * The procedure generated for translating option text 593181834Sroberto */ 594181834Srobertotypedef void (tOptionXlateProc)(void); 595181834Sroberto 596285612Sdelphij/** 597285612Sdelphij * Everything marked "PUBLIC" is also marked "const". Public access is not 598285612Sdelphij * a license to modify. Other fields are used and modified by the library. 599285612Sdelphij * They are also subject to change without any notice. 600285612Sdelphij * Do not even look at these outside of libopts. 601285612Sdelphij */ 602181834Srobertostruct options { 603285612Sdelphij int const structVersion; ///< The version of this struct 604285612Sdelphij unsigned int origArgCt; ///< program argument count 605285612Sdelphij char ** origArgVect; ///< program argument vector 606285612Sdelphij proc_state_mask_t fOptSet; ///< option proc. state flags 607285612Sdelphij unsigned int curOptIdx; ///< current option index 608285612Sdelphij char * pzCurOpt; ///< current option text 609181834Sroberto 610285612Sdelphij /// Public, the full path of the program 611285612Sdelphij char const * const pzProgPath; 612285612Sdelphij /// Public, the name of the executable, without any path 613285612Sdelphij char const * const pzProgName; 614285612Sdelphij /// Public, the upper-cased, shell variable syntax-ed program name 615285612Sdelphij char const * const pzPROGNAME; 616285612Sdelphij /// the name of the "rc file" (configuration file) 617285612Sdelphij char const * const pzRcName; 618285612Sdelphij /// the copyright text 619285612Sdelphij char const * const pzCopyright; 620285612Sdelphij /// the full copyright notice 621285612Sdelphij char const * const pzCopyNotice; 622285612Sdelphij /// a string with the program name, project name and version 623285612Sdelphij char const * const pzFullVersion; 624285612Sdelphij /// a list of pointers to directories to search for the config file 625285612Sdelphij char const * const * const papzHomeList; 626285612Sdelphij /// the title line for usage 627285612Sdelphij char const * const pzUsageTitle; 628285612Sdelphij /// some added explanation for what this program is trying to do 629285612Sdelphij char const * const pzExplain; 630285612Sdelphij /// a detailed explanation of the program's purpose, for use when 631285612Sdelphij /// full help has been requested 632285612Sdelphij char const * const pzDetail; 633285612Sdelphij /// The public array of option descriptors 634285612Sdelphij tOptDesc * const pOptDesc; 635285612Sdelphij /// the email address for reporting bugs 636285612Sdelphij char const * const pzBugAddr; 637181834Sroberto 638285612Sdelphij /// Reserved for future use 639285612Sdelphij void * pExtensions; 640285612Sdelphij /// A copy of the option state when optionSaveState was called. 641285612Sdelphij void * pSavedState; 642181834Sroberto 643285612Sdelphij /// The procedure to call to print usage text 644285612Sdelphij // coverity[+kill] 645285612Sdelphij tpUsageProc pUsageProc; 646285612Sdelphij /// The procedure to call to translate translatable option messages 647285612Sdelphij tOptionXlateProc * pTransProc; 648181834Sroberto 649285612Sdelphij /// Special option indexes. 650285612Sdelphij option_spec_idx_t specOptIdx; 651285612Sdelphij /// the total number of options for the program 652285612Sdelphij int const optCt; 653285612Sdelphij /// The number of "presettable" options, though some may be marked 654285612Sdelphij /// "no-preset". Includes all user specified options, plus a few 655285612Sdelphij /// that are specified by AutoOpts. 656285612Sdelphij int const presetOptCt; 657285612Sdelphij /// user specified full usage text 658285612Sdelphij char const * pzFullUsage; 659285612Sdelphij /// user specifed short usage (usage error triggered) message 660285612Sdelphij char const * pzShortUsage; 661285612Sdelphij /// The option argument settings active when optionSaveState was called 662285612Sdelphij opt_arg_union_t const * const originalOptArgArray; 663285612Sdelphij /// any saved cookie value 664285612Sdelphij void * const * const originalOptArgCookie; 665285612Sdelphij /// the package data directory (e.g. global configuration files) 666285612Sdelphij char const * const pzPkgDataDir; 667285612Sdelphij /// email address of the project packager 668285612Sdelphij char const * const pzPackager; 669181834Sroberto}; 670181834Sroberto 671181834Sroberto/* 672285612Sdelphij * Versions where in various fields first appear: 673285612Sdelphij * ($AO_CURRENT * 4096 + $AO_REVISION, but $AO_REVISION must be zero) 674285612Sdelphij */ 675285612Sdelphij/** 676285612Sdelphij * The version that first stored the original argument vector 677285612Sdelphij */ 678285612Sdelphij#define originalOptArgArray_STRUCT_VERSION 0x20000 /* AO_CURRENT = 32 */ 679285612Sdelphij#define HAS_originalOptArgArray(_opt) \ 680285612Sdelphij ((_opt)->structVersion >= originalOptArgArray_STRUCT_VERSION) 681285612Sdelphij 682285612Sdelphij/** 683285612Sdelphij * The version that first stored the package data directory 684285612Sdelphij */ 685285612Sdelphij#define pzPkgDataDir_STRUCT_VERSION 0x22000 /* AO_CURRENT = 34 */ 686285612Sdelphij#define HAS_pzPkgDataDir(_opt) \ 687285612Sdelphij ((_opt)->structVersion >= pzPkgDataDir_STRUCT_VERSION) 688285612Sdelphij 689285612Sdelphij/** 690285612Sdelphij * The version that first stored the option usage in each option descriptor 691285612Sdelphij */ 692285612Sdelphij#define opt_usage_t_STRUCT_VERSION 0x26000 /* AO_CURRENT = 38 */ 693285612Sdelphij#define HAS_opt_usage_t(_opt) \ 694285612Sdelphij ((_opt)->structVersion >= opt_usage_t_STRUCT_VERSION) 695285612Sdelphij 696285612Sdelphij/** 697181834Sroberto * "token list" structure returned by "string_tokenize()" 698181834Sroberto */ 699181834Srobertotypedef struct { 700285612Sdelphij unsigned long tkn_ct; ///< number of tokens found 701285612Sdelphij 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 714285612Sdelphij/** 715285612Sdelphij * Everything needed to be known about an mmap-ed file. 716285612Sdelphij * 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 { 726285612Sdelphij void * txt_data; ///< text file data 727285612Sdelphij size_t txt_size; ///< actual file size 728285612Sdelphij size_t txt_full_size; ///< mmaped mem size 729285612Sdelphij int txt_fd; ///< file descriptor 730285612Sdelphij int txt_zero_fd; ///< fd for /dev/zero 731285612Sdelphij int txt_errno; ///< warning code 732285612Sdelphij int txt_prot; ///< "prot" flags 733285612Sdelphij int txt_flags; ///< mapping type 734181834Sroberto} tmap_info_t; 735181834Sroberto 736285612Sdelphij/** 737285612Sdelphij * mmap result wrapper that yields "true" when mmap has failed. 738285612Sdelphij */ 739285612Sdelphij#define TEXT_MMAP_FAILED_ADDR(a) (VOIDP(a) == VOIDP(MAP_FAILED)) 740181834Sroberto 741181834Sroberto#ifdef __cplusplus 742285612Sdelphij#define CPLUSPLUS_OPENER extern "C" { 743285612SdelphijCPLUSPLUS_OPENER 744181834Sroberto#define CPLUSPLUS_CLOSER } 745181834Sroberto#else 746181834Sroberto#define CPLUSPLUS_CLOSER 747181834Sroberto#endif 748181834Sroberto 749285612Sdelphij/** 750181834Sroberto * The following routines may be coded into AutoOpts client code: 751181834Sroberto */ 752181834Sroberto 753285612Sdelphij/** 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. 761285612Sdelphij * 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. 765285612Sdelphij * 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 774285612Sdelphij * 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 784285612Sdelphij * 785181834Sroberto * Double quote strings are formed according to the rules of string 786181834Sroberto * constants in ANSI-C programs. 787285612Sdelphij * 788285612Sdelphij * @param string string to be tokenized 789285612Sdelphij * 790285612Sdelphij * @return token_list_t * - pointer to a structure that lists each token 791181834Sroberto */ 792285612Sdelphijextern token_list_t * ao_string_tokenize(char const *); 793181834Sroberto 794181834Sroberto 795285612Sdelphij/** 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()}. 805285612Sdelphij * 806285612Sdelphij * @param fname the file to load 807285612Sdelphij * 808285612Sdelphij * @return const tOptionValue * - An allocated, compound value structure 809181834Sroberto */ 810285612Sdelphijextern const tOptionValue * configFileLoad(char const *); 811181834Sroberto 812181834Sroberto 813285612Sdelphij/** 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. 823285612Sdelphij * 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. 827285612Sdelphij * 828181834Sroberto * See the AutoOpts documentation for a thorough discussion of the 829181834Sroberto * config file format. 830285612Sdelphij * 831181834Sroberto * Configuration files not found or not decipherable are simply ignored. 832285612Sdelphij * 833285612Sdelphij * @param opts program options descriptor 834285612Sdelphij * @param prog program name 835285612Sdelphij * 836285612Sdelphij * @return int - 0 -> SUCCESS, -1 -> FAILURE 837181834Sroberto */ 838285612Sdelphijextern int optionFileLoad(tOptions *, char const *); 839181834Sroberto 840181834Sroberto 841285612Sdelphij/** 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. 847285612Sdelphij * 848285612Sdelphij * @param odesc an option with a nested arg type 849285612Sdelphij * @param pPrevVal the last entry 850285612Sdelphij * @param name name of value to find 851285612Sdelphij * @param value the matching value 852285612Sdelphij * 853285612Sdelphij * @return const tOptionValue * - a compound value structure 854181834Sroberto */ 855285612Sdelphijextern const tOptionValue * optionFindNextValue(const tOptDesc *, const tOptionValue *, char const *, char const *); 856181834Sroberto 857181834Sroberto 858285612Sdelphij/** 859181834Sroberto * optionFindValue - find a hierarcicaly valued option instance 860181834Sroberto * 861285612Sdelphij * This routine will find an entry in a nested value option or configurable. 862285612Sdelphij * It will search through the list and return a matching entry. 863181834Sroberto * 864285612Sdelphij * @param odesc an option with a nested arg type 865285612Sdelphij * @param name name of value to find 866285612Sdelphij * @param val the matching value 867181834Sroberto * 868285612Sdelphij * @return const tOptionValue * - a compound value structure 869181834Sroberto */ 870285612Sdelphijextern const tOptionValue * optionFindValue(const tOptDesc *, char const *, char const *); 871181834Sroberto 872181834Sroberto 873285612Sdelphij/** 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. 878285612Sdelphij * 879285612Sdelphij * @param pOpts program options descriptor 880181834Sroberto */ 881285612Sdelphijextern void optionFree(tOptions *); 882181834Sroberto 883181834Sroberto 884285612Sdelphij/** 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 890285612Sdelphij * returned. If there is no matching value, NULL is returned and errno is 891285612Sdelphij * set to ENOENT. If the provided option value is not a hierarchical value, 892285612Sdelphij * NULL is also returned and errno is set to EINVAL. 893285612Sdelphij * 894285612Sdelphij * @param pOptValue a hierarchcal value 895285612Sdelphij * @param valueName name of value to get 896285612Sdelphij * 897285612Sdelphij * @return const tOptionValue * - a compound value structure 898181834Sroberto */ 899285612Sdelphijextern const tOptionValue * optionGetValue(const tOptionValue *, char const *); 900181834Sroberto 901181834Sroberto 902285612Sdelphij/** 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. 908285612Sdelphij * 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 912285612Sdelphij * the string. The caller need not skip over any introductory hyphens. 913285612Sdelphij * 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. 918285612Sdelphij * 919285612Sdelphij * @param opts program options descriptor 920285612Sdelphij * @param line NUL-terminated text 921181834Sroberto */ 922285612Sdelphijextern void optionLoadLine(tOptions *, char const *); 923181834Sroberto 924181834Sroberto 925285612Sdelphij/** 926285612Sdelphij * optionMemberList - Get the list of members of a bit mask set 927181834Sroberto * 928285612Sdelphij * This converts the OPT_VALUE_name mask value to a allocated string. 929285612Sdelphij * It is the caller's responsibility to free the string. 930181834Sroberto * 931285612Sdelphij * @param od the set membership option description 932181834Sroberto * 933285612Sdelphij * @return char * - the names of the set bits 934285612Sdelphij */ 935285612Sdelphijextern char * optionMemberList(tOptDesc *); 936285612Sdelphij 937285612Sdelphij 938285612Sdelphij/** 939285612Sdelphij * 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()}". 946285612Sdelphij * 947285612Sdelphij * @param pOptValue a hierarchcal list value 948285612Sdelphij * @param pOldValue a value from this list 949285612Sdelphij * 950285612Sdelphij * @return const tOptionValue * - a compound value structure 951181834Sroberto */ 952285612Sdelphijextern const tOptionValue * optionNextValue(const tOptionValue *, const tOptionValue *); 953181834Sroberto 954181834Sroberto 955285612Sdelphij/** 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. 961285612Sdelphij * 962285612Sdelphij * @param pOpts program options descriptor 963285612Sdelphij * @param ex_code exit code for calling exit(3) 964181834Sroberto */ 965285612Sdelphijextern void optionOnlyUsage(tOptions *, int); 966181834Sroberto 967181834Sroberto 968285612Sdelphij/** 969285612Sdelphij * optionPrintVersion - Print the program version 970181834Sroberto * 971285612Sdelphij * This routine will print the version to stdout. 972181834Sroberto * 973285612Sdelphij * @param opts program options descriptor 974285612Sdelphij * @param od the descriptor for this arg 975285612Sdelphij */ 976285612Sdelphijextern void optionPrintVersion(tOptions *, tOptDesc *); 977285612Sdelphij 978285612Sdelphij 979285612Sdelphij/** 980285612Sdelphij * optionPrintVersionAndReturn - Print the program version 981181834Sroberto * 982285612Sdelphij * This routine will print the version to stdout and return 983285612Sdelphij * instead of exiting. Please see the source for the 984285612Sdelphij * @code{print_ver} funtion for details on selecting how 985285612Sdelphij * verbose to be after this function returns. 986181834Sroberto * 987285612Sdelphij * @param opts program options descriptor 988285612Sdelphij * @param od the descriptor for this arg 989285612Sdelphij */ 990285612Sdelphijextern void optionPrintVersionAndReturn(tOptions *, tOptDesc *); 991285612Sdelphij 992285612Sdelphij 993285612Sdelphij/** 994285612Sdelphij * optionProcess - this is the main option processing routine 995285612Sdelphij * 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. 1002285612Sdelphij * 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. 1011285612Sdelphij * 1012285612Sdelphij * @param opts program options descriptor 1013285612Sdelphij * @param a_ct program arg count 1014285612Sdelphij * @param a_v program arg vector 1015285612Sdelphij * 1016285612Sdelphij * @return int - the count of the arguments processed 1017181834Sroberto */ 1018285612Sdelphijextern int optionProcess(tOptions *, int, char **); 1019181834Sroberto 1020181834Sroberto 1021285612Sdelphij/** 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. 1030285612Sdelphij * 1031285612Sdelphij * @param pOpts program options descriptor 1032181834Sroberto */ 1033285612Sdelphijextern void optionRestore(tOptions *); 1034181834Sroberto 1035181834Sroberto 1036285612Sdelphij/** 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 1044285612Sdelphij * file, you should invoke the @code{SET_OPT_SAVE_OPTS(@i{filename})} macro. 1045285612Sdelphij * 1046285612Sdelphij * The recommend usage is as follows: 1047285612Sdelphij * @example 1048285612Sdelphij * optionProcess(&progOptions, argc, argv); 1049285612Sdelphij * if (i_want_a_non_standard_place_for_this) 1050285612Sdelphij * SET_OPT_SAVE_OPTS("myfilename"); 1051285612Sdelphij * optionSaveFile(&progOptions); 1052285612Sdelphij * @end example 1053285612Sdelphij * 1054285612Sdelphij * @param opts program options descriptor 1055181834Sroberto */ 1056285612Sdelphijextern void optionSaveFile(tOptions *); 1057181834Sroberto 1058181834Sroberto 1059285612Sdelphij/** 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) 1068285612Sdelphij * 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. 1073285612Sdelphij * 1074285612Sdelphij * @param pOpts program options descriptor 1075181834Sroberto */ 1076285612Sdelphijextern void optionSaveState(tOptions *); 1077181834Sroberto 1078181834Sroberto 1079285612Sdelphij/** 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}). 1085285612Sdelphij * 1086285612Sdelphij * @param pOptVal the hierarchical value 1087181834Sroberto */ 1088285612Sdelphijextern void optionUnloadNested(tOptionValue const *); 1089181834Sroberto 1090181834Sroberto 1091285612Sdelphij/** 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 * 1097285612Sdelphij * @return char const * - the version string in constant memory 1098181834Sroberto */ 1099285612Sdelphijextern char const * optionVersion(void); 1100181834Sroberto 1101181834Sroberto 1102285612Sdelphij/** 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. 1109285612Sdelphij * 1110285612Sdelphij * @param ch_list characters to equivalence 1111181834Sroberto */ 1112285612Sdelphijextern void strequate(char const *); 1113181834Sroberto 1114181834Sroberto 1115285612Sdelphij/** 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. 1123285612Sdelphij * 1124285612Sdelphij * @param str1 first string 1125285612Sdelphij * @param str2 second string 1126285612Sdelphij * 1127285612Sdelphij * @return int - the difference between two differing characters 1128181834Sroberto */ 1129285612Sdelphijextern int streqvcmp(char const *, char const *); 1130181834Sroberto 1131181834Sroberto 1132285612Sdelphij/** 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 1142285612Sdelphij * 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. 1147285612Sdelphij * 1148181834Sroberto * This function name is mapped to option_streqvmap so as to not conflict 1149181834Sroberto * with the POSIX name space. 1150285612Sdelphij * 1151285612Sdelphij * @param from Input character 1152285612Sdelphij * @param to Mapped-to character 1153285612Sdelphij * @param ct compare length 1154181834Sroberto */ 1155285612Sdelphijextern void streqvmap(char, char, int); 1156181834Sroberto 1157181834Sroberto 1158285612Sdelphij/** 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. 1167285612Sdelphij * 1168285612Sdelphij * @param str1 first string 1169285612Sdelphij * @param str2 second string 1170285612Sdelphij * @param ct compare length 1171285612Sdelphij * 1172285612Sdelphij * @return int - the difference between two differing characters 1173181834Sroberto */ 1174285612Sdelphijextern int strneqvcmp(char const *, char const *, int); 1175181834Sroberto 1176181834Sroberto 1177285612Sdelphij/** 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. 1184285612Sdelphij * 1185285612Sdelphij * The source and destination may be the same. 1186285612Sdelphij * 1187285612Sdelphij * @param dest output string 1188285612Sdelphij * @param src input string 1189181834Sroberto */ 1190285612Sdelphijextern void strtransform(char *, char const *); 1191181834Sroberto 1192181834Sroberto/* AutoOpts PRIVATE FUNCTIONS: */ 1193181834SrobertotOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal; 1194181834Sroberto 1195285612Sdelphijextern char * ao_string_cook(char *, int *); 1196181834Sroberto 1197285612Sdelphijextern unsigned int ao_string_cook_escape_char(char const *, char *, unsigned int); 1198181834Sroberto 1199285612Sdelphijextern void genshelloptUsage(tOptions *, int); 1200181834Sroberto 1201285612Sdelphijextern int optionAlias(tOptions *, tOptDesc *, unsigned int); 1202181834Sroberto 1203285612Sdelphijextern void optionBooleanVal(tOptions *, tOptDesc *); 1204181834Sroberto 1205285612Sdelphijextern uintptr_t optionEnumerationVal(tOptions *, tOptDesc *, char const * const *, unsigned int); 1206181834Sroberto 1207285612Sdelphijextern void optionFileCheck(tOptions *, tOptDesc *, teOptFileType, tuFileMode); 1208181834Sroberto 1209285612Sdelphijextern char const * optionKeywordName(tOptDesc *, unsigned int); 1210181834Sroberto 1211285612Sdelphijextern void optionLoadOpt(tOptions *, tOptDesc *); 1212181834Sroberto 1213285612Sdelphijextern bool optionMakePath(char *, int, char const *, char const *); 1214181834Sroberto 1215285612Sdelphijextern void optionNestedVal(tOptions *, tOptDesc *); 1216181834Sroberto 1217285612Sdelphijextern void optionNumericVal(tOptions *, tOptDesc *); 1218181834Sroberto 1219285612Sdelphijextern void optionPagedUsage(tOptions *, tOptDesc *); 1220181834Sroberto 1221285612Sdelphijextern void optionParseShell(tOptions *); 1222181834Sroberto 1223285612Sdelphijextern void optionPrintParagraphs(char const *, bool, FILE *); 1224181834Sroberto 1225285612Sdelphijextern void optionPutShell(tOptions *); 1226181834Sroberto 1227285612Sdelphijextern char const * optionQuoteString(char const *, char const *); 1228181834Sroberto 1229285612Sdelphijextern void optionResetOpt(tOptions *, tOptDesc *); 1230181834Sroberto 1231285612Sdelphijextern void optionSetMembers(tOptions *, tOptDesc *, char const * const *, unsigned int); 1232181834Sroberto 1233285612Sdelphijextern void optionShowRange(tOptions *, tOptDesc *, void *, int); 1234181834Sroberto 1235285612Sdelphijextern void optionStackArg(tOptions *, tOptDesc *); 1236181834Sroberto 1237285612Sdelphijextern void optionTimeDate(tOptions *, tOptDesc *); 1238181834Sroberto 1239285612Sdelphijextern void optionTimeVal(tOptions *, tOptDesc *); 1240285612Sdelphij 1241285612Sdelphijextern void optionUnstackArg(tOptions *, tOptDesc *); 1242285612Sdelphij 1243285612Sdelphijextern void optionUsage(tOptions *, int); 1244285612Sdelphij 1245285612Sdelphijextern void optionVendorOption(tOptions *, tOptDesc *); 1246285612Sdelphij 1247285612Sdelphijextern void optionVersionStderr(tOptions *, tOptDesc *); 1248285612Sdelphij 1249285612Sdelphijextern void * text_mmap(char const *, int, int, tmap_info_t *); 1250285612Sdelphij 1251285612Sdelphijextern int text_munmap(tmap_info_t *); 1252285612Sdelphij 1253181834SrobertoCPLUSPLUS_CLOSER 1254181834Sroberto#endif /* AUTOOPTS_OPTIONS_H_GUARD */ 1255285612Sdelphij/** @} 1256285612Sdelphij * 1257181834Sroberto * Local Variables: 1258181834Sroberto * c-file-style: "stroustrup" 1259181834Sroberto * indent-tabs-mode: nil 1260181834Sroberto * End: 1261181834Sroberto * options.h ends here */ 1262