=pod

=head1 NAME

librrd - RRD library functions

=head1 DESCRIPTION

B<librrd> contains most of the functionality in B<RRDTool>.  The command
line utilities and language bindings are often just wrappers around the
code contained in B<librrd>.

This manual page documents the B<librrd> API.

B<NOTE:> This document is a work in progress, and should be considered
incomplete as long as this warning persists.  For more information about
the B<librrd> functions, always consult the source code.

=head1 CORE FUNCTIONS

=over 4

=item B<rrd_dump_cb_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)>

In some situations it is necessary to get the output of C<rrd_dump> without
writing it to a file or the standard output. In such cases an application
can ask B<rrd_dump_cb_r> to call an user-defined function each time there
is output to be stored somewhere. This can be used, to e.g. directly feed
an XML parser with the dumped output or transfer the resulting string
in memory.

The arguments for B<rrd_dump_cb_r> are the same as for B<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 B<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 B<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 B<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 B<rrd_dump_cr_r> respectively.

=item B<rrd_fetch_cb_register(rrd_fetch_cb_t c)>

If your data does not reside in rrd files, but you would like to draw charts using the
rrd_graph functionality, you can supply your own rrd_fetch function and register it using
the B<rrd_fetch_cb_register> function.

The argument signature and api must be the same of the callback function must be aequivalent to the on of B<rrd_fetch_fn> in 
F<rrd_fetch.c>.

To activate the callback function you can use the pseudo filename F<cb//>I<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.

=back

=head1 UTILITY FUNCTIONS

=over 4

=item B<rrd_random()>

Generates random numbers just like random().  This further ensures that
the random number generator is seeded exactly once per process.

=item B<rrd_strtodbl>

an rrd aware string to double converter which sets rrd_error in if there is a problem
and uses the return code exclusively for conversion status reporting.

=item B<rrd_strtod>

works like normal strtod, but it is locale independent (and thread safe)

=item B<rrd_snprintf>

works  like normal snprintf but it is locale independent (and thread safe)

=item B<rrd_add_ptr(void ***dest, size_t *dest_size, void *src)>

Dynamically resize the array pointed to by C<dest>.  C<dest_size> is a
pointer to the current size of C<dest>.  Upon successful realloc(), the
C<dest_size> is incremented by 1 and the C<src> pointer is stored at the
end of the new C<dest>.  Returns 1 on success, 0 on failure.

    type **arr = NULL;
    type *elem = "whatever";
    size_t arr_size = 0;
    if (!rrd_add_ptr(&arr, &arr_size, elem))
        handle_failure();

=item B<rrd_add_ptr_chunk(void ***dest, size_t *dest_size, void *src, size_t *alloc, size_t chunk)>

Like C<rrd_add_ptr>, except the destination is allocated in chunks of
C<chunk>.  C<alloc> points to the number of entries allocated, whereas
C<dest_size> points to the number of valid pointers.  If more pointers are
needed, C<chunk> pointers are allocated and C<alloc> is increased
accordingly.  C<alloc> must be E<gt>= C<dest_size>.

This method improves performance on hosts with expensive C<realloc()>.

=item B<rrd_add_strdup(char ***dest, size_t *dest_size, char *src)>

Like C<rrd_add_ptr>, except adds a C<strdup> of the source string.

    char **arr = NULL;
    size_t arr_size = NULL;
    char *str  = "example text";
    if (!rrd_add_strdup(&arr, &arr_size, str))
        handle_failure();

=item B<rrd_add_strdup_chunk(char ***dest, size_t *dest_size, char *src, size_t *alloc, size_t chunk)>

Like C<rrd_add_strdup>, except the destination is allocated in chunks of
C<chunk>.  C<alloc> points to the number of entries allocated, whereas
C<dest_size> points to the number of valid pointers.  If more pointers are
needed, C<chunk> pointers are allocated and C<alloc> is increased
accordingly.  C<alloc> must be E<gt>= C<dest_size>.

=item B<rrd_free_ptrs(void ***src, size_t *cnt)>

Free an array of pointers allocated by C<rrd_add_ptr> or
C<rrd_add_strdup>.  Also frees the array pointer itself.  On return, the
source pointer will be NULL and the count will be zero.

    /* created as above */
    rrd_free_ptrs(&arr, &arr_size);
    /* here, arr == NULL && arr_size == 0 */

=item B<rrd_mkdir_p(const char *pathname, mode_t mode)>

Create the directory named C<pathname> including all of its parent
directories (similar to C<mkdir -p> on the command line - see L<mkdir(1)> for
more information). The argument C<mode> specifies the permissions to use. It
is modified by the process's C<umask>. See L<mkdir(2)> for more details.

The function returns 0 on success, a negative value else. In case of an error,
C<errno> is set accordingly. Aside from the errors documented in L<mkdir(2)>,
the function may fail with the following errors:

=over 4

=item B<EINVAL>

C<pathname> is C<NULL> or the empty string.

=item B<ENOMEM>

Insufficient memory was available.

=item B<any error returned by L<stat(2)>>

=back

In contrast to L<mkdir(2)>, the function does B<not> fail if C<pathname>
already exists and is a directory.

=item B<rrd_scaled_duration (const char * token, unsigned long divisor, unsigned long * valuep)>

Parse a token in a context where it contains a count (of seconds or
PDP instances), or a duration that can be converted to a count by
representing the duration in seconds and dividing by some scaling
factor.  For example, if a user would natively express a 3 day archive
of samples collected every 2 minutes, the sample interval can be
represented by C<2m> instead of C<120>, and the archive duration by
C<3d> (to be divided by 120) instead of C<2160> (3*24*60*60 / 120).
See more examples in L<rrdcreate/"STEP, HEARTBEAT, and Rows As Durations">.

C<token> must be a number with an optional single-character suffix
encoding the scaling factor:

=over 4

=item C<s>

indicates seconds

=item C<m>

indicates minutes.  The value is multiplied by 60.

=item C<h>

indicates hours.  The value is multiplied by 3600 (or C<60m>).

=item C<d>

indicates days.  The value is multiplied by 86400 (or C<24h>).

=item C<w>

indicates weeks.  The value is multiplied by 604800 (or C<7d>).

=item C<M>

indicates months.  The value is multiplied by 2678400 (or C<31d>).
(Note this factor accommodates the maximum number of days in a month.)

=item C<y>

indicates years.  The value is multiplied by 31622400 (or C<366d>).
(Note this factor accommodates leap years.)

=back

C<divisor> is a positive value representing the duration in seconds of
an interval that the desired result counts.

C<valuep> is a pointer to where the decoded value will be stored if
the conversion is successful.

The initial characters of C<token> must be the base-10 representation
of a positive integer, or the conversion fails.

If the remainder C<token> is empty (no suffix), it is a count and no
scaling is performed.

If C<token> has one of the suffixes above, the count is multiplied to
convert it to a duration in seconds.  The resulting number of seconds
is divided by C<divisor> to produce a count of intervals each of
duration C<divisor> seconds.  If division would produce a remainder
(e.g., C<5m> (300 seconds) divided by C<90s>), the conversion is
invalid.

If C<token> has unrecognized trailing characters the conversion fails.

The function returns a null pointer if the conversion was successful
and C<valuep> has been updated to the scaled value.  On failure, it
returns a text diagnostic suitable for use in user error messages.

=back

=head1 CLIENT FUNCTIONS

The following functions are used to connected to an rrdcached instance,
either via a unix or inet address, and create, update, or gather statistics
about a specified RRD database file.

All of the following functions are specified in the C<rrd_client.h>
header file.

=over 4

=item B<rrdc_connect(const char *daemon_addr>

Connect to a running rrdcached instance, specified via C<daemon_addr>.

=item B<rrdc_is_connected(const char *daemon_addr)>

Return a boolean int to determine if the client is connected to the
rrdcache daemon specified by the C<daemon_addr> parameter.

=item B<rrdc_is_any_connected>

Return a boolean int if any daemon connections are connected.

=item B<rrdc_disconnect>

Disconnect gracefully from all present daemon connections.

=item B<rrdc_update(const char *filename, int values_num, const char * const *values)>

Update the RRD C<filename> via the rrdcached. Where C<values_num>
is the number of values to update and C<values> are the new values to add.

=item B<rrdc_info(const char *filename)>

Grab rrd info of the RRD C<filename> from the connected cache daemon.
This function returns an rrd_info_t structure of the following format:

    typedef struct rrd_blob_t {
        unsigned long size; /* size of the blob */
        unsigned char *ptr; /* pointer */
    } rrd_blob_t;

    typedef enum rrd_info_type { RD_I_VAL = 0,
        RD_I_CNT,
        RD_I_STR,
        RD_I_INT,
        RD_I_BLO
    } rrd_info_type_t;

    typedef union rrd_infoval {
        unsigned long u_cnt;
        rrd_value_t u_val;
        char     *u_str;
        int       u_int;
        rrd_blob_t u_blo;
    } rrd_infoval_t;

    typedef struct rrd_info_t {
        char     *key;
        rrd_info_type_t type;
        rrd_infoval_t value;
        struct rrd_info_t *next;
    } rrd_info_t;

=item B<rrdc_last(const char *filename)>

Grab the unix epoch of the last time RRD C<filename> was updated.

=item B<rrdc_first(const char *filename, int rraindex)>

Get the first value of the first sample of the RRD C<filename>,
of the C<rraindex> RRA (Round Robin Archive) index number.
The RRA index number can be determined by pulling the rrd_info_t
off the RRD.

=item B<rrdc_create(const char *filename, unsigned long pdp_step, time_t last_up, int no_overwrite, int argc, const char **argv)>

Create RRD database of path C<filename>.
The RRD will have a step size of C<pfp_step>, the unix epoch timestamp to
start collecting data from. The number of data sources and RRAs C<argc> and
the definitions of the data sources and RRAs C<argv>. Lastly whether or
not to overwrite an existing RRD if one is found with the same
filename; C<no_overwrite>.

=item B<rrdc_create_r2(const char *filename, unsigned long pdp_step, time_t last_up, int no_overwrite, const char **sources, const char *template, int argc, const char **argv)>

Create and RRD database in the daemon. B<rrdc_create_r2> has the same
parameters as B<rrdc_create> with two added parameters of; C<sources>
and C<template>.

where C<template> is the file path to a RRD file template, with, the
form defined in B<rrdcreate>(1),

The C<sources> parameter defines series of file paths with data defined,
to prefill the RRD with. See B<rrdcreate>(1) for more details.

=item B<rrdc_flush(const char *filename)>

flush the currently RRD cached in the daemon specified via C<filename>.

=item B<rrdc_forget(const char *filename)>

Drop the cached data for the RRD file specified via C<filename>.

=item B<rrdc_flush_if_daemon(const char *daemon_addr, const char *filename)>

Flush the specified RRD given by C<filename> only if the daemon
C<daemon_addr> is up and connected.

=item B<rrdc_fetch(const char *filename, const char *cf, time_t *ret_start, time_t *ret_end, unsigned long *ret_step, unsigned long *ret_ds_num, char ***ret_ds_names, rrd_value_t **ret_data)>

Perform a fetch operation on the specified RRD Database given be C<filename>,
where C<cf> is the consolidation function, C<ret_start> is the start time
given by unix epoch, C<ret_end> is the endtime. C<ret_step> is the step size
in seconds, C<ret_ds_num> the number of data sources in the RRD, C<ret_ds_names>
the names of the data sources, and a pointer to an rrd_value_t object to shlep the
data.

=item B<rrdc_stats_get(rrdc_stats_t **ret_stats)>

Get stats from the connected daemon, via a linked list of the following structure:

    struct rrdc_stats_s {
        const char *name;
        uint16_t type;
        #define RRDC_STATS_TYPE_GAUGE   0x0001
        #define RRDC_STATS_TYPE_COUNTER 0x0002
        uint16_t flags;
        union {
            uint64_t counter;
            double   gauge;
        } value;
        struct rrdc_stats_s *next;
    };
    typedef struct rrdc_stats_s rrdc_stats_t;

=item B<rrdc_stats_free(rrdc_stats_t *ret_stats)>

Free the stats struct allocated via B<rrdc_stats_get>.

=back

=head2 SEE ALSO

=over

B<rrcached>(1) B<rrdfetch>(1) B<rrdinfo>(1) B<rrdlast>(1) B<rrdcreate>(1) B<rrdupdate>(1) B<rrdlast>(1)

=back

=head1 AUTHOR

RRD Contributors <rrd-developers@lists.oetiker.ch>