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