librrd contains most of the functionality in RRDTool. The command line utilities and language bindings are often just wrappers around the code contained in librrd.
This manual page documents the librrd API.
NOTE: This document is a work in progress, and should be considered incomplete as long as this warning persists. For more information about the librrd functions, always consult the source code.
The arguments for rrd_dump_cb_r are the same as for rrd_dump_opt_r except that the output filename parameter is replaced by the user-defined callback function and an additional parameter for the callback function that is passed untouched, i.e. to store information about the callback state needed for the user-defined callback to function properly.
Recent versions of rrd_dump_opt_r internally use this callback mechanism to write their output to the file provided by the user.
size_t rrd_dump_opt_cb_fileout(
const void *data,
size_t len,
void *user)
{
return fwrite(data, 1, len, (FILE *)user);
}
The associated call for rrd_dump_cb_r looks like
res = rrd_dump_cb_r(filename, opt_header,
rrd_dump_opt_cb_fileout, (void *)out_file);
where the last parameter specifies the file handle rrd_dump_opt_cb_fileout should write to. There's no specific condition for the callback to detect when it is called for the first time, nor for the last time. If you require this for initialization and cleanup you should do those tasks before and after calling rrd_dump_cr_r respectively.
The argument signature and api must be the same of the callback function must be aequivalent to the on of rrd_fetch_fn in rrd_fetch.c.
To activate the callback function you can use the pseudo filename cb//free_form_text.
Note that rrdtool graph will not ask the same rrd for data twice. It determines this by building a key out of the values supplied to the fetch function. If the values are the same, the previous answer will be used.
type **arr = NULL;
type *elem = "whatever";
size_t arr_size = 0;
if (!rrd_add_ptr(&arr, &arr_size, elem))
handle_failure();
This method improves performance on hosts with expensive "realloc()".
char **arr = NULL;
size_t arr_size = NULL;
char *str = "example text";
if (!rrd_add_strdup(&arr, &arr_size, str))
handle_failure();
/* created as above */
rrd_free_ptrs(&arr, &arr_size);
/* here, arr == NULL && arr_size == 0 */
The function returns 0 on success, a negative value else. In case of an error, "errno" is set accordingly. Aside from the errors documented in mkdir(2), the function may fail with the following errors:
In contrast to mkdir(2), the function does not fail if "pathname" already exists and is a directory.
"token" must be a number with an optional single-character suffix encoding the scaling factor:
"divisor" is a positive value representing the duration in seconds of an interval that the desired result counts.
"valuep" is a pointer to where the decoded value will be stored if the conversion is successful.
The initial characters of "token" must be the base-10 representation of a positive integer, or the conversion fails.
If the remainder "token" is empty (no suffix), it is a count and no scaling is performed.
If "token" has one of the suffixes above, the count is multipled to convert it to a duration in seconds. The resulting number of seconds is divided by "divisor" to produce a count of intervals each of duration "divisor" seconds. If division would produce a remainder (e.g., "5m" (300 seconds) divided by "90s"), the conversion is invalid.
If "token" has unrecognized trailing characters the conversion fails.
The function returns a null pointer if the conversion was successful and "valuep" has been updated to the scaled value. On failure, it returns a text diagnostic suitable for use in user error messages.
RRD Contributors <rrd-developers@lists.oetiker.ch>