This document describes the API as defined by the Conf4C library.  This
document was last revised on 29 October 2004.

   Copyright (C) 2004 jpbarto.

   Permission is granted to make and distribute verbatim copies of this
reference provided by the copyright notice and this permission notice
are preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation.

Conf4C Tutorial & API Reference
*******************************

   This document describes the API as defined by the Conf4C Library.
It aims to provide a programming resource to developers attempting to
incorporate the services of the Conf4C library that will provide a
clear definition of the libraries construction and the use of the
interfaces into the objects contained in the library.

   This document was last revised on 29 October 2004.

Conf4C Overview
***************

   The Conf4C Library is a library designed to provide applications
simple and direct access to a configuration file.

Introduction
============

   The following documents as thoroughly as possible the functions,
structs, and functional requirements of the Conf4C library.  This
document is growing as I get time so please bear with me.  author
homepage (http://jpbarto.freeshell.org)

Configuration File Format
=========================

   Document file format restrictions for input config file

Mailing List / Bug Reports
==========================

   Mailing lists and bug reports - Getting help with LibConf4C

Common Questions
================

   - Question / Answer

   - Question / Answer #2

Conf4C Tutorial
***************

   The following provides a sample application listing and walks
through each step of the source to better illustrate how to read a
configuration file using LibConf4C.

Example Source
==============

   ` #include <stdio.h>

   #include "conf4c.h"

   int main (int argc, char **argv) { 	Conf4CFile *c4cf;
Conf4CFileAttrib *c4cfattrib; 	Conf4CParser *parser;
Conf4CReader *c4cr;

   	/* create an instance of Conf4CFile 		*/ 	/* use values:					*/ 	/*
'#' denotes a comments			*/ 	/* ' ' delimits a name / value pair		*/
/* create room for 3 section types		*/ 	/* create room for 3 instances of
each type 	*/ 	/* create froom for 5 entries in each instance	*/
/* create room for 25 top level n/v entries 	*/ 	c4cfattrib =
conf4c_fileattrib_new ("apache.conf", "#", " ", CONF4C_DELIM_LAZY);
c4cf = conf4c_file_new (3, 25); 	parser = conf4c_parser_new (c4cf,
c4cfattrib);

   	/* parse the file */ 	conf4c_parser_parse (parser, 3, 5);

   	/* create a reader to read the newly parsed file */ 	c4cr =
conf4c_reader_new (c4cf);

   	/* now move the Conf4CReader through each and every name / value
pair the */ 	/* Conf4CFile contains, retreiving section types,
section-instance names, */ 	/* and both name and value strings
along the way */ 	do { 		printf ("Entering Section Type: %s\n",
conf4c_reader_get_section_type (c4cr));

   		do { 			printf ("\tListing Section Instance: %s\n",
conf4c_reader_get_stor_name (c4cr));

   			do { 				printf ("\t\t<Name : Value>: %s : %s\n",
conf4c_reader_get_value_name (c4cr), 						conf4c_reader_get_value (c4cr));
}while (conf4c_reader_next_name_value (c4cr)); 		}while
(conf4c_reader_next_stor (c4cr)); 	}while (conf4c_reader_next_section
(c4cr));

   	/* or if you know the section-type and name of the */ 	/*
value you desire */ 	printf ("IfModule type, prefork.c instance,
MaxClients value: %s\n", 			conf4c_reader_get_named_value (c4cr,
"IfModule", "prefork.c", "MaxClients")); 	return 0; } '

Source Walkthrough
==================

   To gain access to the LibConf4C functions and structures you must
include the line: ` #include "conf4c.h" '
In order to parse any configuration file you need to create at *least*
three objects: Conf4CFileAttrib : Contains attributes about the
configuration file to be parsed such as the filename, what denotes a
comment, and what defines a name / value delimiter Conf4CParser : To
perform the parsing of a configuration file Conf4CFile : Contains the
parsed elements of a configuration file
To parse a configuration file which uses '#' as the start of a comment,
a ' ' character as the delimiter between a name and a value, and a
configuration file called `apache.conf': ` Conf4CFileAttrib *c4cfattrib
= conf4c_fileattrib_new ("apache.conf", "#", " ", CONF4C_DELIM_LAZY); '
Next, before parsing the configuration file memory must be allocated
for storing the parsed configuration values.  To create a Conf4CFile
which allocates enough memory for (initially) 3 section types, and 25
instances in the base section (all name / value pairs outside of
'<></>' section markers): ` Conf4CFile *c4cf = conf4c_file_new (3, 25);
'
Finally, create a Conf4CParser that will parse the configuration file
specified by C4CFATTRIB and populate the Conf4CFile C4CF.  Then to
actually perform the parsing execute CONF4C_PARSER_PARSE ().  By
passing values of '3' and '5', the parse function will (when creating
new section types and section instances) allocate room for 3 section
instances per section-type, and 5 name / value pairs per section
instance.  ` Conf4CParser *c4cp = conf4c_parser_new (c4cf, c4cfattrib);
conf4c_parser_parse (3, 5); '
At this point the Conf4CFile has been populated by the
CONF4C_PARSER_PARSE function.  To easily access the contents of a
parsed Conf4CFile you will also want to create a Conf4CReader.  `
Conf4CReader *c4cr = conf4c_reader_new (c4cf); '
Now to iterate through every name / value pair contained within the
Conf4CFile begin three while loops.  The outermost loop will traverse
all configured section-types.  The second loop will traverse each
section instance of each section-type.  And the innermost loop will
traverse the name / value pairs of each section instance.  ` /* when a
Conf4CReader is initialized it is already pointing at the */ /* first
name / value pair of the first section instance of the first
section-type */ do { 	do { 		do { 		} while
(conf4c_reader_next_name_value (c4cr)); 	} while
(conf4c_reader_next_stor (c4cr)); } while (conf4c_reader_next_section
(c4cr)); '
Then at each level you can access values such as section type, section
instance name, name-value name, and name-value value with the functions:
` conf4c_reader_get_section_type () conf4c_reader_get_stor_name ()
conf4c_reader_get_value_name () conf4c_reader_get_value () '
Or gain direct access with: ` conf4c_reader_get_named_value () '
For more information about the Conf4CReader and its functionality see
the *Note Conf4C Reference::.

Example Configuration File
==========================

   ` ### Main Configuration Section ### ServerRoot /usr/lib/apache2 			#
Section-Type = ' ', Section Instance Name = ' ' PidFile
/var/run/apache2.pid			# These are 5 name / value pairs with a delimiter
of ' ' ErrorLog logs/error_log				# each at the top-most
section-type and instance LogLevel warn DocumentRoot
/var/www/localhost/htdocs

   ### ### Global Configuration ### # For Apache2 we load all conf
files in conf/modules.d Include conf/modules.d/*.conf			# more top-most
name / value pairs Include conf/commonapache2.conf

   ### ### IP Address/Port ### #BindAddress * Listen 80

   ### ### Log configuration Section ### <IfModule mod_log_config.c>			#
Section-Type = 'IfModule', Section Instance Name = 'mod_log_config.c'
CustomLog logs/access_log combined env=!VLOG	# this name / value
pair will be added to the 'mod_log_config.c' section </IfModule>					#
instance of the 'IfModule' section-type

   ### ### Virtual Hosts ###

   Include conf/vhosts/vhosts.conf			# This name / value pair, being
outside of any <></> section identifiers 						# will be added to the
top-most collection of name / value pairs ### ### Performance settings
Section ### # # Timeout: The number of seconds before receives and
sends time out.  # Timeout 300					# More top-most name / value pairs

   KeepAlive On

   MaxKeepAliveRequests 100

   KeepAliveTimeout 15

   <IfModule prefork.c>				# Section-Type = 'IfModule' (like above) and
StartServers         5				# section instance name = 'prefork.c'
MinSpareServers      5				# These name / value pairs will be added to the
'prefork.c' instance MaxSpareServers     10				# of the 'IfModule'
section-type MaxClients         150 MaxRequestsPerChild  0 </IfModule>

   <IfModule worker.c>				# Another section instance of the 'IfModule'
section type StartServers         2 MaxClients         150
MinSpareThreads     25 MaxSpareThreads     75 ThreadsPerChild     25
MaxRequestsPerChild  0 </IfModule>

   <IfModule perchild.c>				# Yet another 'IfModule' section-type
instance NumServers           5 StartThreads         5 MinSpareThreads
   5 MaxSpareThreads     10 MaxThreadsPerChild  20 MaxRequestsPerChild
0 </IfModule>

   Alias /awstatsclasses "/etc/awstats/wwwroot/classes/" Alias
/awstatscss "/etc/awstats/wwwroot/css/" Alias /awstatsicons
"/etc/awstats/wwwroot/icon/" ScriptAlias /awstats/
"/etc/awstats/wwwroot/cgi-bin/"

   <Directory "/etc/awstats/wwwroot">		# A second section-type
(Conf4CSection) will be added to accomodate     Options None				# a
new section-type of 'Directory' with '"/etc/awstats/wwwroot"' as
AllowOverride None				# the first instance of this new section-type
Order allow,deny     Allow from all </Directory> '

Conf4C Reference
****************

   The following contains a listing of each object / data type and its
associated functions.

Conf4CReader
============

   Conf4CReader - A convenience object used to easily read a parsed
Conf4CFile

Synopsis
========

   ` #include "conf4cfile.h"

   struct *Note Conf4CReader: struct_conf4creader;

   *Note Conf4CReader:: *	*Note
conf4c_reader_new::			(*Note Conf4CFile:: *c4cf); *Note Conf4CReader::
*	*Note conf4c_reader_get_named_value::		(*Note Conf4CReader:: *c4cr,
const char *type, 							 const char *stor, 							 const char *name);

   /* *Note Conf4CSection:: manipulation functions */ int		*Note
conf4c_reader_get_section_count::		(*Note Conf4CReader:: *c4cr); int		*Note
conf4c_reader_set_current_section::	(*Note Conf4CReader:: *c4cr, 							 const
unsigned int sect_index); int		*Note
conf4c_reader_set_typed_section::	(*Note Conf4CReader:: *c4cr,
const char *type); int		*Note conf4c_reader_next_section::		(*Note
Conf4CReader:: *c4cr); char *		*Note
conf4c_reader_get_section_type::		(*Note Conf4CReader:: *c4cr);

   /* *Note Conf4CStor:: manipulation functions */ int		*Note
conf4c_reader_get_stor_count::		(*Note Conf4CReader:: *c4cr);
int		*Note conf4c_reader_set_current_stor::		(*Note Conf4CReader::
*c4cr, 							 const unsigned int stor_index); int		*Note
conf4c_reader_set_named_stor::	(*Note Conf4CReader:: *c4cr,
const char *name); int		*Note conf4c_reader_next_stor::			(*Note
Conf4CReader:: *c4cr); char *		*Note
conf4c_reader_get_stor_name::		(*Note Conf4CReader:: *c4cr);

   /* name / value manipulation functions */ int		*Note
conf4c_reader_get_name_value_count::	(*Note Conf4CReader:: *c4cr);
int		*Note conf4c_reader_set_current_name_value::	(*Note
Conf4CReader:: *c4cr, 							 const unsigned int nv_index); int		*Note
conf4c_reader_set_named_value::	(*Note Conf4CReader:: *c4cr,
const char *name); int		*Note conf4c_reader_next_name_value::
(*Note Conf4CReader:: *c4cr); char *		*Note
conf4c_reader_get_value_name::		(*Note Conf4CReader:: *c4cr);
char *		*Note conf4c_reader_get_value::			(*Note Conf4CReader:: *c4cr); '

Description
===========

   The Conf4CReader allows an application to easily traverse an already
parsed Conf4CFile, providing simple sequential access to all name /
value pairs obtained from a configuration file.

Details
=======

struct Conf4CReader
-------------------

   ` struct Conf4CReader; ' This should not be accessed directly.  Use
the accessor functions below.

conf4c_reader_new ()
--------------------

   ` Conf4CReader * conf4c_reader_new (Conf4CFile *c4cf); ' Creates a
new Conf4CReader.
C4CF : an initialized and parsed (see conf4c_file_parse ()) Conf4CFile
_Returns_ : a new Conf4CReader

conf4c_reader_get_named_value ()
--------------------------------

   ` int conf4c_reader_get_named_value 	(Conf4CReader *c4cr,
const char *type, 					 const char *stor, 					 const char *name); ' Retrieves
the specified value.
C4CR : a *Note Conf4CReader::
TYPE : the name of the section-type containing the desired value
STOR : the name of the section instance containing the desired value
NAME : the name of the desired value
_Returns_ : the desired value or NULL if the value is not found

conf4c_reader_get_section_count ()
----------------------------------

   ` int conf4c_reader_get_section_count (*Note Conf4CReader:: *c4cr); '
Returns the number of section types captured from the parsed
configuration file.
C4CR : a Conf4CReader

conf4c_reader_set_current_section ()
------------------------------------

   ` int conf4c_reader_set_current_section	(*Note Conf4CReader::
*c4cr, 					 const unsigned int sect_index); ' Points the Conf4CReader to
the *Note Conf4CSection:: at SECT_INDEX.
C4CR : a Conf4CReader
SECT_INDEX : the index of the desired Conf4CSection
_Returns_ : a 0 if the SECT_INDEX is invalid

conf4c_reader_next_section ()
-----------------------------

   ` int conf4c_reader_next_section	(*Note Conf4CReader:: *c4cr); '
Moves the Conf4CReader on to the next *Note Conf4CSection::.
_Returns_ : a 0 if the end of the Conf4CSection array has been reached

conf4c_reader_get_section_type ()
---------------------------------

   ` char * conf4c_reader_get_section_type	(*Note Conf4CReader::
*c4cr); ' Returns the section type of the current section.

conf4c_reader_set_typed_section ()
----------------------------------

   ` int conf4c_reader_set_typed_section	(*Note Conf4CReader::
*c4cr, 					 const char *type); ' Points the Conf4CReader to the *Note
Conf4CSection:: instances of type TYPE.
C4CR : a Conf4CReader
TYPE : the type of the desired section
_Returns_ : a 0 if the section type is not found

conf4c_reader_get_stor_count ()
-------------------------------

   ` int conf4c_reader_get_stor_count	(*Note Conf4CReader:: *c4cr); '
Returns the number of *Note Conf4CStor:: instances held within the
current *Note Conf4CSection::.

conf4c_reader_set_current_stor ()
---------------------------------

   ` int conf4c_reader_set_current_stor 	(*Note Conf4CReader::
*c4cr, 					 const unsigned int stor_index); ' Sets the current *Note
Conf4CStor:: to that of the STOR_INDEX'th instance.
_Returns_ : a 0 if the STOR_INDEX is invalid

conf4c_reader_set_named_stor ()
-------------------------------

   ` int conf4c_reader_set_named_stor	(*Note Conf4CReader:: *c4cr,
const char *name); ' Points the Conf4CReader to the *Note Conf4CStor::
with name NAME.
C4CR : a Conf4CReader
NAME : the name of the desired section
_Returns_ : a 0 if the section instance is not found

conf4c_reader_next_stor ()
--------------------------

   ` int conf4c_reader_next_stor (*Note Conf4CReader:: *c4cr); ' Moves
the Conf4CReader on to the next *Note Conf4CStor:: instance within the
current *Note Conf4CSection::.
_Returns_ : 0 if no more Conf4CStor instances exist

conf4c_reader_get_stor_name ()
------------------------------

   ` char * conf4c_reader_get_stor_name (*Note Conf4CReader:: *c4cr); '
Returns the name of the current Conf4CStor (the name of the current
section instance).

conf4c_reader_get_name_value_count ()
-------------------------------------

   ` int conf4c_reader_get_name_value_count (*Note Conf4CReader::
*c4cr); ' Returns the number of name / value pairs within the current
Conf4CStor.

conf4c_reader_set_current_name_value ()
---------------------------------------

   ` int conf4c_reader_set_current_name_value	(*Note
Conf4CReader:: *c4cr, 						 const unsigned int nv_index); ' Points
Conf4CReader at the NV_INDEX'th name / value pair.
_Returns_ : 0 if the specified nv_index is invalid (greater than the number of available name / value pairs)

conf4c_reader_set_named_value ()
--------------------------------

   ` int conf4c_reader_set_named_value	(*Note Conf4CReader:: *c4cr,
const char *name); ' Points Conf4CReader at the name / value pair with
name NAME.
_Returns_ : 0 if the specified name / value pair is not found

conf4c_reader_next_name_value ()
--------------------------------

   ` int conf4c_reader_next_name_value (*Note Conf4CReader:: *c4cr); '
Moves the Conf4CReader on to the next name / value pair.
_Returns_ : 0 if the available name / value pairs have been exceeded

conf4c_reader_get_value_name ()
-------------------------------

   ` char * conf4c_reader_get_value_name (*Note Conf4CReader:: *c4cr); '
Returns the name portion of the current name / value pair.

conf4c_reader_get_value ()
--------------------------

   ` char * conf4c_reader_get_value (*Note Conf4CReader:: *c4cr); '
Returns the value portion of the current name / value pair.

Conf4CParser
============

   Conf4CParser - Provides a configuration-file parsing function.

Synopsis
========

   ` #include "conf4cfile.h" #include "conf4cfileattrib.h"

   struct *Note Conf4CParser: struct_conf4cparser;

   *Note Conf4CParser:: *		*Note
conf4c_parser_new::			(*Note Conf4CFile:: *c4cf, 					 			 *Note
Conf4CFileAttrib:: *c4cfattrib); int			*Note
conf4c_parser_parse::			(*Note Conf4CParser:: *c4cp, 								 const unsigned int
instances, 								 const unsigned int entries); *Note Conf4CFile::
*		*Note conf4c_parser_get_conf4cfile::		(*Note Conf4CParser:: *c4cp);
*Note Conf4CFileAttrib:: *	*Note
conf4c_parser_get_conf4cfileattrib::	(*Note Conf4CParser:: *c4cp); '

Description
===========

   The Conf4CParser is provided to separate the actual configuration
file parsing algorithm from the remainder of the library; allowing for
the user to implement their own parsing function (perhaps necessary for
customizations and extensions to the *Note Conf4CFileAttrib:: struct).

Details
=======

Conf4CParser
------------

   ` struct Conf4CParser; ' This should not be accessed directly.  Use
the accessor functions below.

conf4c_parser_new ()
--------------------

   ` Conf4CParser * conf4c_parser_new	(*Note Conf4CFile:: *c4cf, 					 *Note
Conf4CFileAttrib:: *c4cfattrib); ' Creates a new instance of
Conf4CParser.
C4CF : 		the Conf4CFile to be populated by the parsing
C4CFATTRIB : 	the attributes of the configuration file (delimiter and comment definitions) that allow the file
			to be parsed; not to mention the file name of the configuration file

conf4c_parser_parse ()
----------------------

   ` int conf4c_parser_parse	(Conf4CParser *c4cp, 			 const
unsigned int instances, 			 const unsigned int entries); ' Parses
the configuration file specified by the member variable C4CFATTRIB and
stores the results in the second member: C4CF.
C4CP : a Conf4CParser
INSTANCES : the expected number of instances of each section type
ENTRIES : the expected number of name / value pairs per section instance
_Returns_ : an int indicating success or error during the parse; 1 = success, 0 = error

conf4c_parser_get_conf4cfile ()
-------------------------------

   ` *Note Conf4CFile:: * conf4c_parser_get_conf4cfile	(Conf4CParser
*c4cp); ' Returns the stored Conf4CFile (a useless function until after
*Note conf4c_parser_parse:: has been called).

conf4c_parser_get_conf4cfileattrib ()
-------------------------------------

   ` *Note Conf4CFileAttrib:: *
conf4c_parser_get_conf4cfileattrib	(Conf4CParser *c4cp); ' Returns the
stored *Note Conf4CFileAttrib::.

Conf4CFileAttrib
================

   Conf4CFileAttrib - A collection of configuration file attributes

Synopsis
========

   ` enum *Note Conf4CDelimType: enum_conf4cdelimtype;

   struct *Note Conf4CFileAttrib: struct_conf4cfileattrib;

   *Note Conf4CFileAttrib:: *	*Note
conf4c_fileattrib_new::			(const char *fname, 								 const char *comment,
const char *delim, 								 *Note Conf4CDelimType: enum_conf4cdelimtype dtype);
char *			*Note conf4c_fileattrib_get_filename::		(*Note
Conf4CFileAttrib:: *c4cfattrib); char * 			*Note
conf4c_fileattrib_get_commentmarker::	(*Note Conf4CFileAttrib::
*c4cfattrib); char *			*Note
conf4c_fileattrib_get_delimiter::		(*Note Conf4CFileAttrib:: *c4cfattrib);
*Note Conf4CDelimType: enum_conf4cdelimtype		*Note
conf4c_fileattrib_get_delimiter_type::	(*Note Conf4CFileAttrib::
*c4cfattrib); '

Description
===========

   The Conf4CFileAttrib maintains a list of attributes about a
configuration file such as what denotes a comment, the delimiter which
divides a name from a value, and how the delimiter should be treated.
The Conf4CFileAttrib also maintains the filename of the configuration
file.

Details
=======

enum Conf4CDelimType
--------------------

   ` typedef enum { 	DELIM_STRICT = 1, 	DELIM_LAZY } Conf4CDelimType; '
The delimiter type informs the parser of how the delimiter is to be
treated.  A value of DELIM_STRICT will require that the entire
delimiter value be found in its entirity between a name / value pair.
A value of DELIM_LAZY will find the first occurrence of a character
specified within the delimiter string and continue until a character
not within the delimieter 'set' is found.

Conf4CFileAttrib
----------------

   ` struct Conf4CFileAttrib; ' This should not be accessed directly.
Use the accessor functions below.

conf4c_fileattrib_new ()
------------------------

   ` *Note Conf4CFileAttrib:: * conf4c_fileattrib_new	(const char *fname,
const char *comment, 						 const char *delimiter, 						 *Note
Conf4CDelimType: enum_conf4cdelimtype dtype); ' Creates a new instance
of Conf4CFileAttrib.
FNAME : the filename of the configuration file
COMMENT : the string which specifies a comment
DELIMITER : the string which specifies the seperation between name and value
DTYPE : how the delimiter is to be interpreted

conf4c_fileattrib_get_filename ()
---------------------------------

   ` char * conf4c_fileattrib_get_filename (*Note Conf4CFileAttrib::
*c4cfattrib); ' Returns the filename stored within the Conf4CFileAttrib.
C4CFATTRIB : a Conf4CFileAttrib

conf4c_fileattrib_get_commentmarker
-----------------------------------

   ` char * conf4c_fileattrib_get_commentmarker (*Note
Conf4CFileAttrib:: *c4cfattrib); ' Returns the comment string which
indicates the start of a comment within the configuration file.
C4CFATTRIB : a Conf4CFileAttrib

conf4c_fileattrib_get_delimiter ()
----------------------------------

   ` char * conf4c_fileattrib_get_delimiter (*Note Conf4CFileAttrib::
*c4cfattrib); ' Returns the delimiter string.
C4CFATTRIB : a Conf4CFileAttrib

conf4c_fileattrib_get_delimiter_type ()
---------------------------------------

   ` *Note Conf4CDelimType: enum_conf4cdelimtype *Note
conf4c_fileattrib_get_delimiter_type:: (*Note Conf4CFileAttrib::
*c4cfattrib); ' Returns the stored delimiter type.
C4CFATTRIB : a Conf4CFileAttrib

Conf4CFile
==========

   Conf4CFile - A logical construction of a configuration file

Synopsis
========

   ` #include "conf4csection.h" #include "conf4cvector.h"

   struct *Note Conf4CFile: struct_conf4cfile;

   *Note Conf4CFile:: *	*Note conf4c_file_new::				(const char
*fname, 							 const char *comment, 							 const char *delim,
*Note Conf4CDelimType: enum_conf4cdelimtype dtype, 							 const unsigned int
type_capacity, 							 const unsigned int instance_capacity,
const unsigned int entry_capacity, 					 		 const unsigned int
base_entry_capacity); int		*Note conf4c_file_add_section::			(*Note
Conf4CFile:: *c4cf, 					 		 *Note Conf4CSection:: *csect); char
*		*Note conf4c_file_get_filename::		(*Note Conf4CFile:: *c4cf); int		*Note
conf4c_file_get_section_count::		(const *Note Conf4CFile:: *c4cf);
char *		*Note conf4c_file_get_section_type::		(const *Note
Conf4CFile:: *c4cf, 							 const unsigned int index); int 		*Note
conf4c_file_get_section_index::		(const *Note Conf4CFile:: *c4cf,
const char *type); *Note Conf4CSection:: *	*Note
conf4c_file_get_section_by_index::	(const *Note Conf4CFile:: *c4cf,
const unsigned int index); *Note Conf4CSection:: * *Note
conf4c_file_get_section_by_type::		(const *Note Conf4CFile:: *c4cf,
const char *type); '

Description
===========

   Conf4CFile maintains a logical view of a configuration file's
contents in terms of sections, section-instances, and name / value
pairs.

struct Conf4CFile
-----------------

   ` struct Conf4CFile; ' This should not be accessed directly.  Use
the accessor functions below.

conf4c_file_new ()
------------------

   ` Conf4CFile * conf4c_file_new 	(const char *fname, 				 const char
*comment, 				 const char *delim, 				 *Note Conf4CDelimType:
enum_conf4cdelimtype dtype, 				 const unsigned int type_capacity,
const unsigned int instance_capacity, 				 const unsigned int
entry_capacity, 				 const unsigned int base_entry_capacity); ' Creates a
new *Note Conf4CFile::.
_Returns_ : a newly created Conf4CFile, unparsed

conf4c_file_add_section ()
--------------------------

   ` int	conf4c_file_add_section	(*Note Conf4CFile:: *c4cf,
*Note Conf4CSection:: *csect); ' Adds a Conf4CSection instance to the
Conf4CFile.
C4CF : a Conf4CFile
CSECT : the Conf4CSection instance to add to C4CF
_Returns_ : an int value indicating success or failure; 1 = success, 0 = failure

conf4c_file_get_filename ()
---------------------------

   ` char *	conf4c_file_get_filename	(const Conf4CFile
*c4cf); ' Returns the filename of the Conf4CFile instance's
configuration file.
C4CF : a Conf4CFile

conf4c_file_get_section_count ()
--------------------------------

   ` int	conf4c_file_get_section_count	(const *Note
Conf4CFile:: *c4cf); ' Returns the number of *Note Conf4CSection::s
contained within the Conf4CFile.
C4CF : a Conf4CFile

conf4c_file_get_section_type ()
-------------------------------

   ` char *	conf4c_file_get_section_type	(const *Note
Conf4CFile:: *c4cf, 					 const unsigned int index); ' Returns the type of
the *Note Conf4CSection:: indicated by the specified INDEX.
C4CF : a Conf4CFile
INDEX : a positive index indicating which Conf4CSection to reference
_Returns_ : a NULL value if the index is invalid

conf4c_file_get_section_index ()
--------------------------------

   ` int	conf4c_file_get_section_index	(const *Note
Conf4CFile:: *c4cf, 					 const char *type); ' Locates a Conf4CSection by
its type and returns the index of the specified section.
C4CF : a Conf4CFile
TYPE : a string specifying the section type
_Returns_ : a -1 if the specified section type is not found

conf4c_file_get_section_by_index ()
-----------------------------------

   ` *Note Conf4CSection::
*	conf4c_file_get_section_by_index	(const *Note Conf4CFile:: *c4cf 								 const
unsigned int index); ' Returns a pointer to the indexed Conf4CSection.
C4CF : a Conf4CFile
INDEX : the index of the desired Conf4CSection
_Returns_ : NULL is the index is invalid

conf4c_file_get_section_by_type ()
----------------------------------

   ` *Note Conf4CSection::	conf4c_file_get_section_by_type	(const
*Note Conf4CFile:: *c4cf, 							 const char *type); ' Returns a
pointer to the identified Conf4CSection.
C4CF : a Conf4CFile
TYPE : a string identifying the section type
_Returns_ : NULL if the specified section type is not found

Conf4CSection
=============

   Conf4CSection - A container which manages instances of a Section type

Synopsis
========

   ` #include "conf4cstor.h" #include "conf4cvector.h"

   struct *Note Conf4CSection: struct_conf4csection;

   *Note Conf4CSection:: *	*Note conf4c_section_new::
(const char *type, 				    	 	 	 const int initial_capacity); int		*Note
conf4c_section_add_stor:: 		(*Note Conf4CSection:: *csect,
*Note Conf4CStor:: *cs); *Note Conf4CStor:: *	*Note
conf4c_section_get_stor_by_name::		(const *Note Conf4CSection:: *csect,
const char *name); *Note Conf4CStor:: *	*Note
conf4c_section_get_stor_by_index::	(const *Note Conf4CSection:: *csect,
const unsigned int index); int 		*Note
conf4c_section_get_stor_count::		(const *Note Conf4CSection::
*csect); char *		*Note conf4c_section_get_type::			(const *Note
Conf4CSection:: *csect); char *		*Note
conf4c_section_get_stor_name:: 		(const *Note Conf4CSection::
*csect, 							 const int index); int		*Note
conf4c_section_get_stor_index::		(const *Note Conf4CSection::
*csect, 							 const char *name); '

Description
===========

   Conf4CSection contains all instances of a specific section type.  A
Conf4CSection is also identified by it's type.

Details
=======

struct Conf4CSection
--------------------

   ` struct Conf4CSection; ' This should not be accessed directly.  Use
the accessor functions below.

conf4c_section_new ()
---------------------

   ` *Note Conf4CSection:: *	conf4c_section_new	(const char *type,
	 const int initial_capacity); '
TYPE : A string indicating the section-type
INITIAL_CAPACITY : The number of *Note Conf4CStor:: instances to allocate for, initially
_Returns_ : a Conf4CSection

conf4c_section_add_stor ()
--------------------------

   ` int	conf4c_section_add_stor (*Note Conf4CSection:: csect,
*Note Conf4CStor:: *cs); ' Add a *Note Conf4CStor:: to a *Note
Conf4CSection::.
CSECT : a *Note Conf4CSection::
CS : the *Note Conf4CStor:: to add
_Returns_ : an int indicating success or failure; 1 = success, 0 = failure

conf4c_section_get_stor_by_name ()
----------------------------------

   ` Conf4CStor * conf4c_section_get_stor_by_name (const Conf4CSection
*csect, const char *name); ' Retrieve a Conf4CStor by the stor's name.
CSECT: a Conf4CSection
NAME: the name of the Conf4CStor instance
_Returns_: NULL if the named Conf4CStor is not found

conf4c_section_get_stor_by_index ()
-----------------------------------

   ` Conf4CStor * conf4c_section_get_stor_by_index (const Conf4CSection
*csect, const unsigned int index); ' Retrieve a Conf4CStor by the
stor's index.
CSECT: a Conf4CSection
INDEX: the index of the Conf4CStor instance within the collection
_Returns_: NULL if the index is invalid

conf4c_section_get_stor_count ()
--------------------------------

   ` int conf4c_section_get_stor_count (const Conf4CSection *csect); '
CSECT: a Conf4CSection
_Returns_: the number of Conf4CStor instances stored within the Conf4CSection

conf4c_section_get_type ()
--------------------------

   ` char * conf4c_section_get_type (const Conf4CSection *csect); '
CSECT : a Conf4CSection
_Returns_ : the type of the Conf4CSection

conf4c_section_get_stor_name ()
-------------------------------

   ` char * conf4c_section_get_stor_name (const Conf4CSection *csect,
const int index); '
CSECT: a Conf4CSection
INDEX: the index of a Conf4CStor within the collection
_Returns_: the name of the indicated Conf4CStor instance or NULL if index is invalid

conf4c_section_get_stor_index ()
--------------------------------

   ` int conf4c_section_get_stor_index (const Conf4CSection *csect,
const char *name); '
CSECT: a Conf4CSection
NAME: the name of the Conf4CStor instance
_Returns_: the index of the named Conf4CStor or -1 if the instance is not found

Conf4CStor
==========

   Conf4CStor - A collection of Conf4CValue instances representing a
specific section-type instance

Synopsis
========

   ` #include "conf4cvalue.h" #include "conf4cvector.h"

   struct *Note Conf4CStor: struct_conf4cstor;

   *Note Conf4CStor:: * 	*Note conf4c_stor_new:: 		(const
char *name, 						 const int initial_capacity); int		*Note
conf4c_stor_add_conf4cvalue:: 	(*Note Conf4CStor:: *cs,
*Note Conf4CValue:: *cv); char *		*Note conf4c_stor_get_name::
(const *Note Conf4CStor:: *cs); int		*Note conf4c_stor_get_value_count::
(const *Note Conf4CStor:: *cs); char *		*Note
conf4c_stor_get_value_name:: 	(const *Note Conf4CStor:: *cs,
int index); *Note Conf4CValue:: *	*Note conf4c_stor_get_value_by_name::
(const *Note Conf4CStor:: *cs, 						 const char *name); *Note
Conf4CValue:: *	*Note conf4c_stor_get_value_by_index::
(const *Note Conf4CStor:: *cs, 						 const unsigned int index);
int		*Note conf4c_stor_get_value_index:: 	(const *Note Conf4CStor:: *cs,
const char *name); '

Description
===========

   Sections of a configuration file are recognized as name / value
pairs existing between '<section_type instance_name></section_type>'
pairs.  A Conf4CStor maintains the name / value pairs which exist
between the opening and closing section tags and is identified by
'instance_name'.

Details
=======

struct Conf4CStor
-----------------

   ` struct Conf4CStor; ' This should not be accessed directly.  Use
the accessor functions below.

conf4c_stor_new ()
------------------

   ` Conf4CStor * conf4c_stor_new (const char *instance_name, const int
initial_capacity); ' Creates a new Conf4CStor struct.

conf4c_stor_add_conf4cvalue ()
------------------------------

   ` int conf4c_stor_add_conf4cvalue (Conf4CStor *cs, Conf4CValue cv); '
Add a Conf4CValue to an instance of Conf4CStor.
CS: the Conf4CStor instance to add the Conf4CValue to
CV: a Conf4CValue
_Returns_: an int value indicating success or failure; 1 = success and 0 = failure

conf4c_stor_get_name ()
-----------------------

   ` char * conf4c_stor_get_name (const Conf4CStor *cs); ' Return the
'instance_name' of the Conf4CStor.
CS: a Conf4CStor
_Returns_: the 'instance_name' of the specified Conf4CStor

conf4c_stor_get_value_count ()
------------------------------

   ` int conf4c_stor_get_value_count (const Conf4CStor *cs); ' Returns
the number of name / value pairs contained in the Conf4CStor.
CS: a Conf4CStor
_Returns_: the number of stored Conf4CValue instances

conf4c_stor_get_value_name ()
-----------------------------

   ` char * conf4c_stor_get_value_name (const Conf4CStor *cs, int
index); ' Fetch the name of a Conf4CValue instance contained within a
Conf4CStor
CS: a Conf4CStor
INDEX: an integer identifying which Conf4CValue instance to reference
_Returns_: the name of the specified Conf4CValue or NULL if the index is invalid

conf4c_stor_get_value_by_index ()
---------------------------------

   ` Conf4CValue * conf4c_stor_get_value_by_index (const Conf4CStor
*cs, const unsigned int index); ' Retrieve the Conf4CValue located at
index 'index'.
CS: a Conf4CStor
INDEX: an integer identifying which Conf4CValue instance to return
_Returns_: the Conf4CValue located at 'index' or NULL if the index is invalid

conf4c_stor_get_value_by_name ()
--------------------------------

   ` Conf4CValue * conf4c_stor_get_value_by_name (const Conf4CStor *cs,
const char *name); ' Retrieve the Conf4CValue named 'name'.
CS : a Conf4CStor
NAME : the 'name' portion of a name / value pair
_Returns_ : a Conf4CValue instance or NULL if no Conf4CValue is found with name 'name'.

conf4c_stor_get_value_index ()
------------------------------

   ` int conf4c_stor_get_value_index (const Conf4CStor *cs, const char
*name); ' Obtain the index of the Conf4CValue identified by 'name'.
CS: a Conf4CStor
NAME: the 'name' portion of a name / value pair
_Returns_: the index of the specified Conf4CValue or -1 if the Conf4CValue is not found

Conf4CValue
===========

   Conf4CValue - Struct for management and storage of a single name /
value pair

Synopsis
========

   ` struct *Note Conf4CValue: struct_conf4cvalue;

   Conf4CValue * 	*Note conf4c_value_new:: (const char *name, const char
*value); Conf4CValue * 	*Note conf4c_value_update:: (*Note Conf4CValue::
*cv, const char *value); Conf4CValue * 	*Note conf4c_value_get_name::
(const *Note Conf4CValue:: *); Conf4CValue * 	*Note
conf4c_value_get_value:: (const *Note Conf4CValue:: *); '

Description
===========

   The Conf4CValue struct encapsulates a name / value pair of a
configuration file.

Details
=======

struct Conf4CValue
------------------

   ` struct Conf4CValue; ' This should not be accessed directly.  Use
the accessor functions below.

conf4c_value_new ()
-------------------

   ` Conf4CValue * conf4c_value_new (const char *name, const char
*value); ' Creates a new Conf4CValue struct.

conf4c_value_update ()
----------------------

   ` Conf4CValue * conf4c_value_update (Conf4CValue *cv, const char
*value); ' Updates the value portion of the specified name / value pair.
CV: a Conf4CValue
VALUE: a string configuration value
_Returns_: the updated Conf4CValue

conf4c_value_get_name ()
------------------------

   ` char * conf4c_value_get_name (const Conf4CValue *cv); ' Retrieves
the name of the name / value pair.
CV: a Conf4CValue
_Returns_: The name of the stored name / value pair.

conf4c_value_get_value ()
-------------------------

   ` char * conf4c_value_get_value (const Conf4CValue *cv); ' Retrieves
the value of the name / value pair.
CV: a Conf4CValue
_Returns_: The string value of the stored name / value pair.

Index
*****

Table of Contents
*****************


Conf4C Tutorial & API Reference

Conf4C Overview
  Introduction
  Configuration File Format
  Mailing List / Bug Reports
  Common Questions

Conf4C Tutorial
  Example Source
  Source Walkthrough
  Example Configuration File

Conf4C Reference
  Conf4CReader
  Conf4CParser
  Conf4CFileAttrib
  Conf4CFile
  Conf4CSection
  Conf4CStor
  Conf4CValue

Index


