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