Elektra
0.9.7
|
This document describes the design of Elektra's C-API and provides hints for binding writers. It is not aimed at plugin writers, since it does not talk about the implementation details of Elektra.
Elektra aims at following design principles:
The C-API is suitable to be reimplemented, also in non-C-languages, like Rust. Elektra provides a full blown architecture to support configuring systems, and the C-API is the core of this endeavour.
The Key
, KeySet
and KDB
data structures are defined in kdbprivate.h
to allow ABI compatibility. This means, it is not possible to put one of Elektra’s data structures on the stack. You must use the memory management facilities mentioned in the next section.
Elektra provides functions that create and free data. For example after you call:
you need to use:
to get rid of the resources again. The second function may also shut down connections. Therefore it must be called before the end of a program.
In the above pairs, the first function reserves the necessary amount of memory. The second function frees the allocated data segment. There are more allocations happening but they are invisible to the user of the API and happen implicitly within any of these 3 classes: KDB
, Key
and KeySet
.
Key names and values cannot be handled as easy, because Elektra does not provide a string library. There are 2 ways to access the mentioned attributes. The function
returns a string. You are not allowed to change the returned string. The function
shows how long the string is for the specified key. The returned value also specifies the minimum buffer size that keyGetString
will reserve for the copy of the key.
writes the comment in a buffer maintained by you.
The constructors for Key
and KeySet
take a variable sized list of arguments. They can be used as an alternatives to the various keySet*
methods and ksAppendKey
. With them you are able to generate any Key
or KeySet
with a single C-statement. This can be done programmatically by the plugin c
.
To just retrieve a key, use
To obtain a keyset
, use
Alternatively pass a list as described in the documentation. The idea of these variable arguments is, that one function call can create any KeySet
. For binding writers keyVNew
might be useful.
We avoid off-by-one errors by starting all indices with 0, as usual in C. The size returned by the *GetSize
functions (keyGetValueSize
, keyGetCommentSize
and keyGetOwnerSize
) is exactly the size you need to allocate. So if you add 1 to it, too much space is allocated, but no error will occur.
The same is true for elektraStrLen
which also already has the null byte included.
kdb.h
contains a minimal set of functions to fully work with a key database. The functions are implemented in src/libs/elektra
in ANSI C.
Useful extensions are available in further libraries.
Sometimes people confuse the terms “value”, “string” and “binary”:
See also the glossary for further terminology.
In Elektra char*
are used as null-terminated strings, while void*
might contain 0
-bytes:
does not specify whether the returned value is binary or a string. The function just returns the pointer to the value. When key
is a string (check with keyIsString
) at least ""
will be returned. See section “Return Values” to learn more about common values returned by Elektra’s functions. For binary data a NULL
pointer is also possible to distinguish between no data and ‘’\0'`.
does not specify whether the key type is binary or string. The function just returns the size which can be passed to elektraMalloc
to hold the entire value.
stores the string into a buffer maintained by you.
sets the null terminated string value for a certain key.
retrieves binary data which might contain ‘’\0'`.
sets the binary data which might contain ‘’\0'. The length is given by
dataSize`.
Elektra’s function share common error codes. Every function must return -1
on error, if its return type is integer (like int
, ssize_t
). If the function returns a pointer, 0
(NULL
) will indicate an error.
Elektra uses integers for the length of C strings, reference counting, KeySet
length and internal KeySet
allocations.
The interface always accepts ssize_t
and internally uses size_t
, which is able to store larger numbers than ssize_t
.
The real size of C strings and buffers is limited to SSIZE_MAX
. When a string exceeds that limit -1
or a NULL
pointer (see above) must be returned.
The following functions return an internal string:
and in the case that keyIsBinary(key)==0
:
does so, too. If in any of the functions above key
is a NULL
pointer, then they also return NULL
.
If there is no string you will get back ""
, that is a pointer to the value ‘’\0'. The function to determine the size will return
1` in that case. That means that an empty string – nothing except the NULL terminator – has size 1
.
This is not true for keyValue
in the case of binary data, because the value ‘’\0'in the first byte is perfectly legal binary data.
keyGetValueSizemay also return
0` for that reason.
For KDB
functions the user does not only get the return value but also a more elaborate error information, including an error message, in the metadata of the parentKey
or errorKey
. Furthermore, it is also possible to get warnings, even if the calls succeeded.
Using different error categories, the user of the API can have suitable reactions on specific error situations. Additional information about error handling is available here.
Elektra does not set errno
. If a function you call sets errno
, make sure to set it back to the old value again.
All function names begin with their class name, e.g. kdb
, ks
or key
. We use capital letters to separate single words (CamelCase). This leads to short names, but might be not as readable as separating names by other means.
Get and Set are used for getters/and setters. We use Is to ask about a flag or state and Needs to ask about state related to databases. For allocation/deallocation we use C++ styled names (e.g *New
, *Del
).
Macros and Enums are written in capital letters. Flags start with KDB_
, namespaces with KEY_NS_
and macros with ELEKTRA_
.
Data structures start with a capital letter for every part of the word:
KDB
... Key Data Base HandleKeySet
... Key SetKey
... KeyWe use singular for all names.
Function names not belonging to one of the three classes use the prefix elektra*
.
Wherever possible functions should use the keyword const
for parameters. The API uses this keyword for parameters, to show that a function does not modify a Key
or a KeySet
, e.g.:
The reason behind this is, that the above functions – as their name suggest – only retrieve values. The returned value must not be modified directly.
On potential changes of the API/ABI as detected by the build server
, please make sure the API has been reviewed according to the following 2 checklists:
There are several checklists for functions, depending on the language in which the function is written: