This readme document explains the use of the rrd wrapper functions defined
in rrdwrap.c, designed to simplify calls to key functions of the rrd library.

Please note, before using this set of functions, you should be familiar with
the use of the rrd tool, or at the very least, you should have completed the
rrd tutorials which can be found at:
 http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/tutorial/

This is a set of functions which wrap key functions of the rrd c library so that
they can be called in a similar way to their command line equivalents. The rrd
library functions concerned are:

 rrd_create, rrd_update, rrd_graph, rrd_restore, rrd_dump, rrd_tune,

all of which are called using command line type argument vectors. Formatting
of these argument vectors requires a certain amount of string processing
and administration. The wrapper functions are designed to take care of the
administration so that anybody who has been through the tutorials and can format
a string in C, can use the rrd tool c libraries. All you need to do is include the
rrdwrap.c and rrdwrap.h files in your project (as well as all of the usual header
files required by the rrd tool libraries) and then call the wrapper functions which
in turn, will call the original rrd functions after taking care of the necessary
administration and creating the appropriate argument vector.

The wrappers are defined as:

 	int wrap_rrd_create(char *argstr);

 	int wrap_rrd_update(char *argstr);

 	int wrap_rrd_graph(char *argstr);

 	int wrap_rrd_restore(char *argstr);

 	int wrap_rrd_dump(char *argstr);

 	int wrap_rrd_tune(char *argstr);

The argument string (argstr) passed to these wrapper functions should be in exactly
the same format as the command line instruction for the compiled rrd tool.


For example, where we might have a command line instruction of the form:

rrdtool create rrdname.rrd --start timestamp --step seconds DS:source:...etc

the create wrapper is called as:
 wrap_rrd_create(argstr);

where argstr is a pointer to a string, formatted as:
 rrdname.rrd --start timestamp --step seconds DS:source:...etc

or, using the first example of the first tutorial,
rrdtool create test.rrd --start 920804400 DS:speed:COUNTER:600:U:U RRA:AVERAGE:0.5:1:24 RRA:AVERAGE:0.5:6:10

the equivalent call to the create wrapper could be:
wrap_rrd_create("test.rrd --start 920804400 DS:speed:COUNTER:600:U:U RRA:AVERAGE:0.5:1:24 RRA:AVERAGE:0.5:6:10");

The same applies to all of the wrappers. It eliminates the need to worry about
optind and opterr, and it returns the same int returned by rrd_create for error
checking. The argument vector is automatically freed after the function call
to ensure that there are no memory leaks through repeated calls to the wrapper
functions.

I am running it on both Linux and Windows NT and all seems to be well so far.


Things which you need to keep in mind which will be obvious to a programmer who
has done a lot of work with strings and arguement vectors in c, the space character
is used to indicate a new arguement. If it is not intended for the space to indicate
a new arguement, as in the example below for the legend "Line A", that part of the
argument must be in quotes:

rrdtool graph all1.gif -s 978300600 -e 978304200 -h 400 DEF:linea=all.rrd:a:AVERAGE LINE3:linea#FF0000:"Line A"

The argstr could be formatted via a call to sprintf of the form:
sprintf(argstr, "all1.gif -s 978300600 -e 978304200 -h 400 DEF:linea=all.rrd:a:AVERAGE LINE3:linea#FF0000:\"Line A\" " );

and the wrapper function would then be called as:
  wrap_rrd_graph(argstr);

in the sprintf call, the backslash preceding the quote character is required so that
the string is formatted as:
 all1.gif -s 978300600 -e 978304200 -h 400 DEF:linea=all.rrd:a:AVERAGE LINE3:linea#FF0000:"Line A"

rather than:
 all1.gif -s 978300600 -e 978304200 -h 400 DEF:linea=all.rrd:a:AVERAGE LINE3:linea#FF0000:Line A

which would result in the A part of the legend being ignored.

If you are having difficulty with making these functions work, check the format
of the argstr string, prior to the call to the wrapper function, with a printf
call of the form:
 printf("%s", argstr);

try the exact same call from the command line, you will probably find that this
solves most problems.


Contributed by Antony Clothier, December 2001.