path: root/autoopts/funcs.def

/*  -*- buffer-read-only: t -*- vi: set ro:
 *
 *
 *  DO NOT EDIT THIS FILE   (funcs.def)
 *
 *  It has been extracted by getdefs from the following files:
 *
 *      autoopts.c
 *      alias.c
 *      boolean.c
 *      check.c
 *      configfile.c
 *      cook.c
 *      enum.c
 *      env.c
 *      file.c
 *      find.c
 *      genshell.c
 *      load.c
 *      makeshell.c
 *      nested.c
 *      numeric.c
 *      pgusage.c
 *      putshell.c
 *      reset.c
 *      restore.c
 *      save.c
 *      sort.c
 *      stack.c
 *      streqvcmp.c
 *      text_mmap.c
 *      time.c
 *      tokenize.c
 *      usage.c
 *      version.c
 *      ../compat/pathfind.c
 */
autogen definitions options_h;

/* GLOBALDEFS */

#line 594 "autoopts.c"
    library = 'opts';
    header = 'your-opts.h';
    lib_description =
'These are the routines that libopts users may call directly from their
code.  There are several other routines that can be called by code
generated by the libopts option templates, but they are not to be
called from any other user code.  The @file{options.h} header is
fairly clear about this, too.';


#line 206 "cook.c"
export_func = {
    name    = 'ao_string_cook';
    private;
    what = 'concatenate and escape-process strings';
    arg = {
        arg_type = 'char*';
        arg_name = 'pzScan';
        arg_desc = 'The *MODIFIABLE* input buffer';
    };
    arg = {
        arg_type = 'int*';
        arg_name = 'lnct_p';
        arg_desc = 'The (possibly NULL) pointer to a line count';
    };
    ret-type = 'char*';
    ret-desc = 'The address of the text following the processed strings.
The return value is NULL if the strings are ill-formed.';
    doc =
'A series of one or more quoted strings are concatenated together.
If they are quoted with double quotes (@code{"}), then backslash
escapes are processed per the C programming language.  If they are
single quote strings, then the backslashes are honored only when they
precede another backslash or a single quote character.';
    err = '@code{NULL} is returned if the string(s) is/are mal-formed.';
    srcfile = 'cook.c';
    linenum = '206';
};


#line 35 "cook.c"
export_func = {
    name    = 'ao_string_cook_escape_char';
    private;
    what = 'escape-process a string fragment';
    arg = {
        arg_type = 'char const*';
        arg_name = 'pzScan';
        arg_desc = 'points to character after the escape';
    };
    arg = {
        arg_type = 'char*';
        arg_name = 'pRes';
        arg_desc = 'Where to put the result byte';
    };
    arg = {
        arg_type = 'unsigned int';
        arg_name = 'nl_ch';
        arg_desc = 'replacement char if scanned char is \n';
    };
    ret-type = 'unsigned int';
    ret-desc = 'The number of bytes consumed processing the escaped character.';
    doc =
'This function converts "t" into "\\t" and all your other favorite
escapes, including numeric ones:  hex and ocatal, too.
The returned result tells the caller how far to advance the
scan pointer (passed in).  The default is to just pass through the
escaped character and advance the scan by one.

Some applications need to keep an escaped newline, others need to
suppress it.  This is accomplished by supplying a \'\\n\' replacement
character that is different from \\n, if need be.  For example, use
0x7F and never emit a 0x7F.';
    err = '@code{NULL} is returned if the string is mal-formed.';
    srcfile = 'cook.c';
    linenum = '35';
};


#line 164 "tokenize.c"
export_func = {
    name    = 'ao_string_tokenize';
    what = 'tokenize an input string';
    arg = {
        arg_type = 'char const*';
        arg_name = 'string';
        arg_desc = 'string to be tokenized';
    };
    ret_type = 'token_list_t*';
    ret_desc = 'pointer to a structure that lists each token';
    doc =
'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.';
    example =
'@example
#include <stdlib.h>
int ix;
token_list_t* ptl = ao_string_tokenize(some_string)
for (ix = 0; ix < ptl->tkn_ct; ix++)
do_something_with_tkn(ptl->tkn_list[ix]);
free(ptl);
@end example
Note that everything is freed with the one call to @code{free(3C)}.';
    err =
'NULL is returned and @code{errno} will be set to indicate the problem:
@itemize @bullet
@item
@code{EINVAL} - There was an unterminated quoted string.
@item
@code{ENOENT} - The input string was empty.
@item
@code{ENOMEM} - There is not enough memory.
@end itemize';
    srcfile = 'tokenize.c';
    linenum = '164';
};


#line 77 "configfile.c"
export_func = {
    name    = 'configFileLoad';
    what = 'parse a configuration file';
    arg = {
        arg_type = 'char const*';
        arg_name = 'pzFile';
        arg_desc = 'the file to load';
    };
    ret_type = 'const tOptionValue*';
    ret_desc = 'An allocated, compound value structure';
    doc =
'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()}.';
    err =
'If the file cannot be loaded or processed, @code{NULL} is returned and
@var{errno} is set.  It may be set by a call to either @code{open(2)}
@code{mmap(2)} or other file system calls, or it may be:
@itemize @bullet
@item
@code{ENOENT} - the file was not found.
@item
@code{ENOMSG} - the file was empty.
@item
@code{EINVAL} - the file contents are invalid -- not properly formed.
@item
@code{ENOMEM} - not enough memory to allocate the needed structures.
@end itemize';
    srcfile = 'configfile.c';
    linenum = '77';
};


#line 765 "makeshell.c"
export_func = {
    name    = 'genshelloptUsage';
    private;
    what = 'The usage function for the genshellopt generated program';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'exitCode';
        arg_desc = 'usage text type to produce';
    };
    doc =
'This function is used to create the usage strings for the option
processing shell script code.  Two child processes are spawned
each emitting the usage text in either the short (error exit)
style or the long style.  The generated program will capture this
and create shell script variables containing the two types of text.';
    srcfile = 'makeshell.c';
    linenum = '765';
};


#line 32 "alias.c"
export_func = {
    name    = 'optionAlias';
    private;
    what = 'relay an option to its alias';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    arg = {
        arg_type = 'unsigned int';
        arg_name = 'alias';
        arg_desc = 'the aliased-to option index';
    };
    ret-type = 'int';
    doc =
'Handle one option as if it had been specified as another.  Exactly.
Returns "-1" if the aliased-to option has appeared too many times.';
    srcfile = 'alias.c';
    linenum = '32';
};


#line 33 "boolean.c"
export_func = {
    name    = 'optionBooleanVal';
    private;
    what = 'Decipher a boolean value';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Decipher a true or false value for a boolean valued option argument.
The value is true, unless it starts with \'n\' or \'f\' or "#f" or
it is an empty string or it is a number that evaluates to zero.';
    srcfile = 'boolean.c';
    linenum = '33';
};


#line 260 "enum.c"
export_func = {
    name    = 'optionEnumerationVal';
    what = 'Convert from a string to an enumeration value';
    private;
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'the program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOD';
        arg_desc = 'enumeration option description';
    };
    arg = {
        arg_type = 'char const * const *';
        arg_name = 'paz_names';
        arg_desc = 'list of enumeration names';
    };
    arg = {
        arg_type = 'unsigned int';
        arg_name = 'name_ct';
        arg_desc = 'number of names in list';
    };
    ret_type = 'uintptr_t';
    ret_desc = 'the enumeration value';
    doc = 'This converts the optArg.argString string from the option description
into the index corresponding to an entry in the name list.
This will match the generated enumeration value.
Full matches are always accepted.  Partial matches are accepted
if there is only one partial match.';
    srcfile = 'enum.c';
    linenum = '260';
};


#line 151 "file.c"
export_func = {
    name    = 'optionFileCheck';
    private;
    what = 'Decipher a boolean value';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    arg = {
        arg_type = 'teOptFileType';
        arg_name = 'ftype';
        arg_desc = 'File handling type';
    };
    arg = {
        arg_type = 'tuFileMode';
        arg_name = 'mode';
        arg_desc = 'file open mode (if needed)';
    };
    doc =
'Make sure the named file conforms with the file type mode.
The mode specifies if the file must exist, must not exist or may
(or may not) exist.  The mode may also specify opening the';
    file = 'don\'t, open just the descriptor (fd), or open as a stream
(FILE* pointer).';
    srcfile = 'file.c';
    linenum = '151';
};


#line 1066 "configfile.c"
export_func = {
    name    = 'optionFileLoad';
    what = 'Load the locatable config files, in order';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'pzProg';
        arg_desc = 'program name';
    };
    ret_type = 'int';
    ret_desc = '0 -> SUCCESS, -1 -> FAILURE';
    doc =
'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.';
    err = 'Returns the value, "-1" if the program options descriptor
is out of date or indecipherable.  Otherwise, the value "0" will
always be returned.';
    srcfile = 'configfile.c';
    linenum = '1066';
};


#line 211 "configfile.c"
export_func = {
    name    = 'optionFindNextValue';
    FIXME = 'the handling of \'pzName\' and \'pzVal\' is just wrong.';
    what = 'find a hierarcicaly valued option instance';
    arg = {
        arg_type = 'const tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'an option with a nested arg type';
    };
    arg = {
        arg_type = 'const tOptionValue*';
        arg_name = 'pPrevVal';
        arg_desc = 'the last entry';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'name';
        arg_desc = 'name of value to find';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'value';
        arg_desc = 'the matching value';
    };
    ret_type = 'const tOptionValue*';
    ret_desc = 'a compound value structure';
    doc =
'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.';
    err =
'The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value.
@item
@code{ENOENT} - no entry matched the given name.
@end itemize';
    srcfile = 'configfile.c';
    linenum = '211';
};


#line 137 "configfile.c"
export_func = {
    name    = 'optionFindValue';
    what = 'find a hierarcicaly valued option instance';
    arg = {
        arg_type = 'const tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'an option with a nested arg type';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'name';
        arg_desc = 'name of value to find';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'value';
        arg_desc = 'the matching value';
    };
    ret_type = 'const tOptionValue*';
    ret_desc = 'a compound value structure';
    doc =
'This routine will find an entry in a nested value option or configurable.
It will search through the list and return a matching entry.';
    err =
'The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value.
@item
@code{ENOENT} - no entry matched the given name.
@end itemize';
    srcfile = 'configfile.c';
    linenum = '137';
};


#line 166 "restore.c"
export_func = {
    name    = 'optionFree';
    what = 'free allocated option processing memory';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    doc = 'AutoOpts sometimes allocates memory and puts pointers to it in the
option state structures.  This routine deallocates all such memory.';
    err = 'As long as memory has not been corrupted,
this routine is always successful.';
    srcfile = 'restore.c';
    linenum = '166';
};


#line 280 "configfile.c"
export_func = {
    name    = 'optionGetValue';
    what = 'get a specific value from a hierarcical list';
    arg = {
        arg_type = 'const tOptionValue*';
        arg_name = 'pOptValue';
        arg_desc = 'a hierarchcal value';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'valueName';
        arg_desc = 'name of value to get';
    };
    ret_type = 'const tOptionValue*';
    ret_desc = 'a compound value structure';
    doc =
'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.';
    err =
'The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value.
@item
@code{ENOENT} - no entry matched the given name.
@end itemize';
    srcfile = 'configfile.c';
    linenum = '280';
};


#line 237 "enum.c"
export_func = {
    name    = 'optionKeywordName';
    what = 'Convert between enumeration values and strings';
    private;
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOD';
        arg_desc = 'enumeration option description';
    };
    arg = {
        arg_type = 'unsigned int';
        arg_name = 'enum_val';
        arg_desc = 'the enumeration value to map';
    };
    ret_type = 'char const *';
    ret_desc = 'the enumeration name from const memory';
    doc = 'This converts an enumeration value into the matching string.';
    srcfile = 'enum.c';
    linenum = '237';
};


#line 478 "load.c"
export_func = {
    name    = 'optionLoadLine';
    what = 'process a string for an option name and value';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'opts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'line';
        arg_desc = 'NUL-terminated text';
    };
    doc =
'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.';
    err = 'Invalid options are silently ignored.  Invalid option arguments
will cause a warning to print, but the function should return.';
    srcfile = 'load.c';
    linenum = '478';
};


#line 1116 "configfile.c"
export_func = {
    name    = 'optionLoadOpt';
    private;
    what = 'Load an option rc/ini file';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Processes the options found in the file named with
pOptDesc->optArg.argString.';
    srcfile = 'configfile.c';
    linenum = '1116';
};


#line 43 "load.c"
export_func = {
    name    = 'optionMakePath';
    private;
    what = 'translate and construct a path';
    arg = {
        arg_type = 'char*';
        arg_name = 'pzBuf';
        arg_desc = 'The result buffer';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'bufSize';
        arg_desc = 'The size of this buffer';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'pzName';
        arg_desc = 'The input name';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'pzProgPath';
        arg_desc = 'The full path of the current program';
    };
    ret-type = 'bool';
    ret-desc = 'true if the name was handled, otherwise false.
If the name does not start with ``$\'\', then it is handled
simply by copying the input name to the output buffer and
resolving the name with either
@code{canonicalize_file_name(3GLIBC)} or @code{realpath(3C)}.';
    doc =
'This routine will copy the @code{pzName} input name into the
@code{pzBuf} output buffer, not exceeding @code{bufSize} bytes.  If the
first character of the input name is a @code{\'$\'} character, then there
is special handling:
@*
@code{$$} is replaced with the directory name of the @code{pzProgPath},
searching @code{$PATH} if necessary.
@*
@code{$@} is replaced with the AutoGen package data installation directory
(aka @code{pkgdatadir}).
@*
@code{$NAME} is replaced by the contents of the @code{NAME} environment
variable.  If not found, the search fails.

Please note: both @code{$$} and @code{$NAME} must be at the start of the
@code{pzName} string and must either be the entire string or be followed
by the @code{\'/\'} (backslash on windows) character.';
    err = '@code{false} is returned if:
@*
@bullet{} The input name exceeds @code{bufSize} bytes.
@*
@bullet{} @code{$$}, @code{$@@} or @code{$NAME} is not the full string
and the next character is not \'/\'.
@*
@bullet{} libopts was built without PKGDATADIR defined and @code{$@@}
was specified.
@*
@bullet{} @code{NAME} is not a known environment variable
@*
@bullet{} @code{canonicalize_file_name} or @code{realpath} return
errors (cannot resolve the resulting path).';
    srcfile = 'load.c';
    linenum = '43';
};


#line 727 "nested.c"
export_func = {
    name    = 'optionNestedVal';
    private;
    what = 'parse a hierarchical option argument';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Nested value was found on the command line';
    srcfile = 'nested.c';
    linenum = '727';
};


#line 340 "configfile.c"
export_func = {
    name    = 'optionNextValue';
    what = 'get the next value from a hierarchical list';
    arg = {
        arg_type = 'const tOptionValue*';
        arg_name = 'pOptValue';
        arg_desc = 'a hierarchcal list value';
    };
    arg = {
        arg_type = 'const tOptionValue*';
        arg_name = 'pOldValue';
        arg_desc = 'a value from this list';
    };
    ret_type = 'const tOptionValue*';
    ret_desc = 'a compound value structure';
    doc =
'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()}".';
    err =
'The returned result is NULL and errno is set:
@itemize @bullet
@item
@code{EINVAL} - the @code{pOptValue} does not point to a valid
hierarchical option value or @code{pOldValue} does not point to a
member of that option value.
@item
@code{ENOENT} - the supplied @code{pOldValue} pointed to the last entry.
@end itemize';
    srcfile = 'configfile.c';
    linenum = '340';
};


#line 90 "numeric.c"
export_func = {
    name    = 'optionNumericVal';
    private;
    what = 'process an option with a numeric value.';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Decipher a numeric value.';
    srcfile = 'numeric.c';
    linenum = '90';
};


#line 201 "usage.c"
export_func = {
    name    = 'optionOnlyUsage';
    what = 'Print usage text for just the options';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'ex_code';
        arg_desc = 'exit code for calling exit(3)';
    };
    doc =
'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.';
    srcfile = 'usage.c';
    linenum = '201';
};


#line 33 "pgusage.c"
export_func = {
    name    = 'optionPagedUsage';
    private;
    what = 'Decipher a boolean value';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Run the usage output through a pager.
This is very handy if it is very long.
This is disabled on platforms without a working fork() function.';
    srcfile = 'pgusage.c';
    linenum = '33';
};


#line 73 "makeshell.c"
export_func = {
    name    = 'optionParseShell';
    private;
    what = 'Decipher a boolean value';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    doc =
'Emit a shell script that will parse the command line options.';
    srcfile = 'makeshell.c';
    linenum = '73';
};


#line 176 "version.c"
export_func = {
    name    = 'optionPrintVersion';
    private;
    what = 'Print the program version';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'opts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'od';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'This routine will print the version to stdout.';
    srcfile = 'version.c';
    linenum = '176';
};


#line 607 "autoopts.c"
export_func = {
    name    = 'optionProcess';
    what = 'this is the main option processing routine';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'argc';
        arg_desc = 'program arg count';
    };
    arg = {
        arg_type = 'char**';
        arg_name = 'argv';
        arg_desc = 'program arg vector';
    };
    ret_type = 'int';
    ret_desc = 'the count of the arguments processed';
    doc =
'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.';
    err = 'Errors will cause diagnostics to be printed.  @code{exit(3)} may
or may not be called.  It depends upon whether or not the options
were generated with the "allow-errors" attribute, or if the
ERRSKIP_OPTERR or ERRSTOP_OPTERR macros were invoked.';
    srcfile = 'autoopts.c';
    linenum = '607';
};


#line 214 "putshell.c"
export_func = {
    name    = 'optionPutShell';
    what = 'write a portable shell script to parse options';
    private;
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'the program options descriptor';
    };
    doc = 'This routine will emit portable shell script text for parsing
the options described in the option definitions.';
    srcfile = 'putshell.c';
    linenum = '214';
};


#line 58 "reset.c"
export_func = {
    name    = 'optionResetOpt';
    private;
    what = 'Reset the value of an option';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'This code will cause another option to be reset to its initial state.
For example, --reset=foo will cause the --foo option to be reset.';
    srcfile = 'reset.c';
    linenum = '58';
};


#line 123 "restore.c"
export_func = {
    name    = 'optionRestore';
    what = 'restore option state from memory copy';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    doc = '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.';
    err = 'If you have not called @code{optionSaveState} before, a diagnostic is
printed to @code{stderr} and exit is called.';
    srcfile = 'restore.c';
    linenum = '123';
};


#line 648 "save.c"
export_func = {
    name    = 'optionSaveFile';
    what = 'saves the option state to a file';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    doc =
'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';
    err =
'If no @code{homerc} file was specified, this routine will silently return
and do nothing.  If the output file cannot be created or updated, a message
will be printed to @code{stderr} and the routine will return.';
    srcfile = 'save.c';
    linenum = '648';
};


#line 71 "restore.c"
export_func = {
    name    = 'optionSaveState';
    what = 'saves the option state to memory';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    doc =
'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.';
    err = 'If it fails to allocate the memory,
it will print a message to stderr and exit.
Otherwise, it will always succeed.';
    srcfile = 'restore.c';
    linenum = '71';
};


#line 423 "enum.c"
export_func = {
    name    = 'optionSetMembers';
    what = 'Convert between bit flag values and strings';
    private;
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'the program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOD';
        arg_desc = 'enumeration option description';
    };
    arg = {
        arg_type = 'char const * const *';
        arg_name = 'paz_names';
        arg_desc = 'list of enumeration names';
    };
    arg = {
        arg_type = 'unsigned int';
        arg_name = 'name_ct';
        arg_desc = 'number of names in list';
    };
    doc = 'This converts the optArg.argString string from the option description
into the index corresponding to an entry in the name list.
This will match the generated enumeration value.
Full matches are always accepted.  Partial matches are accepted
if there is only one partial match.';
    srcfile = 'enum.c';
    linenum = '423';
};


#line 28 "numeric.c"
export_func = {
    name    = 'optionShowRange';
    private;
    what;
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    arg = {
        arg_type = 'void *';
        arg_name = 'rng_table';
        arg_desc = 'the value range tables';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'rng_count';
        arg_desc = 'the number of entries';
    };
    doc =
'Show information about a numeric option with range constraints.';
    srcfile = 'numeric.c';
    linenum = '28';
};


#line 226 "stack.c"
export_func = {
    name    = 'optionStackArg';
    private;
    what = 'put option args on a stack';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Keep an entry-ordered list of option arguments.';
    srcfile = 'stack.c';
    linenum = '226';
};


#line 64 "time.c"
export_func = {
    name    = 'optionTimeDate';
    private;
    what = 'process an option with a time and date.';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Decipher a time and date value.';
    srcfile = 'time.c';
    linenum = '64';
};


#line 28 "time.c"
export_func = {
    name    = 'optionTimeVal';
    private;
    what = 'process an option with a time duration.';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Decipher a time duration value.';
    srcfile = 'time.c';
    linenum = '28';
};


#line 563 "nested.c"
export_func = {
    name    = 'optionUnloadNested';
    what = 'Deallocate the memory for a nested value';
    arg = {
        arg_type = 'tOptionValue const *';
        arg_name = 'pOptVal';
        arg_desc = 'the hierarchical value';
    };
    doc =
'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}).';
    srcfile = 'nested.c';
    linenum = '563';
};


#line 35 "stack.c"
export_func = {
    name    = 'optionUnstackArg';
    private;
    what = 'Remove option args from a stack';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'Invoked for options that are equivalenced to stacked options.';
    srcfile = 'stack.c';
    linenum = '35';
};


#line 315 "usage.c"
export_func = {
    name    = 'optionUsage';
    private;
    what = 'Print usage text';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'pOptions';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'exitCode';
        arg_desc = 'exit code for calling exit(3)';
    };
    doc =
'This routine will print usage in both GNU-standard and AutoOpts-expanded
formats.  The descriptor specifies the default, but AUTOOPTS_USAGE will
over-ride this, providing the value of it is set to either "gnu" or
"autoopts".  This routine will @strong{not} return.

If "exitCode" is "AO_EXIT_REQ_USAGE" (normally 64), then output will to
to stdout and the actual exit code will be "EXIT_SUCCESS".';
    srcfile = 'usage.c';
    linenum = '315';
};


#line 268 "find.c"
export_func = {
    name    = 'optionVendorOption';
    private;
    what = 'Process a vendor option';
    arg = {
        arg_type = 'tOptions *';
        arg_name = 'pOpts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc *';
        arg_name = 'pOptDesc';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'For POSIX specified utilities, the options are constrained to the options,
@xref{config attributes, Program Configuration}.  AutoOpts clients should
never specify this directly.  It gets referenced when the option
definitions contain a "vendor-opt" attribute.';
    srcfile = 'find.c';
    linenum = '268';
};


#line 31 "version.c"
export_func = {
    name    = 'optionVersion';
    what = 'return the compiled AutoOpts version number';
    ret_type = 'char const*';
    ret_desc = 'the version string in constant memory';
    doc =
'Returns the full version string compiled into the library.
The returned string cannot be modified.';
    srcfile = 'version.c';
    linenum = '31';
};


#line 192 "version.c"
export_func = {
    name    = 'optionVersionStderr';
    private;
    what = 'Print the program version to stderr';
    arg = {
        arg_type = 'tOptions*';
        arg_name = 'opts';
        arg_desc = 'program options descriptor';
    };
    arg = {
        arg_type = 'tOptDesc*';
        arg_name = 'od';
        arg_desc = 'the descriptor for this arg';
    };
    doc =
'This routine will print the version to stderr.';
    srcfile = 'version.c';
    linenum = '192';
};


#line 29 "../compat/pathfind.c"
export_func = {
    name    = 'pathfind';
    what = 'fild a file in a list of directories';
    ifndef = 'HAVE_PATHFIND';
    arg = {
        arg_type = 'char const*';
        arg_name = 'path';
        arg_desc = 'colon separated list of search directories';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'file';
        arg_desc = 'the name of the file to look for';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'mode';
        arg_desc = 'the mode bits that must be set to match';
    };
    ret_type = 'char*';
    ret_desc = 'the path to the located file';
    doc =
'pathfind looks for a a file with name "FILE" and "MODE" access
along colon delimited "PATH", and returns the full pathname as a
string, or NULL if not found.  If "FILE" contains a slash, then
it is treated as a relative or absolute path and "PATH" is ignored.

@strong{NOTE}: this function is compiled into @file{libopts} only if
it is not natively supplied.

The "MODE" argument is a string of option letters chosen from the
list below:
@example
Letter    Meaning
r         readable
w         writable
x         executable
f         normal file       (NOT IMPLEMENTED)
b         block special     (NOT IMPLEMENTED)
c         character special (NOT IMPLEMENTED)
d         directory         (NOT IMPLEMENTED)
p         FIFO (pipe)       (NOT IMPLEMENTED)
u         set user ID bit   (NOT IMPLEMENTED)
g         set group ID bit  (NOT IMPLEMENTED)
k         sticky bit        (NOT IMPLEMENTED)
s         size nonzero      (NOT IMPLEMENTED)
@end example';
    example =
'To find the "ls" command using the "PATH" environment variable:
@example
#include <stdlib.h>
char* pz_ls = pathfind( getenv("PATH"), "ls", "rx" );
<<do whatever with pz_ls>>
free( pz_ls );
@end example
The path is allocated with @code{malloc(3C)}, so you must @code{free(3C)}
the result.  Also, do not use unimplemented file modes.  :-)';
    err = 'returns NULL if the file is not found.';
    srcfile = '../compat/pathfind.c';
    linenum = '29';
};


#line 209 "streqvcmp.c"
export_func = {
    name    = 'strequate';
    what = 'map a list of characters to the same value';
    arg = {
        arg_type = 'char const*';
        arg_name = 'ch_list';
        arg_desc = 'characters to equivalence';
    };
    doc =
'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.';
    err = 'none.';
    srcfile = 'streqvcmp.c';
    linenum = '209';
};


#line 119 "streqvcmp.c"
export_func = {
    name    = 'streqvcmp';
    what = 'compare two strings with an equivalence mapping';
    arg = {
        arg_type = 'char const*';
        arg_name = 'str1';
        arg_desc = 'first string';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'str2';
        arg_desc = 'second string';
    };
    ret_type = 'int';
    ret_desc = 'the difference between two differing characters';
    doc =
'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.';
    err = 'none checked.  Caller responsible for seg faults.';
    srcfile = 'streqvcmp.c';
    linenum = '119';
};


#line 156 "streqvcmp.c"
export_func = {
    name    = 'streqvmap';
    what = 'Set the character mappings for the streqv functions';
    arg = {
        arg_type = 'char';
        arg_name = 'From';
        arg_desc = 'Input character';
    };
    arg = {
        arg_type = 'char';
        arg_name = 'To';
        arg_desc = 'Mapped-to character';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'ct';
        arg_desc = 'compare length';
    };
    doc =
'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.';
    err = 'none.';
    srcfile = 'streqvcmp.c';
    linenum = '156';
};


#line 78 "streqvcmp.c"
export_func = {
    name    = 'strneqvcmp';
    what = 'compare two strings with an equivalence mapping';
    arg = {
        arg_type = 'char const*';
        arg_name = 'str1';
        arg_desc = 'first string';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'str2';
        arg_desc = 'second string';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'ct';
        arg_desc = 'compare length';
    };
    ret_type = 'int';
    ret_desc = 'the difference between two differing characters';
    doc =
'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.';
    err = 'none checked.  Caller responsible for seg faults.';
    srcfile = 'streqvcmp.c';
    linenum = '78';
};


#line 235 "streqvcmp.c"
export_func = {
    name    = 'strtransform';
    what = 'convert a string into its mapped-to value';
    arg = {
        arg_type = 'char*';
        arg_name = 'dest';
        arg_desc = 'output string';
    };
    arg = {
        arg_type = 'char const*';
        arg_name = 'src';
        arg_desc = 'input string';
    };
    doc =
'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.';
    err = 'none.';
    srcfile = 'streqvcmp.c';
    linenum = '235';
};


#line 244 "text_mmap.c"
export_func = {
    name    = 'text_mmap';
    private;
    what = 'map a text file with terminating NUL';
    arg = {
        arg_type = 'char const*';
        arg_name = 'pzFile';
        arg_desc = 'name of the file to map';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'prot';
        arg_desc = 'mmap protections (see mmap(2))';
    };
    arg = {
        arg_type = 'int';
        arg_name = 'flags';
        arg_desc = 'mmap flags (see mmap(2))';
    };
    arg = {
        arg_type = 'tmap_info_t*';
        arg_name = 'mapinfo';
        arg_desc = 'returned info about the mapping';
    };
    ret-type = 'void*';
    ret-desc = 'The mmaped data address';
    doc =
'This routine will mmap a file into memory ensuring that there is at least
one @file{NUL} character following the file data.  It will return the
address where the file contents have been mapped into memory.  If there is a
problem, then it will return @code{MAP_FAILED} and set @code{errno}
appropriately.

The named file does not exist, @code{stat(2)} will set @code{errno} as it
will.  If the file is not a regular file, @code{errno} will be
@code{EINVAL}.  At that point, @code{open(2)} is attempted with the access
bits set appropriately for the requested @code{mmap(2)} protections and flag
bits.  On failure, @code{errno} will be set according to the documentation
for @code{open(2)}.  If @code{mmap(2)} fails, @code{errno} will be set as
that routine sets it.  If @code{text_mmap} works to this point, a valid
address will be returned, but there may still be ``issues\'\'.

If the file size is not an even multiple of the system page size, then
@code{text_map} will return at this point and @code{errno} will be zero.
Otherwise, an anonymous map is attempted.  If not available, then an attempt
is made to @code{mmap(2)} @file{/dev/zero}.  If any of these fail, the
address of the file\'s data is returned, bug @code{no} @file{NUL} characters
are mapped after the end of the data.';
    see = 'mmap(2), open(2), stat(2)';
    err = 'Any error code issued by mmap(2), open(2), stat(2) is possible.
Additionally, if the specified file is not a regular file, then
errno will be set to @code{EINVAL}.';
    example =
'#include <mylib.h>
tmap_info_t mi;
int no_nul;
void* data = text_mmap("file", PROT_WRITE, MAP_PRIVATE, &mi);
if (data == MAP_FAILED) return;
no_nul = (mi.txt_size == mi.txt_full_size);
<< use the data >>
text_munmap(&mi);';
    srcfile = 'text_mmap.c';
    linenum = '244';
};


#line 317 "text_mmap.c"
export_func = {
    name    = 'text_munmap';
    private;
    what = 'unmap the data mapped in by text_mmap';
    arg = {
        arg_type = 'tmap_info_t*';
        arg_name = 'mapinfo';
        arg_desc = 'info about the mapping';
    };
    ret-type = 'int';
    ret-desc = '-1 or 0.  @code{errno} will have the error code.';
    doc =
'This routine will unmap the data mapped in with @code{text_mmap} and close
the associated file descriptors opened by that function.';
    see = 'munmap(2), close(2)';
    err = 'Any error code issued by munmap(2) or close(2) is possible.';
    srcfile = 'text_mmap.c';
    linenum = '317';
};
vers-curr       = "147461";
vers-min        = "102400";
vers-min-str    = "25:0:0";
vers-sovers     = "36:5:11";
library         = opts;

/*
 *  THIS FILE IS DISTRIBUTED
 *
 *  This file is used to construct options.h + doc files.  Because it is
 *  such a nuisance to get the build ordering correct, we distribute
 *  this.  It should be constructed after all binaries are built.
 */