From 2da0223d5d1e91a7154996969ce44f48d9838a4f Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 29 Sep 2021 13:45:39 +0000 Subject: Doc fixes Signed-off-by: Laurent Bercot --- doc/libstddjb/cdb.html | 105 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) (limited to 'doc/libstddjb/cdb.html') diff --git a/doc/libstddjb/cdb.html b/doc/libstddjb/cdb.html index 40a2c41..8d72b9e 100644 --- a/doc/libstddjb/cdb.html +++ b/doc/libstddjb/cdb.html @@ -20,8 +20,111 @@

The skalibs/cdb.h header

+

General information

+ +

+ A cdb, for constant database, +is an immutable key-value store. In skalibs, a cdb is built once via the +cdbmake primitives and stored on disk; the cdb +primitives, documented here, are about accessing the information. +

+ +

Data structures

+ + + +

Macros and functions

+ +

Starting and ending

+ +

+ int cdb_init (cdb *c, char const *file)
+Maps the file named file to the cdb pointed to by c. +*c must be CDB_ZERO before the call. The function returns a +positive integer if it succeeds, and 0 (and sets errno) if it fails. +

+ +

+ int cdb_init_at (cdb *c, int dfd, char const *file)
+Like cdb_init, but file is interpreted relative to the +file descriptor dfd, which must be open on a directory. +

+ +

+ int cdb_init_fromfd (cdb *c, int fd)
+Like cdb_init, but the database file is already open and +readable via then file descriptor fd. +

+ +

+ void cdb_free (cdb *c)
+Frees the resources used by a cdb mapping. After the call, c +is immediately reusable by another cdb_init function. +

+ +

cdb lookup

+ +

Single record lookup

+ +

+ int cdb_find (cdb const *c, cdb_data *data, char const *key, uint32_t klen)
+Looks up key key of length klen in the cdb *c. The function returns +-1 if *c isn't a valid cdb; 0 if no record can be found for the key; and 1 on success, in +which case the corresponding value is returned in *data: data→s +points to the start of the value, and data→len contains the length of +the value. Only the first record with the same key can be obtained this way. +

+ +

Multiple record lookup

+ +

+ void cdb_findstart (cdb_find_state *state)
+Initializes state so that the next invocation of cdb_findnext() +finds the first record for a given key. +

+ +

+ int cdb_findnext (cdb const *c, cdb_data *data, char const *key, uint32_t klen, cdb_find_state *state)
+Like cdb_find, except that the extra argument state memorizes +internal cdb lookup data, so the next cdb_findnext() invocation with the +same key, klen and state will yield the next record +for the key. cdb_findnext returns 0 when all the records for the key have +been exhausted. +

+ +

cdb enumeration

+ +

+ void cdb_traverse_init (uint32_t *pos)
+Initializes *pos so that the next invocation of cdb_traverse_next +finds the first entry in the cdb. *pos can also be initialized to the +macro CDB_TRAVERSE_INIT() instead. +

+

- TODO: write this documentation page. (Sorry!) + int cdb_traverse_next (cdb const *c, cdb_data *key, cdb_data *data, uint32_t *pos)
+Gets the next entry in the cdb *c. On success, the key is stored in *key and the +data is stored in *data. *pos* is an opaque integer storing internal +state; it is automatically updated so that the next invocation of cdb_traverse_next() +yields the next entry. The function returns -1 if *c is not a valid cdb or *pos +is not valid state, 1 on success, and 0 if no entry can be found, i.e. the end of the cdb has +been reached.

-- cgit v1.3.1