\hypertarget{group__kdb}{\section{K\-D\-B}
\label{group__kdb}\index{K\-D\-B@{K\-D\-B}}
}


General methods to access the Key database.  


\subsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
enum \hyperlink{group__kdb_ga98a3d6a4016c9dad9cbd1a99a9c2a45a}{option\-\_\-t} \{ \\*
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa00738455e0ae843c8720809d8287f370}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-N\-E} = 0, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa66a5380c120f25f28f49848c4a863ead}{K\-D\-B\-\_\-\-O\-\_\-\-D\-E\-L} = 1, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa52fb5f2cc86773d393da62bebebf7984}{K\-D\-B\-\_\-\-O\-\_\-\-P\-O\-P} = 1$<$$<$1, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa1a70738b2126badb8db7b012c8a1c610}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-D\-I\-R} = 1$<$$<$2, 
\\*
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa131e99d60253d0b887a1e5886f8aa96c}{K\-D\-B\-\_\-\-O\-\_\-\-D\-I\-R\-O\-N\-L\-Y} = 1$<$$<$3, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa7649f575c2eb0adeaf2c9173ae16e0e6}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-M\-O\-V\-E} = 1$<$$<$6, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaf6ed09cee8aa8cf0d6a0e318a7105440}{K\-D\-B\-\_\-\-O\-\_\-\-R\-E\-M\-O\-V\-E\-O\-N\-L\-Y} = 1$<$$<$7, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa789926d8a8e15b029cf7dded4154bcda}{K\-D\-B\-\_\-\-O\-\_\-\-I\-N\-A\-C\-T\-I\-V\-E} = 1$<$$<$8, 
\\*
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaa7d5265eacbb1590982b718f35443e2e}{K\-D\-B\-\_\-\-O\-\_\-\-S\-Y\-N\-C} = 1$<$$<$9, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aad9d03b36ee88ca5a774cc01b190c99b8}{K\-D\-B\-\_\-\-O\-\_\-\-S\-O\-R\-T} = 1$<$$<$10, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa6adaa17b267027ce50e670bf8cc6e824}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-C\-U\-R\-S\-I\-V\-E} = 1$<$$<$11, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaa5586d229e048f816bf7982765442b86}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-C\-A\-S\-E} = 1$<$$<$12, 
\\*
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aab2ff402f5de9aa67b7f786fb715a7a31}{K\-D\-B\-\_\-\-O\-\_\-\-W\-I\-T\-H\-O\-W\-N\-E\-R} = 1$<$$<$13, 
\hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aae8dd1961707e7d0c27228a3f98b0a94d}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-A\-L\-L} = 1$<$$<$14
 \}
\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
K\-D\-B $\ast$ \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\-Open} (Key $\ast$error\-Key)
\begin{DoxyCompactList}\small\item\em Opens the session with the Key database. \end{DoxyCompactList}\item 
int \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\-Close} (K\-D\-B $\ast$handle, Key $\ast$error\-Key)
\item 
int \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get} (K\-D\-B $\ast$handle, Key\-Set $\ast$ks, Key $\ast$parent\-Key)
\begin{DoxyCompactList}\small\item\em Retrieve keys in an atomic and universal way, all other \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()} Functions rely on that one. \end{DoxyCompactList}\item 
int \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set} (K\-D\-B $\ast$handle, Key\-Set $\ast$ks, Key $\ast$parent\-Key)
\end{DoxyCompactItemize}


\subsection{Detailed Description}
General methods to access the Key database. To use them\-: 
\begin{DoxyCode}
\textcolor{preprocessor}{#include <kdb.h>}
\end{DoxyCode}


The kdb$\ast$() class of methods are used to access the storage, to get and set \hyperlink{group__key}{Keys } or \hyperlink{group__keyset}{Key\-Sets }.

The most important functions are\-:
\begin{DoxyItemize}
\item \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\-Open()}
\item \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\-Close()}
\item \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}
\item \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set()}
\end{DoxyItemize}

The two essential functions for dynamic information about backends are\-:
\begin{DoxyItemize}
\item kdb\-Get\-Mountpoint()
\end{DoxyItemize}

They use some backend implementation to know the details about how to access the storage. Currently we have this backends\-:
\begin{DoxyItemize}
\item {\ttfamily berkeleydb\-:} the keys are stored in a Berkeley D\-B database, providing very small footprint, speed, and other advantages.
\item {\ttfamily filesys\-:} the key hierarchy and data are saved as plain text files in the filesystem.
\item {\ttfamily ini\-:} the key hierarchy are saved into configuration files. \begin{DoxySeeAlso}{See Also}
\href{http://www.libelektra.org/Ini}{\tt http\-://www.\-libelektra.\-org/\-Ini}
\end{DoxySeeAlso}

\item {\ttfamily fstab\-:} a reference backend used to interpret the {\ttfamily /etc/fstab} file as a set of keys under {\ttfamily system/filesystems} .
\item {\ttfamily gconf\-:} makes Elektra use the G\-Conf daemon to access keys. Only the {\ttfamily user/} tree is available since G\-Conf is not system wide.
\end{DoxyItemize}

Backends are physically a library named {\ttfamily /lib/libelektra-\/\{N\-A\-M\-E\}}.so.

See \hyperlink{group__plugin}{writing a new plugin } for information about how to write a plugin.

Language binding writers should follow the same rules\-:
\begin{DoxyItemize}
\item You must relay completely on the backend-\/dependent methods.
\item You may use or reimplement the second set of methods.
\item You should completely reimplement in your language the higher lever methods.
\item Many methods are just for comfort in C. These methods are marked and need not to be implemented if the binding language has e.\-g. string operators which can do the operation easily. 
\end{DoxyItemize}

\subsection{Enumeration Type Documentation}
\hypertarget{group__kdb_ga98a3d6a4016c9dad9cbd1a99a9c2a45a}{\index{K\-D\-B@{K\-D\-B}!option\-\_\-t@{option\-\_\-t}}
\index{option\-\_\-t@{option\-\_\-t}!KDB@{K\-D\-B}}
\subsubsection[{option\-\_\-t}]{\setlength{\rightskip}{0pt plus 5cm}enum {\bf option\-\_\-t}}}\label{group__kdb_ga98a3d6a4016c9dad9cbd1a99a9c2a45a}
Options to change the default behavior of \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}, \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set()} and \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\-Lookup()} functions.

These options can be O\-Red. That is the $|$-\/\-Operator in C.

\begin{DoxySeeAlso}{See Also}
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}, \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set()} 
\end{DoxySeeAlso}
\begin{Desc}
\item[Enumerator\-: ]\par
\begin{description}
\index{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-N\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-N\-E}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-N\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-N\-E}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa00738455e0ae843c8720809d8287f370}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-N\-E}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa00738455e0ae843c8720809d8287f370}
}]No Option set. Will be recursive with no inactive keys.

\begin{DoxySeeAlso}{See Also}
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}, \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set()}, \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\-Lookup()} 
\end{DoxySeeAlso}
\index{K\-D\-B\-\_\-\-O\-\_\-\-D\-E\-L@{K\-D\-B\-\_\-\-O\-\_\-\-D\-E\-L}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-D\-E\-L@{K\-D\-B\-\_\-\-O\-\_\-\-D\-E\-L}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa66a5380c120f25f28f49848c4a863ead}{K\-D\-B\-\_\-\-O\-\_\-\-D\-E\-L}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa66a5380c120f25f28f49848c4a863ead}
}]Delete parent\-Key key in \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}, \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set()} or \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\-Lookup()}.

\begin{DoxySeeAlso}{See Also}
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}, \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set()} 
\end{DoxySeeAlso}
\index{K\-D\-B\-\_\-\-O\-\_\-\-P\-O\-P@{K\-D\-B\-\_\-\-O\-\_\-\-P\-O\-P}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-P\-O\-P@{K\-D\-B\-\_\-\-O\-\_\-\-P\-O\-P}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa52fb5f2cc86773d393da62bebebf7984}{K\-D\-B\-\_\-\-O\-\_\-\-P\-O\-P}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa52fb5f2cc86773d393da62bebebf7984}
}]Pop Parent out of keyset key in \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}.

\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\-Pop()}. 
\end{DoxySeeAlso}
\index{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-D\-I\-R@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-D\-I\-R}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-D\-I\-R@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-D\-I\-R}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa1a70738b2126badb8db7b012c8a1c610}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-D\-I\-R}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa1a70738b2126badb8db7b012c8a1c610}
}]Exclude keys containing other keys in result.

Only return leaves.

\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keytest_gac0a10c602d52a35f81347e8a32312017}{key\-Is\-Dir()} 
\end{DoxySeeAlso}
\index{K\-D\-B\-\_\-\-O\-\_\-\-D\-I\-R\-O\-N\-L\-Y@{K\-D\-B\-\_\-\-O\-\_\-\-D\-I\-R\-O\-N\-L\-Y}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-D\-I\-R\-O\-N\-L\-Y@{K\-D\-B\-\_\-\-O\-\_\-\-D\-I\-R\-O\-N\-L\-Y}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa131e99d60253d0b887a1e5886f8aa96c}{K\-D\-B\-\_\-\-O\-\_\-\-D\-I\-R\-O\-N\-L\-Y}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa131e99d60253d0b887a1e5886f8aa96c}
}]Retrieve only directory keys (keys containing other keys). This will give you an skeleton without leaves. This must not be used together with K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-D\-I\-R. \begin{DoxySeeAlso}{See Also}
\hyperlink{group__keytest_gac0a10c602d52a35f81347e8a32312017}{key\-Is\-Dir()} 
\end{DoxySeeAlso}
\index{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-M\-O\-V\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-M\-O\-V\-E}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-M\-O\-V\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-M\-O\-V\-E}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa7649f575c2eb0adeaf2c9173ae16e0e6}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-M\-O\-V\-E}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa7649f575c2eb0adeaf2c9173ae16e0e6}
}]Don't remove any keys. This must not be used together with K\-D\-B\-\_\-\-O\-\_\-\-R\-E\-M\-O\-V\-E\-O\-N\-L\-Y. \index{K\-D\-B\-\_\-\-O\-\_\-\-R\-E\-M\-O\-V\-E\-O\-N\-L\-Y@{K\-D\-B\-\_\-\-O\-\_\-\-R\-E\-M\-O\-V\-E\-O\-N\-L\-Y}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-R\-E\-M\-O\-V\-E\-O\-N\-L\-Y@{K\-D\-B\-\_\-\-O\-\_\-\-R\-E\-M\-O\-V\-E\-O\-N\-L\-Y}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaf6ed09cee8aa8cf0d6a0e318a7105440}{K\-D\-B\-\_\-\-O\-\_\-\-R\-E\-M\-O\-V\-E\-O\-N\-L\-Y}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaf6ed09cee8aa8cf0d6a0e318a7105440}
}]Only remove keys. This must not be used together with K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-M\-O\-V\-E. \index{K\-D\-B\-\_\-\-O\-\_\-\-I\-N\-A\-C\-T\-I\-V\-E@{K\-D\-B\-\_\-\-O\-\_\-\-I\-N\-A\-C\-T\-I\-V\-E}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-I\-N\-A\-C\-T\-I\-V\-E@{K\-D\-B\-\_\-\-O\-\_\-\-I\-N\-A\-C\-T\-I\-V\-E}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa789926d8a8e15b029cf7dded4154bcda}{K\-D\-B\-\_\-\-O\-\_\-\-I\-N\-A\-C\-T\-I\-V\-E}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa789926d8a8e15b029cf7dded4154bcda}
}]Do not ignore inactive keys (that name begins with .). \begin{DoxySeeAlso}{See Also}
\hyperlink{group__keytest_gaa25f699f592031c1a0abc1504d14e13e}{key\-Is\-Inactive()} 
\end{DoxySeeAlso}
\index{K\-D\-B\-\_\-\-O\-\_\-\-S\-Y\-N\-C@{K\-D\-B\-\_\-\-O\-\_\-\-S\-Y\-N\-C}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-S\-Y\-N\-C@{K\-D\-B\-\_\-\-O\-\_\-\-S\-Y\-N\-C}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaa7d5265eacbb1590982b718f35443e2e}{K\-D\-B\-\_\-\-O\-\_\-\-S\-Y\-N\-C}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaa7d5265eacbb1590982b718f35443e2e}
}]Set keys independent of sync status. \begin{DoxySeeAlso}{See Also}
\hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\-Need\-Sync()} 
\end{DoxySeeAlso}
\index{K\-D\-B\-\_\-\-O\-\_\-\-S\-O\-R\-T@{K\-D\-B\-\_\-\-O\-\_\-\-S\-O\-R\-T}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-S\-O\-R\-T@{K\-D\-B\-\_\-\-O\-\_\-\-S\-O\-R\-T}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aad9d03b36ee88ca5a774cc01b190c99b8}{K\-D\-B\-\_\-\-O\-\_\-\-S\-O\-R\-T}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aad9d03b36ee88ca5a774cc01b190c99b8}
}]This option has no effect. Key\-Sets are always sorted. \begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000001}{Deprecated}]don't use \end{DoxyRefDesc}
\index{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-C\-U\-R\-S\-I\-V\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-C\-U\-R\-S\-I\-V\-E}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-C\-U\-R\-S\-I\-V\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-C\-U\-R\-S\-I\-V\-E}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa6adaa17b267027ce50e670bf8cc6e824}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-R\-E\-C\-U\-R\-S\-I\-V\-E}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa6adaa17b267027ce50e670bf8cc6e824}
}]Do not call \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()} for every key containing other keys (\hyperlink{group__keytest_gac0a10c602d52a35f81347e8a32312017}{key\-Is\-Dir()}). \index{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-C\-A\-S\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-C\-A\-S\-E}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-C\-A\-S\-E@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-C\-A\-S\-E}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaa5586d229e048f816bf7982765442b86}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-C\-A\-S\-E}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aaa5586d229e048f816bf7982765442b86}
}]Ignore case. \index{K\-D\-B\-\_\-\-O\-\_\-\-W\-I\-T\-H\-O\-W\-N\-E\-R@{K\-D\-B\-\_\-\-O\-\_\-\-W\-I\-T\-H\-O\-W\-N\-E\-R}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-W\-I\-T\-H\-O\-W\-N\-E\-R@{K\-D\-B\-\_\-\-O\-\_\-\-W\-I\-T\-H\-O\-W\-N\-E\-R}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aab2ff402f5de9aa67b7f786fb715a7a31}{K\-D\-B\-\_\-\-O\-\_\-\-W\-I\-T\-H\-O\-W\-N\-E\-R}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aab2ff402f5de9aa67b7f786fb715a7a31}
}]Search with owner. \index{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-A\-L\-L@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-A\-L\-L}!K\-D\-B@{K\-D\-B}}\index{K\-D\-B@{K\-D\-B}!K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-A\-L\-L@{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-A\-L\-L}}\item[{\em 
\hypertarget{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aae8dd1961707e7d0c27228a3f98b0a94d}{K\-D\-B\-\_\-\-O\-\_\-\-N\-O\-A\-L\-L}\label{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aae8dd1961707e7d0c27228a3f98b0a94d}
}]Only search from start -\/$>$ cursor to cursor -\/$>$ end. \end{description}
\end{Desc}



\subsection{Function Documentation}
\hypertarget{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{\index{K\-D\-B@{K\-D\-B}!kdb\-Close@{kdb\-Close}}
\index{kdb\-Close@{kdb\-Close}!KDB@{K\-D\-B}}
\subsubsection[{kdb\-Close}]{\setlength{\rightskip}{0pt plus 5cm}int kdb\-Close (
\begin{DoxyParamCaption}
\item[{K\-D\-B $\ast$}]{handle, }
\item[{Key $\ast$}]{error\-Key}
\end{DoxyParamCaption}
)}}\label{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}
Closes the session with the Key database.

You should call this method when you finished your affairs with the key database. You can manipulate Key and Key\-Set objects also after \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\-Close()}. You must not use any kdb$\ast$ call afterwards. You can implement \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\-Close()} in the atexit() handler.

This is the counterpart of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\-Open()}.

The {\ttfamily handle} parameter will be finalized and all resources associated to it will be freed. After a \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\-Close()}, this {\ttfamily handle} can't be used anymore, unless it gets initialized again with another call to \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\-Open()}.

\begin{DoxySeeAlso}{See Also}
\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\-Open()} 
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \\
\hline
{\em error\-Key} & the key which holds error information \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success 

-\/1 on N\-U\-L\-L pointer 
\end{DoxyReturn}
\hypertarget{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{\index{K\-D\-B@{K\-D\-B}!kdb\-Get@{kdb\-Get}}
\index{kdb\-Get@{kdb\-Get}!KDB@{K\-D\-B}}
\subsubsection[{kdb\-Get}]{\setlength{\rightskip}{0pt plus 5cm}int kdb\-Get (
\begin{DoxyParamCaption}
\item[{K\-D\-B $\ast$}]{handle, }
\item[{Key\-Set $\ast$}]{ks, }
\item[{Key $\ast$}]{parent\-Key}
\end{DoxyParamCaption}
)}}\label{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}


Retrieve keys in an atomic and universal way, all other \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()} Functions rely on that one. 

The {\ttfamily returned} Key\-Set must be initialized. The {\ttfamily returned} Key\-Set may already contain some keys. The new retrieved keys will be appended using \hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\-Append\-Key()}.

It will fully retrieve all keys under the {\ttfamily parent\-Key} folder, with all subfolders and their children.\hypertarget{group__kdb_kdbgetexample}{}\subsection{Example}\label{group__kdb_kdbgetexample}
This example demonstrates the typical usecase within an application without updating.

\begin{DoxyParagraph}{Example\-:}

\begin{DoxyCode}
KeySet *myConfig = \hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}(0);
Key *key = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"system/sw/MyApp"},\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
KDB *handle = \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}(key);

\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}(handle, myConfig, key);

\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}(key, \textcolor{stringliteral}{"user/sw/MyApp"});
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}(handle, myConfig, key);

\textcolor{comment}{// check for errors in key}
\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}(key);

key = \hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ksLookupByName}(myConfig,\textcolor{stringliteral}{"/sw/MyApp/key"}, 0);
\textcolor{comment}{// check if key is not 0 and work with it...}

\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel} (myConfig); \textcolor{comment}{// delete the in-memory configuration}


\textcolor{comment}{// maybe you want kdbSet() myConfig here}

\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}(handle, 0); \textcolor{comment}{// no more affairs with the key database.}
\end{DoxyCode}

\end{DoxyParagraph}
\hypertarget{group__kdb_kdbgetdetail}{}\subsection{Details}\label{group__kdb_kdbgetdetail}
When no backend could be found (e.\-g. no backend mounted) the default backend will be used.

If you pass N\-U\-L\-L on any parameter \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()} will fail immediately without doing anything.

When a backend fails \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()} will return -\/1 without any changes to one of the parameter.\hypertarget{group__kdb_kdbgetupdate}{}\subsection{Updating}\label{group__kdb_kdbgetupdate}
In the first run of kdb\-Get all keys are retrieved. On subsequent calls only the keys are retrieved where something was changed inside the key database. The other keys stay unchanged in the keyset, even when they were manipulated.

It is your responsibility to save the original keyset if you need it afterwards.

If you must get the same keyset again, e.\-g. in another thread you need to open a second handle to the key database using \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\-Open()}.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \\
\hline
{\em parent\-Key} & parent key holds the information which keys should be get -\/ invalid name gets all keys \\
\hline
{\em ks} & the (pre-\/initialized) Key\-Set returned with all keys found will not be changed on error or if no update is required \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ks\-Lookup\-By\-Name()} for powerful lookups after the Key\-Set was retrieved 
\end{DoxySeeAlso}
\begin{DoxyReturn}{Returns}
1 if the keys were retrieved successfully 

0 if there was no update -\/ no changes are made to the keyset then 

-\/1 on failure -\/ no changes are made to the keyset then 
\end{DoxyReturn}
\hypertarget{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{\index{K\-D\-B@{K\-D\-B}!kdb\-Open@{kdb\-Open}}
\index{kdb\-Open@{kdb\-Open}!KDB@{K\-D\-B}}
\subsubsection[{kdb\-Open}]{\setlength{\rightskip}{0pt plus 5cm}K\-D\-B$\ast$ kdb\-Open (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{error\-Key}
\end{DoxyParamCaption}
)}}\label{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}


Opens the session with the Key database. 

The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the {\ttfamily K\-D\-B} datastructure will be initialized.

You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\-Close()}. You can use the atexit () handler for it.

The pointer to the {\ttfamily K\-D\-B} structure returned will be initialized like described above, and it must be passed along on any kdb$\ast$() method your application calls.

Get a {\ttfamily K\-D\-B} handle for every thread using elektra. Don't share the handle across threads, and also not the pointer accessing it\-: 
\begin{DoxyCode}
thread1
\{
        KDB * h;
        h = \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}(0);
        \textcolor{comment}{// fetch keys and work with them}
        \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}(h, 0);
\}
thread2
\{
        KDB * h;
        h = \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}(0);
        \textcolor{comment}{// fetch keys and work with them}
        \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}(h, 0);
\}
\end{DoxyCode}


You don't need to use the \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\-Open()} if you only want to manipulate plain in-\/memory Key or Key\-Set objects without any affairs with the backend key database or when your application loads plugins directly.


\begin{DoxyParams}{Parameters}
{\em error\-Key} & the key which holds errors and warnings which were issued must be given \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\-Close()} to end all affairs to the \hyperlink{group__key}{Key} database. 
\end{DoxySeeAlso}
\begin{DoxyReturn}{Returns}
a K\-D\-B pointer on success 

N\-U\-L\-L on failure 
\end{DoxyReturn}
\hypertarget{group__kdb_ga11436b058408f83d303ca5e996832bcf}{\index{K\-D\-B@{K\-D\-B}!kdb\-Set@{kdb\-Set}}
\index{kdb\-Set@{kdb\-Set}!KDB@{K\-D\-B}}
\subsubsection[{kdb\-Set}]{\setlength{\rightskip}{0pt plus 5cm}int kdb\-Set (
\begin{DoxyParamCaption}
\item[{K\-D\-B $\ast$}]{handle, }
\item[{Key\-Set $\ast$}]{ks, }
\item[{Key $\ast$}]{parent\-Key}
\end{DoxyParamCaption}
)}}\label{group__kdb_ga11436b058408f83d303ca5e996832bcf}
Set keys in an atomic and universal way.

All other kdb\-Set Functions rely on that one.\hypertarget{group__kdb_kdbsetparent}{}\subsection{parent\-Key}\label{group__kdb_kdbsetparent}
With parent\-Key you can only store a part of the given keyset.


\begin{DoxyCode}
KeySet *ks = \hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}(0);
Key *parentKey = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/app/myapp/default"}, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet} (h, ks, parentKey));

\textcolor{comment}{//now only set everything below user}
\textcolor{keywordflow}{if} (\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet} (h, ks, parentKey) == -1)
\{
        \textcolor{comment}{// in parentKey you can check the error cause}
        \textcolor{comment}{// ksCurrent(ks) is the faulty key}
\}

\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel} (ks);
\end{DoxyCode}


If you pass a parent\-Key without a name the whole keyset will be set in an atomic way.\hypertarget{group__kdb_kdbsetupdate}{}\subsection{Update}\label{group__kdb_kdbsetupdate}
Each key is checked with \hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\-Need\-Sync()} before being actually committed. So only changed keys are updated. If no key of a backend needs to be synced any affairs to backends omitted and 0 is returned.\hypertarget{group__kdb_kdbseterror}{}\subsection{Error Situations}\label{group__kdb_kdbseterror}
If some error occurs, \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\-Set()} will stop. In this situation the Key\-Set internal cursor will be set on the key that generated the error.

None of the keys are actually commited.

You should present the error message to the user and let the user decide what to do. Possible solutions are\-:
\begin{DoxyItemize}
\item repeat the same kdb\-Set (for temporary errors)
\item remove the key and set it again (for validation or type errors)
\item change the value and try it again (for validation errors)
\item do a kdb\-Get and then (for conflicts ...)
\begin{DoxyItemize}
\item set the same keyset again (in favour of what was set by this user)
\item drop the old keyset (in favour of what was set elsewhere)
\end{DoxyItemize}
\item export the configuration into a file (for unresolvable errors)
\end{DoxyItemize}

\begin{DoxyParagraph}{Example of how this method can be used\-:}

\begin{DoxyCode}
\textcolor{keywordtype}{int} i;
KeySet *ks;  \textcolor{comment}{// the KeySet I want to set}
\textcolor{comment}{// fill ks with some keys}
\textcolor{keywordflow}{for} (i=0; i< NR\_OF\_TRIES; i++) \textcolor{comment}{// limit to NR\_OF\_TRIES tries}
\{
        ret=\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet}(handle, ks, parentKey);
        \textcolor{keywordflow}{if} (ret == -1)
        \{
                \textcolor{comment}{// We got an error. Warn user.}
                Key *problemKey = \hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ksCurrent}(ks);
                \textcolor{comment}{// parentKey has the errorInformation}
                \textcolor{comment}{// problemKey is the faulty key (may be null)}
                \textcolor{keywordtype}{int} userInput = showElektraErrorDialog (parentKey, problemKey);
                \textcolor{keywordflow}{switch} (userInput)
                \{
                \textcolor{keywordflow}{case} INPUT\_REPEAT: \textcolor{keywordflow}{continue};
                \textcolor{keywordflow}{case} INPUT\_REMOVE: \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ksLookup} (ks, parentKey, \hyperlink{group__kdb_gga98a3d6a4016c9dad9cbd1a99a9c2a45aa52fb5f2cc86773d393da62bebebf7984}{KDB\_O\_POP}
      ); \textcolor{keywordflow}{break};
                ...
                \}
        \}
\}
\end{DoxyCode}

\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \\
\hline
{\em ks} & a Key\-Set which should contain changed keys, otherwise nothing is done \\
\hline
{\em parent\-Key} & holds the information below which key keys should be set, see above \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 on success 

0 if nothing had to be done 

-\/1 on failure 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\-Need\-Sync()}, \hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\-Next()}, \hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\-Current()} 
\end{DoxySeeAlso}
