Elektra serves as a universal and secure framework to access configuration parameters in a global, hierarchical key database and provides a mature, consistent and easily comprehensible A\+PI. Its modularity effectively avoids code duplication across applications and tools regarding configuration tasks. Elektra abstracts from cross-\/platform-\/related issues and allows applications to be aware of other applications\textquotesingle{} configurations, leveraging easy application integration.

See the \hyperlink{README_md}{readme} for more introduction. See the \hyperlink{doc_help_elektra-glossary_md}{glossary} for the used terminology.

\subsection*{A\+PI Docu}

This document\textquotesingle{}s main goal is to describe the A\+PI. It covers\+:


\begin{DoxyItemize}
\item external C-\/\+A\+PI (see Modules above), which are the essential core parts
\item C++-\/\+A\+PI (see Data Structures above) from a direct binding to high-\/level functionality, such as mounting functionality
\item plugins A\+PI, see Plugins
\item all other documentation of Elektra (see Related Pages next to Main Page)
\end{DoxyItemize}

On the one hand it gives an overview and an introduction for developers using Elektra, on the other hand it gives an informal description what methods must and may provide to allow an alternative implementation of the A\+PI.

The current version (for stable releases) of this document can be found at \href{https://doc.libelektra.org/api/current/html}{\tt https\+://doc.\+libelektra.\+org/api/current/html}

The latest version (from git master) of this document can be found at \href{https://doc.libelektra.org/api/latest/html}{\tt https\+://doc.\+libelektra.\+org/api/latest/html}

{\bfseries Important\+:} On Git\+Hub links to A\+PI functions are broken, so it is recommended that you continue reading in one of these links above.

\subsection*{Using the Elektra Library}

A C or C++ source file that wants to use Elektra should include\+: \begin{DoxyVerb}#include <kdb.h>
\end{DoxyVerb}


To link an executable with the Elektra library, one way is to use the {\ttfamily pkg-\/config} tool\+: \begin{DoxyVerb}$ gcc -o application `pkg-config --cflags --libs elektra` application.c
\end{DoxyVerb}


Another way is to use C\+Make\+: \begin{DoxyVerb}find_package(Elektra REQUIRED)
include_directories (${ELEKTRA_INCLUDE_DIR})
target_link_libraries (application ${ELEKTRA_LIBRARIES})
\end{DoxyVerb}


Read about \hyperlink{doc_COMPILE_md}{compiling elektra}.

\subsubsection*{Tutorials}


\begin{DoxyItemize}
\item \hyperlink{doc_tutorials_application-integration_md}{Application Integration}
\item \hyperlink{doc_tutorials_compilation-variants_md}{Compilation Variants}
\item \hyperlink{doc_tutorials_elektra-merge-integration_md}{Merge Integration}
\item \hyperlink{doc_tutorials_export_md}{Export}
\item \hyperlink{doc_tutorials_import_md}{Import}
\item \hyperlink{doc_tutorials_merge_md}{Merge}
\item \hyperlink{doc_tutorials_namespaces_md}{Namespaces}
\item \hyperlink{doc_tutorials_plugins_md}{Plugins}
\end{DoxyItemize}

\hyperlink{src_plugins_README_md}{List of all available Plugins} and get started by developing your own plugins \hyperlink{group__plugin}{Plugins}.

\subsection*{Elektra A\+PI}

The A\+PI was written in pure C because Elektra was designed to be useful even for the most basic system programs.

The A\+PI follows an object-\/oriented design, and there are 3 main classes as shown by the figure\+:

 Some general things you can do with each class are\+:

\hyperlink{group__kdb}{K\+DB (Key Database)}


\begin{DoxyItemize}
\item \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{Open} and \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{Close} the Key Database
\item \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{Get} and \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{Set} \hyperlink{group__keyset}{Key\+Set} in the Key Database
\item See \hyperlink{group__kdb}{class documentation} for more
\end{DoxyItemize}

\hyperlink{group__key}{Key}


\begin{DoxyItemize}
\item \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{Create} and \hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{Delete}
\item Get and Set key the \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{name}
\item Get and Set \hyperlink{group__keyvalue_ga622bde1eb0e0c4994728331326340ef2}{string} or \hyperlink{group__keyvalue_gaa50a5358fd328d373a45f395fa1b99e7}{binary} values
\item Get and Set \hyperlink{group__keymeta}{Meta Data}
\item See \hyperlink{group__key}{class documentation} for more
\end{DoxyItemize}

\hyperlink{group__keyset}{Key\+Set}


\begin{DoxyItemize}
\item \hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{Create} and \hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{Delete}
\item Append \hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{a single key} or an entire \hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{Key\+Set}
\item \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{Lookup keys}
\item Pop \hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{the last key}, \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{a key by name}, or \hyperlink{group__keyset_gaba1f1dbea191f4d7e7eb3e4296ae7d5e}{every key}
\item \hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{Work with} its \hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{internal cursor}
\item See \hyperlink{group__keyset}{class documentation} for more
\end{DoxyItemize}

\hyperlink{doc_dev_classes_md}{More background information about the classes}

\subsection*{Namespaces}

There are 5 trees (=namespaces) of keys\+: {\ttfamily spec}, {\ttfamily proc}, {\ttfamily dir}, {\ttfamily user} and {\ttfamily system} that are all unified (in the given order) in one cascading tree starting with {\ttfamily /}.

The cascading tree is the logical tree to be used in applications. The other trees are the physical ones that stem from configuration sources. When using cascading key the best key will be searched at run-\/time, which appears like a tree on its own. See cascading in the documentation of \hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ks\+Lookup\+By\+Name()} on how the selection of keys works.


\begin{DoxyItemize}
\item The {\ttfamily spec} tree

This tree specifies how the lookup should take place and also allows us to define defaults or document a key. The metadata of a key contains this information\+:
\begin{DoxyItemize}
\item {\ttfamily override/\#}\+: use these keys {\itshape in favor} of the key itself (note that {\ttfamily \#} is the syntax for arrays, e.\+g. {\ttfamily \#0} for the first element, {\ttfamily \#10} for the 11th and so on)
\item {\ttfamily namespace/\#}\+: instead of using all namespaces in the predefined order, one can specify which namespaces should be searched in which order
\item {\ttfamily fallback/\#}\+: when no key was found in any of the (specified) namespaces the {\ttfamily fallback}-\/keys will be searched
\item {\ttfamily default}\+: this value will be used if nothing else was found
\end{DoxyItemize}
\item The {\ttfamily proc} tree

Is the only read-\/only tree. The configuration does not stem from the \hyperlink{group__kdb}{K\+DB (Key Database)}, but any other source, e.\+g. command-\/line arguments or environment.
\item The {\ttfamily dir} tree

Allows us to have a per-\/directory overwrite of configuration files, e.\+g. for project specific settings.
\item The {\ttfamily user} tree

Used to store user-\/specific configurations, like the personal settings of a user to certain programs. The user subtree will always be favored if present (except for security concerns the user subtree may not be considered).
\item The {\ttfamily system} tree

It is provided to store system-\/wide configuration keys, that is, the last fallback for applications but the only resort for daemons and system services.
\end{DoxyItemize}

Read more about \hyperlink{doc_help_elektra-namespaces_md}{namespaces} and a tutorial for \hyperlink{doc_tutorials_namespaces_md}{namespaces}.

\subsection*{Rules for Key Names}

When using Elektra to store your application\textquotesingle{}s configuration and state, please keep in mind the following rules\+:


\begin{DoxyItemize}
\item You are not allowed to create keys right under the root. They are reserved for more generic purposes.
\item The keys for your application, called say {\itshape myapp}, should be created under {\ttfamily /sw/org/myapp/\#0/current}
\begin{DoxyItemize}
\item sw is for software
\item org is the organization. For uniqueness a full reverse url encoded with \textquotesingle{}/\textquotesingle{} instead of \textquotesingle{}.\textquotesingle{} is useful.
\item {\ttfamily \#0} is the major version of the configuration
\item current is the default configuration profile.
\item That means you just need to \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()} {\ttfamily /sw/org/myapp/\#0/profile} and then \hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ks\+Lookup\+By\+Name()} in {\ttfamily /sw/org/myapp/\#0/profile/key} where profile is from command-\/line arguments and defaults to current.
\end{DoxyItemize}
\end{DoxyItemize}

Read more about \hyperlink{doc_help_elektra-key-names_md}{key names}

\subsection*{Backend Overview}

The core of Elektra does not store configuration itself to the hard disk. Instead this work is delegated to backends.

If you want to develop a backend, you should already have some experience with Elektra from the user point of view. You should be familiar with the data structures\+: \hyperlink{group__key}{Key} and \hyperlink{group__keyset}{Key\+Set} Then you can start reading about Backends that are composed out of \hyperlink{group__plugin}{Plugins}. To get started with writing plugins, first read our \hyperlink{doc_tutorials_plugins_md}{plugin tutorial} and then lookup details in the A\+PI description in \hyperlink{group__plugin}{Plugins}.

Read more about \hyperlink{doc_help_elektra-mounting_md}{mounting}

\subsection*{S\+EE A\+L\+SO}


\begin{DoxyItemize}
\item See \hyperlink{doc_help_elektra-glossary_md}{elektra-\/glossary(7)}
\item More information about \hyperlink{doc_help_elektra-backends_md}{elektra-\/backends(7)}
\item More information about \hyperlink{doc_dev_plugins-framework_md}{plugins-\/framework} 
\end{DoxyItemize}