1 /* -*- buffer-read-only: t -*- vi: set ro:
3 * DO NOT EDIT THIS FILE (options.h)
5 * It has been AutoGen-ed Saturday May 5, 2007 at 12:02:34 PM PDT
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 1992-Y Bruce Korb
14 * AutoOpts is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU Lesser General Public
16 * License as published by the Free Software Foundation; either
17 * version 2.1 of the License, or (at your option) any later version.
19 * AutoOpts is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * Lesser General Public License for more details.
24 * You should have received a copy of the GNU Lesser General Public
25 * License along with AutoOpts. If not, write to:
26 * The Free Software Foundation, Inc.,
27 * 51 Franklin Street, Fifth Floor
28 * Boston, MA 02110-1301, USA.
30 #ifndef AUTOOPTS_OPTIONS_H_GUARD
31 #define AUTOOPTS_OPTIONS_H_GUARD
32 #include <sys/types.h>
34 #if defined(HAVE_STDINT_H)
36 #elif defined(HAVE_INTTYPES_H)
37 # include <inttypes.h>
38 #endif /* HAVE_STDINT/INTTYPES_H */
40 #if defined(HAVE_LIMITS_H)
42 #elif defined(HAVE_SYS_LIMITS_H)
43 # include <sys/limits.h>
44 #endif /* HAVE_LIMITS/SYS_LIMITS_H */
46 #if defined(HAVE_SYSEXITS_H)
47 # include <sysexits.h>
48 #endif /* HAVE_SYSEXITS_H */
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:
61 * 1. inside an option processing procedure, it is the second argument,
62 * conventionally "tOptDesc* pOD".
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 )".
67 * See the relevant generated header file to determine which and what
68 * values for "opt_name" are available.
71 #define OPTIONS_STRUCT_VERSION 118784
72 #define OPTIONS_VERSION_STRING "29:0:4"
73 #define OPTIONS_MINIMUM_VERSION 102400
74 #define OPTIONS_MIN_VER_STRING "25:0: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 */
86 typedef struct optionValue {
90 char strVal[1]; /* OPARG_TYPE_STRING */
91 unsigned int enumVal; /* OPARG_TYPE_ENUMERATION */
92 unsigned int boolVal; /* OPARG_TYPE_BOOLEAN */
93 unsigned long setVal; /* OPARG_TYPE_MEMBERSHIP */
94 long longVal; /* OPARG_TYPE_NUMERIC */
95 void* nestVal; /* OPARG_TYPE_HIERARCHY */
100 * Bits in the fOptState option descriptor field.
103 OPTST_SET_ID = 0, /* Set via the "SET_OPT()" macro */
104 OPTST_PRESET_ID = 1, /* Set via an RC/INI file */
105 OPTST_DEFINED_ID = 2, /* Set via a command line option */
106 OPTST_EQUIVALENCE_ID = 4, /* selected by equiv'ed option */
107 OPTST_DISABLED_ID = 5, /* option is in disabled state */
108 OPTST_ALLOC_ARG_ID = 6, /* pzOptArg was allocated */
109 OPTST_NO_INIT_ID = 8, /* option cannot be preset */
110 OPTST_NUMBER_OPT_ID = 9, /* opt value (flag) is any digit */
111 OPTST_STACKED_ID = 10, /* opt uses optionStackArg proc */
112 OPTST_INITENABLED_ID = 11, /* option defaults to enabled */
113 OPTST_ARG_TYPE_1_ID = 12, /* bit 1 of arg type enum */
114 OPTST_ARG_TYPE_2_ID = 13, /* bit 2 of arg type enum */
115 OPTST_ARG_TYPE_3_ID = 14, /* bit 3 of arg type enum */
116 OPTST_ARG_TYPE_4_ID = 15, /* bit 4 of arg type enum */
117 OPTST_ARG_OPTIONAL_ID = 16, /* the option arg not required */
118 OPTST_IMM_ID = 17, /* process opt on first pass */
119 OPTST_DISABLE_IMM_ID = 18, /* process disablement immed. */
120 OPTST_OMITTED_ID = 19, /* compiled out of program */
121 OPTST_MUST_SET_ID = 20, /* must be set or pre-set */
122 OPTST_DOCUMENT_ID = 21, /* opt is for doc only */
123 OPTST_TWICE_ID = 22, /* process opt twice - imm + reg */
124 OPTST_DISABLE_TWICE_ID = 23 /* process disabled option twice */
127 #define OPTST_INIT 0U
128 #define OPTST_SET (1U << OPTST_SET_ID)
129 #define OPTST_PRESET (1U << OPTST_PRESET_ID)
130 #define OPTST_DEFINED (1U << OPTST_DEFINED_ID)
131 #define OPTST_EQUIVALENCE (1U << OPTST_EQUIVALENCE_ID)
132 #define OPTST_DISABLED (1U << OPTST_DISABLED_ID)
133 #define OPTST_ALLOC_ARG (1U << OPTST_ALLOC_ARG_ID)
134 #define OPTST_NO_INIT (1U << OPTST_NO_INIT_ID)
135 #define OPTST_NUMBER_OPT (1U << OPTST_NUMBER_OPT_ID)
136 #define OPTST_STACKED (1U << OPTST_STACKED_ID)
137 #define OPTST_INITENABLED (1U << OPTST_INITENABLED_ID)
138 #define OPTST_ARG_TYPE_1 (1U << OPTST_ARG_TYPE_1_ID)
139 #define OPTST_ARG_TYPE_2 (1U << OPTST_ARG_TYPE_2_ID)
140 #define OPTST_ARG_TYPE_3 (1U << OPTST_ARG_TYPE_3_ID)
141 #define OPTST_ARG_TYPE_4 (1U << OPTST_ARG_TYPE_4_ID)
142 #define OPTST_ARG_OPTIONAL (1U << OPTST_ARG_OPTIONAL_ID)
143 #define OPTST_IMM (1U << OPTST_IMM_ID)
144 #define OPTST_DISABLE_IMM (1U << OPTST_DISABLE_IMM_ID)
145 #define OPTST_OMITTED (1U << OPTST_OMITTED_ID)
146 #define OPTST_MUST_SET (1U << OPTST_MUST_SET_ID)
147 #define OPTST_DOCUMENT (1U << OPTST_DOCUMENT_ID)
148 #define OPTST_TWICE (1U << OPTST_TWICE_ID)
149 #define OPTST_DISABLE_TWICE (1U << OPTST_DISABLE_TWICE_ID)
150 #define OPT_STATE_MASK 0x00FFFF77U
152 #define OPTST_SET_MASK ( \
157 #define OPTST_MUTABLE_MASK ( \
161 OPTST_EQUIVALENCE | \
165 #define OPTST_SELECTED_MASK ( \
169 #define OPTST_ARG_TYPE_MASK ( \
175 #ifdef NO_OPTIONAL_OPT_ARGS
176 # undef OPTST_ARG_OPTIONAL
177 # define OPTST_ARG_OPTIONAL 0
180 #define OPTST_PERSISTENT_MASK (~OPTST_MUTABLE_MASK)
182 #define SELECTED_OPT( pod ) ((pod)->fOptState & OPTST_SELECTED_MASK)
183 #define UNUSED_OPT( pod ) (((pod)->fOptState & OPTST_SET_MASK) == 0)
184 #define DISABLED_OPT( pod ) ((pod)->fOptState & OPTST_DISABLED)
185 #define OPTION_STATE( pod ) ((pod)->fOptState)
187 #define OPTST_SET_ARGTYPE(n) ((n) << OPTST_ARG_TYPE_1_ID)
188 #define OPTST_GET_ARGTYPE(f) (((f) & OPTST_ARG_TYPE_MASK)>>OPTST_ARG_TYPE_1_ID)
193 * The following values are used in the generated code to communicate
194 * with the option library procedures. They are not for public use
195 * and may be subject to change.
199 * Define the processing state flags
202 OPTPROC_LONGOPT_ID = 0, /* Process long style options */
203 OPTPROC_SHORTOPT_ID = 1, /* Process short style "flags" */
204 OPTPROC_ERRSTOP_ID = 2, /* Stop on argument errors */
205 OPTPROC_DISABLEDOPT_ID = 3, /* Current option is disabled */
206 OPTPROC_NO_REQ_OPT_ID = 4, /* no options are required */
207 OPTPROC_NUM_OPT_ID = 5, /* there is a number option */
208 OPTPROC_INITDONE_ID = 6, /* have initializations been done? */
209 OPTPROC_NEGATIONS_ID = 7, /* any negation options? */
210 OPTPROC_ENVIRON_ID = 8, /* check environment? */
211 OPTPROC_NO_ARGS_ID = 9, /* Disallow remaining arguments */
212 OPTPROC_ARGS_REQ_ID = 10, /* Require arguments after options */
213 OPTPROC_REORDER_ID = 11, /* reorder operands after options */
214 OPTPROC_GNUUSAGE_ID = 12, /* emit usage in GNU style */
215 OPTPROC_TRANSLATE_ID = 13, /* Translate strings in tOptions */
216 OPTPROC_HAS_IMMED_ID = 14, /* program defines immed options */
217 OPTPROC_PRESETTING_ID = 19 /* opt processing in preset state */
218 } optproc_state_enum_t;
220 #define OPTPROC_NONE 0U
221 #define OPTPROC_LONGOPT (1U << OPTPROC_LONGOPT_ID)
222 #define OPTPROC_SHORTOPT (1U << OPTPROC_SHORTOPT_ID)
223 #define OPTPROC_ERRSTOP (1U << OPTPROC_ERRSTOP_ID)
224 #define OPTPROC_DISABLEDOPT (1U << OPTPROC_DISABLEDOPT_ID)
225 #define OPTPROC_NO_REQ_OPT (1U << OPTPROC_NO_REQ_OPT_ID)
226 #define OPTPROC_NUM_OPT (1U << OPTPROC_NUM_OPT_ID)
227 #define OPTPROC_INITDONE (1U << OPTPROC_INITDONE_ID)
228 #define OPTPROC_NEGATIONS (1U << OPTPROC_NEGATIONS_ID)
229 #define OPTPROC_ENVIRON (1U << OPTPROC_ENVIRON_ID)
230 #define OPTPROC_NO_ARGS (1U << OPTPROC_NO_ARGS_ID)
231 #define OPTPROC_ARGS_REQ (1U << OPTPROC_ARGS_REQ_ID)
232 #define OPTPROC_REORDER (1U << OPTPROC_REORDER_ID)
233 #define OPTPROC_GNUUSAGE (1U << OPTPROC_GNUUSAGE_ID)
234 #define OPTPROC_TRANSLATE (1U << OPTPROC_TRANSLATE_ID)
235 #define OPTPROC_HAS_IMMED (1U << OPTPROC_HAS_IMMED_ID)
236 #define OPTPROC_PRESETTING (1U << OPTPROC_PRESETTING_ID)
237 #define OPTPROC_STATE_MASK 0x00087FFFU
239 #define STMTS(s) do { s; } while (0)
242 * The following must be #defined instead of typedef-ed
243 * because "static const" cannot both be applied to a type,
244 * tho each individually can...so they all are
246 #define tSCC static char const
247 #define tCC char const
248 #define tAoSC static char
249 #define tAoUC unsigned char
250 #define tAoUI unsigned int
251 #define tAoUL unsigned long
252 #define tAoUS unsigned short
255 * It is so disgusting that there must be so many ways
256 * of specifying TRUE and FALSE.
258 typedef enum { AG_FALSE = 0, AG_TRUE } ag_bool;
261 * Define a structure that describes each option and
262 * a pointer to the procedure that handles it.
263 * The argument is the count of this flag previously seen.
265 typedef struct options tOptions;
266 typedef struct optDesc tOptDesc;
267 typedef struct optNames tOptNames;
270 * The option procedures do the special processing for each
271 * option flag that needs it.
273 typedef void (tOptProc)( tOptions* pOpts, tOptDesc* pOptDesc );
274 typedef tOptProc* tpOptProc;
277 * The usage procedure will never return. It calls "exit(2)"
278 * with the "exitCode" argument passed to it.
280 typedef void (tUsageProc)( tOptions* pOpts, int exitCode );
281 typedef tUsageProc* tpUsageProc;
284 * Special definitions. "NOLIMIT" is the 'max' value to use when
285 * a flag may appear multiple times without limit. "NO_EQUIVALENT"
286 * is an illegal value for 'optIndex' (option description index).
288 #define NOLIMIT USHRT_MAX
289 #define OPTION_LIMIT SHRT_MAX
290 #define NO_EQUIVALENT (OPTION_LIMIT+1)
293 * Special values for optValue. It must not be generatable from the
294 * computation "optIndex +96". Since "optIndex" is limited to 100, ...
296 #define NUMBER_OPTION '#'
298 typedef struct argList tArgList;
299 #define MIN_ARG_ALLOC_CT 6
300 #define INCR_ARG_ALLOC_CT 8
304 tCC* apzArgs[ MIN_ARG_ALLOC_CT ];
308 char const * argString;
312 unsigned long argUint;
313 unsigned int argBool;
317 * Descriptor structure for each option.
318 * Only the fields marked "PUBLIC" are for public use.
321 tAoUS const optIndex; /* PUBLIC */
322 tAoUS const optValue; /* PUBLIC */
323 tAoUS optActualIndex; /* PUBLIC */
324 tAoUS optActualValue; /* PUBLIC */
326 tAoUS const optEquivIndex; /* PUBLIC */
327 tAoUS const optMinCt;
328 tAoUS const optMaxCt;
329 tAoUS optOccCt; /* PUBLIC */
331 tAoUI fOptState; /* PUBLIC */
333 optArgBucket_t optArg; /* PUBLIC */
334 # define pzLastArg optArg.argString
335 void* optCookie; /* PUBLIC */
337 const int * pOptMust;
338 const int * pOptCant;
344 char const* pz_DisableName;
345 char const* pz_DisablePfx;
349 * Some options need special processing, so we store their
350 * indexes in a known place:
352 typedef struct optSpecIndex tOptSpecIndex;
353 struct optSpecIndex {
354 const tAoUS more_help;
355 const tAoUS save_opts;
356 const tAoUS number_option;
357 const tAoUS default_opt;
361 * The procedure generated for translating option text
363 typedef void (tOptionXlateProc)(void);
366 int const structVersion;
369 unsigned int fOptSet;
370 unsigned int curOptIdx;
373 char const* pzProgPath;
374 char const* pzProgName;
375 char const* const pzPROGNAME;
376 char const* const pzRcName;
377 char const* const pzCopyright;
378 char const* const pzCopyNotice;
379 char const* const pzFullVersion;
380 char const* const* const papzHomeList;
381 char const* const pzUsageTitle;
382 char const* const pzExplain;
383 char const* const pzDetail;
384 tOptDesc* const pOptDesc;
385 char const* const pzBugAddr;
390 tpUsageProc pUsageProc;
391 tOptionXlateProc* pTransProc;
393 tOptSpecIndex specOptIdx;
395 int const presetOptCt;
399 * "token list" structure returned by "string_tokenize()"
402 unsigned long tkn_ct;
403 unsigned char* tkn_list[1];
407 * Hide the interface - it pollutes a POSIX claim, but leave it for
408 * anyone #include-ing this header
410 #define strneqvcmp option_strneqvcmp
411 #define streqvcmp option_streqvcmp
412 #define streqvmap option_streqvmap
413 #define strequate option_strequate
414 #define strtransform option_strtransform
417 * This is an output only structure used by text_mmap and text_munmap.
418 * Clients must not alter the contents and must provide it to both
419 * the text_mmap and text_munmap procedures. BE ADVISED: if you are
420 * mapping the file with PROT_WRITE the NUL byte at the end MIGHT NOT
421 * BE WRITABLE. In any event, that byte is not be written back
422 * to the source file. ALSO: if "txt_data" is valid and "txt_errno"
423 * is not zero, then there *may* not be a terminating NUL.
426 void* txt_data; /* text file data */
427 size_t txt_size; /* actual file size */
428 size_t txt_full_size; /* mmaped mem size */
429 int txt_fd; /* file descriptor */
430 int txt_zero_fd; /* fd for /dev/zero */
431 int txt_errno; /* warning code */
432 int txt_prot; /* "prot" flags */
433 int txt_flags; /* mapping type */
434 int txt_alloc; /* if we malloced memory */
437 #define TEXT_MMAP_FAILED_ADDR(a) ((void*)(a) == (void*)MAP_FAILED)
441 #define CPLUSPLUS_CLOSER }
443 #define CPLUSPLUS_CLOSER
447 * The following routines may be coded into AutoOpts client code:
450 /* From: tokenize.c line 115
452 * ao_string_tokenize - tokenize an input string
455 * string string to be tokenized
457 * Returns: token_list_t* - pointer to a structure that lists each token
459 * This function will convert one input string into a list of strings.
460 * The list of strings is derived by separating the input based on
461 * white space separation. However, if the input contains either single
462 * or double quote characters, then the text after that character up to
463 * a matching quote will become the string in the list.
465 * The returned pointer should be deallocated with @code{free(3C)} when
466 * are done using the data. The data are placed in a single block of
467 * allocated memory. Do not deallocate individual token/strings.
469 * The structure pointed to will contain at least these two fields:
472 * The number of tokens found in the input string.
474 * An array of @code{tkn_ct + 1} pointers to substring tokens, with
475 * the last pointer set to NULL.
478 * There are two types of quoted strings: single quoted (@code{'}) and
479 * double quoted (@code{"}). Singly quoted strings are fairly raw in that
480 * escape characters (@code{\\}) are simply another character, except when
481 * preceding the following characters:
483 * @code{\\} double backslashes reduce to one
484 * @code{'} incorporates the single quote into the string
485 * @code{\n} suppresses both the backslash and newline character
488 * Double quote strings are formed according to the rules of string
489 * constants in ANSI-C programs.
491 extern token_list_t* ao_string_tokenize( char const* );
494 /* From: configfile.c line 113
496 * configFileLoad - parse a configuration file
499 * pzFile the file to load
501 * Returns: const tOptionValue* - An allocated, compound value structure
503 * This routine will load a named configuration file and parse the
504 * text as a hierarchically valued option. The option descriptor
505 * created from an option definition file is not used via this interface.
506 * The returned value is "named" with the input file name and is of
507 * type "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to
508 * @code{optionGetValue()}, @code{optionNextValue()} and
509 * @code{optionUnloadNested()}.
511 extern const tOptionValue* configFileLoad( char const* );
514 /* From: configfile.c line 883
516 * optionFileLoad - Load the locatable config files, in order
519 * pOpts program options descriptor
520 * pzProg program name
522 * Returns: int - 0 -> SUCCESS, -1 -> FAILURE
524 * This function looks in all the specified directories for a configuration
525 * file ("rc" file or "ini" file) and processes any found twice. The first
526 * time through, they are processed in reverse order (last file first). At
527 * that time, only "immediate action" configurables are processed. For
528 * example, if the last named file specifies not processing any more
529 * configuration files, then no more configuration files will be processed.
530 * Such an option in the @strong{first} named directory will have no effect.
532 * Once the immediate action configurables have been handled, then the
533 * directories are handled in normal, forward order. In that way, later
534 * config files can override the settings of earlier config files.
536 * See the AutoOpts documentation for a thorough discussion of the
537 * config file format.
539 * Configuration files not found or not decipherable are simply ignored.
541 extern int optionFileLoad( tOptions*, char const* );
544 /* From: configfile.c line 245
546 * optionFindNextValue - find a hierarcicaly valued option instance
549 * pOptDesc an option with a nested arg type
550 * pPrevVal the last entry
551 * name name of value to find
552 * value the matching value
554 * Returns: const tOptionValue* - a compound value structure
556 * This routine will find the next entry in a nested value option or
557 * configurable. It will search through the list and return the next entry
558 * that matches the criteria.
560 extern const tOptionValue* optionFindNextValue( const tOptDesc*, const tOptionValue*, char const*, char const* );
563 /* From: configfile.c line 171
565 * optionFindValue - find a hierarcicaly valued option instance
568 * pOptDesc an option with a nested arg type
569 * name name of value to find
570 * value the matching value
572 * Returns: const tOptionValue* - a compound value structure
574 * This routine will find an entry in a nested value option or configurable.
575 * It will search through the list and return a matching entry.
577 extern const tOptionValue* optionFindValue( const tOptDesc*, char const*, char const* );
580 /* From: restore.c line 188
582 * optionFree - free allocated option processing memory
585 * pOpts program options descriptor
587 * AutoOpts sometimes allocates memory and puts pointers to it in the
588 * option state structures. This routine deallocates all such memory.
590 extern void optionFree( tOptions* );
593 /* From: configfile.c line 314
595 * optionGetValue - get a specific value from a hierarcical list
598 * pOptValue a hierarchcal value
599 * valueName name of value to get
601 * Returns: const tOptionValue* - a compound value structure
603 * This routine will find an entry in a nested value option or configurable.
604 * If "valueName" is NULL, then the first entry is returned. Otherwise,
605 * the first entry with a name that exactly matches the argument will be
608 extern const tOptionValue* optionGetValue( const tOptionValue*, char const* );
611 /* From: load.c line 521
613 * optionLoadLine - process a string for an option name and value
616 * pOpts program options descriptor
617 * pzLine NUL-terminated text
619 * This is a client program callable routine for setting options from, for
620 * example, the contents of a file that they read in. Only one option may
621 * appear in the text. It will be treated as a normal (non-preset) option.
623 * When passed a pointer to the option struct and a string, it will find
624 * the option named by the first token on the string and set the option
625 * argument to the remainder of the string. The caller must NUL terminate
626 * the string. Any embedded new lines will be included in the option
627 * argument. If the input looks like one or more quoted strings, then the
628 * input will be "cooked". The "cooking" is identical to the string
629 * formation used in AutoGen definition files (@pxref{basic expression}),
630 * except that you may not use backquotes.
632 extern void optionLoadLine( tOptions*, char const* );
635 /* From: configfile.c line 373
637 * optionNextValue - get the next value from a hierarchical list
640 * pOptValue a hierarchcal list value
641 * pOldValue a value from this list
643 * Returns: const tOptionValue* - a compound value structure
645 * This routine will return the next entry after the entry passed in. At the
646 * end of the list, NULL will be returned. If the entry is not found on the
647 * list, NULL will be returned and "@var{errno}" will be set to EINVAL.
648 * The "@var{pOldValue}" must have been gotten from a prior call to this
649 * routine or to "@code{opitonGetValue()}".
651 extern const tOptionValue* optionNextValue( const tOptionValue*, const tOptionValue* );
654 /* From: usage.c line 128
656 * optionOnlyUsage - Print usage text for just the options
659 * pOpts program options descriptor
660 * ex_code exit code for calling exit(3)
662 * This routine will print only the usage for each option.
663 * This function may be used when the emitted usage must incorporate
664 * information not available to AutoOpts.
666 extern void optionOnlyUsage( tOptions*, int );
669 /* From: autoopts.c line 1012
671 * optionProcess - this is the main option processing routine
674 * pOpts program options descriptor
675 * argc program arg count
676 * argv program arg vector
678 * Returns: int - the count of the arguments processed
680 * This is the main entry point for processing options. It is intended
681 * that this procedure be called once at the beginning of the execution of
682 * a program. Depending on options selected earlier, it is sometimes
683 * necessary to stop and restart option processing, or to select completely
684 * different sets of options. This can be done easily, but you generally
685 * do not want to do this.
687 * The number of arguments processed always includes the program name.
688 * If one of the arguments is "--", then it is counted and the processing
689 * stops. If an error was encountered and errors are to be tolerated, then
690 * the returned value is the index of the argument causing the error.
691 * A hyphen by itself ("-") will also cause processing to stop and will
692 * @emph{not} be counted among the processed arguments. A hyphen by itself
693 * is treated as an operand. Encountering an operand stops option
696 extern int optionProcess( tOptions*, int, char** );
699 /* From: restore.c line 145
701 * optionRestore - restore option state from memory copy
704 * pOpts program options descriptor
706 * Copy back the option state from saved memory.
707 * The allocated memory is left intact, so this routine can be
708 * called repeatedly without having to call optionSaveState again.
709 * If you are restoring a state that was saved before the first call
710 * to optionProcess(3AO), then you may change the contents of the
711 * argc/argv parameters to optionProcess.
713 extern void optionRestore( tOptions* );
716 /* From: save.c line 334
718 * optionSaveFile - saves the option state to a file
721 * pOpts program options descriptor
723 * This routine will save the state of option processing to a file. The name
724 * of that file can be specified with the argument to the @code{--save-opts}
725 * option, or by appending the @code{rcfile} attribute to the last
726 * @code{homerc} attribute. If no @code{rcfile} attribute was specified, it
727 * will default to @code{.@i{programname}rc}. If you wish to specify another
728 * file, you should invoke the @code{SET_OPT_SAVE_OPTS( @i{filename} )} macro.
730 extern void optionSaveFile( tOptions* );
733 /* From: restore.c line 93
735 * optionSaveState - saves the option state to memory
738 * pOpts program options descriptor
740 * This routine will allocate enough memory to save the current option
741 * processing state. If this routine has been called before, that memory
742 * will be reused. You may only save one copy of the option state. This
743 * routine may be called before optionProcess(3AO). If you do call it
744 * before the first call to optionProcess, then you may also change the
745 * contents of argc/argv after you call optionRestore(3AO)
747 * In fact, more strongly put: it is safest to only use this function
748 * before having processed any options. In particular, the saving and
749 * restoring of stacked string arguments and hierarchical values is
750 * disabled. The values are not saved.
752 extern void optionSaveState( tOptions* );
755 /* From: nested.c line 559
757 * optionUnloadNested - Deallocate the memory for a nested value
760 * pOptVal the hierarchical value
762 * A nested value needs to be deallocated. The pointer passed in should
763 * have been gotten from a call to @code{configFileLoad()} (See
764 * @pxref{libopts-configFileLoad}).
766 extern void optionUnloadNested( tOptionValue const * );
769 /* From: version.c line 58
771 * optionVersion - return the compiled AutoOpts version number
773 * Returns: char const* - the version string in constant memory
775 * Returns the full version string compiled into the library.
776 * The returned string cannot be modified.
778 extern char const* optionVersion( void );
781 /* From: ../compat/pathfind.c line 34
783 * pathfind - fild a file in a list of directories
786 * path colon separated list of search directories
787 * file the name of the file to look for
788 * mode the mode bits that must be set to match
790 * Returns: char* - the path to the located file
792 * the pathfind function is available only if HAVE_PATHFIND is not defined
794 * pathfind looks for a a file with name "FILE" and "MODE" access
795 * along colon delimited "PATH", and returns the full pathname as a
796 * string, or NULL if not found. If "FILE" contains a slash, then
797 * it is treated as a relative or absolute path and "PATH" is ignored.
799 * @strong{NOTE}: this function is compiled into @file{libopts} only if
800 * it is not natively supplied.
802 * The "MODE" argument is a string of option letters chosen from the
809 * f normal file (NOT IMPLEMENTED)
810 * b block special (NOT IMPLEMENTED)
811 * c character special (NOT IMPLEMENTED)
812 * d directory (NOT IMPLEMENTED)
813 * p FIFO (pipe) (NOT IMPLEMENTED)
814 * u set user ID bit (NOT IMPLEMENTED)
815 * g set group ID bit (NOT IMPLEMENTED)
816 * k sticky bit (NOT IMPLEMENTED)
817 * s size nonzero (NOT IMPLEMENTED)
820 #ifndef HAVE_PATHFIND
821 extern char* pathfind( char const*, char const*, char const* );
822 #endif /* HAVE_PATHFIND */
825 /* From: streqvcmp.c line 233
827 * strequate - map a list of characters to the same value
830 * ch_list characters to equivalence
832 * Each character in the input string get mapped to the first character
834 * This function name is mapped to option_strequate so as to not conflict
835 * with the POSIX name space.
837 extern void strequate( char const* );
840 /* From: streqvcmp.c line 143
842 * streqvcmp - compare two strings with an equivalence mapping
848 * Returns: int - the difference between two differing characters
850 * Using a character mapping, two strings are compared for "equivalence".
851 * Each input character is mapped to a comparison character and the
852 * mapped-to characters are compared for the two NUL terminated input strings.
853 * This function name is mapped to option_streqvcmp so as to not conflict
854 * with the POSIX name space.
856 extern int streqvcmp( char const*, char const* );
859 /* From: streqvcmp.c line 180
861 * streqvmap - Set the character mappings for the streqv functions
864 * From Input character
865 * To Mapped-to character
868 * Set the character mapping. If the count (@code{ct}) is set to zero, then
869 * the map is cleared by setting all entries in the map to their index
870 * value. Otherwise, the "@code{From}" character is mapped to the "@code{To}"
871 * character. If @code{ct} is greater than 1, then @code{From} and @code{To}
872 * are incremented and the process repeated until @code{ct} entries have been
875 * streqvmap( 'a', 'A', 26 );
878 * will alter the mapping so that all English lower case letters
879 * will map to upper case.
881 * This function name is mapped to option_streqvmap so as to not conflict
882 * with the POSIX name space.
884 extern void streqvmap( char, char, int );
887 /* From: streqvcmp.c line 102
889 * strneqvcmp - compare two strings with an equivalence mapping
896 * Returns: int - the difference between two differing characters
898 * Using a character mapping, two strings are compared for "equivalence".
899 * Each input character is mapped to a comparison character and the
900 * mapped-to characters are compared for the two NUL terminated input strings.
901 * The comparison is limited to @code{ct} bytes.
902 * This function name is mapped to option_strneqvcmp so as to not conflict
903 * with the POSIX name space.
905 extern int strneqvcmp( char const*, char const*, int );
908 /* From: streqvcmp.c line 259
910 * strtransform - convert a string into its mapped-to value
916 * Each character in the input string is mapped and the mapped-to
917 * character is put into the output.
918 * This function name is mapped to option_strtransform so as to not conflict
919 * with the POSIX name space.
921 extern void strtransform( char*, char const* );
923 /* AutoOpts PRIVATE FUNCTIONS: */
924 tOptProc optionStackArg, optionUnstackArg, optionBooleanVal, optionNumericVal;
926 extern char* ao_string_cook( char*, int* );
928 extern unsigned int ao_string_cook_escape_char( char const*, char*, unsigned int );
930 extern void export_options_to_guile( tOptions* );
932 extern void genshelloptUsage( tOptions*, int );
934 extern void optionBooleanVal( tOptions*, tOptDesc* );
936 extern uintptr_t optionEnumerationVal( tOptions*, tOptDesc*, char const * const *, unsigned int );
938 extern char const* optionKeywordName( tOptDesc*, unsigned int );
940 extern void optionLoadOpt( tOptions*, tOptDesc* );
942 extern ag_bool optionMakePath( char*, int, char const*, char const* );
944 extern void optionNestedVal( tOptions*, tOptDesc* );
946 extern void optionNumericVal( tOptions*, tOptDesc* );
948 extern void optionPagedUsage( tOptions*, tOptDesc* );
950 extern void optionParseShell( tOptions* );
952 extern void optionPrintVersion( tOptions*, tOptDesc* );
954 extern void optionPutShell( tOptions* );
956 extern void optionSetMembers( tOptions*, tOptDesc*, char const * const *, unsigned int );
958 extern void optionStackArg( tOptions*, tOptDesc* );
960 extern void optionUnstackArg( tOptions*, tOptDesc* );
962 extern void optionUsage( tOptions*, int );
964 extern void optionVersionStderr( tOptions*, tOptDesc* );
966 extern void* text_mmap( char const*, int, int, tmap_info_t* );
968 extern int text_munmap( tmap_info_t* );
971 #endif /* AUTOOPTS_OPTIONS_H_GUARD */
974 * c-file-style: "stroustrup"
975 * indent-tabs-mode: nil
977 * options.h ends here */