1. Introduction

This manual is only partial documentation for the libopts library. The complete documentation is incorporated into the documentation for the AutoOpts option parsing suite. However, because this library can support stand alone configuration file parsing, this document covers that part of the interface.

To use libopts as an configuration file parser, first include the option header in your program:

#include "autoopts/options.h"

Then find and examine the named values you are interested in:

const tOptionValue* pOV   = configFileLoad( "hello.conf" );
const tOptionValue* pGetV = optionGetValue( pOV, "greeting" );
while (pGetV && (strcmp(pGetV->pzName, "greeting") == 0))
    pGetV = optionNextValue( pOV, pGetV );

Finally, free the config file data structures:

optionUnloadNested( pOV );

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

2.1 configFileLoad

parse a configuration file

Usage:

const tOptionValue* res = configFileLoad( pzFile );

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 empty.
• EINVAL - the file contents are invalid - not properly formed.
• ENOMEM - not enough memory to allocate the needed structures.

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

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.

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

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

3. Config file example

If for some reason it is difficult or unworkable to integrate configuration file processing with command line option parsing, the libopts (see section libopts External Procedures) library can still be used to process configuration files. Below is a "Hello, World!" greeting program that tries to load a configuration file `hello.conf' to see if it should use an alternate greeting or to personalize the salutation.

#include <sys/types.h>
#include <pwd.h>
#include <string.h>
#include <unistd.h>
#include <autoopts/options.h>
int main( int argc, char** argv ) {
  char* greeting = "Hello";
  char* greeted  = "World";
  const tOptionValue* pOV = configFileLoad( "hello.conf" );

  if (pOV != NULL) {
    const tOptionValue* pGetV = optionGetValue( pOV, "greeting" );

    if (  (pGetV != NULL)
       && (pGetV->valType == OPARG_TYPE_STRING))
      greeting = strdup( pGetV->v.strVal );

    pGetV = optionGetValue( pOV, "personalize" );
    if (pGetV != NULL) {
      struct passwd* pwe = getpwuid( getuid() );
      if (pwe != NULL)
        greeted = strdup( pwe->pw_gecos );
    }

    optionUnloadNested( pOV ); /* deallocate config data */
  }
  printf( "%s, %s!\n", greeting, greeted );
  return 0;
}

With that text in a file named "hello.c", this short script:

opts=`autoopts-config cflags ldflags`
cc -o hello hello.c ${opts}
./hello
echo 'greeting Buzz off' > hello.conf
./hello
echo personalize > hello.conf
./hello

will produce the following output (for me):

Hello, World!
Buzz off, World!
Hello, Bruce Korb!

About This Document

This document was generated by Bruce Korb on June, 28 2005 using texi2html 1.76.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated by Bruce Korb on June, 28 2005 using texi2html 1.76.