diff options
Diffstat (limited to 'autoopts/funcs.def')
| -rw-r--r-- | autoopts/funcs.def | 1620 |
1 files changed, 1620 insertions, 0 deletions
diff --git a/autoopts/funcs.def b/autoopts/funcs.def new file mode 100644 index 0000000..3696339 --- /dev/null +++ b/autoopts/funcs.def @@ -0,0 +1,1620 @@ +/* -*- 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. + */ |