author | Olivier Brunel
<jjk@jjacky.com> 2023-04-22 11:06:24 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-05-20 18:06:37 UTC |
parent | 21eee58eb0ff82a4147d93b96a4894949fe46ef0 |
src/doc/cdbmake.h.0.md | +14 | -7 |
src/doc/cdbmake.h/cdbmaker_sa_start.3.md | +22 | -12 |
src/liblimb/include/limb/cdbmake.h | +3 | -0 |
diff --git a/src/doc/cdbmake.h.0.md b/src/doc/cdbmake.h.0.md index b630e24..a3bd10d 100644 --- a/src/doc/cdbmake.h.0.md +++ b/src/doc/cdbmake.h.0.md @@ -26,37 +26,44 @@ The header defines the needed functions to create constant databases, known as The following structures are defined : : *struct cdbmaker_sa* -:: Semi-opaque structure used during the creating of a cdb in-memory. +:: An opaque structure to be passed to the functions below. + ## Macros The following macros are defined : : *CDBMAKER_SA_ZERO* -:: Can be used to initialized a *cdbmaker_sa* structure. +:: Value to initialize a *cdbmaker_sa* structure. ## Types -The followng types are defined : +The following types are defined : : *cdbmaker_sa* -:: Semi-opaque structure used during the creating of a cdb in-memory. +:: Opaque structure to be passed to the functions below. ## Functions -The following functions are defined : +The following functions/macros are defined : : [cdbmaker_sa_add](3) :: Similar to [cdbmake_add](3) but the cdb will be created in-memory. +: [cdbmaker_sa_data](3) +:: To get a pointer to the in-memory cdb. + +: [cdbmaker_sa_dlen](3) +:: To get the length of the in-memory cdb. + : [cdbmaker_sa_finish](3) :: Similar to [cdbmake_finish](3) but the cdb will be created in-memory. : [cdbmaker_sa_free](3) -:: To free memory associated with a semi-opaque *cdbmaker_sa* when done. +:: To free memory associated with an opaque *cdbmaker_sa* when done. : [cdbmaker_sa_init](3) -:: To initialize a *cdbmaker_sa* if not initalized through *CDBMAKER_SA_ZERO*. +:: To initialize a *cdbmaker_sa* if not initialized 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 d9a7077..c2556cf 100644 --- a/src/doc/cdbmake.h/cdbmaker_sa_start.3.md +++ b/src/doc/cdbmake.h/cdbmaker_sa_start.3.md @@ -4,7 +4,7 @@ # NAME cdbmaker\_sa\_init, cdbmaker\_sa\_start, cdbmaker\_sa\_add, cdbmaker\_sa\_finish, -cdbmaker\_sa\_free - create a cdb in memory +cdbmaker\_sa\_data, cdbmaker\_sa\_dlen, cdbmaker\_sa\_free - create a cdb in memory # SYNOPSIS @@ -17,6 +17,8 @@ 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>) +const char *cdbmaker_sa_data(cdbmaker_sa *<em>mkr</em>) +size_t cdbmaker_sa_dlen(cdbmaker_sa *<em>mkr</em>) void cdbmaker_sa_free(cdbmaker_sa *<em>mkr</em>) ``` @@ -31,9 +33,9 @@ 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`() 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. +The `cdbmaker_sa_start`() prepares the 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 @@ -51,15 +53,15 @@ Finally, the `cdbmaker_sa_finish`() function must be called after all elements have been added via `cdbmaker_sa_add`(), in order for the cdb to be actually created. -Specifically, the *cdbmaker_sa* structure pointed to by `mkr` has a member `sa` -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. +Then, the `cdbmaker_sa_data`() function will return a pointer to the in-memory +cdb data, i.e. the /content/ of a cdb file, whose length will be returned by +the `cdbmaker_sa_dlen`() function. -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. +The returned pointer can be used until the `cdbmaker_sa_free`() function is +called, which will free memory associated with the 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 @@ -67,6 +69,14 @@ The `cdbmaker_sa_start`(), `cdbmaker_sa_add`() and `cdbmaker_sa_finish`() functions return 1 on success. Otherwise, they return 0 and set `errno` to indicate the error. +The `cdbmaker_sa_data`() function returns a pointer to the generated cdb data. + +The `cdbmaker_sa_dlen`() function returns the length (in bytes) of the generated +cdb data, of which a pointer to can be obtained via `cdbmaker_sa_data`(). + +It is invalid to call either `cdbmaker_sa_data`() or `cdbmaker_sa_dlen`() +before a successful call to `cdbmaker_sa_finish`() was made. + # ERRORS The `cdbmaker_sa_start`(), `cdbmaker_sa_add`() and `cdbmaker_sa_finish`() may diff --git a/src/liblimb/include/limb/cdbmake.h b/src/liblimb/include/limb/cdbmake.h index f83c6b4..10d9952 100644 --- a/src/liblimb/include/limb/cdbmake.h +++ b/src/liblimb/include/limb/cdbmake.h @@ -18,10 +18,13 @@ 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); extern int cdbmaker_sa_finish(cdbmaker_sa *m); +#define cdbmaker_sa_data(ctx) ((const char *) (ctx)->sa.s) +#define cdbmaker_sa_dlen(ctx) (ctx)->sa.len extern void cdbmaker_sa_free(cdbmaker_sa *m); #endif /* LIMB_CDBMAKE_H */