1librrd(3)                           rrdtool                          librrd(3)
2
3
4

NAME

6       librrd - RRD library functions
7

DESCRIPTION

9       librrd contains most of the functionality in RRDtool.  The command line
10       utilities and language bindings are often just wrappers around the code
11       contained in librrd.
12
13       This manual page documents the librrd API.
14
15       NOTE: This document is a work in progress, and should be considered
16       incomplete as long as this warning persists.  For more information
17       about the librrd functions, always consult the source code.
18

CORE FUNCTIONS

20       rrd_dump_cb_r(char *filename, int opt_header, rrd_output_callback_t cb,
21       void *user)
22           In some situations it is necessary to get the output of "rrd_dump"
23           without writing it to a file or the standard output. In such cases
24           an application can ask rrd_dump_cb_r to call a user-defined
25           function each time there is output to be stored somewhere. This can
26           be used, to e.g. directly feed an XML parser with the dumped output
27           or transfer the resulting string in memory.
28
29           The arguments for rrd_dump_cb_r are the same as for rrd_dump_opt_r
30           except that the output filename parameter is replaced by the user-
31           defined callback function and an additional parameter for the
32           callback function that is passed untouched, i.e. to store
33           information about the callback state needed for the user-defined
34           callback to function properly.
35
36           Recent versions of rrd_dump_opt_r internally use this callback
37           mechanism to write their output to the file provided by the user.
38
39               size_t rrd_dump_opt_cb_fileout(
40                   const void *data,
41                   size_t len,
42                   void *user)
43               {
44                   return fwrite(data, 1, len, (FILE *)user);
45               }
46
47           The associated call for rrd_dump_cb_r looks like
48
49               res = rrd_dump_cb_r(filename, opt_header,
50                   rrd_dump_opt_cb_fileout, (void *)out_file);
51
52           where the last parameter specifies the file handle
53           rrd_dump_opt_cb_fileout should write to. There's no specific
54           condition for the callback to detect when it is called for the
55           first time, nor for the last time. If you require this for
56           initialization and cleanup you should do those tasks before and
57           after calling rrd_dump_cb_r respectively.
58
59       rrd_fetch_cb_register(rrd_fetch_cb_t c)
60           If your data does not reside in rrd files, but you would like to
61           draw charts using the rrd_graph functionality, you can supply your
62           own rrd_fetch function and register it using the
63           rrd_fetch_cb_register function.
64
65           The argument signature and api must be the same of the callback
66           function and must be equivalent to the one of rrd_fetch_fn in
67           rrd_fetch.c.
68
69           To activate the callback function you can use the pseudo filename
70           cb//free_form_text.
71
72           Note that rrdtool graph will not ask the same rrd for data twice.
73           It determines this by building a key out of the values supplied to
74           the fetch function. If the values are the same, the previous answer
75           will be used.
76

UTILITY FUNCTIONS

78       rrd_random()
79           Generates random numbers just like random().  This further ensures
80           that the random number generator is seeded exactly once per
81           process.
82
83       rrd_strtodbl
84           an rrd aware string to double converter which sets rrd_error in if
85           there is a problem and uses the return code exclusively for
86           conversion status reporting.
87
88       rrd_strtod
89           works like normal strtod, but it is locale independent (and thread
90           safe)
91
92       rrd_snprintf
93           works  like normal snprintf but it is locale independent (and
94           thread safe)
95
96       rrd_add_ptr(void ***dest, size_t *dest_size, void *src)
97           Dynamically resize the array pointed to by "dest".  "dest_size" is
98           a pointer to the current size of "dest".  Upon successful
99           realloc(), the "dest_size" is incremented by 1 and the "src"
100           pointer is stored at the end of the new "dest".  Returns 1 on
101           success, 0 on failure.
102
103               type **arr = NULL;
104               type *elem = "whatever";
105               size_t arr_size = 0;
106               if (!rrd_add_ptr(&arr, &arr_size, elem))
107                   handle_failure();
108
109       rrd_add_ptr_chunk(void ***dest, size_t *dest_size, void *src, size_t
110       *alloc, size_t chunk)
111           Like "rrd_add_ptr", except the destination is allocated in chunks
112           of "chunk".  "alloc" points to the number of entries allocated,
113           whereas "dest_size" points to the number of valid pointers.  If
114           more pointers are needed, "chunk" pointers are allocated and
115           "alloc" is increased accordingly.  "alloc" must be >= "dest_size".
116
117           This method improves performance on hosts with expensive
118           "realloc()".
119
120       rrd_add_strdup(char ***dest, size_t *dest_size, char *src)
121           Like "rrd_add_ptr", except adds a "strdup" of the source string.
122
123               char **arr = NULL;
124               size_t arr_size = NULL;
125               char *str  = "example text";
126               if (!rrd_add_strdup(&arr, &arr_size, str))
127                   handle_failure();
128
129       rrd_add_strdup_chunk(char ***dest, size_t *dest_size, char *src, size_t
130       *alloc, size_t chunk)
131           Like "rrd_add_strdup", except the destination is allocated in
132           chunks of "chunk".  "alloc" points to the number of entries
133           allocated, whereas "dest_size" points to the number of valid
134           pointers.  If more pointers are needed, "chunk" pointers are
135           allocated and "alloc" is increased accordingly.  "alloc" must be >=
136           "dest_size".
137
138       rrd_free_ptrs(void ***src, size_t *cnt)
139           Free an array of pointers allocated by "rrd_add_ptr" or
140           "rrd_add_strdup".  Also frees the array pointer itself.  On return,
141           the source pointer will be NULL and the count will be zero.
142
143               /* created as above */
144               rrd_free_ptrs(&arr, &arr_size);
145               /* here, arr == NULL && arr_size == 0 */
146
147       rrd_mkdir_p(const char *pathname, mode_t mode)
148           Create the directory named "pathname" including all of its parent
149           directories (similar to "mkdir -p" on the command line - see
150           mkdir(1) for more information). The argument "mode" specifies the
151           permissions to use. It is modified by the process's "umask". See
152           mkdir(2) for more details.
153
154           The function returns 0 on success, a negative value else. In case
155           of an error, "errno" is set accordingly. Aside from the errors
156           documented in mkdir(2), the function may fail with the following
157           errors:
158
159           EINVAL
160               "pathname" is "NULL" or the empty string.
161
162           ENOMEM
163               Insufficient memory was available.
164
165           any error returned by stat(2)
166
167           In contrast to mkdir(2), the function does not fail if "pathname"
168           already exists and is a directory.
169
170       rrd_scaled_duration (const char * token, unsigned long divisor,
171       unsigned long * valuep)
172           Parse a token in a context where it contains a count (of seconds or
173           PDP instances), or a duration that can be converted to a count by
174           representing the duration in seconds and dividing by some scaling
175           factor.  For example, if a user would natively express a 3 day
176           archive of samples collected every 2 minutes, the sample interval
177           can be represented by "2m" instead of 120, and the archive duration
178           by "3d" (to be divided by 120) instead of 2160 (3*24*60*60 / 120).
179           See more examples in "STEP, HEARTBEAT, and Rows As Durations" in
180           rrdcreate.
181
182           "token" must be a number with an optional single-character suffix
183           encoding the scaling factor:
184
185           "s" indicates seconds
186
187           "m" indicates minutes.  The value is multiplied by 60.
188
189           "h" indicates hours.  The value is multiplied by 3600 (or "60m").
190
191           "d" indicates days.  The value is multiplied by 86400 (or "24h").
192
193           "w" indicates weeks.  The value is multiplied by 604800 (or "7d").
194
195           "M" indicates months.  The value is multiplied by 2678400 (or
196               "31d").  (Note this factor accommodates the maximum number of
197               days in a month.)
198
199           "y" indicates years.  The value is multiplied by 31622400 (or
200               "366d").  (Note this factor accommodates leap years.)
201
202           "divisor" is a positive value representing the duration in seconds
203           of an interval that the desired result counts.
204
205           "valuep" is a pointer to where the decoded value will be stored if
206           the conversion is successful.
207
208           The initial characters of "token" must be the base-10
209           representation of a positive integer, or the conversion fails.
210
211           If the remainder "token" is empty (no suffix), it is a count and no
212           scaling is performed.
213
214           If "token" has one of the suffixes above, the count is multiplied
215           to convert it to a duration in seconds.  The resulting number of
216           seconds is divided by "divisor" to produce a count of intervals
217           each of duration "divisor" seconds.  If division would produce a
218           remainder (e.g., "5m" (300 seconds) divided by "90s"), the
219           conversion is invalid.
220
221           If "token" has unrecognized trailing characters the conversion
222           fails.
223
224           The function returns a null pointer if the conversion was
225           successful and "valuep" has been updated to the scaled value.  On
226           failure, it returns a text diagnostic suitable for use in user
227           error messages.
228

CLIENT FUNCTIONS

230       The following functions are used to connected to an rrdcached instance,
231       either via a unix or inet address, and create, update, or gather
232       statistics about a specified RRD database file.
233
234       There are two different interfaces: The rrd_client_ family of functions
235       operate on a user-provided client object (rrd_client_t) and support
236       multiple concurrent connections to rrdcache instances. The simpler
237       rrdc_ family of functions handles connections transparently but can
238       only be used for one connection at a time.
239
240       All of the following functions and data types are specified in the
241       "rrd_client.h" header file.
242
243       rrd_client_new(const char *daemon_addr)
244           Create a new client connection object. If specified, connect to the
245           daemon at "daemon_addr". The connection can later be changed by
246           calling rrd_client_connect.
247
248       rrd_client_destroy(rrd_client_t *client)
249           Close a client connection and destroy the object by freeing all
250           dynamically allocated memory. After calling this function, "client"
251           can no longer be used.
252
253       rrd_client_connect(rrd_client_t *client, const char *daemon_addr)
254       rrdc_connect(const char *daemon_addr)
255           Connect to a running rrdcached instance, specified via
256           "daemon_addr". Any previous connection will be closed. If
257           "daemon_addr" is "NULL", it defaults to the value of the
258           "ENV_RRDCACHED_ADDRESS" environment address.
259
260       rrd_client_is_connected(rrd_client_t *client)
261           Return a boolean int if the client is connected to the server.
262
263       rrd_client_address(rrd_client_t *client)
264           Returns the server address belonging to the current connection.
265
266       rrdc_is_connected(const char *daemon_addr)
267           Return a boolean int to determine if the client is connected to the
268           rrdcache daemon specified by the "daemon_addr" parameter.
269
270       rrd_client_ping(rrd_client_t *client)
271       rrdc_ping
272           Check the client connection by pinging the remote side.
273
274       rrdc_is_any_connected
275           Return a boolean int if any daemon connections are connected.
276
277       rrd_client_disconnect(rrd_client_t *client)
278       rrdc_disconnect
279           Disconnect gracefully from the present daemon connection.
280
281       rrd_client_update(rrd_client_t *client, const char *filename, int
282       values_num, const char * const *values)
283       rrdc_update(const char *filename, int values_num, const char * const
284       *values)
285           Update the RRD "filename" via the rrdcached. Where "values_num" is
286           the number of values to update and "values" are the new values to
287           add.
288
289       rrd_client_info(rrd_client_t *client, const char *filename)
290       rrdc_info(const char *filename)
291           Grab rrd info of the RRD "filename" from the connected cache
292           daemon.  This function returns an rrd_info_t structure of the
293           following format:
294
295               typedef struct rrd_blob_t {
296                   unsigned long size; /* size of the blob */
297                   unsigned char *ptr; /* pointer */
298               } rrd_blob_t;
299
300               typedef enum rrd_info_type { RD_I_VAL = 0,
301                   RD_I_CNT,
302                   RD_I_STR,
303                   RD_I_INT,
304                   RD_I_BLO
305               } rrd_info_type_t;
306
307               typedef union rrd_infoval {
308                   unsigned long u_cnt;
309                   rrd_value_t u_val;
310                   char     *u_str;
311                   int       u_int;
312                   rrd_blob_t u_blo;
313               } rrd_infoval_t;
314
315               typedef struct rrd_info_t {
316                   char     *key;
317                   rrd_info_type_t type;
318                   rrd_infoval_t value;
319                   struct rrd_info_t *next;
320               } rrd_info_t;
321
322       rrd_client_last(rrd_client_t *client, const char *filename)
323       rrdc_last(const char *filename)
324           Grab the unix epoch of the last time RRD "filename" was updated.
325
326       rrd_client_first(rrd_client_t *client, const char *filename, int
327       rraindex)
328       rrdc_first(const char *filename, int rraindex)
329           Get the first value of the first sample of the RRD "filename", of
330           the "rraindex" RRA (Round Robin Archive) index number.  The RRA
331           index number can be determined by pulling the rrd_info_t off the
332           RRD.
333
334       rrd_client_create(rrd_client_t *client, const char *filename, unsigned
335       long pdp_step, time_t last_up, int no_overwrite, int argc, const char
336       **argv)
337       rrdc_create(const char *filename, unsigned long pdp_step, time_t
338       last_up, int no_overwrite, int argc, const char **argv)
339           Create RRD database of path "filename".  The RRD will have a step
340           size of "pfp_step", the unix epoch timestamp to start collecting
341           data from. The number of data sources and RRAs "argc" and the
342           definitions of the data sources and RRAs "argv". Lastly whether or
343           not to overwrite an existing RRD if one is found with the same
344           filename; "no_overwrite".
345
346       rrdc_create_r2(rrd_client_t *client, const char *filename, unsigned
347       long pdp_step, time_t last_up, int no_overwrite, const char **sources,
348       const char *template, int argc, const char **argv)
349       rrdc_create_r2(const char *filename, unsigned long pdp_step, time_t
350       last_up, int no_overwrite, const char **sources, const char *template,
351       int argc, const char **argv)
352           Create an RRD database in the daemon. rrdc_create_r2 has the same
353           parameters as rrdc_create with two added parameters of; "sources"
354           and "template".
355
356           where "template" is the file path to a RRD file template, with, the
357           form defined in rrdcreate(1),
358
359           The "sources" parameter defines series of file paths with data
360           defined, to prefill the RRD with. See rrdcreate(1) for more
361           details.
362
363       rrd_client_flush(rrd_client_t *client, const char *filename)
364       rrdc_flush(const char *filename)
365           flush the currently RRD cached in the daemon specified via
366           "filename".
367
368       rrd_client_forget(rrd_client_t *client, const char *filename)
369       rrdc_forget(const char *filename)
370           Drop the cached data for the RRD file specified via "filename".
371
372       rrdc_flush_if_daemon(const char *daemon_addr, const char *filename)
373           Flush the specified RRD given by "filename" only if the daemon
374           "daemon_addr" is up and connected.
375
376       rrd_client_fetch(rrd_client_t *client, const char *filename, const char
377       *cf, time_t *ret_start, time_t *ret_end, unsigned long *ret_step,
378       unsigned long *ret_ds_num, char ***ret_ds_names, rrd_value_t
379       **ret_data)
380       rrdc_fetch(const char *filename, const char *cf, time_t *ret_start,
381       time_t *ret_end, unsigned long *ret_step, unsigned long *ret_ds_num,
382       char ***ret_ds_names, rrd_value_t **ret_data)
383           Perform a fetch operation on the specified RRD Database given be
384           "filename", where "cf" is the consolidation function, "ret_start"
385           is the start time given by unix epoch, "ret_end" is the endtime.
386           "ret_step" is the step size in seconds, "ret_ds_num" the number of
387           data sources in the RRD, "ret_ds_names" the names of the data
388           sources, and a pointer to an rrd_value_t object to shlep the data.
389
390       rrdc_stats_get(rrd_client_t *client, rrdc_stats_t **ret_stats)
391       rrdc_stats_get(rrdc_stats_t **ret_stats)
392           Get stats from the connected daemon, via a linked list of the
393           following structure:
394
395               struct rrdc_stats_s {
396                   const char *name;
397                   uint16_t type;
398                   #define RRDC_STATS_TYPE_GAUGE   0x0001
399                   #define RRDC_STATS_TYPE_COUNTER 0x0002
400                   uint16_t flags;
401                   union {
402                       uint64_t counter;
403                       double   gauge;
404                   } value;
405                   struct rrdc_stats_s *next;
406               };
407               typedef struct rrdc_stats_s rrdc_stats_t;
408
409       rrdc_stats_free(rrdc_stats_t *ret_stats)
410           Free the stats struct allocated via rrdc_stats_get.
411
412   SEE ALSO
413       rrcached(1) rrdfetch(1) rrdinfo(1) rrdlast(1) rrdcreate(1) rrdupdate(1)
414       rrdlast(1)
415

AUTHOR

417       RRD Contributors <rrd-developers@lists.oetiker.ch>
418
419
420
4211.8.0                             2022-03-14                         librrd(3)
Impressum