doc/librrd.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>librrd</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:root@localhost" />
   8 </head>
   9
  10 <body style="background-color: white">
  11
  12
  13 <!-- INDEX BEGIN -->
  14 <div name="index">
  15 <p><a name="__index__"></a></p>
  16 <!--
  17
  18 <ul>
  19
  20         <li><a href="#name">NAME</a></li>
  21         <li><a href="#description">DESCRIPTION</a></li>
  22         <li><a href="#core_functions">CORE FUNCTIONS</a></li>
  23         <li><a href="#utility_functions">UTILITY FUNCTIONS</a></li>
  24 </ul>
  25
  26 -->
  27
  28
  29 </div>
  30 <!-- INDEX END -->
  31
  32 <p>
  33 </p>
  34 <hr />
  35 <h1><a name="name">NAME</a></h1>
  36 <p>librrd - RRD library functions</p>
  37 <p>
  38 </p>
  39 <hr />
  40 <h1><a name="description">DESCRIPTION</a></h1>
  41 <p><strong>librrd</strong> contains most of the functionality in <strong>RRDTool</strong>.  The command
  42 line utilities and language bindings are often just wrappers around the
  43 code contained in <strong>librrd</strong>.</p>
  44 <p>This manual page documents the <strong>librrd</strong> API.</p>
  45 <p><strong>NOTE:</strong> This document is a work in progress, and should be considered
  46 incomplete as long as this warning persists.  For more information about
  47 the <strong>librrd</strong> functions, always consult the source code.</p>
  48 <p>
  49 </p>
  50 <hr />
  51 <h1><a name="core_functions">CORE FUNCTIONS</a></h1>
  52 <dl>
  53 <dt><strong><a name="rrd_dump_cb_r" class="item"><strong>rrd_dump_cb_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)</strong></a></strong></dt>
  54
  55 <dd>
  56 <p>In some situations it is necessary to get the output of <code>rrd_dump</code> without
  57 writing it to a file or the standard output. In such cases an application
  58 can ask <strong>rrd_dump_cb_r</strong> to call an user-defined function each time there
  59 is output to be stored somewhere. This can be used, to e.g. directly feed
  60 an XML parser with the dumped output or transfer the resulting string
  61 in memory.</p>
  62 <p>The arguments for <strong>rrd_dump_cb_r</strong> are the same as for <strong>rrd_dump_opt_r</strong>
  63 except that the output filename parameter is replaced by the user-defined
  64 callback function and an additional parameter for the callback function
  65 that is passed untouched, i.e. to store information about the callback state
  66 needed for the user-defined callback to function properly.</p>
  67 <p>Recent versions of <strong>rrd_dump_opt_r</strong> internally use this callback mechanism
  68 to write their output to the file provided by the user.</p>
  69 <pre>
  70     size_t rrd_dump_opt_cb_fileout(
  71         const void *data,
  72         size_t len,
  73         void *user)
  74     {
  75         return fwrite(data, 1, len, (FILE *)user);
  76     }</pre>
  77 <p>The associated call for <strong>rrd_dump_cb_r</strong> looks like</p>
  78 <pre>
  79     res = rrd_dump_cb_r(filename, opt_header,
  80         rrd_dump_opt_cb_fileout, (void *)out_file);</pre>
  81 <p>where the last parameter specifies the file handle <strong>rrd_dump_opt_cb_fileout</strong>
  82 should write to. There's no specific condition for the callback to detect
  83 when it is called for the first time, nor for the last time. If you require
  84 this for initialization and cleanup you should do those tasks before and
  85 after calling <strong>rrd_dump_cr_r</strong> respectively.</p>
  86 </dd>
  87 </dl>
  88 <p>
  89 </p>
  90 <hr />
  91 <h1><a name="utility_functions">UTILITY FUNCTIONS</a></h1>
  92 <dl>
  93 <dt><strong><a name="rrd_random" class="item"><strong>rrd_random()</strong></a></strong></dt>
  94
  95 <dd>
  96 <p>Generates random numbers just like <code>random()</code>.  This further ensures that
  97 the random number generator is seeded exactly once per process.</p>
  98 </dd>
  99 <dt><strong><a name="rrd_add_ptr" class="item"><strong>rrd_add_ptr(void ***dest, size_t *dest_size, void *src)</strong></a></strong></dt>
 100
 101 <dd>
 102 <p>Dynamically resize the array pointed to by <code>dest</code>.  <code>dest_size</code> is a
 103 pointer to the current size of <code>dest</code>.  Upon successful <code>realloc()</code>, the
 104 <code>dest_size</code> is incremented by 1 and the <code>src</code> pointer is stored at the
 105 end of the new <code>dest</code>.  Returns 1 on success, 0 on failure.</p>
 106 <pre>
 107     type **arr = NULL;
 108     type *elem = &quot;whatever&quot;;
 109     size_t arr_size = 0;
 110     if (!rrd_add_ptr(&amp;arr, &amp;arr_size, elem))
 111         handle_failure();</pre>
 112 </dd>
 113 <dt><strong><a name="rrd_add_strdup" class="item"><strong>rrd_add_strdup(char ***dest, size_t *dest_size, char *src)</strong></a></strong></dt>
 114
 115 <dd>
 116 <p>Like <a href="#rrd_add_ptr"><code>rrd_add_ptr</code></a>, except adds a <code>strdup</code> of the source string.</p>
 117 <pre>
 118     char **arr = NULL;
 119     size_t arr_size = NULL;
 120     char *str  = &quot;example text&quot;;
 121     if (!rrd_add_strdup(&amp;arr, &amp;arr_size, str))
 122         handle_failure();</pre>
 123 </dd>
 124 <dt><strong><a name="rrd_free_ptrs" class="item"><strong>rrd_free_ptrs(void ***src, size_t *cnt)</strong></a></strong></dt>
 125
 126 <dd>
 127 <p>Free an array of pointers allocated by <a href="#rrd_add_ptr"><code>rrd_add_ptr</code></a> or
 128 <a href="#rrd_add_strdup"><code>rrd_add_strdup</code></a>.  Also frees the array pointer itself.  On return, the
 129 source pointer will be NULL and the count will be zero.</p>
 130 <pre>
 131     /* created as above */
 132     rrd_free_ptrs(&amp;arr, &amp;arr_size);
 133     /* here, arr == NULL &amp;&amp; arr_size == 0 */</pre>
 134 </dd>
 135 <dt><strong><a name="rrd_mkdir_p" class="item"><strong>rrd_mkdir_p(const char *pathname, mode_t mode)</strong></a></strong></dt>
 136
 137 <dd>
 138 <p>Create the directory named <code>pathname</code> including all of its parent
 139 directories (similar to <code>mkdir -p</code> on the command line - see <em>mkdir(1)</em> for
 140 more information). The argument <code>mode</code> specifies the permissions to use. It
 141 is modified by the process's <code>umask</code>. See <em>mkdir(2)</em> for more details.</p>
 142 <p>The function returns 0 on success, a negative value else. In case of an error,
 143 <code>errno</code> is set accordingly. Aside from the errors documented in <em>mkdir(2)</em>,
 144 the function may fail with the following errors:</p>
 145 <dl>
 146 <dt><strong><a name="einval" class="item"><strong>EINVAL</strong></a></strong></dt>
 147
 148 <dd>
 149 <p><code>pathname</code> is <code>NULL</code> or the empty string.</p>
 150 </dd>
 151 <dt><strong><a name="enomem" class="item"><strong>ENOMEM</strong></a></strong></dt>
 152
 153 <dd>
 154 <p>Insufficient memory was available.</p>
 155 </dd>
 156 <dt><strong><a name="stat" class="item"><strong>any error returned by <a href="#stat">stat(2)</a></strong></a></strong></dt>
 157
 158 </dl>
 159 <p>In contrast to <em>mkdir(2)</em>, the function does <strong>not</strong> fail if <code>pathname</code>
 160 already exists and is a directory.</p>
 161 </dd>
 162 </dl>
 163
 164 </body>
 165
 166 </html>