From 4bfa907ae3800fb47268b513a5211ae30698dbed Mon Sep 17 00:00:00 2001 From: oetiker Date: Mon, 28 Sep 2009 16:21:13 +0000 Subject: [PATCH] Moved rrd_dump_cb_r() to section "CORE FUNCTIONS" since this is not a utility function but rather part of RRDtool's core. -- Sebastian Harl git-svn-id: svn://svn.oetiker.ch/rrdtool/trunk/program@1918 a5681a0c-68f1-0310-ab6d-d61299d08faa --- doc/librrd.pod | 82 +++++++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 38 deletions(-) diff --git a/doc/librrd.pod b/doc/librrd.pod index 4daa93c..038746c 100644 --- a/doc/librrd.pod +++ b/doc/librrd.pod @@ -16,9 +16,52 @@ B This document is a work in progress, and should be considered incomplete as long as this warning persists. For more information about the B functions, always consult the source code. +=head1 CORE FUNCTIONS + +=over 4 + +=item B + +In some situations it is necessary to get the output of C without +writing it to a file or the standard output. In such cases an application +can ask B 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 B are the same as for B +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 B 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 B 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 B +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 B respectively. + +=back + =head1 UTILITY FUNCTIONS -=over +=over 4 =item B @@ -86,41 +129,4 @@ Insufficient memory was available. In contrast to L, the function does B fail if C already exists and is a directory. -=item B - -In some situations it is necessary to get the output of C without -writing it to a file or the standard output. In such cases an application -can ask B 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 B are the same as for B -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 B 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 B 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 B -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 B respectively. - =back -- 2.11.0