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_strdup(char ***dest, size_t *dest_size, char *src)>
  85
  86 Like C<rrd_add_ptr>, except adds a C<strdup> of the source string.
  87
  88     char **arr = NULL;
  89     size_t arr_size = NULL;
  90     char *str  = "example text";
  91     if (!rrd_add_strdup(&arr, &arr_size, str))
  92         handle_failure();
  93
  94 =item B<rrd_free_ptrs(void ***src, size_t *cnt)>
  95
  96 Free an array of pointers allocated by C<rrd_add_ptr> or
  97 C<rrd_add_strdup>.  Also frees the array pointer itself.  On return, the
  98 source pointer will be NULL and the count will be zero.
  99
 100     /* created as above */
 101     rrd_free_ptrs(&arr, &arr_size);
 102     /* here, arr == NULL && arr_size == 0 */
 103
 104 =item B<rrd_mkdir_p(const char *pathname, mode_t mode)>
 105
 106 Create the directory named C<pathname> including all of its parent
 107 directories (similar to C<mkdir -p> on the command line - see L<mkdir(1)> for
 108 more information). The argument C<mode> specifies the permissions to use. It
 109 is modified by the process's C<umask>. See L<mkdir(2)> for more details.
 110
 111 The function returns 0 on success, a negative value else. In case of an error,
 112 C<errno> is set accordingly. Aside from the errors documented in L<mkdir(2)>,
 113 the function may fail with the following errors:
 114
 115 =over 4
 116
 117 =item B<EINVAL>
 118
 119 C<pathname> is C<NULL> or the empty string.
 120
 121 =item B<ENOMEM>
 122
 123 Insufficient memory was available.
 124
 125 =item B<any error returned by L<stat(2)>>
 126
 127 =back
 128
 129 In contrast to L<mkdir(2)>, the function does B<not> fail if C<pathname>
 130 already exists and is a directory.
 131
 132 =back