![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/librrd.txt b/doc/librrd.txt
index da82e48b203be609ca879f356535ee5fb5517412..bfc23cbc5d73b90f3fb514a145705eeb4973805f 100644 (file)
--- a/doc/librrd.txt
+++ b/doc/librrd.txt
-LIBRRD(1) rrdtool LIBRRD(1)
+librrd(3) rrdtool librrd(3)
incomplete as long as this warning persists. For more information
about the l\bli\bib\bbr\brr\brd\bd functions, always consult the source code.
+C\bCO\bOR\bRE\bE F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS
+ r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_c\bcb\bb_\b_r\br(\b(c\bch\bha\bar\br *\b*f\bfi\bil\ble\ben\bna\bam\bme\be,\b, i\bin\bnt\bt o\bop\bpt\bt_\b_h\bhe\bea\bad\bde\ber\br,\b, r\brr\brd\bd_\b_o\bou\but\btp\bpu\but\bt_\b_c\bca\bal\bll\blb\bba\bac\bck\bk_\b_t\bt c\bcb\bb,\b,
+ v\bvo\boi\bid\bd *\b*u\bus\bse\ber\br)\b)
+ 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 r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_c\bcb\bb_\b_r\br 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 r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_c\bcb\bb_\b_r\br are the same as for r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_o\bop\bpt\bt_\b_r\br
+ 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 r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_o\bop\bpt\bt_\b_r\br 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 r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_c\bcb\bb_\b_r\br 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
+ r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_o\bop\bpt\bt_\b_c\bcb\bb_\b_f\bfi\bil\ble\beo\bou\but\bt 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 r\brr\brd\bd_\b_d\bdu\bum\bmp\bp_\b_c\bcr\br_\b_r\br respectively.
+
U\bUT\bTI\bIL\bLI\bIT\bTY\bY F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS
_\br\br_\br\br_\bd\bd_\b_\b__\br\br_\ba\ba_\bn\bn_\bd\bd_\bo\bo_\bm\bm_\b(\b(_\b)\b)
Generates random numbers just like _\br_\ba_\bn_\bd_\bo_\bm_\b(_\b). 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.
r\brr\brd\bd_\b_a\bad\bdd\bd_\b_p\bpt\btr\br(\b(v\bvo\boi\bid\bd *\b**\b**\b*d\bde\bes\bst\bt,\b, s\bsi\biz\bze\be_\b_t\bt *\b*d\bde\bes\bst\bt_\b_s\bsi\biz\bze\be,\b, v\bvo\boi\bid\bd *\b*s\bsr\brc\bc)\b)
Dynamically resize the array pointed to by "dest". "dest_size" is
- a pointer to the current size of "dest". Upon successful _\br_\be_\ba_\bl_\b-
- _\bl_\bo_\bc_\b(_\b), 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
+ _\br_\be_\ba_\bl_\bl_\bo_\bc_\b(_\b), 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";
rrd_free_ptrs(&arr, &arr_size);
/* here, arr == NULL && arr_size == 0 */
+ r\brr\brd\bd_\b_m\bmk\bkd\bdi\bir\br_\b_p\bp(\b(c\bco\bon\bns\bst\bt c\bch\bha\bar\br *\b*p\bpa\bat\bth\bhn\bna\bam\bme\be,\b, m\bmo\bod\bde\be_\b_t\bt m\bmo\bod\bde\be)\b)
+ Create the directory named "pathname" including all of its parent
+ directories (similar to "mkdir -p" on the command line - see
+ _\bm_\bk_\bd_\bi_\br(1) for more information). The argument "mode" specifies the
+ permissions to use. It is modified by the process's "umask". See
+ _\bm_\bk_\bd_\bi_\br(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 _\bm_\bk_\bd_\bi_\br(2), the function may fail with the following
+ errors:
+
+ E\bEI\bIN\bNV\bVA\bAL\bL
+ "pathname" is "NULL" or the empty string.
+
+ E\bEN\bNO\bOM\bME\bEM\bM
+ Insufficient memory was available.
+
+ a\ban\bny\by e\ber\brr\bro\bor\br r\bre\bet\btu\bur\brn\bne\bed\bd b\bby\by _\bs\bs_\bt\bt_\ba\ba_\bt\bt(\b(2\b2)\b)
+
+ In contrast to _\bm_\bk_\bd_\bi_\br(2), the function does n\bno\bot\bt 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)