$darkmode
Elektra 0.11.0
Plugin: dump

This plugin is a storage plugin that supports full Elektra semantics. Combined with a resolver plugin it already assembles a fully featured backend. No other plugins are needed.

Format

The file starts with the magic word kdbOpen followed by a version number (currently 2) and a newline. The plugin can read files of version 1 and 2, but it only writes version 2.

After this first line, the format consists of a series of commands. The supported commands are $key, $meta and $copymeta. We use the $ prefix to make the commands standout more. However, $ does not always mean command. Keynames and values could also start with $, but since the plugin always knows whether a command or something else comes next, we do not need any kind of escaping.

The $key command creates a new key. It takes 5 arguments. The first 3 are on the same line separated by a space. The other two are on separate lines:

1 $key <type> <nsize> <vsize>
2 <name>
3 <value>

<type> is either string or binary and indicates what kind of value the key contains. <nsize> and <vsize> are the name size and value size respectively. For the name and for string values, the size does not include the null-terminator present in C strings. For binary keys all bytes (including any null-terminators) are counted. <name> and <value> are the keyname and key value. Because we know their length, they can contain arbitrary characters. Even newlines are allowed. The newlines between <name> and <value>, and after <value> are just to make the file more readable. They must be present, but they do not determine where <name> or <value> end.

The $meta command adds a new metakey to the last key. It is very similar to the $key command, but it only takes 4 arguments. There is no type argument, because metakeys always have string values.

1 $meta <nsize> <vsize>
2 <name>
3 <value>

The arguments work just like they do for $key.

Finally, there is $copymeta. It is needed, because a keyCopyMeta call results in two keys with the same metakey (equal pointers). To achieve this, we indicate which metakey should be copied from which key. The $copymeta command also takes 4 arguments:

1 $copymeta <knsize> <mnsize>
2 <keyname>
3 <metaname>

<keyname> is the name of the key from which the metadata is copied and <knsize> is its size (without the null-terminator). Similarly, <metaname> is the name of the metakey that is copied and <mnsize> is its size (without the null-terminator).

There is also $end. It is used to signal the end of the data to the plugin. The $end command is completely optional. Without it, the plugin will just read the file until the end. However, in streaming use $end is needed, because there is no end of the "file".

Format Examples

The following is an example dump file that was mounted at system:/elektra/mountpoints:

1 kdbOpen 2
2 $key binary 0 0
3 
4 
5 $meta 6 0
6 binary
7 
8 $meta 7 27
9 comment
10 Below are the mount points.
11 $key string 4 18
12 dbus
13 serialized Backend
14 $key string 11 0
15 dbus/config
16 
17 $meta 7 71
18 comment
19 This is a configuration for a backend,
20 see subkeys for more information
21 $key string 12 0
22 fstab/config
23 
24 $copymeta 11 7
25 dbus/config
26 comment
27 $end

A few things you might have noticed:

Limitations

(status -1000)

Examples

Export a KeySet using dump:

1 kdb export system:/example dump > example.ecf

Import a KeySet using dump:

1 cat example.ecf | kdb import system:/example dump

Using grep/diff or other Unix tools on the dump file. Make sure that you treat it as text file, e.g.:

1 grep --text 'mount points' example.ecf