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