libopts External Procedures
---------------------------

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 options.h header is fairly clear about this, too.

This subsection was automatically generated by AutoGen using extracted information and the aginfo3.tpl template.

ao_string_tokenize
..................

tokenize an input string

Usage:

     token_list_t * res = ao_string_tokenize( string );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  string   char const *
string to be tokenized
  returns   token_list_t *
pointer to a structure that lists each token

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 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:

tkn_ct
     The number of tokens found in the input string.

tok_list
     An array of tkn_ct + 1 pointers to substring tokens, with the last pointer set to NULL.

There are two types of quoted strings: single quoted (') and double quoted (").  Singly quoted strings are fairly raw in that escape characters (\\) are simply another character, except when preceding the following characters:

     \\  double backslashes reduce to one
     '   incorporates the single quote into the string
     \n  suppresses both the backslash and newline character

Double quote strings are formed according to the rules of string constants in ANSI-C programs.

NULL is returned and errno will be set to indicate the problem:

  * EINVAL - There was an unterminated quoted string.

  * ENOENT - The input string was empty.

  * ENOMEM - There is not enough memory.

configFileLoad
..............

parse a configuration file

Usage:

     const tOptionValue * res = configFileLoad( fname );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  fname   char const *
the file to load
  returns   const tOptionValue *
An allocated, compound value structure

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 "OPARG_TYPE_HIERARCHY".  It may be used in calls to optionGetValue(), optionNextValue() and optionUnloadNested().

If the file cannot be loaded or processed, NULL is returned and ERRNO is set.  It may be set by a call to either open(2) mmap(2) or other file system calls, or it may be:

  * ENOENT - the file was not found.

  * ENOMSG - the file was empty.

  * EINVAL - the file contents are invalid -- not properly formed.

  * ENOMEM - not enough memory to allocate the needed structures.

optionFileLoad
..............

Load the locatable config files, in order

Usage:

     int res = optionFileLoad( opts, prog );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  opts   tOptions *
program options descriptor

  prog   char const *
program name
  returns   int
0 -> SUCCESS, -1 -> FAILURE

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 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.

Returns the value, "-1" if the program options descriptor is out of date or indecipherable.  Otherwise, the value "0" will always be returned.

optionFindNextValue
...................

find a hierarcicaly valued option instance

Usage:

     const tOptionValue * res = optionFindNextValue( odesc, pPrevVal, name, value );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  odesc   const tOptDesc *
an option with a nested arg type

  pPrevVal   const tOptionValue *
the last entry

  name   char const *
name of value to find

  value   char const *
the matching value
  returns   const tOptionValue *
a compound value structure

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.

The returned result is NULL and errno is set:

  * EINVAL - the pOptValue does not point to a valid hierarchical option value.

  * ENOENT - no entry matched the given name.

optionFindValue
...............

find a hierarcicaly valued option instance

Usage:

     const tOptionValue * res = optionFindValue( odesc, name, val );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  odesc   const tOptDesc *
an option with a nested arg type

  name   char const *
name of value to find

  val   char const *
the matching value
  returns   const tOptionValue *
a compound value structure

This routine will find an entry in a nested value option or configurable. It will search through the list and return a matching entry.

The returned result is NULL and errno is set:

  * EINVAL - the pOptValue does not point to a valid hierarchical option value.

  * ENOENT - no entry matched the given name.

optionFree
..........

free allocated option processing memory

Usage:

     optionFree( pOpts );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  pOpts   tOptions *
program options descriptor

AutoOpts sometimes allocates memory and puts pointers to it in the option state structures.  This routine deallocates all such memory.

As long as memory has not been corrupted, this routine is always successful.

optionGetValue
..............

get a specific value from a hierarcical list

Usage:

     const tOptionValue * res = optionGetValue( pOptValue, valueName );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  pOptValue   const tOptionValue *
a hierarchcal value

  valueName   char const *
name of value to get
  returns   const tOptionValue *
a compound value structure

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.

The returned result is NULL and errno is set:

  * EINVAL - the pOptValue does not point to a valid hierarchical option value.

  * ENOENT - no entry matched the given name.

optionLoadLine
..............

process a string for an option name and value

Usage:

     optionLoadLine( opts, line );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  opts   tOptions *
program options descriptor

  line   char const *
NUL-terminated text

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 (see basic expression), except that you may not use backquotes.

Invalid options are silently ignored.  Invalid option arguments will cause a warning to print, but the function should return.

optionMemberList
................

Get the list of members of a bit mask set

Usage:

     char * res = optionMemberList( od );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  od   tOptDesc *
the set membership option description
  returns   char *
the names of the set bits

This converts the OPT_VALUE_name mask value to a allocated string. It is the caller's responsibility to free the string.

optionNextValue
...............

get the next value from a hierarchical list

Usage:

     const tOptionValue * res = optionNextValue( pOptValue, pOldValue );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  pOptValue   const tOptionValue *
a hierarchcal list value

  pOldValue   const tOptionValue *
a value from this list
  returns   const tOptionValue *
a compound value structure

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 "ERRNO" will be set to EINVAL. The "POLDVALUE" must have been gotten from a prior call to this routine or to "opitonGetValue()".

The returned result is NULL and errno is set:

  * EINVAL - the pOptValue does not point to a valid hierarchical option value or pOldValue does not point to a member of that option value.

  * ENOENT - the supplied pOldValue pointed to the last entry.

optionOnlyUsage
...............

Print usage text for just the options

Usage:

     optionOnlyUsage( pOpts, ex_code );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  pOpts   tOptions *
program options descriptor

  ex_code   int
exit code for calling exit(3)

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.

optionPrintVersion
..................

Print the program version

Usage:

     optionPrintVersion( opts, od );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  opts   tOptions *
program options descriptor

  od   tOptDesc *
the descriptor for this arg

This routine will print the version to stdout.

optionPrintVersionAndReturn
...........................

Print the program version

Usage:

     optionPrintVersionAndReturn( opts, od );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  opts   tOptions *
program options descriptor

  od   tOptDesc *
the descriptor for this arg

This routine will print the version to stdout and return instead of exiting.  Please see the source for the print_ver funtion for details on selecting how verbose to be after this function returns.

optionProcess
.............

this is the main option processing routine

Usage:

     int res = optionProcess( opts, a_ct, a_v );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  opts   tOptions *
program options descriptor

  a_ct   int
program arg count

  a_v   char **
program arg vector
  returns   int
the count of the arguments processed

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 not be counted among the processed arguments.  A hyphen by itself is treated as an operand.  Encountering an operand stops option processing.

Errors will cause diagnostics to be printed.  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.

optionRestore
.............

restore option state from memory copy

Usage:

     optionRestore( pOpts );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  pOpts   tOptions *
program options descriptor

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.

If you have not called optionSaveState before, a diagnostic is printed to stderr and exit is called.

optionSaveFile
..............

saves the option state to a file

Usage:

     optionSaveFile( opts );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  opts   tOptions *
program options descriptor

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 --save-opts option, or by appending the rcfile attribute to the last homerc attribute.  If no rcfile attribute was specified, it will default to .programnamerc.  If you wish to specify another file, you should invoke the SET_OPT_SAVE_OPTS(filename) macro.

The recommend usage is as follows:

     optionProcess(&progOptions, argc, argv);
     if (i_want_a_non_standard_place_for_this)
     SET_OPT_SAVE_OPTS("myfilename");
     optionSaveFile(&progOptions);

If no 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 stderr and the routine will return.

optionSaveState
...............

saves the option state to memory

Usage:

     optionSaveState( pOpts );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  pOpts   tOptions *
program options descriptor

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.

If it fails to allocate the memory, it will print a message to stderr and exit. Otherwise, it will always succeed.

optionUnloadNested
..................

Deallocate the memory for a nested value

Usage:

     optionUnloadNested( pOptVal );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  pOptVal   tOptionValue const *
the hierarchical value

A nested value needs to be deallocated.  The pointer passed in should have been gotten from a call to configFileLoad() (See libopts-configFileLoad).

optionVersion
.............

return the compiled AutoOpts version number

Usage:

     char const * res = optionVersion();

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  returns   char const *
the version string in constant memory

Returns the full version string compiled into the library. The returned string cannot be modified.

strequate
.........

map a list of characters to the same value

Usage:

     strequate( ch_list );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  ch_list   char const *
characters to equivalence

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.

none.

streqvcmp
.........

compare two strings with an equivalence mapping

Usage:

     int res = streqvcmp( str1, str2 );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  str1   char const *
first string

  str2   char const *
second string
  returns   int
the difference between two differing characters

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.

none checked.  Caller responsible for seg faults.

streqvmap
.........

Set the character mappings for the streqv functions

Usage:

     streqvmap( from, to, ct );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  from   char
Input character

  to   char
Mapped-to character

  ct   int
compare length

Set the character mapping.  If the count (ct) is set to zero, then the map is cleared by setting all entries in the map to their index value.  Otherwise, the "From" character is mapped to the "To" character.  If ct is greater than 1, then From and To are incremented and the process repeated until ct entries have been set. For example,

     streqvmap('a', 'A', 26);

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.

none.

strneqvcmp
..........

compare two strings with an equivalence mapping

Usage:

     int res = strneqvcmp( str1, str2, ct );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  str1   char const *
first string

  str2   char const *
second string

  ct   int
compare length
  returns   int
the difference between two differing characters

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 ct bytes. This function name is mapped to option_strneqvcmp so as to not conflict with the POSIX name space.

none checked.  Caller responsible for seg faults.

strtransform
............

convert a string into its mapped-to value

Usage:

     strtransform( dest, src );

Where the arguments are:

  Name   Type   Description
  -----   -----   -------------
  dest   char *
output string

  src   char const *
input string

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.

none.

bye