Code

prepare for the release of rrdtool-1.3rc2
[rrdtool.git] / src / rrd.h
1 /*****************************************************************************
2  * RRDtool 1.3rc2  Copyright by Tobi Oetiker, 1997-2008
3  *****************************************************************************
4  * rrdlib.h   Public header file for librrd
5  *****************************************************************************
6  * $Id$
7  * $Log$
8  * Revision 1.9  2005/02/13 16:13:33  oetiker
9  * let rrd_graph return the actual value range it picked ...
10  * -- Henrik Stoerner <henrik@hswn.dk>
11  *
12  * Revision 1.8  2004/05/26 22:11:12  oetiker
13  * reduce compiler warnings. Many small fixes. -- Mike Slifcak <slif@bellsouth.net>
14  *
15  * Revision 1.7  2003/11/12 22:14:26  oetiker
16  * allow to pass an open filehandle into rrd_graph as an extra argument
17  *
18  * Revision 1.6  2003/11/11 19:46:21  oetiker
19  * replaced time_value with rrd_time_value as MacOS X introduced a struct of that name in their standard headers
20  *
21  * Revision 1.5  2003/04/25 18:35:08  jake
22  * Alternate update interface, updatev. Returns info about CDPs written to disk as result of update. Output format is similar to rrd_info, a hash of key-values.
23  *
24  * Revision 1.4  2003/04/01 22:52:23  jake
25  * Fix Win32 build. VC++ 6.0 and 7.0 now use the thread-safe code.
26  *
27  * Revision 1.3  2003/02/13 07:05:27  oetiker
28  * Find attached the patch I promised to send to you. Please note that there
29  * are three new source files (src/rrd_is_thread_safe.h, src/rrd_thread_safe.c
30  * and src/rrd_not_thread_safe.c) and the introduction of librrd_th. This
31  * library is identical to librrd, but it contains support code for per-thread
32  * global variables currently used for error information only. This is similar
33  * to how errno per-thread variables are implemented.  librrd_th must be linked
34  * alongside of libpthred
35  *
36  * There is also a new file "THREADS", holding some documentation.
37  *
38  * -- Peter Stamfest <peter@stamfest.at>
39  *
40  * Revision 1.2  2002/05/07 21:58:32  oetiker
41  * new command rrdtool xport integrated
42  * --  Wolfgang Schrimm <Wolfgang.Schrimm@urz.uni-heidelberg.de>
43  *
44  * Revision 1.1.1.1  2001/02/25 22:25:05  oetiker
45  * checkin
46  *
47  *****************************************************************************/
48 #ifdef  __cplusplus
49 extern    "C" {
50 #endif
52 #ifndef _RRDLIB_H
53 #define _RRDLIB_H
55 #include <sys/types.h>  /* for off_t */
56 #include <unistd.h>     /* for off_t */
57 #include <time.h>
58 #include <stdio.h>      /* for FILE */
61 /* Formerly rrd_nan_inf.h */
62 #ifndef DNAN
63 # define DNAN set_to_DNAN()
64 #endif
66 #ifndef DINF
67 # define DINF set_to_DINF()
68 #endif
69     double    set_to_DNAN(
70     void);
71     double    set_to_DINF(
72     void);
73 /* end of rrd_nan_inf.h */
75 /* Transplanted from rrd_format.h */
76     typedef double rrd_value_t; /* the data storage type is
77                                  * double */
78 /* END rrd_format.h */
80 /* information about an rrd file */
81     typedef struct rrd_file_t {
82         int       fd;   /* file descriptor if this rrd file */
83         char     *file_start;   /* start address of an open rrd file */
84         off_t     header_len;   /* length of the header of this rrd file */
85         off_t     file_len; /* total size of the rrd file */
86         off_t     pos;  /* current pos in file */
87     } rrd_file_t;
89 /* rrd info interface */
90     typedef struct rrd_blob_t {
91         unsigned long size; /* size of the blob */
92         unsigned char *ptr; /* pointer */
93     } rrd_blob_t;
95     enum info_type { RD_I_VAL = 0,
96         RD_I_CNT,
97         RD_I_STR,
98         RD_I_INT,
99         RD_I_BLO
100     };
102     typedef union infoval {
103         unsigned long u_cnt;
104         rrd_value_t u_val;
105         char     *u_str;
106         int       u_int;
107         struct rrd_blob_t u_blo;
108     } infoval;
110     typedef struct info_t {
111         char     *key;
112         enum info_type type;
113         union infoval value;
114         struct info_t *next;
115     } info_t;
118 /* main function blocks */
119     int       rrd_create(
120     int,
121     char **);
122     int       rrd_update(
123     int,
124     char **);
125     int       rrd_graph(
126     int,
127     char **,
128     char ***,
129     int *,
130     int *,
131     FILE *,
132     double *,
133     double *);
134     info_t   *rrd_graph_v(
135     int,
136     char **);
138     int       rrd_fetch(
139     int,
140     char **,
141     time_t *,
142     time_t *,
143     unsigned long *,
144     unsigned long *,
145     char ***,
146     rrd_value_t **);
147     int       rrd_restore(
148     int,
149     char **);
150     int       rrd_dump(
151     int,
152     char **);
153     int       rrd_tune(
154     int,
155     char **);
156     time_t    rrd_last(
157     int,
158     char **);
159     time_t    rrd_first(
160     int,
161     char **);
162     int       rrd_resize(
163     int,
164     char **);
165     char     *rrd_strversion(
166     void);
167     double    rrd_version(
168     void);
169     int       rrd_xport(
170     int,
171     char **,
172     int *,
173     time_t *,
174     time_t *,
175     unsigned long *,
176     unsigned long *,
177     char ***,
178     rrd_value_t **);
180 /* thread-safe (hopefully) */
181     int       rrd_create_r(
182     const char *filename,
183     unsigned long pdp_step,
184     time_t last_up,
185     int argc,
186     const char **argv);
187 /* NOTE: rrd_update_r are only thread-safe if no at-style time
188    specifications get used!!! */
190     int       rrd_update_r(
191     const char *filename,
192     const char *_template,
193     int argc,
194     const char **argv);
195     int       rrd_fetch_r(
196     const char *filename,
197     const char *cf,
198     time_t *start,
199     time_t *end,
200     unsigned long *step,
201     unsigned long *ds_cnt,
202     char ***ds_namv,
203     rrd_value_t **data);
204     int       rrd_dump_r(
205     const char *filename,
206     char *outname);
207     time_t    rrd_last_r(
208     const char *filename);
209     time_t    rrd_first_r(
210     const char *filename,
211     int rraindex);
213 /* Transplanted from parsetime.h */
214     typedef enum {
215         ABSOLUTE_TIME,
216         RELATIVE_TO_START_TIME,
217         RELATIVE_TO_END_TIME
218     } timetype;
220 #define TIME_OK NULL
222     struct rrd_time_value {
223         timetype  type;
224         long      offset;
225         struct tm tm;
226     };
228     char     *parsetime(
229     const char *spec,
230     struct rrd_time_value *ptv);
231 /* END parsetime.h */
233     struct rrd_context {
234         int       len;
235         int       errlen;
236         char     *lib_errstr;
237         char     *rrd_error;
238     };
240 /* returns the current per-thread rrd_context */
241     struct rrd_context *rrd_get_context(
242     void);
245     int       proc_start_end(
246     struct rrd_time_value *,
247     struct rrd_time_value *,
248     time_t *,
249     time_t *);
251 /* HELPER FUNCTIONS */
252     void      rrd_set_error(
253     char *,
254     ...);
255     void      rrd_clear_error(
256     void);
257     int       rrd_test_error(
258     void);
259     char     *rrd_get_error(
260     void);
262 /** MULTITHREADED HELPER FUNCTIONS */
263     struct rrd_context *rrd_new_context(
264     void);
265     void      rrd_free_context(
266     struct rrd_context *buf);
268 /* void   rrd_set_error_r  (struct rrd_context *, char *, ...); */
269 /* void   rrd_clear_error_r(struct rrd_context *); */
270 /* int    rrd_test_error_r (struct rrd_context *); */
271 /* char  *rrd_get_error_r  (struct rrd_context *); */
273     int       LockRRD(
274     int in_file);
276 #endif                  /* _RRDLIB_H */
278 #ifdef  __cplusplus
280 #endif