author | Olivier Brunel
<jjk@jjacky.com> 2023-04-18 20:18:50 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-05-20 18:06:37 UTC |
parent | 5716d1983de2b48421e50468541c1e534e79d536 |
src/doc/cdbmake.h.0.md | +11 | -1 |
src/doc/cdbmake.h/cdbmaker_sa_start.3.md | +26 | -8 |
src/liblimb/cdbmake.h/cdbmaker_sa_init.c | +11 | -0 |
src/liblimb/cdbmake.h/cdbmaker_sa_start.c | +1 | -2 |
src/liblimb/include/limb/cdbmake.h | +5 | -2 |
diff --git a/src/doc/cdbmake.h.0.md b/src/doc/cdbmake.h.0.md index 271e455..b630e24 100644 --- a/src/doc/cdbmake.h.0.md +++ b/src/doc/cdbmake.h.0.md @@ -28,12 +28,19 @@ The following structures are defined : : *struct cdbmaker_sa* :: Semi-opaque structure used during the creating of a cdb in-memory. +## Macros + +The following macros are defined : + +: *CDBMAKER_SA_ZERO* +:: Can be used to initialized a *cdbmaker_sa* structure. + ## Types The followng types are defined : : *cdbmaker_sa* -:: Semi-opaque structure used durng the creating of a cdb in-memory. +:: Semi-opaque structure used during the creating of a cdb in-memory. ## Functions @@ -48,5 +55,8 @@ The following functions are defined : : [cdbmaker_sa_free](3) :: To free memory associated with a semi-opaque *cdbmaker_sa* when done. +: [cdbmaker_sa_init](3) +:: To initialize a *cdbmaker_sa* if not initalized through *CDBMAKER_SA_ZERO*. + : [cdbmaker_sa_start](3) :: Similar to [cdbmake_start](3) but the cdb will be created in-memory. diff --git a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md index e232bb9..d9a7077 100644 --- a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md +++ b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md @@ -3,7 +3,7 @@ # NAME -cdbmaker\_sa\_start, cdbmaker\_sa\_add, cdbmaker\_sa\_finish, +cdbmaker\_sa\_init, cdbmaker\_sa\_start, cdbmaker\_sa\_add, cdbmaker\_sa\_finish, cdbmaker\_sa\_free - create a cdb in memory # SYNOPSIS @@ -11,21 +11,33 @@ cdbmaker\_sa\_free - create a cdb in memory #include <limb/cdbmake.h> ```pre hl -int cdbmaker_sa_finish(cdbmaker_sa *<em>mkr</em>) -int cdbmaker_sa_add(cdbmaker_sa *<em>mkr</em>, const char *<em>key</em>, u32 <em>klen</em>, const char *<em>data</em>, u32 <em>dlen</em>) +#define CDBMAKER_SA_ZERO + +void cdbmaker_sa_init(cdbmaker_sa *<em>mkr</em>) int cdbmaker_sa_start(cdbmaker_sa *<em>mkr</em>) +int cdbmaker_sa_add(cdbmaker_sa *<em>mkr</em>, const char *<em>key</em>, u32 <em>klen</em>, const char *<em>data</em>, u32 <em>dlen</em>) +int cdbmaker_sa_finish(cdbmaker_sa *<em>mkr</em>) void cdbmaker_sa_free(cdbmaker_sa *<em>mkr</em>) ``` # DESCRIPTION +Before using a *cdbmaker_sa* it should first be properly initialized. This can +be done upon declaration using the *CDBMAKER_SA_ZERO* macro. If not, the +`cdbmaker_sa_init`() function should then be called first. + The `cdbmaker_sa_start`(), `cdbmaker_sa_add`() and `cdbmaker_sa_finish`() functions are similar to [cdbmake_start](3), [cdbmake_add](3) and [cdbmake_finish](3) respectively, only the resulting cdb will not be written to a file but instead be available in memory. -The `cdbmaker_sa_start`() initializes the semi-opaque structure pointed to by -`mkr` in order to begin creation of a cdb. +The `cdbmaker_sa_start`() prepares the semi-opaque structure pointed to by +`mkr` in order to begin creation of a new cdb. Said structure must have +previously been initialized as mentioned before. + +Note that, after a successful call to `cdbmaker_sa_finish`() it is possible to +re-use the same *cdbmaker_sa* structure, to create another cdb, by calling +`cdbmaker_sa_start`() again. 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 @@ -44,9 +56,10 @@ which is a *stralloc*, which - after a successful call to `cdbmaker_sa_finish`() - will hold the newly-created cdb (i.e. the content of a cdb file), available from `mkr->sa.s` for a length of `mkr->sa.len` bytes. -When done with the cdb, the `cdbmaker_sa_free`() function must be called in -order to free memory associated with the semi-opaque structure pointed to by -`mkr`. +The `cdbmaker_sa_free`() function will free memory associated with the semi-opaque +structure pointed to by `mkr`, starting with the generated cdb data. It is not +needed to use it before calling `cdbmaker_sa_start`() again in order to generate +a new cdb, thusly re-using the already allocated memory area. # RETURN VALUE @@ -62,6 +75,11 @@ fail if : : *ENOMEM* :: Not enough memory to create to cdb. +The `cdbmaker_sa_start`() function may also fail if : + +: *EINVAL* +:: The *cdbmaker_sa* structure is not in a valid/properly initialized state. + The `cdbmaker_sa_add`() function may also fail if : : *EOVERFLOW* diff --git a/src/liblimb/cdbmake.h/cdbmaker_sa_init.c b/src/liblimb/cdbmake.h/cdbmaker_sa_init.c new file mode 100644 index 0000000..94003e2 --- /dev/null +++ b/src/liblimb/cdbmake.h/cdbmaker_sa_init.c @@ -0,0 +1,11 @@ +/* This file is part of limb https://lila.oss/limb + * Copyright (C) 2023 Olivier Brunel jjk@jjacky.com */ +/* SPDX-License-Identifier: GPL-2.0-only */ +#include <limb/cdbmake.h> + +void +cdbmaker_sa_init(cdbmaker_sa *m) +{ + m->sa = stralloc_zero; + m->hplist = genalloc_zero; +} diff --git a/src/liblimb/cdbmake.h/cdbmaker_sa_start.c b/src/liblimb/cdbmake.h/cdbmaker_sa_start.c index 15e36fb..0c567bb 100644 --- a/src/liblimb/cdbmake.h/cdbmaker_sa_start.c +++ b/src/liblimb/cdbmake.h/cdbmaker_sa_start.c @@ -6,8 +6,7 @@ int cdbmaker_sa_start(cdbmaker_sa *m) { - m->sa = stralloc_zero; - m->hplist = genalloc_zero; + m->sa.len = m->hplist.len = 0; if (!stralloc_readyplus(&m->sa, 2048)) return 0; m->sa.len = 2048; diff --git a/src/liblimb/include/limb/cdbmake.h b/src/liblimb/include/limb/cdbmake.h index 2447cb8..f83c6b4 100644 --- a/src/liblimb/include/limb/cdbmake.h +++ b/src/liblimb/include/limb/cdbmake.h @@ -16,9 +16,12 @@ struct cdbmaker_sa }; typedef struct cdbmaker_sa cdbmaker_sa; -extern int cdbmaker_sa_finish(cdbmaker_sa *m); -extern int cdbmaker_sa_add(cdbmaker_sa *m, const char *key, u32 klen, const char *data, u32 dlen); +#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); +extern int cdbmaker_sa_finish(cdbmaker_sa *m); extern void cdbmaker_sa_free(cdbmaker_sa *m); #endif /* LIMB_CDBMAKE_H */