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 CORE FUNCTIONS
  20
  21 =over 4
  22
  23 =item B<rrd_dump_cb_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)>
  24
  25 In some situations it is necessary to get the output of C<rrd_dump> without
  26 writing it to a file or the standard output. In such cases an application
  27 can ask B<rrd_dump_cb_r> to call an user-defined function each time there
  28 is output to be stored somewhere. This can be used, to e.g. directly feed
  29 an XML parser with the dumped output or transfer the resulting string
  30 in memory.
  31
  32 The arguments for B<rrd_dump_cb_r> are the same as for B<rrd_dump_opt_r>
  33 except that the output filename parameter is replaced by the user-defined
  34 callback function and an additional parameter for the callback function
  35 that is passed untouched, i.e. to store information about the callback state
  36 needed for the user-defined callback to function properly.
  37
  38 Recent versions of B<rrd_dump_opt_r> internally use this callback mechanism
  39 to write their output to the file provided by the user.
  40
  41     size_t rrd_dump_opt_cb_fileout(
  42         const void *data,
  43         size_t len,
  44         void *user)
  45     {
  46         return fwrite(data, 1, len, (FILE *)user);
  47     }
  48
  49 The associated call for B<rrd_dump_cb_r> looks like
  50
  51     res = rrd_dump_cb_r(filename, opt_header,
  52         rrd_dump_opt_cb_fileout, (void *)out_file);
  53
  54 where the last parameter specifies the file handle B<rrd_dump_opt_cb_fileout>
  55 should write to. There's no specific condition for the callback to detect
  56 when it is called for the first time, nor for the last time. If you require
  57 this for initialization and cleanup you should do those tasks before and
  58 after calling B<rrd_dump_cr_r> respectively.
  59
  60 =back
  61
  62 =head1 UTILITY FUNCTIONS
  63
  64 =over 4
  65
  66 =item B<rrd_random()>
  67
  68 Generates random numbers just like random().  This further ensures that
  69 the random number generator is seeded exactly once per process.
  70
  71 =item B<rrd_add_ptr(void ***dest, size_t *dest_size, void *src)>
  72
  73 Dynamically resize the array pointed to by C<dest>.  C<dest_size> is a
  74 pointer to the current size of C<dest>.  Upon successful realloc(), the
  75 C<dest_size> is incremented by 1 and the C<src> pointer is stored at the
  76 end of the new C<dest>.  Returns 1 on success, 0 on failure.
  77
  78     type **arr = NULL;
  79     type *elem = "whatever";
  80     size_t arr_size = 0;
  81     if (!rrd_add_ptr(&arr, &arr_size, elem))
  82         handle_failure();
  83
  84 =item B<rrd_add_ptr_chunk(void ***dest, size_t *dest_size, void *src, size_t *alloc, size_t chunk)>
  85
  86 Like C<rrd_add_ptr>, except the destination is allocated in chunks of
  87 C<chunk>.  C<alloc> points to the number of entries allocated, whereas
  88 C<dest_size> points to the number of valid pointers.  If more pointers are
  89 needed, C<chunk> pointers are allocated and C<alloc> is increased
  90 accordingly.  C<alloc> must be E<gt>= C<dest_size>.
  91
  92 This method improves performance on hosts with expensive C<realloc()>.
  93
  94 =item B<rrd_add_strdup(char ***dest, size_t *dest_size, char *src)>
  95
  96 Like C<rrd_add_ptr>, except adds a C<strdup> of the source string.
  97
  98     char **arr = NULL;
  99     size_t arr_size = NULL;
 100     char *str  = "example text";
 101     if (!rrd_add_strdup(&arr, &arr_size, str))
 102         handle_failure();
 103
 104 =item B<rrd_add_strdup_chunk(char ***dest, size_t *dest_size, char *src, size_t *alloc, size_t chunk)>
 105
 106 Like C<rrd_add_strdup>, except the destination is allocated in chunks of
 107 C<chunk>.  C<alloc> points to the number of entries allocated, whereas
 108 C<dest_size> points to the number of valid pointers.  If more pointers are
 109 needed, C<chunk> pointers are allocated and C<alloc> is increased
 110 accordingly.  C<alloc> must be E<gt>= C<dest_size>.
 111
 112 =item B<rrd_free_ptrs(void ***src, size_t *cnt)>
 113
 114 Free an array of pointers allocated by C<rrd_add_ptr> or
 115 C<rrd_add_strdup>.  Also frees the array pointer itself.  On return, the
 116 source pointer will be NULL and the count will be zero.
 117
 118     /* created as above */
 119     rrd_free_ptrs(&arr, &arr_size);
 120     /* here, arr == NULL && arr_size == 0 */
 121
 122 =item B<rrd_mkdir_p(const char *pathname, mode_t mode)>
 123
 124 Create the directory named C<pathname> including all of its parent
 125 directories (similar to C<mkdir -p> on the command line - see L<mkdir(1)> for
 126 more information). The argument C<mode> specifies the permissions to use. It
 127 is modified by the process's C<umask>. See L<mkdir(2)> for more details.
 128
 129 The function returns 0 on success, a negative value else. In case of an error,
 130 C<errno> is set accordingly. Aside from the errors documented in L<mkdir(2)>,
 131 the function may fail with the following errors:
 132
 133 =over 4
 134
 135 =item B<EINVAL>
 136
 137 C<pathname> is C<NULL> or the empty string.
 138
 139 =item B<ENOMEM>
 140
 141 Insufficient memory was available.
 142
 143 =item B<any error returned by L<stat(2)>>
 144
 145 =back
 146
 147 In contrast to L<mkdir(2)>, the function does B<not> fail if C<pathname>
 148 already exists and is a directory.
 149
 150 =back
 151
 152 =head1 AUTHOR
 153
 154 RRD Contributors <rrd-developers@lists.oetiker.ch>