document the 'internal' functions in rrd.h but mark them as deprecated, so

that anyone using them will see that they should not be doing it.

git-svn-id: svn://svn.oetiker.ch/rrdtool/trunk/program@1426 a5681a0c-68f1-0310-ab6d-d61299d08faa

diff --git a/src/Makefile.am b/src/Makefile.am
index 4f19be5..c567679 100644 (file)
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -79,7 +79,7 @@ librrd_th_la_LDFLAGS         = $(MULTITHREAD_LDFLAGS) -version-info @LIBVERS@
 librrd_th_la_LDFLAGS         += -export-symbols librrd.sym
 librrd_th_la_LIBADD          = $(ALL_LIBS)
 
-include_HEADERS        = rrd.h
+include_HEADERS        = rrd.h rrd_format.h
 
 bin_PROGRAMS   = rrdtool rrdupdate
 

diff --git a/src/rrd.h b/src/rrd.h
index a458b57..764d429 100644 (file)
--- a/src/rrd.h
+++ b/src/rrd.h
@@ -299,6 +299,60 @@ extern    "C" {
 /* int    rrd_test_error_r (rrd_context_t *); */
 /* char  *rrd_get_error_r  (rrd_context_t *); */
 
+/*
+ * The following functions are _internal_ functions needed to read the raw RRD
+ * files. Since they are _internal_ they may change with the file format and
+ * will be replaced with a more general interface in RRDTool 1.4. Don't use
+ * these functions unless you have good reasons to do so. If you do use these
+ * functions you will have to adapt your code for RRDTool 1.4!
+ *
+ * To enable the deprecated functions define `RRD_EXPORT_DEPRECATED' before
+ * including <rrd_test.h>. You have been warned! If you come back to the
+ * RRDTool mailing list and whine about your broken application, you will get
+ * hit with something smelly!
+ */
+#if defined(_RRD_TOOL_H) || defined(RRD_EXPORT_DEPRECATED)
+
+# if defined(_RRD_TOOL_H)
+#  include "rrd_format.h"
+# else
+#  include <rrd_format.h>
+# endif
+
+#if defined(__GNUC__) && defined (RRD_EXPORT_DEPRECATED)
+# define RRD_DEPRECATED __attribute__((deprecated))
+#else
+# define RRD_DEPRECATED /**/
+#endif
+
+    void        rrd_free     (rrd_t *rrd)
+      RRD_DEPRECATED;
+    void        rrd_init     (rrd_t *rrd)
+      RRD_DEPRECATED;
+
+    rrd_file_t *rrd_open   (const char *const file_name, rrd_t *rrd,
+        unsigned rdwr)
+      RRD_DEPRECATED;
+
+    void        rrd_dontneed (rrd_file_t *rrd_file, rrd_t *rrd)
+      RRD_DEPRECATED;
+    int         rrd_close    (rrd_file_t *rrd_file)
+      RRD_DEPRECATED;
+    ssize_t     rrd_read     (rrd_file_t *rrd_file, void *buf, size_t count)
+      RRD_DEPRECATED;
+    ssize_t     rrd_write    (rrd_file_t *rrd_file,
+        const void *buf, size_t count)
+      RRD_DEPRECATED;
+    void        rrd_flush    (rrd_file_t *rrd_file)
+      RRD_DEPRECATED;
+    off_t       rrd_seek     (rrd_file_t *rrd_file, off_t off, int whence)
+      RRD_DEPRECATED;
+    off_t       rrd_tell     (rrd_file_t *rrd_file)
+      RRD_DEPRECATED;
+    int         rrd_lock     (rrd_file_t *file)
+      RRD_DEPRECATED;
+#endif /* defined(_RRD_TOOL_H) || defined(RRD_EXPORT_DEPRECATED) */
+
 #endif                  /* _RRDLIB_H */
 
 #ifdef  __cplusplus

diff --git a/src/rrd_format.h b/src/rrd_format.h
index b8f0790..7f974cb 100644 (file)
--- a/src/rrd_format.h
+++ b/src/rrd_format.h
@@ -7,6 +7,18 @@
 #ifndef _RRD_FORMAT_H
 #define _RRD_FORMAT_H
 
+/* 
+ * _RRD_TOOL_H
+ *   We're building RRDTool itself.
+ *
+ * RRD_EXPORT_DEPRECATED
+ *   User is requesting internal function which need this struct. They have
+ *   been told that this will change and have agreed to adapt their programs.
+ */
+#if !defined(_RRD_TOOL_H) && !defined(RRD_EXPORT_DEPRECATED)
+# error "Do not include rrd_format.h directly. Include rrd.h instead!"
+#endif
+
 #include "rrd.h"
 
 /*****************************************************************************

diff --git a/src/rrd_hw_math.c b/src/rrd_hw_math.c
index 2b2c00f..7ce9dc2 100644 (file)
--- a/src/rrd_hw_math.c
+++ b/src/rrd_hw_math.c
@@ -2,6 +2,7 @@
  * rrd_hw_math.c  Math functions for Holt-Winters computations
  *****************************************************************************/
 
+#include "rrd_tool.h"
 #include "rrd_hw_math.h"
 #include "rrd_config.h"
 

diff --git a/src/rrd_hw_update.c b/src/rrd_hw_update.c
index 89d0c8e..80da40a 100644 (file)
--- a/src/rrd_hw_update.c
+++ b/src/rrd_hw_update.c
@@ -2,6 +2,7 @@
  * rrd_hw_update.c  Functions for updating a Holt-Winters RRA
  ****************************************************************************/
 
+#include "rrd_tool.h"
 #include "rrd_format.h"
 #include "rrd_config.h"
 #include "rrd_hw_math.h"

diff --git a/src/rrd_tool.h b/src/rrd_tool.h
index a8a01fa..e211c6b 100644 (file)
--- a/src/rrd_tool.h
+++ b/src/rrd_tool.h
@@ -87,41 +87,6 @@ extern    "C" {
     char ***ds_namv,
     rrd_value_t **data);
 
-    void      rrd_free(
-    rrd_t *rrd);
-    void      rrd_freemem(
-    void *mem);
-    void      rrd_init(
-    rrd_t *rrd);
-
-    rrd_file_t *rrd_open(
-    const char *const file_name,
-    rrd_t *rrd,
-    unsigned rdwr);
-    void      rrd_dontneed(
-    rrd_file_t *rrd_file,
-    rrd_t *rrd);
-    int       rrd_close(
-    rrd_file_t *rrd_file);
-    ssize_t   rrd_read(
-    rrd_file_t *rrd_file,
-    void *buf,
-    size_t count);
-    ssize_t   rrd_write(
-    rrd_file_t *rrd_file,
-    const void *buf,
-    size_t count);
-    void      rrd_flush(
-    rrd_file_t *rrd_file);
-    off_t     rrd_seek(
-    rrd_file_t *rrd_file,
-    off_t off,
-    int whence);
-    off_t     rrd_tell(
-    rrd_file_t *rrd_file);
-    int       rrd_lock(
-    rrd_file_t *file);
-
 #define RRD_READONLY    (1<<0)
 #define RRD_READWRITE   (1<<1)
 #define RRD_CREAT       (1<<2)