7.6 Programmatic Interface

The user interface for access to the argument information is completely defined in the generated header file and in the portions of the distributed file "options.h" that are marked "public".

In the following macros, text marked <NAME> or name is the name of the option in upper case and segmented with underscores _. The macros and enumerations defined in the options header (interface) file are used as follows:

To see how these #define macros are used in a program, the reader is referred to the several ‘opts.h’ files included with the AutoGen sources.

7.6.1 Data for Option Processing

This section describes the data that may be accessed from within the option processing callback routines. The following fields may be used in the following ways and may be used for read only. The first set is addressed from the tOptDesc* pointer:

‘optIndex’

‘optValue’

These may be used by option procedures to determine which option they are working on (in case they handle several options).

‘optActualIndex’

‘optActualValue’

These may be used by option procedures to determine which option was used to set the current option. This may be different from the above if the options are members of an equivalence class.

‘optOccCt’

If AutoOpts is processing command line arguments, then this value will contain the current occurrence count. During the option preset phase (reading configuration files and examining environment variables), the value is zero.

‘fOptState’

The field may be tested for the following bit values (prefix each name with OPTST_, e.g. OPTST_INIT):

‘INIT’

Initial compiled value. As a bit test, it will always yield FALSE.

‘SET’

The option was set via the SET_OPT() macro.

‘PRESET’

The option was set via a configuration file.

‘DEFINED’

The option was set via a command line option.

‘SET_MASK’

This is a mask of flags that show the set state, one of the above four values.

‘EQUIVALENCE’

This bit is set when the option was selected by an equivalenced option.

‘DISABLED’

This bit is set if the option is to be disabled. (Meaning it was a long option prefixed by the disablement prefix, or the option has not been specified yet and initializes as disabled.)

As an example of how this might be used, in AutoGen I want to allow template writers to specify that the template output can be left in a writable or read-only state. To support this, there is a Guile function named set-writable (see section ‘set-writable’ - Make the output file be writable). Also, I provide for command options ‘--writable’ and ‘--not-writable’. I give precedence to command line and RC file options, thus:

switch (STATE_OPT( WRITABLE )) { case OPTST_DEFINED: case OPTST_PRESET: fprintf(stderr, zOverrideWarn, pCurTemplate->pzFileName, pCurMacro->lineNo); break; default: if (gh_boolean_p( set ) && (set == SCM_BOOL_F)) CLEAR_OPT( WRITABLE ); else SET_OPT_WRITABLE; }

‘pzLastArg’

Pointer to the latest argument string. BEWARE If the argument type is numeric, an enumeration or a bit mask, then this will be the argument value and not a pointer to a string.

The following two fields are addressed from the tOptions* pointer:

‘pzProgName’

Points to a NUL-terminated string containing the current program name, as retrieved from the argument vector.

‘pzProgPath’

Points to a NUL-terminated string containing the full path of the current program, as retrieved from the argument vector. (If available on your system.)

Note these fields get filled in during the first call to optionProcess(). All other fields are private, for the exclusive use of AutoOpts code and are subject to change.

7.6.2 CLEAR_OPT( <NAME> ) - Clear Option Markings

Make as if the option had never been specified. HAVE_OPT(<NAME>) will yield FALSE after invoking this macro.

7.6.3 COUNT_OPT( <NAME> ) - Definition Count

This macro will tell you how many times the option was specified on the command line. It does not include counts of preset options.

if (COUNT_OPT( NAME ) != desired-count) {
    make-an-undesirable-message.
}

7.6.4 DESC( <NAME> ) - Option Descriptor

This macro is used internally by other AutoOpt macros. It is not for general use. It is used to obtain the option description corresponding to its UPPER CASED option name argument. This is primarily used in other macro definitions.

7.6.5 DISABLE_OPT_name - Disable an option

This macro is emitted if it is both settable and it can be disabled. If it cannot be disabled, it may always be CLEAR-ed (see above).

The form of the macro will actually depend on whether the option is equivalenced to another, and/or has an assigned handler procedure. Unlike the SET_OPT macro, this macro does not allow an option argument.

DISABLE_OPT_NAME;

7.6.6 ENABLED_OPT( <NAME> ) - Is Option Enabled?

Yields true if the option defaults to disabled and ISUNUSED_OPT() would yield true. It also yields true if the option has been specified with a disablement prefix, disablement value or the DISABLE_OPT_NAME macro was invoked.

7.6.7 ERRSKIP_OPTERR - Ignore Option Errors

When it is necessary to continue (return to caller) on option errors, invoke this option. It is reversible. See section ERRSTOP_OPTERR - Stop on Errors.

7.6.8 ERRSTOP_OPTERR - Stop on Errors

After invoking this macro, if optionProcess() encounters an error, it will call exit(1) rather than return. This is the default processing mode. It can be overridden by specifying allow-errors in the definitions file, or invoking the macro See section ERRSKIP_OPTERR - Ignore Option Errors.

7.6.9 HAVE_OPT( <NAME> ) - Have this option?

This macro yields true if the option has been specified in any fashion at all. It is used thus:

if (HAVE_OPT( NAME )) {
    <do-things-associated-with-opt-name>;
}

7.6.10 ISSEL_OPT( <NAME> ) - Is Option Selected?

This macro yields true if the option has been specified either on the command line or via a SET/DISABLE macro.

7.6.11 ISUNUSED_OPT( <NAME> ) - Never Specified?

This macro yields true if the option has never been specified, or has been cleared via the CLEAR_OPT() macro.

7.6.12 OPTION_CT - Full Count of Options

The full count of all options, both those defined and those generated automatically by AutoOpts. This is primarily used to initialize the program option descriptor structure.

7.6.13 OPT_ARG( <NAME> ) - Option Argument String

The option argument value as a pointer to string. Note that argument values that have been specified as numbers are stored as numbers or keywords. For such options, use instead the OPT_VALUE_name define. It is used thus:

if (HAVE_OPT( NAME )) {
    char* p = OPT_ARG( NAME );
    <do-things-with-opt-name-argument-string>;
}

7.6.14 OPT_NO_XLAT_CFG_NAMES - option name xlation

Invoking this macro will disable the translation of option names only while processing configuration files and environment variables. This must be invoked before the first call to optionProcess.. You need not invoke this if your option definition file contains the attribute assignment, no-xlate = opt-cfg;.

7.6.15 OPT_NO_XLAT_OPT_NAMES - option name xlation

Invoking this macro will completely disable the translation of option names. This must be invoked before the first call to optionProcess. You need not invoke this if your option definition file contains the attribute assignment, no-xlate = opt;.

7.6.16 OPT_VALUE_name - Option Argument Value

This macro gets emitted only for options that take numeric, keyword or set membership arguments. The macro yields a word-sized integer containing the enumeration, bit set or numeric value for the option argument.

int opt_val = OPT_VALUE_name;

7.6.17 OPT_XLAT_CFG_NAMES - option name xlation

If ENABLE_NLS is defined and no-xlate has been not set to the value anything, this macro will cause the translation of option names to happen before starting the processing of configuration files and environment variables. This will change the recognition of options within the $PROGRAMNAME environment variable, but will not alter the names used for setting options via $PROGRAMNAME_name environment variables.

This must be invoked before the first call to optionProcess. You might need to use this macro if your option definition file contains the attribute assignment, no-xlate = opt; or no-xlate = opt-cfg;, and you have determined in some way that you wish to override that.

7.6.18 OPT_XLAT_OPT_NAMES - option name xlation

If ENABLE_NLS is defined and no-xlate has been not set to the value anything, translate the option names before processing the command line options. Long option names may thus be localized. (If the names were translated before configuration processing, they will not be re-translated.)

This must be invoked before the first call to optionProcess. You might need to use this macro if your option definition file contains the attribute assignment, no-xlate = opt; and you have determined in some way that you wish to override that.

7.6.19 RESTART_OPT( n ) - Resume Option Processing

If option processing has stopped (either because of an error or something was encountered that looked like a program argument), it can be resumed by providing this macro with the index n of the next option to process and calling optionProcess() again.

int main(int argc, char ** argv) {
  for (int ai = 0; ai < argc ;) {
  restart:
    ai = optionProcess(&progOptions, argc, argv);
    for (; ai < argc; ai++) {
      char * arg = arg[ai];
      if (*arg == '-') {
        RESTART_OPT(ai);
        goto restart;
      }
      process(arg);
    }
  }
}

If you want a program to operate this way, you might consider specifying a for-each main function (see section for-each main procedure) with the interleaved attribute. It will allow you to process interleaved operands and options from either the command line or when reading them from standard input.

7.6.20 SET_OPT_name - Force an option to be set

This macro gets emitted only when the given option has the settable attribute specified.

The form of the macro will actually depend on whether the option is equivalenced to another, has an option argument and/or has an assigned handler procedure. If the option has an argument, then this macro will too. Beware that the argument is not reallocated, so the value must not be on the stack or deallocated in any other way for as long as the value might get referenced.

If you have supplied at least one ‘homerc’ file (see section Program Description Attributes), this macro will be emitted for the ‘--save-opts’ option.

SET_OPT_SAVE_OPTS( "filename" );

See section Automatically Supported Options, for a discussion of the implications of using this particular example.

7.6.21 STACKCT_OPT( <NAME> ) - Stacked Arg Count

When the option handling attribute is specified as stack_arg, this macro may be used to determine how many of them actually got stacked.

Do not use this on options that have not been stacked or has not been specified (the stack_arg attribute must have been specified, and HAVE_OPT(<NAME>) must yield TRUE). Otherwise, you will likely seg fault.

if (HAVE_OPT( NAME )) {
    int     ct = STACKCT_OPT(  NAME );
    char**  pp = STACKLST_OPT( NAME );

    do  {
        char* p = *pp++;
        do-things-with-p;
    } while (--ct > 0);
}

7.6.22 STACKLST_OPT( <NAME> ) - Argument Stack

The address of the list of pointers to the option arguments. The pointers are ordered by the order in which they were encountered in the option presets and command line processing.

Do not use this on options that have not been stacked or has not been specified (the stack_arg attribute must have been specified, and HAVE_OPT(<OPTION>) must yield TRUE). Otherwise, you will likely seg fault.

if (HAVE_OPT( NAME )) {
    int     ct = STACKCT_OPT(  NAME );
    char**  pp = STACKLST_OPT( NAME );

    do  {
        char* p = *pp++;
        do-things-with-p;
    } while (--ct > 0);
}

7.6.23 START_OPT - Restart Option Processing

This is just a shortcut for RESTART_OPT(1) (See section RESTART_OPT( n ) - Resume Option Processing.)

7.6.24 STATE_OPT( <NAME> ) - Option State

If you need to know if an option was set because of presetting actions (configuration file processing or environment variables), versus a command line entry versus one of the SET/DISABLE macros, then use this macro. It will yield one of four values: OPTST_INIT, OPTST_SET, OPTST_PRESET or OPTST_DEFINED. It is used thus:

switch (STATE_OPT( NAME )) {
    case OPTST_INIT:
        not-preset, set or on the command line.  (unless CLEAR-ed)

    case OPTST_SET:
        option set via the SET_OPT_NAME() macro.

    case OPTST_PRESET:
        option set via an configuration file or environment variable

    case OPTST_DEFINED:
        option set via a command line option.

    default:
        cannot happen :)
}

7.6.25 USAGE( exit-code ) - Usage invocation macro

This macro invokes the procedure registered to display the usage text. Normally, this will be optionUsage from the AutoOpts library, but you may select another procedure by specifying usage = "proc_name" program attribute. This procedure must take two arguments first, a pointer to the option descriptor, and second the exit code. The macro supplies the option descriptor automatically. This routine is expected to call exit(3) with the provided exit code.

The optionUsage routine also behaves differently depending on the exit code:

EXIT_SUCCESS (the value zero)

It is assumed that full usage help has been requested. Consequently, more information is provided than when displaying usage and exiting with a non-zero exit code. Output will be sent to ‘stdout’ and the program will exit with a zero status code.

EX_USAGE (64)

The abbreviated usage will be printed to ‘stdout’ and the program will exit with a zero status code. EX_USAGE may or may not be 64. If your system provides ‘/usr/include/sysexits.h’ that has a different value, then that value will be used.

any other value

The abbreviated usage will be printed to stderr and the program will exit with the provided status code.

7.6.26 VALUE_OPT_name - Option Flag Value

This is a #define for the flag character used to specify an option on the command line. If value was not specified for the option, then it is a unique number associated with the option. option value refers to this value, option argument refers to the (optional) argument to the option.

switch (WHICH_OPT_OTHER_OPT) {
case VALUE_OPT_NAME:
    this-option-was-really-opt-name;
case VALUE_OPT_OTHER_OPT:
    this-option-was-really-other-opt;
}

7.6.27 VERSION - Version and Full Version

If the version attribute is defined for the program, then a stringified version will be #defined as PROGRAM_VERSION and PROGRAM_FULL_VERSION. PROGRAM_FULL_VERSION is used for printing the program version in response to the version option. The version option is automatically supplied in response to this attribute, too.

You may access PROGRAM_VERSION via programOptions.pzFullVersion.

7.6.28 WHICH_IDX_name - Which Equivalenced Index

This macro gets emitted only for equivalenced-to options. It is used to obtain the index for the one of the several equivalence class members set the equivalenced-to option.

switch (WHICH_IDX_OTHER_OPT) {
case INDEX_OPT_NAME:
    this-option-was-really-opt-name;
case INDEX_OPT_OTHER_OPT:
    this-option-was-really-other-opt;
}

7.6.29 WHICH_OPT_name - Which Equivalenced Option

This macro gets emitted only for equivalenced-to options. It is used to obtain the value code for the one of the several equivalence class members set the equivalenced-to option.

switch (WHICH_OPT_OTHER_OPT) {
case VALUE_OPT_NAME:
    this-option-was-really-opt-name;
case VALUE_OPT_OTHER_OPT:
    this-option-was-really-other-opt;
}

7.6.30 teOptIndex - Option Index and Enumeration

This enum defines the complete set of options, both user specified and automatically provided. This can be used, for example, to distinguish which of the equivalenced options was actually used.

switch (pOptDesc->optActualIndex) {
case INDEX_OPT_FIRST:
    stuff;
case INDEX_OPT_DIFFERENT:
    different-stuff;
default:
    unknown-things;
}

7.6.31 OPTIONS_STRUCT_VERSION - active version

You will not actually need to reference this value, but you need to be aware that it is there. It is the first value in the option descriptor that you pass to optionProcess. It contains a magic number and version information. Normally, you should be able to work with a more recent option library than the one you compiled with. However, if the library is changed incompatibly, then the library will detect the out of date magic marker, explain the difficulty and exit. You will then need to rebuild and recompile your option definitions. This has rarely been necessary.

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

7.6.32.1 ao_string_tokenize

tokenize an input string

Usage:

token_list_t * res = ao_string_tokenize( string );

Where the arguments are:

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.

7.6.32.2 configFileLoad

parse a configuration file

Usage:

const tOptionValue * res = configFileLoad( fname );

Where the arguments are:

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.

7.6.32.3 optionFileLoad

Load the locatable config files, in order

Usage:

int res = optionFileLoad( opts, prog );

Where the arguments are:

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.

7.6.32.4 optionFindNextValue

find a hierarcicaly valued option instance

Usage:

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

Where the arguments are:

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.

7.6.32.5 optionFindValue

find a hierarcicaly valued option instance

Usage:

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

Where the arguments are:

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.

7.6.32.6 optionFree

free allocated option processing memory

Usage:

optionFree( pOpts );

Where the arguments are:

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.

7.6.32.7 optionGetValue

get a specific value from a hierarcical list

Usage:

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

Where the arguments are:

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.

7.6.32.8 optionLoadLine

process a string for an option name and value

Usage:

optionLoadLine( opts, line );

Where the arguments are:

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

7.6.32.9 optionMemberList

Get the list of members of a bit mask set

Usage:

char * res = optionMemberList( od );

Where the arguments are:

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

7.6.32.10 optionNextValue

get the next value from a hierarchical list

Usage:

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

Where the arguments are:

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.

7.6.32.11 optionOnlyUsage

Print usage text for just the options

Usage:

optionOnlyUsage( pOpts, ex_code );

Where the arguments are:

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.

7.6.32.12 optionPrintVersion

Print the program version

Usage:

optionPrintVersion( opts, od );

Where the arguments are:

This routine will print the version to stdout.

7.6.32.13 optionPrintVersionAndReturn

Print the program version

Usage:

optionPrintVersionAndReturn( opts, od );

Where the arguments are:

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.

7.6.32.14 optionProcess

this is the main option processing routine

Usage:

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

Where the arguments are:

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.

7.6.32.15 optionRestore

restore option state from memory copy

Usage:

optionRestore( pOpts );

Where the arguments are:

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.

7.6.32.16 optionSaveFile

saves the option state to a file

Usage:

optionSaveFile( opts );

Where the arguments are:

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.

7.6.32.17 optionSaveState

saves the option state to memory

Usage:

optionSaveState( pOpts );

Where the arguments are:

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.

7.6.32.18 optionUnloadNested

Deallocate the memory for a nested value

Usage:

optionUnloadNested( pOptVal );

Where the arguments are:

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

7.6.32.19 optionVersion

return the compiled AutoOpts version number

Usage:

char const * res = optionVersion();

Where the arguments are:

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

7.6.32.20 strequate

map a list of characters to the same value

Usage:

strequate( ch_list );

Where the arguments are:

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.

7.6.32.21 streqvcmp

compare two strings with an equivalence mapping

Usage:

int res = streqvcmp( str1, str2 );

Where the arguments are:

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.

7.6.32.22 streqvmap

Set the character mappings for the streqv functions

Usage:

streqvmap( from, to, ct );

Where the arguments are:

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.

7.6.32.23 strneqvcmp

compare two strings with an equivalence mapping

Usage:

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

Where the arguments are:

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.

7.6.32.24 strtransform

convert a string into its mapped-to value

Usage:

strtransform( dest, src );

Where the arguments are:

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.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.