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