[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 ); |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 | ||
2.2 optionGetValue | ||
2.3 optionNextValue | ||
2.4 optionUnloadNested |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
parse a configuration file
Usage:
const tOptionValue* res = configFileLoad( pzFile ); |
Where the arguments are:
Name | Type | Description | |
--- | --- | --------- | |
pzFile | | 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 empty.
EINVAL
- the file contents are invalid - not properly formed.
ENOMEM
- not enough memory to allocate the needed structures.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
get a specific value from a hierarcical list
Usage:
const tOptionValue* res = optionGetValue( pOptValue, valueName ); |
Where the arguments are:
Name | Type | Description | |
--- | --- | --------- | |
pOptValue | | a hierarchcal value | |
valueName | | 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.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
get the next value from a hierarchical list
Usage:
const tOptionValue* res = optionNextValue( pOptValue, pOldValue ); |
Where the arguments are:
Name | Type | Description | |
--- | --- | --------- | |
pOptValue | | a hierarchcal list value | |
pOldValue | | 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Deallocate the memory for a nested value
Usage:
optionUnloadNested( pOptVal ); |
Where the arguments are:
Name | Type | Description | |
--- | --- | --------- | |
pOptVal | | the hierarchical value |
A nested value needs to be deallocated. The pointer passed in should
have been gotten from a call to configFileLoad()
(See
see section configFileLoad).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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! |
[Top] | [Contents] | [Index] | [ ? ] |
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:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ < ] | Back | previous section in reading order | 1.2.2 |
[ > ] | Forward | next section in reading order | 1.2.4 |
[ << ] | FastBack | beginning of this chapter or previous chapter | 1 |
[ Up ] | Up | up section | 1.2 |
[ >> ] | FastForward | next chapter | 2 |
[Top] | Top | cover (top) of document | |
[Contents] | Contents | table of contents | |
[Index] | Index | index | |
[ ? ] | About | about (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated by Bruce Korb on June, 28 2005 using texi2html 1.76.