<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">
\begin{DoxyItemize}
\item infos = Information about the dump plugin is in keys below
\item infos/author = Markus Raab \href{mailto:elektra@libelektra.org}{\tt elektra@libelektra.\+org}, Klemens BÃ¶swirth \href{mailto:k.boeswirth+git@gmail.com}{\tt k.\+boeswirth+git@gmail.\+com}
\item infos/licence = B\+SD
\item infos/needs =
\item infos/provides = storage/dump
\item infos/recommends =
\item infos/placements = getstorage setstorage
\item infos/status = productive maintained conformant unittest tested nodep -\/1000
\item infos/metadata =
\item infos/description = Dumps into a format tailored for complete Key\+Set semantics
\end{DoxyItemize}

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.

The file starts with the magic word {\ttfamily kdb\+Open} followed by a version number (currently {\ttfamily 2}) and a newline. The plugin can read files of version {\ttfamily 1} and {\ttfamily 2}, but it only writes version {\ttfamily 2}.

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

The {\ttfamily \$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\+:


\begin{DoxyCode}
$key &lt;type&gt; &lt;nsize&gt; &lt;vsize&gt;
&lt;name&gt;
&lt;value&gt;
\end{DoxyCode}


{\ttfamily $&lt;$type$&gt;$} is either {\ttfamily string} or {\ttfamily binary} and indicates what kind of value the key contains. {\ttfamily $&lt;$nsize$&gt;$} and {\ttfamily $&lt;$vsize$&gt;$} 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. {\ttfamily $&lt;$name$&gt;$} and {\ttfamily $&lt;$value$&gt;$} are the keyname and key value. Because we know their length, they can contain arbitrary characters. Even newlines are allowed. The newlines between {\ttfamily $&lt;$name$&gt;$} and {\ttfamily $&lt;$value$&gt;$}, and after {\ttfamily $&lt;$value$&gt;$} are just to make the file more readable. They must be present, but they do not determine where {\ttfamily $&lt;$name$&gt;$} or {\ttfamily $&lt;$value$&gt;$} end.

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


\begin{DoxyCode}
$meta &lt;nsize&gt; &lt;vsize&gt;
&lt;name&gt;
&lt;value&gt;
\end{DoxyCode}


The arguments work just like they do for {\ttfamily \$key}.

Finally, there is {\ttfamily \$copymeta}. It is needed, because a {\ttfamily key\+Copy\+Meta} 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 {\ttfamily \$copymeta} command also takes 4 arguments\+:


\begin{DoxyCode}
$copymeta &lt;knsize&gt; &lt;mnsize&gt;
&lt;keyname&gt;
&lt;metaname&gt;
\end{DoxyCode}


{\ttfamily $&lt;$keyname$&gt;$} is the name of the key from which the metadata is copied and {\ttfamily $&lt;$knsize$&gt;$} is its size (without the null-\/terminator). Similarly, {\ttfamily $&lt;$metaname$&gt;$} is the name of the metakey that is copied and {\ttfamily $&lt;$mnsize$&gt;$} is its size (without the null-\/terminator).

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

The following is an example {\ttfamily dump} file that was mounted at {\ttfamily system/elektra/mountpoints}\+:


\begin{DoxyCode}
kdbOpen 2
$key binary 0 0


$meta 6 0
binary

$meta 7 27
comment
Below are the mount points.
$key string 4 18
dbus
serialized Backend
$key string 11 0
dbus/config

$meta 7 71
comment
This is a configuration for a backend,
see subkeys for more information
$key string 12 0
fstab/config

$copymeta 11 7
dbus/config
comment
$end
\end{DoxyCode}


A few things you might have noticed\+:


\begin{DoxyItemize}
\item The first key has an empty name, because it is the root key of this mountpoint.
\item The value size of {\ttfamily 0} for the first key makes it a {\ttfamily N\+U\+LL} key, but only because it is {\ttfamily binary}. The third key ({\ttfamily \$key string 11 0}) also has value size 0, but is a {\ttfamily string} key. This means its value is an empty string {\ttfamily \char`\"{}\char`\"{}}.
\item The empty lines after {\ttfamily \$key binary 0 -\/1} and {\ttfamily dbus/config} are because the respective names/values are empty.
\item The comment above {\ttfamily \$key string 25 0} shows that newlines in key values are completely fine, because we know what size the value has to be.
\end{DoxyItemize}

(status -\/1000)


\begin{DoxyItemize}
\item It is quite slow
\end{DoxyItemize}

Export a Key\+Set using {\ttfamily dump}\+:


\begin{DoxyCode}
kdb export system/example dump &gt; example.ecf
\end{DoxyCode}


Import a Key\+Set using {\ttfamily dump}\+:


\begin{DoxyCode}
cat example.ecf | kdb import system/example dump
\end{DoxyCode}


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


\begin{DoxyCode}
grep --text 'mount points' example.ecf
\end{DoxyCode}
 </pre></body></html>