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