1 /* $NetBSD: options.h,v 1.2 2010/12/04 23:08:48 christos Exp $ */ 2 3 /* -*- buffer-read-only: t -*- vi: set ro: 4 * 5 * DO NOT EDIT THIS FILE (options.h) 6 * 7 * It has been AutoGen-ed November 8, 2009 at 08:41:08 AM by AutoGen 5.9.10pre13 8 * From the definitions funcs.def 9 * and the template file options_h 10 * 11 * This file defines all the global structures and special values 12 * used in the automated option processing library. 13 * 14 * Automated Options copyright (c) 1992-Y by Bruce Korb 15 * 16 * AutoOpts is free software: you can redistribute it and/or modify it 17 * under the terms of the GNU Lesser General Public License as published 18 * by the Free Software Foundation, either version 3 of the License, or 19 * (at your option) any later version. 20 * 21 * AutoOpts is distributed in the hope that it will be useful, but 22 * WITHOUT ANY WARRANTY; without even the implied warranty of 23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 24 * See the GNU Lesser General Public License for more details. 25 * 26 * You should have received a copy of the GNU Lesser General Public License 27 * along with this program. If not, see <http://www.gnu.org/licenses/>. 28 */ 29 #ifndef AUTOOPTS_OPTIONS_H_GUARD 30 #define AUTOOPTS_OPTIONS_H_GUARD 1 31 #include <sys/types.h> 32 #include <stdio.h> 33 34 #if defined(HAVE_STDINT_H) 35 # include <stdint.h> 36 #elif defined(HAVE_INTTYPES_H) 37 # include <inttypes.h> 38 #endif /* HAVE_STDINT/INTTYPES_H */ 39 40 #if defined(HAVE_LIMITS_H) 41 # include <limits.h> 42 #elif defined(HAVE_SYS_LIMITS_H) 43 # include <sys/limits.h> 44 #endif /* HAVE_LIMITS/SYS_LIMITS_H */ 45 46 #if defined(HAVE_SYSEXITS_H) 47 # include <sysexits.h> 48 #endif /* HAVE_SYSEXITS_H */ 49 50 #ifndef EX_USAGE 51 # define EX_USAGE 64 52 #endif 53 54 /* 55 * PUBLIC DEFINES 56 * 57 * The following defines may be used in applications that need to test the 58 * state of an option. To test against these masks and values, a pointer 59 * to an option descriptor must be obtained. There are two ways: 60 * 61 * 1. inside an option processing procedure, it is the second argument, 62 * conventionally "tOptDesc* pOD". 63 * 64 * 2. Outside of an option procedure (or to reference a different option 65 * descriptor), use either "&DESC( opt_name )" or "&pfx_DESC( opt_name )". 66 * 67 * See the relevant generated header file to determine which and what 68 * values for "opt_name" are available. 69 */ 70 71 #define OPTIONS_STRUCT_VERSION 135168 72 #define OPTIONS_VERSION_STRING "33:0:8" 73 #define OPTIONS_MINIMUM_VERSION 102400 74 #define OPTIONS_MIN_VER_STRING "25:0:0" 75 76 typedef enum { 77 OPARG_TYPE_NONE = 0, 78 OPARG_TYPE_STRING = 1, /* default type/ vanilla string */ 79 OPARG_TYPE_ENUMERATION = 2, /* opt arg is an enum (keyword list) */ 80 OPARG_TYPE_BOOLEAN = 3, /* opt arg is boolean-valued */ 81 OPARG_TYPE_MEMBERSHIP = 4, /* opt arg sets set membership bits */ 82 OPARG_TYPE_NUMERIC = 5, /* opt arg has numeric value */ 83 OPARG_TYPE_HIERARCHY = 6, /* option arg is hierarchical value */ 84 OPARG_TYPE_FILE = 7, /* option arg names a file */ 85 OPARG_TYPE_TIME = 8 /* opt arg is a time duration */ 86 } teOptArgType; 87 88 typedef struct optionValue { 89 teOptArgType valType; 90 char* pzName; 91 union { 92 char strVal[1]; /* OPARG_TYPE_STRING */ 93 unsigned int enumVal; /* OPARG_TYPE_ENUMERATION */ 94 unsigned int boolVal; /* OPARG_TYPE_BOOLEAN */ 95 unsigned long setVal; /* OPARG_TYPE_MEMBERSHIP */ 96 long longVal; /* OPARG_TYPE_NUMERIC */ 97 void* nestVal; /* OPARG_TYPE_HIERARCHY */ 98 } v; 99 } tOptionValue; 100 101 typedef enum { 102 FTYPE_MODE_MAY_EXIST = 0x00, 103 FTYPE_MODE_MUST_EXIST = 0x01, 104 FTYPE_MODE_MUST_NOT_EXIST = 0x02, 105 FTYPE_MODE_EXIST_MASK = 0x03, 106 FTYPE_MODE_NO_OPEN = 0x00, 107 FTYPE_MODE_OPEN_FD = 0x10, 108 FTYPE_MODE_FOPEN_FP = 0x20, 109 FTYPE_MODE_OPEN_MASK = 0x30 110 } teOptFileType; 111 112 typedef union { 113 int file_flags; 114 char const * file_mode; 115 } tuFileMode; 116 117 /* 118 * Bits in the fOptState option descriptor field. 119 */ 120 typedef enum { 121 OPTST_SET_ID = 0, /* Set via the "SET_OPT()" macro */ 122 OPTST_PRESET_ID = 1, /* Set via an RC/INI file */ 123 OPTST_DEFINED_ID = 2, /* Set via a command line option */ 124 OPTST_RESET_ID = 3, /* Reset via command line option */ 125 OPTST_EQUIVALENCE_ID = 4, /* selected by equiv'ed option */ 126 OPTST_DISABLED_ID = 5, /* option is in disabled state */ 127 OPTST_ALLOC_ARG_ID = 6, /* pzOptArg was allocated */ 128 OPTST_NO_INIT_ID = 8, /* option cannot be preset */ 129 OPTST_NUMBER_OPT_ID = 9, /* opt value (flag) is any digit */ 130 OPTST_STACKED_ID = 10, /* opt uses optionStackArg proc */ 131 OPTST_INITENABLED_ID = 11, /* option defaults to enabled */ 132 OPTST_ARG_TYPE_1_ID = 12, /* bit 1 of arg type enum */ 133 OPTST_ARG_TYPE_2_ID = 13, /* bit 2 of arg type enum */ 134 OPTST_ARG_TYPE_3_ID = 14, /* bit 3 of arg type enum */ 135 OPTST_ARG_TYPE_4_ID = 15, /* bit 4 of arg type enum */ 136 OPTST_ARG_OPTIONAL_ID = 16, /* the option arg not required */ 137 OPTST_IMM_ID = 17, /* process opt on first pass */ 138 OPTST_DISABLE_IMM_ID = 18, /* process disablement immed. */ 139 OPTST_OMITTED_ID = 19, /* compiled out of program */ 140 OPTST_MUST_SET_ID = 20, /* must be set or pre-set */ 141 OPTST_DOCUMENT_ID = 21, /* opt is for doc only */ 142 OPTST_TWICE_ID = 22, /* process opt twice - imm + reg */ 143 OPTST_DISABLE_TWICE_ID = 23, /* process disabled option twice */ 144 OPTST_SCALED_NUM_ID = 24, /* scaled integer value */ 145 OPTST_NO_COMMAND_ID = 25, /* disable from cmd line */ 146 OPTST_DEPRECATED_ID = 26 /* support is being removed */ 147 } opt_state_enum_t; 148 149 #define OPTST_INIT 0U 150 #define OPTST_SET (1U << OPTST_SET_ID) 151 #define OPTST_PRESET (1U << OPTST_PRESET_ID) 152 #define OPTST_DEFINED (1U << OPTST_DEFINED_ID) 153 #define OPTST_RESET (1U << OPTST_RESET_ID) 154 #define OPTST_EQUIVALENCE (1U << OPTST_EQUIVALENCE_ID) 155 #define OPTST_DISABLED (1U << OPTST_DISABLED_ID) 156 #define OPTST_ALLOC_ARG (1U << OPTST_ALLOC_ARG_ID) 157 #define OPTST_NO_INIT (1U << OPTST_NO_INIT_ID) 158 #define OPTST_NUMBER_OPT (1U << OPTST_NUMBER_OPT_ID) 159 #define OPTST_STACKED (1U << OPTST_STACKED_ID) 160 #define OPTST_INITENABLED (1U << OPTST_INITENABLED_ID) 161 #define OPTST_ARG_TYPE_1 (1U << OPTST_ARG_TYPE_1_ID) 162 #define OPTST_ARG_TYPE_2 (1U << OPTST_ARG_TYPE_2_ID) 163 #define OPTST_ARG_TYPE_3 (1U << OPTST_ARG_TYPE_3_ID) 164 #define OPTST_ARG_TYPE_4 (1U << OPTST_ARG_TYPE_4_ID) 165 #define OPTST_ARG_OPTIONAL (1U << OPTST_ARG_OPTIONAL_ID) 166 #define OPTST_IMM (1U << OPTST_IMM_ID) 167 #define OPTST_DISABLE_IMM (1U << OPTST_DISABLE_IMM_ID) 168 #define OPTST_OMITTED (1U << OPTST_OMITTED_ID) 169 #define OPTST_MUST_SET (1U << OPTST_MUST_SET_ID) 170 #define OPTST_DOCUMENT (1U << OPTST_DOCUMENT_ID) 171 #define OPTST_TWICE (1U << OPTST_TWICE_ID) 172 #define OPTST_DISABLE_TWICE (1U << OPTST_DISABLE_TWICE_ID) 173 #define OPTST_SCALED_NUM (1U << OPTST_SCALED_NUM_ID) 174 #define OPTST_NO_COMMAND (1U << OPTST_NO_COMMAND_ID) 175 #define OPTST_DEPRECATED (1U << OPTST_DEPRECATED_ID) 176 #define OPT_STATE_MASK 0x07FFFF7FU 177 178 #define OPTST_SET_MASK ( \ 179 OPTST_DEFINED | OPTST_PRESET | OPTST_RESET | \ 180 OPTST_SET \ 181 /* 0x0000000FU */ ) 182 183 #define OPTST_MUTABLE_MASK ( \ 184 OPTST_ALLOC_ARG | OPTST_DEFINED | \ 185 OPTST_DISABLED | OPTST_EQUIVALENCE | \ 186 OPTST_PRESET | OPTST_RESET | \ 187 OPTST_SET \ 188 /* 0x0000007FU */ ) 189 190 #define OPTST_SELECTED_MASK ( \ 191 OPTST_DEFINED | OPTST_SET \ 192 /* 0x00000005U */ ) 193 194 #define OPTST_ARG_TYPE_MASK ( \ 195 OPTST_ARG_TYPE_1 | OPTST_ARG_TYPE_2 | OPTST_ARG_TYPE_3 | \ 196 OPTST_ARG_TYPE_4 \ 197 /* 0x0000F000U */ ) 198 199 #define OPTST_DO_NOT_SAVE_MASK ( \ 200 OPTST_DOCUMENT | OPTST_NO_INIT | OPTST_OMITTED \ 201 /* 0x00280100U */ ) 202 203 #define OPTST_NO_USAGE_MASK ( \ 204 OPTST_DEPRECATED | OPTST_NO_COMMAND | OPTST_OMITTED \ 205 /* 0x06080000U */ ) 206 207 #ifdef NO_OPTIONAL_OPT_ARGS 208 # undef OPTST_ARG_OPTIONAL 209 # define OPTST_ARG_OPTIONAL 0 210 #endif 211 212 #define OPTST_PERSISTENT_MASK (~OPTST_MUTABLE_MASK) 213 214 #define SELECTED_OPT(_od) ((_od)->fOptState & OPTST_SELECTED_MASK) 215 #define UNUSED_OPT( _od) (((_od)->fOptState & OPTST_SET_MASK) == 0) 216 #define DISABLED_OPT(_od) ((_od)->fOptState & OPTST_DISABLED) 217 #define OPTION_STATE(_od) ((_od)->fOptState) 218 #define OPTST_SET_ARGTYPE(_n) ((_n) << OPTST_ARG_TYPE_1_ID) 219 #define OPTST_GET_ARGTYPE(_f) (((_f)&OPTST_ARG_TYPE_MASK)>>OPTST_ARG_TYPE_1_ID) 220 221 /* 222 * PRIVATE INTERFACES 223 * 224 * The following values are used in the generated code to communicate 225 * with the option library procedures. They are not for public use 226 * and may be subject to change. 227 */ 228 229 /* 230 * Define the processing state flags 231 */ 232 typedef enum { 233 OPTPROC_LONGOPT_ID = 0, /* Process long style options */ 234 OPTPROC_SHORTOPT_ID = 1, /* Process short style "flags" */ 235 OPTPROC_ERRSTOP_ID = 2, /* Stop on argument errors */ 236 OPTPROC_DISABLEDOPT_ID = 3, /* Current option is disabled */ 237 OPTPROC_NO_REQ_OPT_ID = 4, /* no options are required */ 238 OPTPROC_NUM_OPT_ID = 5, /* there is a number option */ 239 OPTPROC_INITDONE_ID = 6, /* have inits been done? */ 240 OPTPROC_NEGATIONS_ID = 7, /* any negation options? */ 241 OPTPROC_ENVIRON_ID = 8, /* check environment? */ 242 OPTPROC_NO_ARGS_ID = 9, /* Disallow remaining arguments */ 243 OPTPROC_ARGS_REQ_ID = 10, /* Require args after options */ 244 OPTPROC_REORDER_ID = 11, /* reorder operands after opts */ 245 OPTPROC_GNUUSAGE_ID = 12, /* emit usage in GNU style */ 246 OPTPROC_TRANSLATE_ID = 13, /* Translate strings in tOptions */ 247 OPTPROC_NXLAT_OPT_CFG_ID = 16, /* suppress for config only */ 248 OPTPROC_NXLAT_OPT_ID = 17, /* suppress xlation always */ 249 OPTPROC_PRESETTING_ID = 19 /* opt processing in preset state */ 250 } optproc_state_enum_t; 251 252 #define OPTPROC_NONE 0U 253 #define OPTPROC_LONGOPT (1U << OPTPROC_LONGOPT_ID) 254 #define OPTPROC_SHORTOPT (1U << OPTPROC_SHORTOPT_ID) 255 #define OPTPROC_ERRSTOP (1U << OPTPROC_ERRSTOP_ID) 256 #define OPTPROC_DISABLEDOPT (1U << OPTPROC_DISABLEDOPT_ID) 257 #define OPTPROC_NO_REQ_OPT (1U << OPTPROC_NO_REQ_OPT_ID) 258 #define OPTPROC_NUM_OPT (1U << OPTPROC_NUM_OPT_ID) 259 #define OPTPROC_INITDONE (1U << OPTPROC_INITDONE_ID) 260 #define OPTPROC_NEGATIONS (1U << OPTPROC_NEGATIONS_ID) 261 #define OPTPROC_ENVIRON (1U << OPTPROC_ENVIRON_ID) 262 #define OPTPROC_NO_ARGS (1U << OPTPROC_NO_ARGS_ID) 263 #define OPTPROC_ARGS_REQ (1U << OPTPROC_ARGS_REQ_ID) 264 #define OPTPROC_REORDER (1U << OPTPROC_REORDER_ID) 265 #define OPTPROC_GNUUSAGE (1U << OPTPROC_GNUUSAGE_ID) 266 #define OPTPROC_TRANSLATE (1U << OPTPROC_TRANSLATE_ID) 267 #define OPTPROC_NXLAT_OPT_CFG (1U << OPTPROC_NXLAT_OPT_CFG_ID) 268 #define OPTPROC_NXLAT_OPT (1U << OPTPROC_NXLAT_OPT_ID) 269 #define OPTPROC_PRESETTING (1U << OPTPROC_PRESETTING_ID) 270 #define OPTPROC_STATE_MASK 0x000B3FFFU 271 272 #define OPTPROC_NO_XLAT_MASK ( \ 273 OPTPROC_NXLAT_OPT | OPTPROC_NXLAT_OPT_CFG \ 274 /* 0x00030000U */ ) 275 276 #define STMTS(s) do { s; } while (0) 277 278 /* 279 * The following must be #defined instead of typedef-ed 280 * because "static const" cannot both be applied to a type, 281 * tho each individually can...so they all are 282 */ 283 #define tSCC static char const 284 #define tCC char const 285 #define tAoSC static char 286 #define tAoUC unsigned char 287 #define tAoUI unsigned int 288 #define tAoUL unsigned long 289 #define tAoUS unsigned short 290 291 /* 292 * It is so disgusting that there must be so many ways 293 * of specifying TRUE and FALSE. 294 */ 295 typedef enum { AG_FALSE = 0, AG_TRUE } ag_bool; 296 297 /* 298 * Define a structure that describes each option and 299 * a pointer to the procedure that handles it. 300 * The argument is the count of this flag previously seen. 301 */ 302 typedef struct options tOptions; 303 typedef struct optDesc tOptDesc; 304 typedef struct optNames tOptNames; 305 #define OPTPROC_EMIT_USAGE ((tOptions *)0x01UL) 306 #define OPTPROC_EMIT_SHELL ((tOptions *)0x02UL) 307 #define OPTPROC_RETURN_VALNAME ((tOptions *)0x03UL) 308 #define OPTPROC_EMIT_LIMIT ((tOptions *)0x0FUL) 309 310 /* 311 * The option procedures do the special processing for each 312 * option flag that needs it. 313 */ 314 typedef void (tOptProc)(tOptions* pOpts, tOptDesc* pOptDesc); 315 typedef tOptProc* tpOptProc; 316 317 /* 318 * The usage procedure will never return. It calls "exit(2)" 319 * with the "exitCode" argument passed to it. 320 */ 321 // coverity[+kill] 322 typedef void (tUsageProc)(tOptions* pOpts, int exitCode); 323 typedef tUsageProc* tpUsageProc; 324 325 /* 326 * Special definitions. "NOLIMIT" is the 'max' value to use when 327 * a flag may appear multiple times without limit. "NO_EQUIVALENT" 328 * is an illegal value for 'optIndex' (option description index). 329 */ 330 #define NOLIMIT USHRT_MAX 331 #define OPTION_LIMIT SHRT_MAX 332 #define NO_EQUIVALENT (OPTION_LIMIT+1) 333 334 /* 335 * Special values for optValue. It must not be generatable from the 336 * computation "optIndex +96". Since "optIndex" is limited to 100, ... 337 */ 338 #define NUMBER_OPTION '#' 339 340 typedef struct argList tArgList; 341 #define MIN_ARG_ALLOC_CT 6 342 #define INCR_ARG_ALLOC_CT 8 343 struct argList { 344 int useCt; 345 int allocCt; 346 tCC* apzArgs[ MIN_ARG_ALLOC_CT ]; 347 }; 348 349 typedef union { 350 char const * argString; 351 uintptr_t argEnum; 352 uintptr_t argIntptr; 353 long argInt; 354 unsigned long argUint; 355 unsigned int argBool; 356 FILE* argFp; 357 int argFd; 358 } optArgBucket_t; 359 360 /* 361 * Descriptor structure for each option. 362 * Only the fields marked "PUBLIC" are for public use. 363 */ 364 struct optDesc { 365 tAoUS const optIndex; /* PUBLIC */ 366 tAoUS const optValue; /* PUBLIC */ 367 tAoUS optActualIndex; /* PUBLIC */ 368 tAoUS optActualValue; /* PUBLIC */ 369 370 tAoUS const optEquivIndex; /* PUBLIC */ 371 tAoUS const optMinCt; 372 tAoUS const optMaxCt; 373 tAoUS optOccCt; /* PUBLIC */ 374 375 tAoUI fOptState; /* PUBLIC */ 376 tAoUI reserved; 377 optArgBucket_t optArg; /* PUBLIC */ 378 # define pzLastArg optArg.argString 379 void* optCookie; /* PUBLIC */ 380 381 int const * const pOptMust; 382 int const * const pOptCant; 383 tpOptProc const pOptProc; 384 char const* const pzText; 385 386 char const* const pz_NAME; 387 char const* const pz_Name; 388 char const* const pz_DisableName; 389 char const* const pz_DisablePfx; 390 }; 391 392 /* 393 * Some options need special processing, so we store their 394 * indexes in a known place: 395 */ 396 typedef struct optSpecIndex tOptSpecIndex; 397 struct optSpecIndex { 398 const tAoUS more_help; 399 const tAoUS save_opts; 400 const tAoUS number_option; 401 const tAoUS default_opt; 402 }; 403 404 /* 405 * The procedure generated for translating option text 406 */ 407 typedef void (tOptionXlateProc)(void); 408 409 struct options { 410 int const structVersion; 411 unsigned int origArgCt; 412 char** origArgVect; 413 unsigned int fOptSet; 414 unsigned int curOptIdx; 415 char* pzCurOpt; 416 417 char const* pzProgPath; /* PUBLIC */ 418 char const* pzProgName; /* PUBLIC */ 419 char const* const pzPROGNAME; /* PUBLIC */ 420 char const* const pzRcName; /* PUBLIC */ 421 char const* const pzCopyright; /* PUBLIC */ 422 char const* const pzCopyNotice; /* PUBLIC */ 423 char const* const pzFullVersion; /* PUBLIC */ 424 char const* const* const papzHomeList; 425 char const* const pzUsageTitle; 426 char const* const pzExplain; 427 char const* const pzDetail; 428 tOptDesc* const pOptDesc; /* PUBLIC */ 429 char const* const pzBugAddr; /* PUBLIC */ 430 431 void* pExtensions; 432 void* pSavedState; 433 434 // coverity[+kill] 435 tpUsageProc pUsageProc; 436 tOptionXlateProc* pTransProc; 437 438 tOptSpecIndex specOptIdx; 439 int const optCt; 440 int const presetOptCt; 441 char const * pzFullUsage; 442 char const * pzShortUsage; 443 /* PUBLIC: */ 444 optArgBucket_t const * const originalOptArgArray; 445 void * const * const originalOptArgCookie; 446 }; 447 448 /* 449 * Versions where in various fields first appear: 450 * ($AO_CURRENT * 4096 + $AO_REVISION, but $AO_REVISION must be zero) 451 */ 452 #define originalOptArgArray_STRUCT_VERSION 131072 /* AO_CURRENT = 32 */ 453 #define HAS_originalOptArgArray(_opt) \ 454 ((_opt)->structVersion >= originalOptArgArray_STRUCT_VERSION) 455 456 /* 457 * "token list" structure returned by "string_tokenize()" 458 */ 459 typedef struct { 460 unsigned long tkn_ct; 461 unsigned char* tkn_list[1]; 462 } token_list_t; 463 464 /* 465 * Hide the interface - it pollutes a POSIX claim, but leave it for 466 * anyone #include-ing this header 467 */ 468 #define strneqvcmp option_strneqvcmp 469 #define streqvcmp option_streqvcmp 470 #define streqvmap option_streqvmap 471 #define strequate option_strequate 472 #define strtransform option_strtransform 473 474 /* 475 * This is an output only structure used by text_mmap and text_munmap. 476 * Clients must not alter the contents and must provide it to both 477 * the text_mmap and text_munmap procedures. BE ADVISED: if you are 478 * mapping the file with PROT_WRITE the NUL byte at the end MIGHT NOT 479 * BE WRITABLE. In any event, that byte is not be written back 480 * to the source file. ALSO: if "txt_data" is valid and "txt_errno" 481 * is not zero, then there *may* not be a terminating NUL. 482 */ 483 typedef struct { 484 void* txt_data; /* text file data */ 485 size_t txt_size; /* actual file size */ 486 size_t txt_full_size; /* mmaped mem size */ 487 int txt_fd; /* file descriptor */ 488 int txt_zero_fd; /* fd for /dev/zero */ 489 int txt_errno; /* warning code */ 490 int txt_prot; /* "prot" flags */ 491 int txt_flags; /* mapping type */ 492 int txt_alloc; /* if we malloced memory */ 493 } tmap_info_t; 494 495 #define TEXT_MMAP_FAILED_ADDR(a) ((void*)(a) == (void*)MAP_FAILED) 496 497 #ifdef __cplusplus 498 extern "C" { 499 #define CPLUSPLUS_CLOSER } 500 #else 501 #define CPLUSPLUS_CLOSER 502 #endif 503 504 /* 505 * The following routines may be coded into AutoOpts client code: 506 */ 507 508 /* From: tokenize.c line 117 509 * 510 * ao_string_tokenize - tokenize an input string 511 * 512 * Arguments: 513 * string string to be tokenized 514 * 515 * Returns: token_list_t* - pointer to a structure that lists each token 516 * 517 * This function will convert one input string into a list of strings. 518 * The list of strings is derived by separating the input based on 519 * white space separation. However, if the input contains either single 520 * or double quote characters, then the text after that character up to 521 * a matching quote will become the string in the list. 522 * 523 * The returned pointer should be deallocated with @code{free(3C)} when 524 * are done using the data. The data are placed in a single block of 525 * allocated memory. Do not deallocate individual token/strings. 526 * 527 * The structure pointed to will contain at least these two fields: 528 * @table @samp 529 * @item tkn_ct 530 * The number of tokens found in the input string. 531 * @item tok_list 532 * An array of @code{tkn_ct + 1} pointers to substring tokens, with 533 * the last pointer set to NULL. 534 * @end table 535 * 536 * There are two types of quoted strings: single quoted (@code{'}) and 537 * double quoted (@code{"}). Singly quoted strings are fairly raw in that 538 * escape characters (@code{\\}) are simply another character, except when 539 * preceding the following characters: 540 * @example 541 * @code{\\} double backslashes reduce to one 542 * @code{'} incorporates the single quote into the string 543 * @code{\n} suppresses both the backslash and newline character 544 * @end example 545 * 546 * Double quote strings are formed according to the rules of string 547 * constants in ANSI-C programs. 548 */ 549 extern token_list_t* ao_string_tokenize(char const*); 550 551 552 /* From: configfile.c line 85 553 * 554 * configFileLoad - parse a configuration file 555 * 556 * Arguments: 557 * pzFile the file to load 558 * 559 * Returns: const tOptionValue* - An allocated, compound value structure 560 * 561 * This routine will load a named configuration file and parse the 562 * text as a hierarchically valued option. The option descriptor 563 * created from an option definition file is not used via this interface. 564 * The returned value is "named" with the input file name and is of 565 * type "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to 566 * @code{optionGetValue()}, @code{optionNextValue()} and 567 * @code{optionUnloadNested()}. 568 */ 569 extern const tOptionValue* configFileLoad(char const*); 570 571 572 /* From: configfile.c line 897 573 * 574 * optionFileLoad - Load the locatable config files, in order 575 * 576 * Arguments: 577 * pOpts program options descriptor 578 * pzProg program name 579 * 580 * Returns: int - 0 -> SUCCESS, -1 -> FAILURE 581 * 582 * This function looks in all the specified directories for a configuration 583 * file ("rc" file or "ini" file) and processes any found twice. The first 584 * time through, they are processed in reverse order (last file first). At 585 * that time, only "immediate action" configurables are processed. For 586 * example, if the last named file specifies not processing any more 587 * configuration files, then no more configuration files will be processed. 588 * Such an option in the @strong{first} named directory will have no effect. 589 * 590 * Once the immediate action configurables have been handled, then the 591 * directories are handled in normal, forward order. In that way, later 592 * config files can override the settings of earlier config files. 593 * 594 * See the AutoOpts documentation for a thorough discussion of the 595 * config file format. 596 * 597 * Configuration files not found or not decipherable are simply ignored. 598 */ 599 extern int optionFileLoad(tOptions*, char const*); 600 601 602 /* From: configfile.c line 217 603 * 604 * optionFindNextValue - find a hierarcicaly valued option instance 605 * 606 * Arguments: 607 * pOptDesc an option with a nested arg type 608 * pPrevVal the last entry 609 * name name of value to find 610 * value the matching value 611 * 612 * Returns: const tOptionValue* - a compound value structure 613 * 614 * This routine will find the next entry in a nested value option or 615 * configurable. It will search through the list and return the next entry 616 * that matches the criteria. 617 */ 618 extern const tOptionValue* optionFindNextValue(const tOptDesc*, const tOptionValue*, char const*, char const*); 619 620 621 /* From: configfile.c line 143 622 * 623 * optionFindValue - find a hierarcicaly valued option instance 624 * 625 * Arguments: 626 * pOptDesc an option with a nested arg type 627 * name name of value to find 628 * value the matching value 629 * 630 * Returns: const tOptionValue* - a compound value structure 631 * 632 * This routine will find an entry in a nested value option or configurable. 633 * It will search through the list and return a matching entry. 634 */ 635 extern const tOptionValue* optionFindValue(const tOptDesc*, char const*, char const*); 636 637 638 /* From: restore.c line 165 639 * 640 * optionFree - free allocated option processing memory 641 * 642 * Arguments: 643 * pOpts program options descriptor 644 * 645 * AutoOpts sometimes allocates memory and puts pointers to it in the 646 * option state structures. This routine deallocates all such memory. 647 */ 648 extern void optionFree(tOptions*); 649 650 651 /* From: configfile.c line 286 652 * 653 * optionGetValue - get a specific value from a hierarcical list 654 * 655 * Arguments: 656 * pOptValue a hierarchcal value 657 * valueName name of value to get 658 * 659 * Returns: const tOptionValue* - a compound value structure 660 * 661 * This routine will find an entry in a nested value option or configurable. 662 * If "valueName" is NULL, then the first entry is returned. Otherwise, 663 * the first entry with a name that exactly matches the argument will be 664 * returned. 665 */ 666 extern const tOptionValue* optionGetValue(const tOptionValue*, char const*); 667 668 669 /* From: load.c line 498 670 * 671 * optionLoadLine - process a string for an option name and value 672 * 673 * Arguments: 674 * pOpts program options descriptor 675 * pzLine NUL-terminated text 676 * 677 * This is a client program callable routine for setting options from, for 678 * example, the contents of a file that they read in. Only one option may 679 * appear in the text. It will be treated as a normal (non-preset) option. 680 * 681 * When passed a pointer to the option struct and a string, it will find 682 * the option named by the first token on the string and set the option 683 * argument to the remainder of the string. The caller must NUL terminate 684 * the string. Any embedded new lines will be included in the option 685 * argument. If the input looks like one or more quoted strings, then the 686 * input will be "cooked". The "cooking" is identical to the string 687 * formation used in AutoGen definition files (@pxref{basic expression}), 688 * except that you may not use backquotes. 689 */ 690 extern void optionLoadLine(tOptions*, char const*); 691 692 693 /* From: configfile.c line 345 694 * 695 * optionNextValue - get the next value from a hierarchical list 696 * 697 * Arguments: 698 * pOptValue a hierarchcal list value 699 * pOldValue a value from this list 700 * 701 * Returns: const tOptionValue* - a compound value structure 702 * 703 * This routine will return the next entry after the entry passed in. At the 704 * end of the list, NULL will be returned. If the entry is not found on the 705 * list, NULL will be returned and "@var{errno}" will be set to EINVAL. 706 * The "@var{pOldValue}" must have been gotten from a prior call to this 707 * routine or to "@code{opitonGetValue()}". 708 */ 709 extern const tOptionValue* optionNextValue(const tOptionValue*, const tOptionValue*); 710 711 712 /* From: usage.c line 107 713 * 714 * optionOnlyUsage - Print usage text for just the options 715 * 716 * Arguments: 717 * pOpts program options descriptor 718 * ex_code exit code for calling exit(3) 719 * 720 * This routine will print only the usage for each option. 721 * This function may be used when the emitted usage must incorporate 722 * information not available to AutoOpts. 723 */ 724 extern void optionOnlyUsage(tOptions*, int); 725 726 727 /* From: autoopts.c line 1058 728 * 729 * optionProcess - this is the main option processing routine 730 * 731 * Arguments: 732 * pOpts program options descriptor 733 * argc program arg count 734 * argv program arg vector 735 * 736 * Returns: int - the count of the arguments processed 737 * 738 * This is the main entry point for processing options. It is intended 739 * that this procedure be called once at the beginning of the execution of 740 * a program. Depending on options selected earlier, it is sometimes 741 * necessary to stop and restart option processing, or to select completely 742 * different sets of options. This can be done easily, but you generally 743 * do not want to do this. 744 * 745 * The number of arguments processed always includes the program name. 746 * If one of the arguments is "--", then it is counted and the processing 747 * stops. If an error was encountered and errors are to be tolerated, then 748 * the returned value is the index of the argument causing the error. 749 * A hyphen by itself ("-") will also cause processing to stop and will 750 * @emph{not} be counted among the processed arguments. A hyphen by itself 751 * is treated as an operand. Encountering an operand stops option 752 * processing. 753 */ 754 extern int optionProcess(tOptions*, int, char**); 755 756 757 /* From: restore.c line 122 758 * 759 * optionRestore - restore option state from memory copy 760 * 761 * Arguments: 762 * pOpts program options descriptor 763 * 764 * Copy back the option state from saved memory. 765 * The allocated memory is left intact, so this routine can be 766 * called repeatedly without having to call optionSaveState again. 767 * If you are restoring a state that was saved before the first call 768 * to optionProcess(3AO), then you may change the contents of the 769 * argc/argv parameters to optionProcess. 770 */ 771 extern void optionRestore(tOptions*); 772 773 774 /* From: save.c line 671 775 * 776 * optionSaveFile - saves the option state to a file 777 * 778 * Arguments: 779 * pOpts program options descriptor 780 * 781 * This routine will save the state of option processing to a file. The name 782 * of that file can be specified with the argument to the @code{--save-opts} 783 * option, or by appending the @code{rcfile} attribute to the last 784 * @code{homerc} attribute. If no @code{rcfile} attribute was specified, it 785 * will default to @code{.@i{programname}rc}. If you wish to specify another 786 * file, you should invoke the @code{SET_OPT_SAVE_OPTS( @i{filename} )} macro. 787 * 788 * The recommend usage is as follows: 789 * @example 790 * optionProcess(&progOptions, argc, argv); 791 * if (i_want_a_non_standard_place_for_this) 792 * SET_OPT_SAVE_OPTS("myfilename"); 793 * optionSaveFile(&progOptions); 794 * @end example 795 */ 796 extern void optionSaveFile(tOptions*); 797 798 799 /* From: restore.c line 70 800 * 801 * optionSaveState - saves the option state to memory 802 * 803 * Arguments: 804 * pOpts program options descriptor 805 * 806 * This routine will allocate enough memory to save the current option 807 * processing state. If this routine has been called before, that memory 808 * will be reused. You may only save one copy of the option state. This 809 * routine may be called before optionProcess(3AO). If you do call it 810 * before the first call to optionProcess, then you may also change the 811 * contents of argc/argv after you call optionRestore(3AO) 812 * 813 * In fact, more strongly put: it is safest to only use this function 814 * before having processed any options. In particular, the saving and 815 * restoring of stacked string arguments and hierarchical values is 816 * disabled. The values are not saved. 817 */ 818 extern void optionSaveState(tOptions*); 819 820 821 /* From: nested.c line 569 822 * 823 * optionUnloadNested - Deallocate the memory for a nested value 824 * 825 * Arguments: 826 * pOptVal the hierarchical value 827 * 828 * A nested value needs to be deallocated. The pointer passed in should 829 * have been gotten from a call to @code{configFileLoad()} (See 830 * @pxref{libopts-configFileLoad}). 831 */ 832 extern void optionUnloadNested(tOptionValue const *); 833 834 835 /* From: version.c line 37 836 * 837 * optionVersion - return the compiled AutoOpts version number 838 * 839 * Returns: char const* - the version string in constant memory 840 * 841 * Returns the full version string compiled into the library. 842 * The returned string cannot be modified. 843 */ 844 extern char const* optionVersion(void); 845 846 847 /* From: ../compat/pathfind.c line 32 848 * 849 * pathfind - fild a file in a list of directories 850 * 851 * Arguments: 852 * path colon separated list of search directories 853 * file the name of the file to look for 854 * mode the mode bits that must be set to match 855 * 856 * Returns: char* - the path to the located file 857 * 858 * the pathfind function is available only if HAVE_PATHFIND is not defined 859 * 860 * pathfind looks for a a file with name "FILE" and "MODE" access 861 * along colon delimited "PATH", and returns the full pathname as a 862 * string, or NULL if not found. If "FILE" contains a slash, then 863 * it is treated as a relative or absolute path and "PATH" is ignored. 864 * 865 * @strong{NOTE}: this function is compiled into @file{libopts} only if 866 * it is not natively supplied. 867 * 868 * The "MODE" argument is a string of option letters chosen from the 869 * list below: 870 * @example 871 * Letter Meaning 872 * r readable 873 * w writable 874 * x executable 875 * f normal file (NOT IMPLEMENTED) 876 * b block special (NOT IMPLEMENTED) 877 * c character special (NOT IMPLEMENTED) 878 * d directory (NOT IMPLEMENTED) 879 * p FIFO (pipe) (NOT IMPLEMENTED) 880 * u set user ID bit (NOT IMPLEMENTED) 881 * g set group ID bit (NOT IMPLEMENTED) 882 * k sticky bit (NOT IMPLEMENTED) 883 * s size nonzero (NOT IMPLEMENTED) 884 * @end example 885 */ 886 #ifndef HAVE_PATHFIND 887 extern char* pathfind(char const*, char const*, char const*); 888 #endif /* HAVE_PATHFIND */ 889 890 891 /* From: streqvcmp.c line 208 892 * 893 * strequate - map a list of characters to the same value 894 * 895 * Arguments: 896 * ch_list characters to equivalence 897 * 898 * Each character in the input string get mapped to the first character 899 * in the string. 900 * This function name is mapped to option_strequate so as to not conflict 901 * with the POSIX name space. 902 */ 903 extern void strequate(char const*); 904 905 906 /* From: streqvcmp.c line 118 907 * 908 * streqvcmp - compare two strings with an equivalence mapping 909 * 910 * Arguments: 911 * str1 first string 912 * str2 second string 913 * 914 * Returns: int - the difference between two differing characters 915 * 916 * Using a character mapping, two strings are compared for "equivalence". 917 * Each input character is mapped to a comparison character and the 918 * mapped-to characters are compared for the two NUL terminated input strings. 919 * This function name is mapped to option_streqvcmp so as to not conflict 920 * with the POSIX name space. 921 */ 922 extern int streqvcmp(char const*, char const*); 923 924 925 /* From: streqvcmp.c line 155 926 * 927 * streqvmap - Set the character mappings for the streqv functions 928 * 929 * Arguments: 930 * From Input character 931 * To Mapped-to character 932 * ct compare length 933 * 934 * Set the character mapping. If the count (@code{ct}) is set to zero, then 935 * the map is cleared by setting all entries in the map to their index 936 * value. Otherwise, the "@code{From}" character is mapped to the "@code{To}" 937 * character. If @code{ct} is greater than 1, then @code{From} and @code{To} 938 * are incremented and the process repeated until @code{ct} entries have been 939 * set. For example, 940 * @example 941 * streqvmap( 'a', 'A', 26 ); 942 * @end example 943 * @noindent 944 * will alter the mapping so that all English lower case letters 945 * will map to upper case. 946 * 947 * This function name is mapped to option_streqvmap so as to not conflict 948 * with the POSIX name space. 949 */ 950 extern void streqvmap(char, char, int); 951 952 953 /* From: streqvcmp.c line 77 954 * 955 * strneqvcmp - compare two strings with an equivalence mapping 956 * 957 * Arguments: 958 * str1 first string 959 * str2 second string 960 * ct compare length 961 * 962 * Returns: int - the difference between two differing characters 963 * 964 * Using a character mapping, two strings are compared for "equivalence". 965 * Each input character is mapped to a comparison character and the 966 * mapped-to characters are compared for the two NUL terminated input strings. 967 * The comparison is limited to @code{ct} bytes. 968 * This function name is mapped to option_strneqvcmp so as to not conflict 969 * with the POSIX name space. 970 */ 971 extern int strneqvcmp(char const*, char const*, int); 972 973 974 /* From: streqvcmp.c line 234 975 * 976 * strtransform - convert a string into its mapped-to value 977 * 978 * Arguments: 979 * dest output string 980 * src input string 981 * 982 * Each character in the input string is mapped and the mapped-to 983 * character is put into the output. 984 * This function name is mapped to option_strtransform so as to not conflict 985 * with the POSIX name space. 986 * 987 * The source and destination may be the same. 988 */ 989 extern void strtransform(char*, char const*); 990 991 /* AutoOpts PRIVATE FUNCTIONS: */ 992 tOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal; 993 994 extern char* ao_string_cook(char*, int*); 995 996 extern unsigned int ao_string_cook_escape_char(char const*, char*, unsigned int); 997 998 extern void export_options_to_guile(tOptions*); 999 1000 extern void genshelloptUsage(tOptions*, int); 1001 1002 extern void optionBooleanVal(tOptions*, tOptDesc*); 1003 1004 extern uintptr_t optionEnumerationVal(tOptions*, tOptDesc*, char const * const *, unsigned int); 1005 1006 extern void optionFileCheck(tOptions*, tOptDesc*, teOptFileType, tuFileMode); 1007 1008 extern char const* optionKeywordName(tOptDesc*, unsigned int); 1009 1010 extern void optionLoadOpt(tOptions*, tOptDesc*); 1011 1012 extern ag_bool optionMakePath(char*, int, char const*, char const*); 1013 1014 extern void optionNestedVal(tOptions*, tOptDesc*); 1015 1016 extern void optionNumericVal(tOptions*, tOptDesc*); 1017 1018 extern void optionPagedUsage(tOptions*, tOptDesc*); 1019 1020 extern void optionParseShell(tOptions*); 1021 1022 extern void optionPrintVersion(tOptions*, tOptDesc*); 1023 1024 extern void optionPutShell(tOptions*); 1025 1026 extern void optionResetOpt(tOptions*, tOptDesc*); 1027 1028 extern void optionSetMembers(tOptions*, tOptDesc*, char const * const *, unsigned int); 1029 1030 extern void optionShowRange(tOptions*, tOptDesc*, void *, int); 1031 1032 extern void optionStackArg(tOptions*, tOptDesc*); 1033 1034 extern void optionTimeVal(tOptions*, tOptDesc*); 1035 1036 extern void optionUnstackArg(tOptions*, tOptDesc*); 1037 1038 extern void optionUsage(tOptions*, int); 1039 1040 extern void optionVersionStderr(tOptions*, tOptDesc*); 1041 1042 extern void* text_mmap(char const*, int, int, tmap_info_t*); 1043 1044 extern int text_munmap(tmap_info_t*); 1045 1046 CPLUSPLUS_CLOSER 1047 #endif /* AUTOOPTS_OPTIONS_H_GUARD */ 1048 /* 1049 * Local Variables: 1050 * c-file-style: "stroustrup" 1051 * indent-tabs-mode: nil 1052 * End: 1053 * options.h ends here */ 1054