src/rrd.h

   1 #ifndef RRDLIB_H_4FD7D37D56A448C392AF46508C56D3CC
   2 #define RRDLIB_H_4FD7D37D56A448C392AF46508C56D3CC
   3
   4 /*****************************************************************************
   5  * RRDtool 1.7.2 Copyright by Tobi Oetiker, 1997-2019
   6  *****************************************************************************
   7  * rrdlib.h   Public header file for librrd
   8  *****************************************************************************
   9  * $Id$
  10  * $Log$
  11  * Revision 1.9  2005/02/13 16:13:33  oetiker
  12  * let rrd_graph return the actual value range it picked ...
  13  * -- Henrik Stoerner <henrik@hswn.dk>
  14  *
  15  * Revision 1.8  2004/05/26 22:11:12  oetiker
  16  * reduce compiler warnings. Many small fixes. -- Mike Slifcak <slif@bellsouth.net>
  17  *
  18  * Revision 1.7  2003/11/12 22:14:26  oetiker
  19  * allow to pass an open filehandle into rrd_graph as an extra argument
  20  *
  21  * Revision 1.6  2003/11/11 19:46:21  oetiker
  22  * replaced time_value with rrd_time_value as MacOS X introduced a struct of that name in their standard headers
  23  *
  24  * Revision 1.5  2003/04/25 18:35:08  jake
  25  * 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.
  26  *
  27  * Revision 1.4  2003/04/01 22:52:23  jake
  28  * Fix Win32 build. VC++ 6.0 and 7.0 now use the thread-safe code.
  29  *
  30  * Revision 1.3  2003/02/13 07:05:27  oetiker
  31  * Find attached the patch I promised to send to you. Please note that there
  32  * are three new source files (src/rrd_is_thread_safe.h, src/rrd_thread_safe.c
  33  * and src/rrd_not_thread_safe.c) and the introduction of librrd_th. This
  34  * library is identical to librrd, but it contains support code for per-thread
  35  * global variables currently used for error information only. This is similar
  36  * to how errno per-thread variables are implemented.  librrd_th must be linked
  37  * alongside of libpthread
  38  *
  39  * There is also a new file "THREADS", holding some documentation.
  40  *
  41  * -- Peter Stamfest <peter@stamfest.at>
  42  *
  43  * Revision 1.2  2002/05/07 21:58:32  oetiker
  44  * new command rrdtool xport integrated
  45  * --  Wolfgang Schrimm <Wolfgang.Schrimm@urz.uni-heidelberg.de>
  46  *
  47  * Revision 1.1.1.1  2001/02/25 22:25:05  oetiker
  48  * checkin
  49  *
  50  *****************************************************************************/
  51 #ifdef  __cplusplus
  52 extern    "C" {
  53 #endif
  54
  55 #include <sys/types.h>  /* for off_t */
  56
  57 #ifndef _WIN32
  58 #include <unistd.h>     /* for off_t */
  59 #endif
  60
  61 #ifdef _MSC_VER
  62 #include <BaseTsd.h>
  63     typedef SSIZE_T ssize_t;
  64 #ifndef PERLPATCHLEVEL
  65     typedef int mode_t;
  66 #endif
  67 #if _MSC_VER < 1800
  68 #define strtoll _strtoi64
  69 #endif
  70 #endif
  71
  72 #include <time.h>
  73 #include <stdio.h>      /* for FILE */
  74 #include <string.h>
  75
  76 /* Formerly rrd_nan_inf.h */
  77 #ifndef DNAN
  78 # define DNAN rrd_set_to_DNAN()
  79 #endif
  80
  81 /* declare opaque data structure, so we can use its pointers for type safety */
  82
  83     struct rrd_t;
  84
  85 #ifndef DINF
  86 # define DINF rrd_set_to_DINF()
  87 #endif
  88     double    rrd_set_to_DNAN(
  89     void);
  90     double    rrd_set_to_DINF(
  91     void);
  92 /* end of rrd_nan_inf.h */
  93
  94 /* Transplanted from rrd_format.h */
  95     typedef double rrd_value_t; /* the data storage type is
  96                                  * double */
  97 /* END rrd_format.h */
  98
  99 /* information about an rrd file */
 100     typedef struct rrd_file_t {
 101         size_t    header_len;   /* length of the header of this rrd file */
 102         size_t    file_len; /* total size of the rrd file */
 103         size_t    pos;  /* current pos in file */
 104         void     *pvt;
 105         struct rrd_t *rrd;  /* the corresponding RRD structure, if any */
 106 #ifdef HAVE_LIBRADOS
 107         struct rrd_rados_t *rados;
 108 #endif
 109     } rrd_file_t;
 110
 111 /* information used for the conventional file access methods */
 112     typedef struct rrd_simple_file_t {
 113         int       fd;   /* file descriptor of this rrd file */
 114 #ifdef HAVE_MMAP
 115         char     *file_start;   /* start address of an open rrd file */
 116         int       mm_prot;
 117         int       mm_flags;
 118 #endif
 119     } rrd_simple_file_t;
 120
 121 /* rrd info interface */
 122     typedef struct rrd_blob_t {
 123         unsigned long size; /* size of the blob */
 124         unsigned char *ptr; /* pointer */
 125     } rrd_blob_t;
 126
 127     typedef enum rrd_info_type { RD_I_VAL = 0,
 128         RD_I_CNT,
 129         RD_I_STR,
 130         RD_I_INT,
 131         RD_I_BLO
 132     } rrd_info_type_t;
 133
 134     typedef union rrd_infoval {
 135         unsigned long u_cnt;
 136         rrd_value_t u_val;
 137         char     *u_str;
 138         int       u_int;
 139         rrd_blob_t u_blo;
 140     } rrd_infoval_t;
 141
 142     typedef struct rrd_info_t {
 143         char     *key;
 144         rrd_info_type_t type;
 145         rrd_infoval_t value;
 146         struct rrd_info_t *next;
 147     } rrd_info_t;
 148
 149     typedef size_t (
 150     *rrd_output_callback_t) (
 151     const void *,
 152     size_t,
 153     void *);
 154
 155 /* main function blocks */
 156     int       rrd_create(
 157     int,
 158     char **);
 159     rrd_info_t *rrd_info(
 160     int,
 161     char **);
 162     rrd_info_t *rrd_info_push(
 163     rrd_info_t *,
 164     char *,
 165     rrd_info_type_t,
 166     rrd_infoval_t);
 167     void      rrd_info_print(
 168     rrd_info_t *data);
 169     void      rrd_info_free(
 170     rrd_info_t *);
 171     char     *rrd_list(
 172     int,
 173     char **);
 174     char     *rrd_list_r(
 175     int,
 176     char *dirname);
 177     int       rrd_update(
 178     int,
 179     char **);
 180     rrd_info_t *rrd_update_v(
 181     int,
 182     char **);
 183     int       rrd_graph(
 184     int,
 185     char **,
 186     char ***,
 187     int *,
 188     int *,
 189     FILE *,
 190     double *,
 191     double *);
 192     rrd_info_t *rrd_graph_v(
 193     int,
 194     char **);
 195
 196     int       rrd_fetch(
 197     int,
 198     char **,
 199     time_t *,
 200     time_t *,
 201     unsigned long *,
 202     unsigned long *,
 203     char ***,
 204     rrd_value_t **);
 205     int       rrd_restore(
 206     int,
 207     char **);
 208     int       rrd_dump(
 209     int,
 210     char **);
 211     int       rrd_tune(
 212     int,
 213     char **);
 214     time_t    rrd_last(
 215     int,
 216     char **);
 217     int       rrd_lastupdate(
 218     int argc,
 219     char **argv);
 220     time_t    rrd_first(
 221     int,
 222     char **);
 223     int       rrd_resize(
 224     int,
 225     char **);
 226     char     *rrd_strversion(
 227     void);
 228     double    rrd_version(
 229     void);
 230     int       rrd_xport(
 231     int,
 232     char **,
 233     int *,
 234     time_t *,
 235     time_t *,
 236     unsigned long *,
 237     unsigned long *,
 238     char ***,
 239     rrd_value_t **);
 240     int       rrd_flushcached(
 241     int argc,
 242     char **argv);
 243
 244     void      rrd_freemem(
 245     void *mem);
 246
 247 /* thread-safe (hopefully) */
 248     int       rrd_create_r(
 249     const char *filename,
 250     unsigned long pdp_step,
 251     time_t last_up,
 252     /* int no_overwrite, */
 253     int argc,
 254     const char **argv);
 255     int       rrd_create_r2(
 256     const char *filename,
 257     unsigned long pdp_step,
 258     time_t last_up,
 259     int no_overwrite,
 260     const char **sources,
 261     const char *_template,
 262     int argc,
 263     const char **argv);
 264     rrd_info_t *rrd_info_r(
 265     const char *);
 266 /* NOTE: rrd_update_r and rrd_update_v_r are only thread-safe if no at-style
 267    time specifications get used!!! */
 268
 269     int       rrd_update_r(
 270     const char *filename,
 271     const char *_template,
 272     int argc,
 273     const char **argv);
 274     int       rrd_update_v_r(
 275     const char *filename,
 276     const char *_template,
 277     int argc,
 278     const char **argv,
 279     rrd_info_t *pcdp_summary);
 280
 281 /* extra flags */
 282 #define RRD_SKIP_PAST_UPDATES 0x01
 283
 284     int       rrd_updatex_r(
 285     const char *filename,
 286     const char *_template,
 287     int extra_flags,
 288     int argc,
 289     const char **argv);
 290     int       rrd_updatex_v_r(
 291     const char *filename,
 292     const char *_template,
 293     int extra_flags,
 294     int argc,
 295     const char **argv,
 296     rrd_info_t *pcdp_summary);
 297     int       rrd_fetch_r(
 298     const char *filename,
 299     const char *cf,
 300     time_t *start,
 301     time_t *end,
 302     unsigned long *step,
 303     unsigned long *ds_cnt,
 304     char ***ds_namv,
 305     rrd_value_t **data);
 306     int       rrd_tune_r(
 307     const char *filename,
 308     int argc,
 309     const char **argv);
 310     int       rrd_dump_opt_r(
 311     const char *filename,
 312     char *outname,
 313     int opt_noheader);
 314     int       rrd_dump_r(
 315     const char *filename,
 316     char *outname);
 317     time_t    rrd_last_r(
 318     const char *filename);
 319     int       rrd_lastupdate_r(
 320     const char *filename,
 321     time_t *ret_last_update,
 322     unsigned long *ret_ds_count,
 323     char ***ret_ds_names,
 324     char ***ret_last_ds);
 325     time_t    rrd_first_r(
 326     const char *filename,
 327     const int rraindex);
 328
 329     int       rrd_dump_cb_r(
 330     const char *filename,
 331     int opt_header,
 332     rrd_output_callback_t cb,
 333     void *user);
 334
 335 /* Transplanted from rrd_parsetime.h */
 336     typedef enum {
 337         ABSOLUTE_TIME,
 338         RELATIVE_TO_START_TIME,
 339         RELATIVE_TO_END_TIME,
 340         RELATIVE_TO_EPOCH
 341     } rrd_timetype_t;
 342
 343 #define TIME_OK NULL
 344
 345     typedef struct rrd_time_value {
 346         rrd_timetype_t type;
 347         long      offset;
 348         struct tm tm;
 349     } rrd_time_value_t;
 350
 351     char     *rrd_parsetime(
 352     const char *spec,
 353     rrd_time_value_t *ptv);
 354 /* END rrd_parsetime.h */
 355
 356     typedef struct rrd_context {
 357         char      lib_errstr[256];
 358         char      rrd_error[4096];
 359     } rrd_context_t;
 360
 361 /* returns the current per-thread rrd_context */
 362     rrd_context_t *rrd_get_context(
 363     void);
 364
 365 #ifdef _WIN32
 366 /* this was added by the win32 porters Christof.Wegmann@exitgames.com */
 367     rrd_context_t *rrd_force_new_context(
 368     void);
 369 #endif
 370
 371     int       rrd_proc_start_end(
 372     rrd_time_value_t *,
 373     rrd_time_value_t *,
 374     time_t *,
 375     time_t *);
 376
 377 /* HELPER FUNCTIONS */
 378     void      rrd_set_error(
 379     char *,
 380     ...);
 381     void      rrd_clear_error(
 382     void);
 383     int       rrd_test_error(
 384     void);
 385     char     *rrd_get_error(
 386     void);
 387
 388     /* rrd_strerror is thread safe, but still it uses a global buffer
 389        (but one per thread), thus subsequent calls within a single
 390        thread overwrite the same buffer */
 391     const char *rrd_strerror(
 392     int err);
 393
 394 /** MULTITHREADED HELPER FUNCTIONS */
 395     rrd_context_t *rrd_new_context(
 396     void);
 397     void      rrd_free_context(
 398     rrd_context_t *buf);
 399
 400 /* void   rrd_set_error_r  (rrd_context_t *, char *, ...); */
 401 /* void   rrd_clear_error_r(rrd_context_t *); */
 402 /* int    rrd_test_error_r (rrd_context_t *); */
 403 /* char  *rrd_get_error_r  (rrd_context_t *); */
 404
 405 /** UTILITY FUNCTIONS */
 406
 407     long      rrd_random(
 408     void);
 409
 410     int       rrd_add_ptr_chunk(
 411     void ***dest,
 412     size_t *dest_size,
 413     void *src,
 414     size_t *alloc,
 415     size_t chunk);
 416     int       rrd_add_ptr(
 417     void ***dest,
 418     size_t *dest_size,
 419     void *src);
 420     int       rrd_add_strdup(
 421     char ***dest,
 422     size_t *dest_size,
 423     char *src);
 424     int       rrd_add_strdup_chunk(
 425     char ***dest,
 426     size_t *dest_size,
 427     char *src,
 428     size_t *alloc,
 429     size_t chunk);
 430     void      rrd_free_ptrs(
 431     void ***src,
 432     size_t *cnt);
 433
 434     int       rrd_mkdir_p(
 435     const char *pathname,
 436     mode_t mode);
 437
 438     const char *rrd_scaled_duration(
 439     const char *token,
 440     unsigned long divisor,
 441     unsigned long *valuep);
 442     void      rrd_thread_init(
 443     void);
 444
 445 /*
 446  * The following functions are _internal_ functions needed to read the raw RRD
 447  * files. Since they are _internal_ they may change with the file format and
 448  * will be replaced with a more general interface in RRDtool 1.7.2 Don't use
 449  * these functions unless you have good reasons to do so. If you do use these
 450  * functions you will have to adapt your code for RRDtool 1.7.2
 451  *
 452  * To enable the deprecated functions define `RRD_EXPORT_DEPRECATED' before
 453  * including <rrd_test.h>. You have been warned! If you come back to the
 454  * RRDtool mailing list and whine about your broken application, you will get
 455  * hit with something smelly!
 456  */
 457 #if defined(RRD_TOOL_H_3853987DDF7E4709A5B5849E5A6204F4) || defined(RRD_EXPORT_DEPRECATED)
 458
 459 # if defined(RRD_TOOL_H_3853987DDF7E4709A5B5849E5A6204F4)
 460 #  include "rrd_format.h"
 461 # else
 462 #  include <rrd_format.h>
 463 # endif
 464
 465 #if defined(__GNUC__) && defined (RRD_EXPORT_DEPRECATED)
 466 # define RRD_DEPRECATED __attribute__((deprecated))
 467 #else
 468 # define RRD_DEPRECATED          /**/
 469 #endif
 470     void      rrd_free(
 471     rrd_t *rrd)
 472               RRD_DEPRECATED;
 473     void      rrd_init(
 474     rrd_t *rrd)
 475               RRD_DEPRECATED;
 476
 477     rrd_file_t *rrd_open(
 478     const char *const file_name,
 479     rrd_t *rrd,
 480     unsigned rdwr)
 481               RRD_DEPRECATED;
 482
 483     void      rrd_dontneed(
 484     rrd_file_t *rrd_file,
 485     rrd_t *rrd)
 486               RRD_DEPRECATED;
 487     int       rrd_close(
 488     rrd_file_t *rrd_file)
 489               RRD_DEPRECATED;
 490     ssize_t   rrd_read(
 491     rrd_file_t *rrd_file,
 492     void *buf,
 493     size_t count)
 494               RRD_DEPRECATED;
 495     ssize_t   rrd_write(
 496     rrd_file_t *rrd_file,
 497     const void *buf,
 498     size_t count)
 499               RRD_DEPRECATED;
 500     void      rrd_flush(
 501     rrd_file_t *rrd_file)
 502               RRD_DEPRECATED;
 503     off_t     rrd_seek(
 504     rrd_file_t *rrd_file,
 505     off_t off,
 506     int whence)
 507               RRD_DEPRECATED;
 508     off_t     rrd_tell(
 509     rrd_file_t *rrd_file)
 510               RRD_DEPRECATED;
 511     int       rrd_lock(
 512     rrd_file_t *file)
 513               RRD_DEPRECATED;
 514     void      rrd_notify_row(
 515     rrd_file_t *rrd_file,
 516     int rra_idx,
 517     unsigned long rra_row,
 518     time_t rra_time)
 519               RRD_DEPRECATED;
 520     unsigned long rrd_select_initial_row(
 521     rrd_file_t *rrd_file,
 522     int rra_idx,
 523     rra_def_t *rra)
 524               RRD_DEPRECATED;
 525 #endif                  /* defined(_RRD_TOOL_H) || defined(RRD_EXPORT_DEPRECATED) */
 526
 527 #ifdef  __cplusplus
 528 }
 529 #endif
 530 #endif                  /* RRDLIB_H */