src/rrd.h

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