Configuration file backend, v 0.0.0
===================================
(c) 2000 Red Hat, Inc.
Programmed by Bernhard "Bero" Rosenkraenzer <bero@redhat.com>

What is it?
===========
rhcfile is a library for accessing and creating config files - both locally
and over the network - even both of them at the same time (for network wide
settings with local additions).
It currently doesn't have all the features the final version will have - but
the ones that are there will remain there and unchanged API-wise, and already
make some sense.


What does it run on?
====================
rhcfile is developed on Red Hat Linux. It should work with any other unix
variant with little or no changes.


How do I use it?
================
Any program reading a config file using rhcfile will automatically check
/etc/config.cf for the real location of config files - an example entry in
config.cf would be

httpd.conf {
	http://configserver/httpd.conf+file:/etc/httpd/local.additions
	file:/etc/httpd/httpd.conf
}

Meaning: httpd.conf is the content of http://configserver/httpd.conf with the
content of the local file /etc/httpd/local.additions added.
If this isn't possible (configserver can't be accessed or
/etc/httpd/local.additions doesn't exist), the second choice (the local file
/etc/httpd/httpd.conf) will be used. You can add an infinite number of
fallbacks - the first available one will be used.


How do I get a program to use rhcfile?
======================================
Getting a program that uses the "normal" functions to access its files to use
rhcfile is relatively easy.
Here's a list of normal calls and their rhcfile equivalent (the parameters
are generally the same):
	open		Open
	creat		Creat
	read		Read
	write		Write
	close		Close

	FILE		CFGFILE
	fopen		Fopen
	fgetc		Fgetc
	fputc		Fputc
	fputs		Fputs
	fprintf		Fprintf
	vfprintf	Vfprintf
	fclose		Fclose

For example, change this:
	int fd;
	fd=open("/etc/config.file", O_RDONLY);
	if(fd<0) {
		perror("Error opening config file");
		exit(1);
	}
	read(fd, buf, 1024);
	close(fd);
to this:
	int fd;
	fd=Open("/etc/config.file", O_RDONLY);
	if(fd<0) {
		perror("Error opening config file");
		exit(1);
	}
	Read(fd, buf, 1024);
	Close(fd);

The test programs in test/ should give you an impression of what it currently
does.

If you don't want to change the calls, you can just add the line
#include <rhcfile/configfile.h>
This file adds defines that should take care of the modifications.


Which protocols are supported?
==============================
At this time, rhcfile supports file: (accessing local files) and http:
(http, read-only); more protocols such as cvs: (accessing a CVS repository,
including versioning transparency) and ldap: (config files stored in an LDAP
server) will be added soon.
Currently, only read access is fully supported.


Does rhcfile provide any other functions?
=========================================
rhcfile provides some functions not mentioned here; however, they're mostly
for internal use and should not be used by other programs at this time
(their API may be changed or they may disappear completely in future versions).
If you need to use them nevertheless, you're probably better off copying them
from the source files than depending on their existence in rhcfile.

For some higher level functions for accessing config files (such as
reading a file into a doubly-linked list of strings) using rhcfile, look at
rhclib.


I've found a bug, need a feature, ...
=====================================
Send a bug report (preferably along with a patch that fixes it ;) ) to
bero@redhat.com.

