X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Flibrrd.pod;h=0d05f6eeaa0f8c50b5a6e363299d34828b1a50af;hp=4daa93cf73c74bc5533564b60ca8073175e2c1aa;hb=9e2eb0abd095264f584490ede57ae5afe8beb748;hpb=8753076ac00af4a10484417a91d1c07baa872fbe

diff --git a/doc/librrd.pod b/doc/librrd.pod
index 4daa93c..0d05f6e 100644
--- a/doc/librrd.pod
+++ b/doc/librrd.pod
@@ -16,9 +16,52 @@ B<NOTE:> This document is a work in progress, and should be considered
 incomplete as long as this warning persists.  For more information about
 the B<librrd> functions, always consult the source code.
 
+=head1 CORE FUNCTIONS
+
+=over 4
+
+=item B<rrd_dump_cb_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)>
+
+In some situations it is necessary to get the output of C<rrd_dump> without
+writing it to a file or the standard output. In such cases an application
+can ask B<rrd_dump_cb_r> 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<rrd_dump_cb_r> are the same as for B<rrd_dump_opt_r>
+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<rrd_dump_opt_r> 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<rrd_dump_cb_r> 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<rrd_dump_opt_cb_fileout>
+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<rrd_dump_cr_r> respectively.
+
+=back
+
 =head1 UTILITY FUNCTIONS
 
-=over
+=over 4
 
 =item B<rrd_random()>
 
@@ -38,6 +81,16 @@ end of the new C<dest>.  Returns 1 on success, 0 on failure.
     if (!rrd_add_ptr(&arr, &arr_size, elem))
         handle_failure();
 
+=item B<rrd_add_ptr_chunk(void ***dest, size_t *dest_size, void *src, size_t *alloc, size_t chunk)>
+
+Like C<rrd_add_ptr>, except the destination is allocated in chunks of
+C<chunk>.  C<alloc> points to the number of entries allocated, whereas
+C<dest_size> points to the number of valid pointers.  If more pointers are
+needed, C<chunk> pointers are allocated and C<alloc> is increased
+accordingly.  C<alloc> must be E<gt>= C<dest_size>.
+
+This method improves performance on hosts with expensive C<realloc()>.
+
 =item B<rrd_add_strdup(char ***dest, size_t *dest_size, char *src)>
 
 Like C<rrd_add_ptr>, except adds a C<strdup> of the source string.
@@ -48,6 +101,14 @@ Like C<rrd_add_ptr>, except adds a C<strdup> of the source string.
     if (!rrd_add_strdup(&arr, &arr_size, str))
         handle_failure();
 
+=item B<rrd_add_strdup_chunk(char ***dest, size_t *dest_size, char *src, size_t *alloc, size_t chunk)>
+
+Like C<rrd_add_strdup>, except the destination is allocated in chunks of
+C<chunk>.  C<alloc> points to the number of entries allocated, whereas
+C<dest_size> points to the number of valid pointers.  If more pointers are
+needed, C<chunk> pointers are allocated and C<alloc> is increased
+accordingly.  C<alloc> must be E<gt>= C<dest_size>.
+
 =item B<rrd_free_ptrs(void ***src, size_t *cnt)>
 
 Free an array of pointers allocated by C<rrd_add_ptr> or
@@ -86,41 +147,8 @@ Insufficient memory was available.
 In contrast to L<mkdir(2)>, the function does B<not> fail if C<pathname>
 already exists and is a directory.
 
-=item B<rrd_dump_cr_r(char *filename, int opt_header, rrd_output_callback_t cb, void *user)>
-
-In some situations it is necessary to get the output of C<rrd_dump> without
-writing it to a file or the standard output. In such cases an application
-can ask B<rrd_dump_cb_r> 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<rrd_dump_cb_r> are the same as for B<rrd_dump_opt_r>
-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<rrd_dump_opt_r> 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<rrd_dump_cb_r> looks like
-
-    res = rrd_dump_cb_r(filename, opt_header,
-        rrd_dump_opt_cb_fileout, (void *)out_file);
+=back
 
-where the last parameter specifies the file handle B<rrd_dump_opt_cb_fileout>
-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<rrd_dump_cr_r> respectively.
+=head1 AUTHOR
 
-=back
+RRD Contributors <rrd-developers@lists.oetiker.ch>