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 =back