\subsection*{Structure of the key database}

The {\itshape key database} of Elektra is {\itshape hierarchically structured}. This means that keys are organized similar to directories in a file system.

Lets add some keys to the database. To add a key we can use this command\+: \begin{DoxyVerb}    kdb set <key> <value>
\end{DoxyVerb}


Now add the the key $\ast$$\ast$/a$\ast$$\ast$ with the Value {\bfseries Value 1} and the key $\ast$$\ast$/b/c$\ast$$\ast$ with the Value {\bfseries Value 2}\+: \begin{DoxyVerb}    kdb set /a 'Value 1'
    kdb set /b/c 'Value 2'
\end{DoxyVerb}


 Here you see the internal structure of the database after adding the keys $\ast$$\ast$/a$\ast$$\ast$ and $\ast$$\ast$/b/c$\ast$$\ast$. For instance the key $\ast$$\ast$/b/c$\ast$$\ast$ has the path $\ast$$\ast$/$\ast$$\ast$ -\/$>$ {\bfseries b} -\/$>$ {\bfseries c}.

Note how the name of the key determines the path to its value.

You can use the file system analogy as a mnemonic to remember these commands (like the file system commands in your favorite operating system)\+:
\begin{DoxyItemize}
\item {\ttfamily kdb ls $<$path$>$} lists keys below {\itshape path}
\item {\ttfamily kdb rm $<$key$>$} removes a {\itshape key}
\item {\ttfamily kdb cp $<$source$>$ $<$dest$>$} copies a key to another path
\item {\ttfamily kdb get $<$key$>$} gets the value of {\itshape key}
\end{DoxyItemize}

For example {\ttfamily kdb get /b/c} should return {\ttfamily Value 2} now, if you set the values before.

\subsection*{Namespaces}

Now we abandon the file system analogy and introduce the concept of {\itshape namespaces}.

Every key in Elektra belongs to one of these namespaces\+:
\begin{DoxyItemize}
\item {\bfseries spec} for specification of other keys
\item {\bfseries proc} for in-\/memory keys (e.\+g. command-\/line)
\item {\bfseries dir} for dir keys in current working directory
\item {\bfseries user} for user keys in home directory
\item {\bfseries system} for system keys in /etc or /
\end{DoxyItemize}

All namespaces save their keys in a {\itshape separate hierarchical structure} from the other namespaces.

But when we set the keys $\ast$$\ast$/a$\ast$$\ast$ and $\ast$$\ast$/b/c$\ast$$\ast$ before we didn't provide a namespace. So I hear you asking, if every key has to belong to a namespace, where are the keys? They are in the {\itshape user} namespace, as you can verify with\+: \begin{DoxyVerb}    kdb ls user
    # user/a
    # user/b/c
\end{DoxyVerb}


When we don't provide a namespace Elektra assumes a default namespace, which should be {\bfseries user} for non-\/root users. So if you are a normal user the command {\ttfamily kdb set /b/c 'Value 2'} was synonymous to {\ttfamily kdb set user/b/c 'Value 2'}.

At this point the key database should have this structure\+:  \paragraph*{Cascading keys}

Another question you may ask yourself now is, what happens if we lookup a key without providing a namespace. So let us retrieve the key $\ast$$\ast$/b/c$\ast$$\ast$ with the -\/v flag in order to make {\itshape kdb} more talkative. \begin{DoxyVerb}    kdb get -v /b/c
    # got 3 keys
    #  searching spec/b/c, found: <nothing>, options: KDB_O_CALLBACK
    #  searching proc/b/c, found: <nothing>, options:
    #  searching dir/b/c, found: <nothing>, options:
    #  searching user/b/c, found: user/b/c, options:
    # The resulting keyname is user/b/c
    # Value 2
\end{DoxyVerb}


Here you see how Elektra searches all namespaces for matching keys in this order\+: {\bfseries spec}, {\bfseries proc}, {\bfseries dir}, {\bfseries user} and finally {\bfseries system}

If a key is found in a namespace, it masks the key in all subsequent namespaces, which is the reason why the system namespace isn't searched. Finally the virtual key $\ast$$\ast$/b/c$\ast$$\ast$ gets resolved to the real key {\bfseries user/b/c}. Because of the way a key without a namespace is retrieved, we call keys, that start with '$\ast$$\ast$/$\ast$$\ast$' {\bfseries cascading keys}. You can find out more about cascading lookups \hyperlink{doc_tutorials_cascading_md}{here}.

Having namespaces enables both admins and users to set specific parts of the application's configuration, as you will see in the following example.

\subsection*{How it works on the command line (kdb)}

Let's say your app requires the following configuration data\+:


\begin{DoxyItemize}
\item $\ast$$\ast$/sw/org/myapp/policy$\ast$$\ast$ -\/ a security policy to be applied
\item $\ast$$\ast$/sw/org/myapp/default\+\_\+dir$\ast$$\ast$ -\/ a place where the application stores its data per default
\end{DoxyItemize}

We now want to enter this configuration by using the {\bfseries kdb} tool.

The security policy will most probably be set by your system administrator. So she enters \begin{DoxyVerb}    sudo kdb set "system/sw/org/myapp/policy" "super-high-secure"
\end{DoxyVerb}


The key {\bfseries system/app/policy} will be stored in the system namespace (probably at /etc/kdb on a Linux/\+U\+N\+I\+X system).

Then the user sets his app directory by issuing\+: \begin{DoxyVerb}    kdb set "user/sw/org/myapp/default_dir" "/home/user/.myapp"
\end{DoxyVerb}


This key will be stored in the user namespace (at the home directory) and thus may vary from user to user. Elektra loads the value for the current user and passes it to the application.

You can also retrieve the values in the command line by using the {\bfseries kdb} tool\+: \begin{DoxyVerb}    kdb get system/sw/org/maypp
\end{DoxyVerb}


{\itshape Cascading keys} are keys that start with $\ast$$\ast$/$\ast$$\ast$ and are a way of making key lookups much easier. Let's say you want to load the configuration from the example above. You do not need to search every namespace by yourself. Just make a lookup for $\ast$$\ast$/sw/org/myapp$\ast$$\ast$, like this\+: \begin{DoxyVerb}    kdb get /sw/org/myapp/policy
    kdb get /sw/org/myapp/default_dir
\end{DoxyVerb}


When using cascading key the best key will be searched at runtime. If you are only interested in the system key, you would use\+: \begin{DoxyVerb}    kdb get system/sw/org/myapp/policy
\end{DoxyVerb}


\subsection*{How it works in C}

The idea is to call {\bfseries \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} to retrieve the root key for the application. Looking for a specific part of the configuration is done by {\bfseries \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\+Lookup()}}.

The documentation provides the following example to illustrate the intended usage. If you want to use a {\itshape cascading key} (starting with /), you use the {\bfseries \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\+Lookup()}} or {\bfseries \hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ks\+Lookup\+By\+Name()}} function (also see \href{http://doc.libelektra.org/api/current/html/group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004}{\tt doxygen} )\+: \begin{DoxyVerb}    if (kdbGet(handle, myConfig,  p=keyNew("/sw/org/myapp", KEY_END)) == -1)
            errorHandler ("Could not get Keys", parentKey);
    if ((myKey = ksLookupByName (myConfig, "/sw/org/myapp/mykey", 0)) == NULL)
            errorHandler ("Could not Lookup Key");\end{DoxyVerb}
 