src/rrd.h

   1 /*****************************************************************************
   2  * RRDtool 1.2.99907080300  Copyright by Tobi Oetiker, 1997-2007
   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
  51
  52 #ifndef _RRDLIB_H
  53 #define _RRDLIB_H
  54
  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 */
  59
  60
  61 /* Formerly rrd_nan_inf.h */
  62 #ifndef DNAN
  63 # define DNAN set_to_DNAN()
  64 #endif
  65
  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 */
  74
  75 /* Transplanted from rrd_format.h */
  76     typedef double rrd_value_t; /* the data storage type is
  77                                  * double */
  78 /* END rrd_format.h */
  79
  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;
  88
  89 /* main function blocks */
  90     int       rrd_create(
  91     int,
  92     char **);
  93     int       rrd_update(
  94     int,
  95     char **);
  96     int       rrd_graph(
  97     int,
  98     char **,
  99     char ***,
 100     int *,
 101     int *,
 102     FILE *,
 103     double *,
 104     double *);
 105
 106     unsigned char *rrd_graph_in_memory(
 107     int argc,
 108     char **argv,
 109     char ***prdata,
 110     int *xsize,
 111     int *ysize,
 112     double *ymin,
 113     double *ymax,
 114     size_t * img_size);
 115
 116     int       rrd_fetch(
 117     int,
 118     char **,
 119     time_t *,
 120     time_t *,
 121     unsigned long *,
 122     unsigned long *,
 123     char ***,
 124     rrd_value_t **);
 125     int       rrd_restore(
 126     int,
 127     char **);
 128     int       rrd_dump(
 129     int,
 130     char **);
 131     int       rrd_tune(
 132     int,
 133     char **);
 134     time_t    rrd_last(
 135     int,
 136     char **);
 137     time_t    rrd_first(
 138     int,
 139     char **);
 140     int       rrd_resize(
 141     int,
 142     char **);
 143     char     *rrd_strversion(
 144     void);
 145     double    rrd_version(
 146     void);
 147     int       rrd_xport(
 148     int,
 149     char **,
 150     int *,
 151     time_t *,
 152     time_t *,
 153     unsigned long *,
 154     unsigned long *,
 155     char ***,
 156     rrd_value_t **);
 157
 158 /* thread-safe (hopefully) */
 159     int       rrd_create_r(
 160     const char *filename,
 161     unsigned long pdp_step,
 162     time_t last_up,
 163     int argc,
 164     const char **argv);
 165 /* NOTE: rrd_update_r are only thread-safe if no at-style time
 166    specifications get used!!! */
 167
 168     int       rrd_update_r(
 169     const char *filename,
 170     const char *_template,
 171     int argc,
 172     const char **argv);
 173     int       rrd_fetch_r(
 174     const char *filename,
 175     const char *cf,
 176     time_t *start,
 177     time_t *end,
 178     unsigned long *step,
 179     unsigned long *ds_cnt,
 180     char ***ds_namv,
 181     rrd_value_t **data);
 182     int       rrd_dump_r(
 183     const char *filename,
 184     char *outname);
 185     time_t    rrd_last_r(
 186     const char *filename);
 187     time_t    rrd_first_r(
 188     const char *filename,
 189     int rraindex);
 190
 191 /* Transplanted from parsetime.h */
 192     typedef enum {
 193         ABSOLUTE_TIME,
 194         RELATIVE_TO_START_TIME,
 195         RELATIVE_TO_END_TIME
 196     } timetype;
 197
 198 #define TIME_OK NULL
 199
 200     struct rrd_time_value {
 201         timetype  type;
 202         long      offset;
 203         struct tm tm;
 204     };
 205
 206     char     *parsetime(
 207     const char *spec,
 208     struct rrd_time_value *ptv);
 209 /* END parsetime.h */
 210
 211     struct rrd_context {
 212         int       len;
 213         int       errlen;
 214         char     *lib_errstr;
 215         char     *rrd_error;
 216     };
 217
 218 /* returns the current per-thread rrd_context */
 219     struct rrd_context *rrd_get_context(
 220     void);
 221
 222
 223     int       proc_start_end(
 224     struct rrd_time_value *,
 225     struct rrd_time_value *,
 226     time_t *,
 227     time_t *);
 228
 229 /* HELPER FUNCTIONS */
 230     void      rrd_set_error(
 231     char *,
 232     ...);
 233     void      rrd_clear_error(
 234     void);
 235     int       rrd_test_error(
 236     void);
 237     char     *rrd_get_error(
 238     void);
 239
 240 /** MULTITHREADED HELPER FUNCTIONS */
 241     struct rrd_context *rrd_new_context(
 242     void);
 243     void      rrd_free_context(
 244     struct rrd_context *buf);
 245
 246 /* void   rrd_set_error_r  (struct rrd_context *, char *, ...); */
 247 /* void   rrd_clear_error_r(struct rrd_context *); */
 248 /* int    rrd_test_error_r (struct rrd_context *); */
 249 /* char  *rrd_get_error_r  (struct rrd_context *); */
 250
 251     int       LockRRD(
 252     int in_file);
 253
 254 #endif                  /* _RRDLIB_H */
 255
 256 #ifdef  __cplusplus
 257 }
 258 #endif