binlog.h

   1 #ifndef INCLUDE_binlog_h
   2 #define INCLUDE_binlog_h
   3 #include <unistd.h>
   4 /**
   5  * @file binlog.h
   6  * @brief binary logging functions
   7  * @defgroup merlin-util Merlin utility functions
   8  * @ingroup Merlin utility functions
   9  * @{
  10  */
  11
  12 /** A binary log. */
  13 typedef struct binlog binlog;
  14
  15 #define BINLOG_APPEND 1
  16 #define BINLOG_UNLINK 2
  17
  18 /**
  19  * Check if binlog is valid.
  20  * "valid" in this case means "has it escaped being invalidated"?
  21  * @param bl The binary log to check for validity
  22  * @return 1 if the binlog is valid, 0 otherwise
  23  */
  24 extern int binlog_is_valid(binlog *bl);
  25
  26 /**
  27  * Invalidate the binlog
  28  * This is useful for applications that requires their binlogs to
  29  * be sequential.
  30  * @param bl The binary log to operate on
  31  */
  32 extern void binlog_invalidate(binlog *bl);
  33
  34 /**
  35  * Get the on-disk binlog storage path
  36  * @param bl The binary log whose path we should return
  37  * @return The on-disk binlog storage path
  38  */
  39 extern const char *binlog_path(binlog *bl);
  40
  41 /**
  42  * Create a binary logging object. If fsize is 0, path may be NULL.
  43  * @param path The path to store on-disk logs.
  44  * @param msize The maximum amount of memory used for storing
  45  *              events in the mem-cache of this backlog.
  46  * @param fsize The max size files are allowed to grow to.
  47  * @param flags Decide what to do with an already existing file at path
  48  * @return A binlog object on success, NULL on errors.
  49  */
  50 extern binlog *binlog_create(const char *path, unsigned int msize, unsigned int fsize, int flags);
  51
  52 /**
  53  * Get the number of unread entries in the binlog
  54  * @param bl The binary log to examine
  55  * @returns Number of entries in binlog
  56  */
  57 extern unsigned int binlog_num_entries(binlog *bl);
  58 #define binlog_has_entries(bl) binlog_num_entries(bl)
  59 #define binlog_entries(bl) binlog_num_entries(bl)
  60
  61 /**
  62  * Wipes a binary log, freeing all memory associated with it and
  63  * restoring the old defaults. Also validates the binlog again,
  64  * making it re-usable.
  65  * @param bl The binlog to wipe
  66  * @param flags takes BINLOG_UNLINK to remove the file from disk
  67  */
  68 extern void binlog_wipe(binlog *bl, int flags);
  69
  70 /**
  71  * Destroys a binary log, freeing all memory associated with it and
  72  * optionally unlinking the on-disk log (if any).
  73  * @param bl The binary log object.
  74  * @param flags Takes BINLOG_UNLINK to remove the file from disk
  75  * @return 0 on success. < 0 on failure.
  76  */
  77 extern void binlog_destroy(binlog *bl, int flags);
  78
  79 /**
  80  * Read the first (sequential) event from the binary log.
  81  * @param bl The binary log object.
  82  * @param buf A pointer to the pointer where data will be stored.
  83  * @param len A pointer to where the size of the logged event will be stored.
  84  * @return 0 on success. < 0 on failure.
  85  */
  86 extern int binlog_read(binlog *bl, void **buf, unsigned int *len);
  87
  88 /**
  89  * "unread" one entry from the binlog. This lets one maintain
  90  * sequential reading from the binlog even when event processing
  91  * fails. Note that the data isn't duplicated again here, since
  92  * the most common case is that the recently read data is pushed
  93  * back immediately after whatever action was supposed to be
  94  * taken on it has failed.
  95  * @param bl The binlog to unread() from/to
  96  * @param buf The data to unread
  97  * @param len The length of the data to read
  98  * @return 0 on success. < 0 on failure.
  99  */
 100 extern int binlog_unread(binlog *bl, void *buf, unsigned int len);
 101
 102 /**
 103  * Add an event to the binary log.
 104  * If maximum memory size for the in-memory cache has been, or
 105  * would have been exceeded by adding the new event, all in-memory
 106  * events are flushed to disk and the mem-cache is reset.
 107  * @param bl The binary log object.
 108  * @param buf A pointer to the data involved in the event.
 109  * @param len The size of the data to store.
 110  * @return 0 on success. < 0 on failure.
 111  */
 112 extern int binlog_add(binlog *bl, void *buf, unsigned int len);
 113
 114 /**
 115  * Close a file associated to a binary log. In normal circum-
 116  * stances, files are kept open until binary log is flushed
 117  * in order to increase performance. This is a means for a
 118  * program that makes heavy use of file-descriptors to free
 119  * some up for its normal operations should it ever run out.
 120  * @param bl The binary log object.
 121  * @return The return value of close(2).
 122  */
 123 extern int binlog_close(binlog *bl);
 124
 125 /**
 126  * Flush in-memory events to disk, releasing all the memory
 127  * allocated to the events.
 128  * @param bl The binary log object.
 129  * @return 0 on success. < 0 on failure.
 130  */
 131 extern int binlog_flush(binlog *bl);
 132
 133 /**
 134  * Get binlog memory consumption size
 135  * @param bl The binary log object.
 136  * @return memory consumption
 137  */
 138 extern unsigned int binlog_msize(binlog *bl);
 139
 140 /**
 141  * Get on-disk binlog size
 142  * @param bl The binary log object.
 143  * @return disk storage consumption
 144  */
 145 extern unsigned int binlog_fsize(binlog *bl);
 146
 147 /**
 148  * Get binlog size
 149  * @param bl The binary log object.
 150  * @return disk storage consumption and memory consumption
 151  */
 152 extern unsigned int binlog_size(binlog *bl);
 153
 154 /**
 155  * Get number of available entries in the binlog
 156  * @param bl The binary log objects.
 157  * @return Number of bytes available for reading from this log
 158  */
 159 extern unsigned int binlog_available(binlog *bl);
 160
 161 /** warning condition for backlog base path having insecure permissions */
 162 #define BINLOG_UNSAFE  1
 163
 164 /** failed to stat() backlog base path or non-empty backlog path */
 165 #define BINLOG_ESTAT   (-1)
 166
 167 /** backlog base path is not a directory */
 168 #define BINLOG_ENOTDIR (-2)
 169
 170 /** backlog_open() requested with no path set */
 171 #define BINLOG_ENOPATH (-3)
 172
 173 /** incomplete write to backlog */
 174 #define BINLOG_EINCOMPLETE (-4)
 175
 176 /** attempt to read from empty binlog */
 177 #define BINLOG_EMPTY (-5)
 178
 179 /**
 180  * backlog was invalidated due to incomplete write followed by
 181  * failed lseek(2) to original position
 182  */
 183 #define BINLOG_EINVALID (-6)
 184
 185 /** Binlog is full but attempted to write to it anyway */
 186 #define BINLOG_ENOSPC (-7)
 187
 188 /** An event was dropped for some reason (not out-of-space) */
 189 #define BINLOG_EDROPPED (-8)
 190
 191 /** A NULL pointer was passed when a pointer was expected */
 192 #define BINLOG_EADDRESS (-9)
 193
 194 /** @} */
 195 #endif