doc/librrd.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 librrd - RRD library functions
   6
   7 =head1 DESCRIPTION
   8
   9 B<librrd> contains most of the functionality in B<RRDTool>.  The command
  10 line utilities and language bindings are often just wrappers around the
  11 code contained in B<librrd>.
  12
  13 This manual page documents the B<librrd> API.
  14
  15 B<NOTE:> This document is a work in progress, and should be considered
  16 incomplete as long as this warning persists.  For more information about
  17 the B<librrd> functions, always consult the source code.
  18
  19 =head1 UTILITY FUNCTIONS
  20
  21 =over
  22
  23 =item B<rrd_random()>
  24
  25 Generates random numbers just like random().  This further ensures that
  26 the random number generator is seeded exactly once per process.
  27
  28 =item B<rrd_add_ptr(void ***dest, size_t *dest_size, void *src)>
  29
  30 Dynamically resize the array pointed to by C<dest>.  C<dest_size> is a
  31 pointer to the current size of C<dest>.  Upon successful realloc(), the
  32 C<dest_size> is incremented by 1 and the C<src> pointer is stored at the
  33 end of the new C<dest>.  Returns 1 on success, 0 on failure.
  34
  35     type **arr = NULL;
  36     type *elem = "whatever";
  37     size_t arr_size = 0;
  38     if (!rrd_add_ptr(&arr, &arr_size, elem))
  39         handle_failure();
  40
  41 =item B<rrd_add_strdup(char ***dest, size_t *dest_size, char *src)>
  42
  43 Like C<rrd_add_ptr>, except adds a C<strdup> of the source string.
  44
  45     char **arr = NULL;
  46     size_t arr_size = NULL;
  47     char *str  = "example text";
  48     if (!rrd_add_strdup(&arr, &arr_size, str))
  49         handle_failure();
  50
  51 =item B<rrd_free_ptrs(void ***src, size_t *cnt)>
  52
  53 Free an array of pointers allocated by C<rrd_add_ptr> or
  54 C<rrd_add_strdup>.  Also frees the array pointer itself.  On return, the
  55 source pointer will be NULL and the count will be zero.
  56
  57     /* created as above */
  58     rrd_free_ptrs(&arr, &arr_size);
  59     /* here, arr == NULL && arr_size == 0 */
  60
  61 =item B<rrd_dump_cr_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)>
  62
  63 In some situations it is necessary to get the output of C<rrd_dump> without
  64 writing it to a file or the standard output. In such cases an application
  65 can ask B<rrd_dump_cb_r> to call an user-defined function each time there
  66 is output to be stored somewhere. This can be used, to e.g. directly feed
  67 an XML parser with the dumped output or transfer the resulting string
  68 in memory.
  69
  70 The arguments for B<rrd_dump_cb_r> are the same as for B<rrd_dump_opt_r>
  71 except that the output filename parameter is replaced by the user-defined
  72 callback function and an additional parameter for the callback function
  73 that is passed untouched, i.e. to store information about the callback state
  74 needed for the user-defined callback to function properly.
  75
  76 Recent versions of B<rrd_dump_opt_r> internally use this callback mechanism
  77 to write their output to the file provided by the user.
  78
  79     size_t rrd_dump_opt_cb_fileout(
  80         const void *data,
  81         size_t len,
  82         void *user)
  83     {
  84         return fwrite(data, 1, len, (FILE *)user);
  85     }
  86
  87 The associated call for B<rrd_dump_cb_r> looks like
  88
  89     res = rrd_dump_cb_r(filename, opt_header,
  90         rrd_dump_opt_cb_fileout, (void *)out_file);
  91
  92 where the last parameter specifies the file handle B<rrd_dump_opt_cb_fileout>
  93 should write to. There's no specific condition for the callback to detect
  94 when it is called for the first time, nor for the last time. If you require
  95 this for initialization and cleanup you should do those tasks before and
  96 after calling B<rrd_dump_cr_r> respectively.
  97
  98 =back