X-Git-Url: https://git.tokkee.org/?p=pkg-rrdtool.git;a=blobdiff_plain;f=doc%2Flibrrd.txt;h=bfc23cbc5d73b90f3fb514a145705eeb4973805f;hp=da82e48b203be609ca879f356535ee5fb5517412;hb=645054bac6187b0e83fd4125fd59e4feda216b64;hpb=ffa00ac697dccce18dca8880ca7a14066521ac5c

diff --git a/doc/librrd.txt b/doc/librrd.txt
index da82e48..bfc23cb 100644
--- a/doc/librrd.txt
+++ b/doc/librrd.txt
@@ -1,4 +1,4 @@
-LIBRRD(1)                           rrdtool                          LIBRRD(1)
+librrd(3)                           rrdtool                          librrd(3)
 
 
 
@@ -16,18 +16,58 @@ DDEESSCCRRIIPPTTIIOONN
        incomplete as long as this warning persists.  For more information
        about the lliibbrrrrdd functions, always consult the source code.
 
+CCOORREE FFUUNNCCTTIIOONNSS
+       rrrrdd__dduummpp__ccbb__rr((cchhaarr **ffiilleennaammee,, iinntt oopptt__hheeaaddeerr,, rrrrdd__oouuttppuutt__ccaallllbbaacckk__tt ccbb,,
+       vvooiidd **uusseerr))
+           In some situations it is necessary to get the output of "rrd_dump"
+           without writing it to a file or the standard output. In such cases
+           an application can ask rrrrdd__dduummpp__ccbb__rr to call an user-defined
+           function each time there is output to be stored somewhere. This can
+           be used, to e.g. directly feed an XML parser with the dumped output
+           or transfer the resulting string in memory.
+
+           The arguments for rrrrdd__dduummpp__ccbb__rr are the same as for rrrrdd__dduummpp__oopptt__rr
+           except that the output filename parameter is replaced by the user-
+           defined callback function and an additional parameter for the
+           callback function that is passed untouched, i.e. to store
+           information about the callback state needed for the user-defined
+           callback to function properly.
+
+           Recent versions of rrrrdd__dduummpp__oopptt__rr internally use this callback
+           mechanism to write their output to the file provided by the user.
+
+               size_t rrd_dump_opt_cb_fileout(
+                   const void *data,
+                   size_t len,
+                   void *user)
+               {
+                   return fwrite(data, 1, len, (FILE *)user);
+               }
+
+           The associated call for rrrrdd__dduummpp__ccbb__rr looks like
+
+               res = rrd_dump_cb_r(filename, opt_header,
+                   rrd_dump_opt_cb_fileout, (void *)out_file);
+
+           where the last parameter specifies the file handle
+           rrrrdd__dduummpp__oopptt__ccbb__ffiilleeoouutt should write to. There's no specific
+           condition for the callback to detect when it is called for the
+           first time, nor for the last time. If you require this for
+           initialization and cleanup you should do those tasks before and
+           after calling rrrrdd__dduummpp__ccrr__rr respectively.
+
 UUTTIILLIITTYY FFUUNNCCTTIIOONNSS
        _rr_rr_dd____rr_aa_nn_dd_oo_mm_((_))
            Generates random numbers just like _r_a_n_d_o_m_(_).  This further ensures
-           that the random number generator is seeded exactly once per pro-
-           cess.
+           that the random number generator is seeded exactly once per
+           process.
 
        rrrrdd__aadddd__ppttrr((vvooiidd ******ddeesstt,, ssiizzee__tt **ddeesstt__ssiizzee,, vvooiidd **ssrrcc))
            Dynamically resize the array pointed to by "dest".  "dest_size" is
-           a pointer to the current size of "dest".  Upon successful _r_e_a_l_-
-           _l_o_c_(_), the "dest_size" is incremented by 1 and the "src" pointer is
-           stored at the end of the new "dest".  Returns 1 on success, 0 on
-           failure.
+           a pointer to the current size of "dest".  Upon successful
+           _r_e_a_l_l_o_c_(_), the "dest_size" is incremented by 1 and the "src"
+           pointer is stored at the end of the new "dest".  Returns 1 on
+           success, 0 on failure.
 
                type **arr = NULL;
                type *elem = "whatever";
@@ -53,6 +93,29 @@ UUTTIILLIITTYY FFUUNNCCTTIIOONNSS
                rrd_free_ptrs(&arr, &arr_size);
                /* here, arr == NULL && arr_size == 0 */
 
+       rrrrdd__mmkkddiirr__pp((ccoonnsstt cchhaarr **ppaatthhnnaammee,, mmooddee__tt mmooddee))
+           Create the directory named "pathname" including all of its parent
+           directories (similar to "mkdir -p" on the command line - see
+           _m_k_d_i_r(1) for more information). The argument "mode" specifies the
+           permissions to use. It is modified by the process's "umask". See
+           _m_k_d_i_r(2) for more details.
+
+           The function returns 0 on success, a negative value else. In case
+           of an error, "errno" is set accordingly. Aside from the errors
+           documented in _m_k_d_i_r(2), the function may fail with the following
+           errors:
+
+           EEIINNVVAALL
+               "pathname" is "NULL" or the empty string.
+
+           EENNOOMMEEMM
+               Insufficient memory was available.
+
+           aannyy eerrrroorr rreettuurrnneedd bbyy _ss_tt_aa_tt((22))
+
+           In contrast to _m_k_d_i_r(2), the function does nnoott fail if "pathname"
+           already exists and is a directory.
+
 
 
-1.3.99909060808                   2009-04-20                         LIBRRD(1)
+1.3.999                           2009-09-30                         librrd(3)