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_mkdir_p(const char *pathname, mode_t mode)>
  62
  63 Create the directory named C<pathname> including all of its parent
  64 directories (similar to C<mkdir -p> on the command line - see L<mkdir(1)> for
  65 more information). The argument C<mode> specifies the permissions to use. It
  66 is modified by the process's C<umask>. See L<mkdir(2)> for more details.
  67
  68 The function returns 0 on success, a negative value else. In case of an error,
  69 C<errno> is set accordingly. Aside from the errors documented in L<mkdir(2)>,
  70 the function may fail with the following errors:
  71
  72 =over 4
  73
  74 =item B<EINVAL>
  75
  76 C<pathname> is C<NULL> or the empty string.
  77
  78 =item B<ENOMEM>
  79
  80 Insufficient memory was available.
  81
  82 =item B<any error returned by L<stat(2)>>
  83
  84 =back
  85
  86 In contrast to L<mkdir(2)>, the function does B<not> fail if C<pathname>
  87 already exists and is a directory.
  88
  89 =item B<rrd_dump_cr_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)>
  90
  91 In some situations it is necessary to get the output of C<rrd_dump> without
  92 writing it to a file or the standard output. In such cases an application
  93 can ask B<rrd_dump_cb_r> to call an user-defined function each time there
  94 is output to be stored somewhere. This can be used, to e.g. directly feed
  95 an XML parser with the dumped output or transfer the resulting string
  96 in memory.
  97
  98 The arguments for B<rrd_dump_cb_r> are the same as for B<rrd_dump_opt_r>
  99 except that the output filename parameter is replaced by the user-defined
 100 callback function and an additional parameter for the callback function
 101 that is passed untouched, i.e. to store information about the callback state
 102 needed for the user-defined callback to function properly.
 103
 104 Recent versions of B<rrd_dump_opt_r> internally use this callback mechanism
 105 to write their output to the file provided by the user.
 106
 107     size_t rrd_dump_opt_cb_fileout(
 108         const void *data,
 109         size_t len,
 110         void *user)
 111     {
 112         return fwrite(data, 1, len, (FILE *)user);
 113     }
 114
 115 The associated call for B<rrd_dump_cb_r> looks like
 116
 117     res = rrd_dump_cb_r(filename, opt_header,
 118         rrd_dump_opt_cb_fileout, (void *)out_file);
 119
 120 where the last parameter specifies the file handle B<rrd_dump_opt_cb_fileout>
 121 should write to. There's no specific condition for the callback to detect
 122 when it is called for the first time, nor for the last time. If you require
 123 this for initialization and cleanup you should do those tasks before and
 124 after calling B<rrd_dump_cr_r> respectively.
 125
 126 =back