Welcome to little lamb

Code » limb » commit 30f5a35

doc: Complete cdbmake.h

author Olivier Brunel
2023-07-01 21:10:29 UTC
committer Olivier Brunel
2023-07-24 10:16:41 UTC
parent ccc5fd5653f0e60262e365e23f3a75b7f7b5a738

doc: Complete cdbmake.h

src/doc/cdbmake.h.0.md +19 -14
src/doc/cdbmake.h/cdbmaker_add.3.md +61 -0
src/doc/cdbmake.h/cdbmaker_finish.3.md +1 -0
src/doc/cdbmake.h/cdbmaker_sa_start.3.md +3 -3
src/doc/cdbmake.h/cdbmaker_start.3.md +1 -0
src/liblimb/include/limb/cdbmake.h +4 -1

diff --git a/src/doc/cdbmake.h.0.md b/src/doc/cdbmake.h.0.md
index 20c8ef6..c5f24a9 100644
--- a/src/doc/cdbmake.h.0.md
+++ b/src/doc/cdbmake.h.0.md
@@ -16,35 +16,40 @@ cdbmake.h - creating constant databases
 The header defines the needed functions to create constant databases, known as
 .cdb files.
 
-! INFO: skalibs
-! This header is a complement to skalibs' own [skalibs/cdbmake.h](0) and thusly
-! includes said header.
+<inc skalibs.md>
 
-## Structures
+## Types
 
-The following structures are defined :
+The following types are defined :
 
-: *struct cdbmaker_sa*
-:: An opaque structure to be passed to the functions below.
+: *cdbmaker*
+:: Opaque structure to be passed to the *cdbmaker_* family of functions below.
 
+: *cdbmaker_sa*
+:: Opaque structure to be passed to the *cdbmaker_sa_* family of functions below.
 
 ## Macros
 
 The following macros are defined :
 
+: *CDBMAKER_ZERO*
+:: Value to initialize a *cdbmaker*.
+
 : *CDBMAKER_SA_ZERO*
-:: Value to initialize a *cdbmaker_sa* structure.
+:: Value to initialize a *cdbmaker_sa*.
 
-## Types
+## Functions
 
-The following types are defined :
+The following functions/macros are defined :
 
-: *cdbmaker_sa*
-:: Opaque structure to be passed to the functions below.
+: [cdbmaker_add](3)
+:: Add an element into a *cdbmaker*.
 
-## Functions
+: [cdbmaker_finish](3)
+:: Finalize & write the cdb from a *cdbmaker*.
 
-The following functions/macros are defined :
+: [cdbmaker_start](3)
+:: Prepare a *cdbmaker* to create a new cdb.
 
 : [cdbmaker_sa_add](3)
 :: Similar to [cdbmake_add](3) but the cdb will be created in-memory.
diff --git a/src/doc/cdbmake.h/cdbmaker_add.3.md b/src/doc/cdbmake.h/cdbmaker_add.3.md
new file mode 100644
index 0000000..f5cdbdc
--- /dev/null
+++ b/src/doc/cdbmake.h/cdbmaker_add.3.md
@@ -0,0 +1,61 @@
+% limb manual
+% cdbmaker_start(3)
+
+# NAME
+
+cdbmaker_sa_start, cdbmaker_sa_add, cdbmaker_sa_finish - create a new cdb file
+
+# SYNOPSIS
+
+    #include <limb/cdbmake.h>
+
+```pre hl
+#define CDBMAKER_ZERO
+
+int cdbmaker_start(cdbmaker *<em>mkr</em>, int <em>fd</em>)
+int cdbmaker_add(cdbmaker *<em>mkr</em>, const char *<em>key</em>, u32 <em>klen</em>, const char *<em>data</em>, u32 <em>dlen</em>)
+int cdbmaker_finish(cdbmaker *<em>mkr</em>)
+```
+
+# DESCRIPTION
+
+The `cdbmaker_start`() prepares the opaque structure pointed to by `mkr` in
+order to begin creation of a new cdb, which will be written into the file
+represented by the file descriptor `fd`, which must be opened for writing.
+
+The `cdbmaker_add`() function is to be called for each element to be added to
+the cdb, specifying the key pointed to by `key` of length `klen` bytes, and the
+data pointed to by `data` of length `dlen` bytes. The actual content of both key
+and data will be of course be copied into the cdb.
+
+Elements will be added into the cdb in the order of the calls made to
+`cdbmaker_add`().
+
+Finally, the `cdbmaker_finish`() function must be called after all elements
+have been added via `cdbmaker_add`(), in order for the cdb to be finalized.
+
+Note that the file descriptor given to `cdbmake_start`() will /not/ be closed.
+
+# RETURN VALUE
+
+The `cdbmaker_start`(), `cdbmaker_add`() and `cdbmaker_finish`() functions
+return 1 on success. Otherwise, they return 0 and set `errno` to indicate the
+error.
+
+# ERRORS
+
+The `cdbmaker_start`() and `cdbmaker_finish`() functions may fail for any of
+the errors described for [lseek](3).
+
+The `cdbmaker_add`() and `cdbmaker_finish`() functions may fail if :
+
+: *ENOMEM*
+:: The resulting cdb would overflow, i.e. go over its 4 GiB limit.
+
+The `cdbmaker_add`() function may also fail if :
+
+: *ENOMEM*
+:: Not enough memory to create the cdb.
+
+The `cdbmaker_add`() and `cdbmaker_finish`() functions may also fail for any of
+the errors described for [buffer_flush](3).
diff --git a/src/doc/cdbmake.h/cdbmaker_finish.3.md b/src/doc/cdbmake.h/cdbmaker_finish.3.md
new file mode 120000
index 0000000..262f54f
--- /dev/null
+++ b/src/doc/cdbmake.h/cdbmaker_finish.3.md
@@ -0,0 +1 @@
+cdbmaker_add.3.md
\ No newline at end of file
diff --git a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
index c2556cf..953bd7b 100644
--- a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
+++ b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md
@@ -3,8 +3,8 @@
 
 # NAME
 
-cdbmaker\_sa\_init, cdbmaker\_sa\_start, cdbmaker\_sa\_add, cdbmaker\_sa\_finish,
-cdbmaker\_sa\_data, cdbmaker\_sa\_dlen, cdbmaker\_sa\_free - create a cdb in memory
+cdbmaker_sa_init, cdbmaker_sa_start, cdbmaker_sa_add, cdbmaker_sa_finish,
+cdbmaker_sa_data, cdbmaker_sa_dlen, cdbmaker_sa_free - create a cdb in memory
 
 # SYNOPSIS
 
@@ -43,7 +43,7 @@ re-use the same *cdbmaker_sa* structure, to create another cdb, by calling
 
 The `cdbmaker_sa_add`() function is to be called for each element to be added to
 the cdb, specifying the key pointed to by `key` of length `klen` bytes, and the
-data pointed to be `data` of length `dlen` bytes. The actual content of both key
+data pointed to by `data` of length `dlen` bytes. The actual content of both key
 and data will be of course be copied into the cdb.
 
 Elements will be added into the cdb in the order of the calls made to
diff --git a/src/doc/cdbmake.h/cdbmaker_start.3.md b/src/doc/cdbmake.h/cdbmaker_start.3.md
new file mode 120000
index 0000000..262f54f
--- /dev/null
+++ b/src/doc/cdbmake.h/cdbmaker_start.3.md
@@ -0,0 +1 @@
+cdbmaker_add.3.md
\ No newline at end of file
diff --git a/src/liblimb/include/limb/cdbmake.h b/src/liblimb/include/limb/cdbmake.h
index b0715e8..e61688f 100644
--- a/src/liblimb/include/limb/cdbmake.h
+++ b/src/liblimb/include/limb/cdbmake.h
@@ -9,6 +9,10 @@
 #include <limb/int.h>
 #include <limb/stralloc.h>
 
+#define cdbmaker_start      cdbmake_start
+#define cdbmaker_add        cdbmake_add
+#define cdbmaker_finish     cdbmake_finish
+
 struct cdbmaker_sa
 {
     stralloc sa;
@@ -18,7 +22,6 @@ typedef struct cdbmaker_sa cdbmaker_sa;
 
 #define CDBMAKER_SA_ZERO        { STRALLOC_ZERO, GENALLOC_ZERO }
 
-
 extern void cdbmaker_sa_init(cdbmaker_sa *m);
 extern int cdbmaker_sa_start(cdbmaker_sa *m);
 extern int cdbmaker_sa_add(cdbmaker_sa *m, const char *key, u32 klen, const char *data, u32 dlen);