tdb2.h 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712
  1. #ifndef CCAN_TDB2_H
  2. #define CCAN_TDB2_H
  3. /*
  4. TDB version 2: trivial database library
  5. Copyright (C) Andrew Tridgell 1999-2004
  6. Copyright (C) Rusty Russell 2010-2011
  7. ** NOTE! The following LGPL license applies to the tdb
  8. ** library. This does NOT imply that all of Samba is released
  9. ** under the LGPL
  10. This library is free software; you can redistribute it and/or
  11. modify it under the terms of the GNU Lesser General Public
  12. License as published by the Free Software Foundation; either
  13. version 3 of the License, or (at your option) any later version.
  14. This library is distributed in the hope that it will be useful,
  15. but WITHOUT ANY WARRANTY; without even the implied warranty of
  16. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17. Lesser General Public License for more details.
  18. You should have received a copy of the GNU Lesser General Public
  19. License along with this library; if not, see <http://www.gnu.org/licenses/>.
  20. */
  21. #ifdef __cplusplus
  22. extern "C" {
  23. #endif
  24. #ifndef _SAMBA_BUILD_
  25. /* For mode_t */
  26. #include <sys/types.h>
  27. /* For O_* flags. */
  28. #include <sys/stat.h>
  29. /* For sig_atomic_t. */
  30. #include <signal.h>
  31. /* For uint64_t */
  32. #include <stdint.h>
  33. /* For bool */
  34. #include <stdbool.h>
  35. /* For memcmp */
  36. #include <string.h>
  37. #endif
  38. #include <ccan/compiler/compiler.h>
  39. #include <ccan/typesafe_cb/typesafe_cb.h>
  40. #include <ccan/cast/cast.h>
  41. union tdb_attribute;
  42. struct tdb_context;
  43. /**
  44. * tdb_open - open a database file
  45. * @name: the file name (can be NULL if flags contains TDB_INTERNAL)
  46. * @tdb_flags: options for this database
  47. * @open_flags: flags argument for tdb's open() call.
  48. * @mode: mode argument for tdb's open() call.
  49. * @attributes: linked list of extra attributes for this tdb.
  50. *
  51. * This call opens (and potentially creates) a database file.
  52. * Multiple processes can have the TDB file open at once.
  53. *
  54. * On failure it will return NULL, and set errno: it may also call
  55. * any log attribute found in @attributes.
  56. *
  57. * See also:
  58. * union tdb_attribute
  59. */
  60. struct tdb_context *tdb_open(const char *name, int tdb_flags,
  61. int open_flags, mode_t mode,
  62. union tdb_attribute *attributes);
  63. /* flags for tdb_open() */
  64. #define TDB_DEFAULT 0 /* just a readability place holder */
  65. #define TDB_INTERNAL 2 /* don't store on disk */
  66. #define TDB_NOLOCK 4 /* don't do any locking */
  67. #define TDB_NOMMAP 8 /* don't use mmap */
  68. #define TDB_CONVERT 16 /* convert endian */
  69. #define TDB_NOSYNC 64 /* don't use synchronous transactions */
  70. #define TDB_SEQNUM 128 /* maintain a sequence number */
  71. /**
  72. * tdb_close - close and free a tdb.
  73. * @tdb: the tdb context returned from tdb_open()
  74. *
  75. * This always succeeds, in that @tdb is unusable after this call. But if
  76. * some unexpected error occurred while closing, it will return non-zero
  77. * (the only clue as to cause will be via the log attribute).
  78. */
  79. int tdb_close(struct tdb_context *tdb);
  80. /**
  81. * struct tdb_data - representation of keys or values.
  82. * @dptr: the data pointer
  83. * @dsize: the size of the data pointed to by dptr.
  84. *
  85. * This is the "blob" representation of keys and data used by TDB.
  86. */
  87. typedef struct tdb_data {
  88. unsigned char *dptr;
  89. size_t dsize;
  90. } TDB_DATA;
  91. /**
  92. * enum TDB_ERROR - error returns for TDB
  93. *
  94. * See Also:
  95. * tdb_errorstr()
  96. */
  97. enum TDB_ERROR {
  98. TDB_SUCCESS = 0, /* No error. */
  99. TDB_ERR_CORRUPT = -1, /* We read the db, and it was bogus. */
  100. TDB_ERR_IO = -2, /* We couldn't read/write the db. */
  101. TDB_ERR_LOCK = -3, /* Locking failed. */
  102. TDB_ERR_OOM = -4, /* Out of Memory. */
  103. TDB_ERR_EXISTS = -5, /* The key already exists. */
  104. TDB_ERR_NOEXIST = -6, /* The key does not exist. */
  105. TDB_ERR_EINVAL = -7, /* You're using it wrong. */
  106. TDB_ERR_RDONLY = -8, /* The database is read-only. */
  107. TDB_ERR_LAST = TDB_ERR_RDONLY
  108. };
  109. /**
  110. * tdb_store - store a key/value pair in a tdb.
  111. * @tdb: the tdb context returned from tdb_open()
  112. * @key: the key
  113. * @dbuf: the data to associate with the key.
  114. * @flag: TDB_REPLACE, TDB_INSERT or TDB_MODIFY.
  115. *
  116. * This inserts (or overwrites) a key/value pair in the TDB. If flag
  117. * is TDB_REPLACE, it doesn't matter whether the key exists or not;
  118. * TDB_INSERT means it must not exist (returns TDB_ERR_EXISTS otherwise),
  119. * and TDB_MODIFY means it must exist (returns TDB_ERR_NOEXIST otherwise).
  120. *
  121. * On success, this returns TDB_SUCCESS.
  122. *
  123. * See also:
  124. * tdb_fetch, tdb_transaction_start, tdb_append, tdb_delete.
  125. */
  126. enum TDB_ERROR tdb_store(struct tdb_context *tdb,
  127. struct tdb_data key,
  128. struct tdb_data dbuf,
  129. int flag);
  130. /* flags to tdb_store() */
  131. #define TDB_REPLACE 1 /* A readability place holder */
  132. #define TDB_INSERT 2 /* Don't overwrite an existing entry */
  133. #define TDB_MODIFY 3 /* Don't create an existing entry */
  134. /**
  135. * tdb_fetch - fetch a value from a tdb.
  136. * @tdb: the tdb context returned from tdb_open()
  137. * @key: the key
  138. * @data: pointer to data.
  139. *
  140. * This looks up a key in the database and sets it in @data.
  141. *
  142. * If it returns TDB_SUCCESS, the key was found: it is your
  143. * responsibility to call free() on @data->dptr.
  144. *
  145. * Otherwise, it returns an error (usually, TDB_ERR_NOEXIST) and @data is
  146. * undefined.
  147. */
  148. enum TDB_ERROR tdb_fetch(struct tdb_context *tdb, struct tdb_data key,
  149. struct tdb_data *data);
  150. /**
  151. * tdb_errorstr - map the tdb error onto a constant readable string
  152. * @ecode: the enum TDB_ERROR to map.
  153. *
  154. * This is useful for displaying errors to users.
  155. */
  156. const char *tdb_errorstr(enum TDB_ERROR ecode);
  157. /**
  158. * tdb_append - append a value to a key/value pair in a tdb.
  159. * @tdb: the tdb context returned from tdb_open()
  160. * @key: the key
  161. * @dbuf: the data to append.
  162. *
  163. * This is equivalent to fetching a record, reallocating .dptr to add the
  164. * data, and writing it back, only it's much more efficient. If the key
  165. * doesn't exist, it's equivalent to tdb_store (with an additional hint that
  166. * you expect to expand the record in future).
  167. *
  168. * See Also:
  169. * tdb_fetch(), tdb_store()
  170. */
  171. enum TDB_ERROR tdb_append(struct tdb_context *tdb,
  172. struct tdb_data key, struct tdb_data dbuf);
  173. /**
  174. * tdb_delete - delete a key from a tdb.
  175. * @tdb: the tdb context returned from tdb_open()
  176. * @key: the key to delete.
  177. *
  178. * Returns TDB_SUCCESS on success, or an error (usually TDB_ERR_NOEXIST).
  179. *
  180. * See Also:
  181. * tdb_fetch(), tdb_store()
  182. */
  183. enum TDB_ERROR tdb_delete(struct tdb_context *tdb, struct tdb_data key);
  184. /**
  185. * tdb_exists - does a key exist in the database?
  186. * @tdb: the tdb context returned from tdb_open()
  187. * @key: the key to search for.
  188. *
  189. * Returns true if it exists, or false if it doesn't or any other error.
  190. */
  191. bool tdb_exists(struct tdb_context *tdb, TDB_DATA key);
  192. /**
  193. * tdb_deq - are struct tdb_data equal?
  194. * @a: one struct tdb_data
  195. * @b: another struct tdb_data
  196. */
  197. static inline bool tdb_deq(struct tdb_data a, struct tdb_data b)
  198. {
  199. return a.dsize == b.dsize && memcmp(a.dptr, b.dptr, a.dsize) == 0;
  200. }
  201. /**
  202. * tdb_mkdata - make a struct tdb_data from const data
  203. * @p: the constant pointer
  204. * @len: the length
  205. *
  206. * As the dptr member of struct tdb_data is not constant, you need to
  207. * cast it. This function keeps thost casts in one place, as well as
  208. * suppressing the warning some compilers give when casting away a
  209. * qualifier (eg. gcc with -Wcast-qual)
  210. */
  211. static inline struct tdb_data tdb_mkdata(const void *p, size_t len)
  212. {
  213. struct tdb_data d;
  214. d.dptr = cast_const(void *, p);
  215. d.dsize = len;
  216. return d;
  217. }
  218. /**
  219. * tdb_transaction_start - start a transaction
  220. * @tdb: the tdb context returned from tdb_open()
  221. *
  222. * This begins a series of atomic operations. Other processes will be able
  223. * to read the tdb, but not alter it (they will block), nor will they see
  224. * any changes until tdb_transaction_commit() is called.
  225. *
  226. * See Also:
  227. * tdb_transaction_cancel, tdb_transaction_commit.
  228. */
  229. enum TDB_ERROR tdb_transaction_start(struct tdb_context *tdb);
  230. /**
  231. * tdb_transaction_cancel - abandon a transaction
  232. * @tdb: the tdb context returned from tdb_open()
  233. *
  234. * This aborts a transaction, discarding any changes which were made.
  235. * tdb_close() does this implicitly.
  236. */
  237. void tdb_transaction_cancel(struct tdb_context *tdb);
  238. /**
  239. * tdb_transaction_commit - commit a transaction
  240. * @tdb: the tdb context returned from tdb_open()
  241. *
  242. * This completes a transaction, writing any changes which were made.
  243. *
  244. * fsync() is used to commit the transaction (unless TDB_NOSYNC is set),
  245. * making it robust against machine crashes, but very slow compared to
  246. * other TDB operations.
  247. *
  248. * A failure can only be caused by unexpected errors (eg. I/O or
  249. * memory); this is no point looping on transaction failure.
  250. *
  251. * See Also:
  252. * tdb_transaction_prepare_commit()
  253. */
  254. enum TDB_ERROR tdb_transaction_commit(struct tdb_context *tdb);
  255. /**
  256. * tdb_transaction_prepare_commit - prepare to commit a transaction
  257. * @tdb: the tdb context returned from tdb_open()
  258. *
  259. * This ensures we have the resources to commit a transaction (using
  260. * tdb_transaction_commit): if this succeeds then a transaction will only
  261. * fail if the write() or fsync() calls fail.
  262. *
  263. * See Also:
  264. * tdb_transaction_commit()
  265. */
  266. enum TDB_ERROR tdb_transaction_prepare_commit(struct tdb_context *tdb);
  267. /**
  268. * tdb_traverse - traverse a TDB
  269. * @tdb: the tdb context returned from tdb_open()
  270. * @fn: the function to call for every key/value pair (or NULL)
  271. * @p: the pointer to hand to @f
  272. *
  273. * This walks the TDB until all they keys have been traversed, or @fn
  274. * returns non-zero. If the traverse function or other processes are
  275. * changing data or adding or deleting keys, the traverse may be
  276. * unreliable: keys may be skipped or (rarely) visited twice.
  277. *
  278. * There is one specific exception: the special case of deleting the
  279. * current key does not undermine the reliability of the traversal.
  280. *
  281. * On success, returns the number of keys iterated. On error returns
  282. * a negative enum TDB_ERROR value.
  283. */
  284. #define tdb_traverse(tdb, fn, p) \
  285. tdb_traverse_(tdb, typesafe_cb_preargs(int, (fn), (p), \
  286. struct tdb_context *, \
  287. TDB_DATA, TDB_DATA), (p))
  288. int64_t tdb_traverse_(struct tdb_context *tdb,
  289. int (*fn)(struct tdb_context *,
  290. TDB_DATA, TDB_DATA, void *), void *p);
  291. /**
  292. * tdb_parse_record - operate directly on data in the database.
  293. * @tdb: the tdb context returned from tdb_open()
  294. * @key: the key whose record we should hand to @parse
  295. * @parse: the function to call for the data
  296. * @p: the private pointer to hand to @parse (types must match).
  297. *
  298. * This avoids a copy for many cases, by handing you a pointer into
  299. * the memory-mapped database. It also locks the record to prevent
  300. * other accesses at the same time.
  301. *
  302. * Do not alter the data handed to parse()!
  303. */
  304. #define tdb_parse_record(tdb, key, parse, p) \
  305. tdb_parse_record_((tdb), (key), \
  306. typesafe_cb_preargs(enum TDB_ERROR, (parse), (p), \
  307. TDB_DATA, TDB_DATA), (p))
  308. enum TDB_ERROR tdb_parse_record_(struct tdb_context *tdb,
  309. TDB_DATA key,
  310. enum TDB_ERROR (*parse)(TDB_DATA key,
  311. TDB_DATA data,
  312. void *p),
  313. void *p);
  314. /**
  315. * tdb_get_seqnum - get a database sequence number
  316. * @tdb: the tdb context returned from tdb_open()
  317. *
  318. * This returns a sequence number: any change to the database from a
  319. * tdb context opened with the TDB_SEQNUM flag will cause that number
  320. * to increment. Note that the incrementing is unreliable (it is done
  321. * without locking), so this is only useful as an optimization.
  322. *
  323. * For example, you may have a regular database backup routine which
  324. * does not operate if the sequence number is unchanged. In the
  325. * unlikely event of a failed increment, it will be backed up next
  326. * time any way.
  327. *
  328. * Returns an enum TDB_ERROR (ie. negative) on error.
  329. */
  330. int64_t tdb_get_seqnum(struct tdb_context *tdb);
  331. /**
  332. * tdb_firstkey - get the "first" key in a TDB
  333. * @tdb: the tdb context returned from tdb_open()
  334. * @key: pointer to key.
  335. *
  336. * This returns an arbitrary key in the database; with tdb_nextkey() it allows
  337. * open-coded traversal of the database, though it is slightly less efficient
  338. * than tdb_traverse.
  339. *
  340. * It is your responsibility to free @key->dptr on success.
  341. *
  342. * Returns TDB_ERR_NOEXIST if the database is empty.
  343. */
  344. enum TDB_ERROR tdb_firstkey(struct tdb_context *tdb, struct tdb_data *key);
  345. /**
  346. * tdb_nextkey - get the "next" key in a TDB
  347. * @tdb: the tdb context returned from tdb_open()
  348. * @key: a key returned by tdb_firstkey() or tdb_nextkey().
  349. *
  350. * This returns another key in the database; it will free @key.dptr for
  351. * your convenience.
  352. *
  353. * Returns TDB_ERR_NOEXIST if there are no more keys.
  354. */
  355. enum TDB_ERROR tdb_nextkey(struct tdb_context *tdb, struct tdb_data *key);
  356. /**
  357. * tdb_chainlock - lock a record in the TDB
  358. * @tdb: the tdb context returned from tdb_open()
  359. * @key: the key to lock.
  360. *
  361. * This prevents any changes from occurring to a group of keys including @key,
  362. * even if @key does not exist. This allows primitive atomic updates of
  363. * records without using transactions.
  364. *
  365. * You cannot begin a transaction while holding a tdb_chainlock(), nor can
  366. * you do any operations on any other keys in the database. This also means
  367. * that you cannot hold more than one tdb_chainlock() at a time.
  368. *
  369. * See Also:
  370. * tdb_chainunlock()
  371. */
  372. enum TDB_ERROR tdb_chainlock(struct tdb_context *tdb, TDB_DATA key);
  373. /**
  374. * tdb_chainunlock - unlock a record in the TDB
  375. * @tdb: the tdb context returned from tdb_open()
  376. * @key: the key to unlock.
  377. *
  378. * The key must have previously been locked by tdb_chainlock().
  379. */
  380. void tdb_chainunlock(struct tdb_context *tdb, TDB_DATA key);
  381. /**
  382. * tdb_lockall - lock the entire TDB
  383. * @tdb: the tdb context returned from tdb_open()
  384. *
  385. * You cannot hold a tdb_chainlock while calling this. It nests, so you
  386. * must call tdb_unlockall as many times as you call tdb_lockall.
  387. */
  388. enum TDB_ERROR tdb_lockall(struct tdb_context *tdb);
  389. /**
  390. * tdb_unlockall - unlock the entire TDB
  391. * @tdb: the tdb context returned from tdb_open()
  392. */
  393. void tdb_unlockall(struct tdb_context *tdb);
  394. /**
  395. * tdb_lockall_read - lock the entire TDB for reading
  396. * @tdb: the tdb context returned from tdb_open()
  397. *
  398. * This prevents others writing to the database, eg. tdb_delete, tdb_store,
  399. * tdb_append, but not tdb_fetch.
  400. *
  401. * You cannot hold a tdb_chainlock while calling this. It nests, so you
  402. * must call tdb_unlockall_read as many times as you call tdb_lockall_read.
  403. */
  404. enum TDB_ERROR tdb_lockall_read(struct tdb_context *tdb);
  405. /**
  406. * tdb_unlockall_read - unlock the entire TDB for reading
  407. * @tdb: the tdb context returned from tdb_open()
  408. */
  409. void tdb_unlockall_read(struct tdb_context *tdb);
  410. /**
  411. * tdb_wipe_all - wipe the database clean
  412. * @tdb: the tdb context returned from tdb_open()
  413. *
  414. * Completely erase the database. This is faster than iterating through
  415. * each key and doing tdb_delete.
  416. */
  417. enum TDB_ERROR tdb_wipe_all(struct tdb_context *tdb);
  418. /**
  419. * tdb_check - check a TDB for consistency
  420. * @tdb: the tdb context returned from tdb_open()
  421. * @check: function to check each key/data pair (or NULL)
  422. * @private_data: argument for @check, must match type.
  423. *
  424. * This performs a consistency check of the open database, optionally calling
  425. * a check() function on each record so you can do your own data consistency
  426. * checks as well. If check() returns an error, that is returned from
  427. * tdb_check().
  428. *
  429. * Returns TDB_SUCCESS or an error.
  430. */
  431. #define tdb_check(tdb, check, private_data) \
  432. tdb_check_((tdb), typesafe_cb_preargs(enum TDB_ERROR, \
  433. (check), (private_data), \
  434. struct tdb_data, \
  435. struct tdb_data), \
  436. (private_data))
  437. enum TDB_ERROR tdb_check_(struct tdb_context *tdb,
  438. enum TDB_ERROR (*check)(struct tdb_data key,
  439. struct tdb_data data,
  440. void *private_data),
  441. void *private_data);
  442. /**
  443. * tdb_error - get the last error (not threadsafe)
  444. * @tdb: the tdb context returned from tdb_open()
  445. *
  446. * Returns the last error returned by a TDB function.
  447. *
  448. * This makes porting from TDB1 easier, but note that the last error is not
  449. * reliable in threaded programs.
  450. */
  451. enum TDB_ERROR tdb_error(struct tdb_context *tdb);
  452. /**
  453. * enum tdb_summary_flags - flags for tdb_summary.
  454. */
  455. enum tdb_summary_flags {
  456. TDB_SUMMARY_HISTOGRAMS = 1 /* Draw graphs in the summary. */
  457. };
  458. /**
  459. * tdb_summary - return a string describing the TDB state
  460. * @tdb: the tdb context returned from tdb_open()
  461. * @flags: flags to control the summary output.
  462. * @summary: pointer to string to allocate.
  463. *
  464. * This returns a developer-readable string describing the overall
  465. * state of the tdb, such as the percentage used and sizes of records.
  466. * It is designed to provide information about the tdb at a glance
  467. * without displaying any keys or data in the database.
  468. *
  469. * On success, sets @summary to point to a malloc()'ed nul-terminated
  470. * multi-line string. It is your responsibility to free() it.
  471. */
  472. enum TDB_ERROR tdb_summary(struct tdb_context *tdb,
  473. enum tdb_summary_flags flags,
  474. char **summary);
  475. /**
  476. * tdb_get_flags - return the flags for a tdb
  477. * @tdb: the tdb context returned from tdb_open()
  478. *
  479. * This returns the flags on the current tdb. Some of these are caused by
  480. * the flags argument to tdb_open(), others (such as TDB_CONVERT) are
  481. * intuited.
  482. */
  483. unsigned int tdb_get_flags(struct tdb_context *tdb);
  484. /**
  485. * tdb_add_flag - set a flag for a tdb
  486. * @tdb: the tdb context returned from tdb_open()
  487. * @flag: one of TDB_NOLOCK, TDB_NOMMAP or TDB_NOSYNC.
  488. *
  489. * You can use this to set a flag on the TDB. You cannot set these flags
  490. * on a TDB_INTERNAL tdb.
  491. */
  492. void tdb_add_flag(struct tdb_context *tdb, unsigned flag);
  493. /**
  494. * tdb_remove_flag - unset a flag for a tdb
  495. * @tdb: the tdb context returned from tdb_open()
  496. * @flag: one of TDB_NOLOCK, TDB_NOMMAP or TDB_NOSYNC.
  497. *
  498. * You can use this to clear a flag on the TDB. You cannot clear flags
  499. * on a TDB_INTERNAL tdb.
  500. */
  501. void tdb_remove_flag(struct tdb_context *tdb, unsigned flag);
  502. /**
  503. * tdb_name - get the name of a tdb
  504. * @tdb: the tdb context returned from tdb_open()
  505. *
  506. * This returns a copy of the name string, made at tdb_open() time. If that
  507. * argument was NULL (possible for a TDB_INTERNAL db) this will return NULL.
  508. *
  509. * This is mostly useful for logging.
  510. */
  511. const char *tdb_name(const struct tdb_context *tdb);
  512. /**
  513. * tdb_fd - get the file descriptor of a tdb
  514. * @tdb: the tdb context returned from tdb_open()
  515. *
  516. * This returns the file descriptor for the underlying database file, or -1
  517. * for TDB_INTERNAL.
  518. */
  519. int tdb_fd(const struct tdb_context *tdb);
  520. /**
  521. * enum tdb_attribute_type - descriminator for union tdb_attribute.
  522. */
  523. enum tdb_attribute_type {
  524. TDB_ATTRIBUTE_LOG = 0,
  525. TDB_ATTRIBUTE_HASH = 1,
  526. TDB_ATTRIBUTE_SEED = 2,
  527. TDB_ATTRIBUTE_STATS = 3
  528. };
  529. /**
  530. * struct tdb_attribute_base - common fields for all tdb attributes.
  531. */
  532. struct tdb_attribute_base {
  533. enum tdb_attribute_type attr;
  534. union tdb_attribute *next;
  535. };
  536. /**
  537. * enum tdb_log_level - log levels for tdb_attribute_log
  538. * @TDB_LOG_ERROR: used to log unrecoverable errors such as I/O errors
  539. * or internal consistency failures.
  540. * @TDB_LOG_USE_ERROR: used to log usage errors such as invalid parameters
  541. * or writing to a read-only database.
  542. * @TDB_LOG_WARNING: used for informational messages on issues which
  543. * are unusual but handled by TDB internally, such
  544. * as a failure to mmap or failure to open /dev/urandom.
  545. */
  546. enum tdb_log_level {
  547. TDB_LOG_ERROR,
  548. TDB_LOG_USE_ERROR,
  549. TDB_LOG_WARNING
  550. };
  551. /**
  552. * struct tdb_attribute_log - log function attribute
  553. *
  554. * This attribute provides a hook for you to log errors.
  555. */
  556. struct tdb_attribute_log {
  557. struct tdb_attribute_base base; /* .attr = TDB_ATTRIBUTE_LOG */
  558. void (*log_fn)(struct tdb_context *tdb,
  559. enum tdb_log_level level,
  560. void *log_private,
  561. const char *message);
  562. void *log_private;
  563. };
  564. /**
  565. * struct tdb_attribute_hash - hash function attribute
  566. *
  567. * This attribute allows you to provide an alternative hash function.
  568. * This hash function will be handed keys from the database; it will also
  569. * be handed the 8-byte TDB_HASH_MAGIC value for checking the header (the
  570. * tdb_open() will fail if the hash value doesn't match the header).
  571. *
  572. * Note that if your hash function gives different results on
  573. * different machine endians, your tdb will no longer work across
  574. * different architectures!
  575. */
  576. struct tdb_attribute_hash {
  577. struct tdb_attribute_base base; /* .attr = TDB_ATTRIBUTE_HASH */
  578. uint64_t (*hash_fn)(const void *key, size_t len, uint64_t seed,
  579. void *priv);
  580. void *hash_private;
  581. };
  582. /**
  583. * struct tdb_attribute_seed - hash function seed attribute
  584. *
  585. * The hash function seed is normally taken from /dev/urandom (or equivalent)
  586. * but can be set manually here. This is mainly for testing purposes.
  587. */
  588. struct tdb_attribute_seed {
  589. struct tdb_attribute_base base; /* .attr = TDB_ATTRIBUTE_SEED */
  590. uint64_t seed;
  591. };
  592. /**
  593. * struct tdb_attribute_stats - tdb operational statistics
  594. *
  595. * This attribute records statistics of various low-level TDB operations.
  596. * This can be used to assist performance evaluation.
  597. *
  598. * New fields will be added at the end, hence the "size" argument which
  599. * indicates how large your structure is. If your size is larger than
  600. * that known about by this version of tdb, the size will be reduced to
  601. * the known structure size. Thus you can detect older versions, and
  602. * thus know that newer stats will not be updated.
  603. */
  604. struct tdb_attribute_stats {
  605. struct tdb_attribute_base base; /* .attr = TDB_ATTRIBUTE_STATS */
  606. size_t size; /* = sizeof(struct tdb_attribute_stats) */
  607. uint64_t allocs;
  608. uint64_t alloc_subhash;
  609. uint64_t alloc_chain;
  610. uint64_t alloc_bucket_exact;
  611. uint64_t alloc_bucket_max;
  612. uint64_t alloc_leftover;
  613. uint64_t alloc_coalesce_tried;
  614. uint64_t alloc_coalesce_lockfail;
  615. uint64_t alloc_coalesce_race;
  616. uint64_t alloc_coalesce_succeeded;
  617. uint64_t alloc_coalesce_num_merged;
  618. uint64_t compares;
  619. uint64_t compare_wrong_bucket;
  620. uint64_t compare_wrong_offsetbits;
  621. uint64_t compare_wrong_keylen;
  622. uint64_t compare_wrong_rechash;
  623. uint64_t compare_wrong_keycmp;
  624. uint64_t expands;
  625. uint64_t frees;
  626. uint64_t locks;
  627. uint64_t lock_lowlevel;
  628. uint64_t lock_nonblock;
  629. };
  630. /**
  631. * union tdb_attribute - tdb attributes.
  632. *
  633. * This represents all the known attributes.
  634. *
  635. * See also:
  636. * struct tdb_attribute_log, struct tdb_attribute_hash,
  637. * struct tdb_attribute_seed, struct tdb_attribute_stats.
  638. */
  639. union tdb_attribute {
  640. struct tdb_attribute_base base;
  641. struct tdb_attribute_log log;
  642. struct tdb_attribute_hash hash;
  643. struct tdb_attribute_seed seed;
  644. struct tdb_attribute_stats stats;
  645. };
  646. #ifdef __cplusplus
  647. }
  648. #endif
  649. #endif /* tdb2.h */