\hypertarget{group__api}{\section{A\+P\+I Proposals for Elektra}
\label{group__api}\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
}


for kdb.\+h.  


Collaboration diagram for A\+P\+I Proposals for Elektra\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=350pt]{group__api}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
ssize\+\_\+t \hyperlink{group__api_ga812eb6c4f506dafa5733bf531c52199c}{key\+Set\+String\+F} (Key $\ast$key, const char $\ast$format,...)
\begin{DoxyCompactList}\small\item\em Set a formatted string. \end{DoxyCompactList}\item 
int \hyperlink{group__api_gac3e995819383f904369c260f212125f5}{elektra\+Ks\+To\+Mem\+Array} (Key\+Set $\ast$ks, Key $\ast$$\ast$buffer)
\begin{DoxyCompactList}\small\item\em Builds an array of pointers to the keys in the supplied keyset. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \hyperlink{group__api_ga7557d07db07649b9d81e6da63ce59376}{ks\+Rename\+Keys} (Key\+Set $\ast$config, const Key $\ast$name)
\begin{DoxyCompactList}\small\item\em Takes the first key and cuts off this common part for all other keys, instead name will be prepended. \end{DoxyCompactList}\item 
int \hyperlink{group__api_ga2dd8d2650e59a90e933c631267bfbb85}{key\+Lock} (Key $\ast$key, \hyperlink{group__keyset_ga98a3d6a4016c9dad9cbd1a99a9c2a45a}{option\+\_\+t} what)
\begin{DoxyCompactList}\small\item\em Permanently locks a part of the key. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \hyperlink{group__api_ga48120f254e09e0c5cceff4864f110ceb}{elektra\+Key\+Get\+Meta\+Key\+Set} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Return meta data as keyset. \end{DoxyCompactList}\item 
Key $\ast$ \hyperlink{group__api_gae7d268f13dd89a6e126b3718b117996f}{ks\+Prev} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Returns the previous Key in a Key\+Set. \end{DoxyCompactList}\item 
Key $\ast$ \hyperlink{group__api_ga32f8e3258033e970589f23d9d7102bd1}{ks\+Pop\+At\+Cursor} (Key\+Set $\ast$ks, cursor\+\_\+t pos)
\begin{DoxyCompactList}\small\item\em Pop key at given cursor position. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
for kdb.\+h. 

\begin{DoxyWarning}{Warning}
Do not use these methods if you do not want to depend on exactly the Elektra version your binary was built for.
\end{DoxyWarning}
These methods are a technical preview of what might be added in future Elektra releases. It is a requirement that methods are first added here, before they are added to the public A\+P\+I.

Usually, names in proposal stage should be prefixed with elektra to clearly mark that the signature is likely to be changed and not yet A\+B\+I compatible. 

\subsection{Function Documentation}
\hypertarget{group__api_ga48120f254e09e0c5cceff4864f110ceb}{\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!elektra\+Key\+Get\+Meta\+Key\+Set@{elektra\+Key\+Get\+Meta\+Key\+Set}}
\index{elektra\+Key\+Get\+Meta\+Key\+Set@{elektra\+Key\+Get\+Meta\+Key\+Set}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection[{elektra\+Key\+Get\+Meta\+Key\+Set}]{\setlength{\rightskip}{0pt plus 5cm}Key\+Set$\ast$ elektra\+Key\+Get\+Meta\+Key\+Set (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__api_ga48120f254e09e0c5cceff4864f110ceb}


Return meta data as keyset. 


\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a duplication of the keyset representing the meta data 
\end{DoxyReturn}
\hypertarget{group__api_gac3e995819383f904369c260f212125f5}{\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!elektra\+Ks\+To\+Mem\+Array@{elektra\+Ks\+To\+Mem\+Array}}
\index{elektra\+Ks\+To\+Mem\+Array@{elektra\+Ks\+To\+Mem\+Array}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection[{elektra\+Ks\+To\+Mem\+Array}]{\setlength{\rightskip}{0pt plus 5cm}int elektra\+Ks\+To\+Mem\+Array (
\begin{DoxyParamCaption}
\item[{Key\+Set $\ast$}]{ks, }
\item[{Key $\ast$$\ast$}]{buffer}
\end{DoxyParamCaption}
)}}\label{group__api_gac3e995819383f904369c260f212125f5}


Builds an array of pointers to the keys in the supplied keyset. 

The keys are not copied, calling key\+Del may remove them from the keyset.

The size of the buffer can be easily allocated via ks\+Get\+Size. Example\+: 
\begin{DoxyCode}
1 KeySet *ks = somekeyset;
2 Key **keyArray = calloc (ksGetSize(ks), sizeof (Key *));
3 elektraKsToMemArray (ks, keyArray);
4 ... work with the array ...
5 elektraFree (keyArray);
\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em ks} & the keyset object to work with \\
\hline
{\em buffer} & the buffer to put the result into \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the number of elements in the array if successful 

a negative number on null pointers or if an error occurred 
\end{DoxyReturn}
\hypertarget{group__api_ga2dd8d2650e59a90e933c631267bfbb85}{\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!key\+Lock@{key\+Lock}}
\index{key\+Lock@{key\+Lock}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection[{key\+Lock}]{\setlength{\rightskip}{0pt plus 5cm}int key\+Lock (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{key, }
\item[{{\bf option\+\_\+t}}]{what}
\end{DoxyParamCaption}
)}}\label{group__api_ga2dd8d2650e59a90e933c631267bfbb85}


Permanently locks a part of the key. 

This can be\+:
\begin{DoxyItemize}
\item K\+E\+Y\+\_\+\+F\+L\+A\+G\+\_\+\+L\+O\+C\+K\+\_\+\+N\+A\+M\+E to lock the name
\item K\+E\+Y\+\_\+\+F\+L\+A\+G\+\_\+\+L\+O\+C\+K\+\_\+\+V\+A\+L\+U\+E to lock the value
\item K\+E\+Y\+\_\+\+F\+L\+A\+G\+\_\+\+L\+O\+C\+K\+\_\+\+M\+E\+T\+A to lock the meta data
\end{DoxyItemize}

To unlock the key, duplicate it.

It is also possible to lock when the key is created with \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}.

Some data structures need to lock the key (most likely its name), so that the ordering does not get confused.


\begin{DoxyParams}{Parameters}
{\em key} & which name should be locked\\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}, \hyperlink{group__key_gae6ec6a60cc4b8c1463fa08623d056ce3}{key\+Dup()}, \hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()} 
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em $>$0} & the bits that were successfully locked \\
\hline
{\em 0} & if everything was locked before \\
\hline
{\em -\/1} & if it could not be locked (nullpointer) \\
\hline
\end{DoxyRetVals}
\hypertarget{group__api_ga812eb6c4f506dafa5733bf531c52199c}{\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!key\+Set\+String\+F@{key\+Set\+String\+F}}
\index{key\+Set\+String\+F@{key\+Set\+String\+F}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection[{key\+Set\+String\+F}]{\setlength{\rightskip}{0pt plus 5cm}ssize\+\_\+t key\+Set\+String\+F (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{key, }
\item[{const char $\ast$}]{format, }
\item[{}]{...}
\end{DoxyParamCaption}
)}}\label{group__api_ga812eb6c4f506dafa5733bf531c52199c}


Set a formatted string. 


\begin{DoxyParams}{Parameters}
{\em key} & the key to set the string value \\
\hline
{\em format} & N\+U\+L\+L-\/terminated text format string \\
\hline
{\em ...} & more arguments\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size of the string as set (with including 0) 
\end{DoxyReturn}
\hypertarget{group__api_ga32f8e3258033e970589f23d9d7102bd1}{\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!ks\+Pop\+At\+Cursor@{ks\+Pop\+At\+Cursor}}
\index{ks\+Pop\+At\+Cursor@{ks\+Pop\+At\+Cursor}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection[{ks\+Pop\+At\+Cursor}]{\setlength{\rightskip}{0pt plus 5cm}Key$\ast$ ks\+Pop\+At\+Cursor (
\begin{DoxyParamCaption}
\item[{Key\+Set $\ast$}]{ks, }
\item[{cursor\+\_\+t}]{pos}
\end{DoxyParamCaption}
)}}\label{group__api_ga32f8e3258033e970589f23d9d7102bd1}


Pop key at given cursor position. 


\begin{DoxyParams}{Parameters}
{\em ks} & the keyset to pop key from \\
\hline
{\em c} & where to pop\\
\hline
\end{DoxyParams}
The internal cursor will be rewinded using \hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}. You can use \hyperlink{group__keyset_gaffe507ab9281c322eb16c3e992075d29}{ks\+Get\+Cursor()} and \hyperlink{group__keyset_gad94c9ffaa3e8034564c0712fd407c345}{ks\+Set\+Cursor()} jump back to the previous position. e.\+g. to pop at current position within \hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()} loop\+: 
\begin{DoxyCode}
1 cursor\_t c = ksGetCursor(ks);
2 keyDel (ksPopAtCursor(ks, c));
3 ksSetCursor(ks, c);
4 ksPrev(ks); // to have correct key after next ksNext()
\end{DoxyCode}


\begin{DoxyWarning}{Warning}
do not use, will be superseded by external iterator A\+P\+I
\end{DoxyWarning}
\begin{DoxyReturn}{Returns}
the popped key 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & if ks is 0 \\
\hline
\end{DoxyRetVals}
\hypertarget{group__api_gae7d268f13dd89a6e126b3718b117996f}{\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!ks\+Prev@{ks\+Prev}}
\index{ks\+Prev@{ks\+Prev}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection[{ks\+Prev}]{\setlength{\rightskip}{0pt plus 5cm}Key$\ast$ ks\+Prev (
\begin{DoxyParamCaption}
\item[{Key\+Set $\ast$}]{ks}
\end{DoxyParamCaption}
)}}\label{group__api_gae7d268f13dd89a6e126b3718b117996f}


Returns the previous Key in a Key\+Set. 

Key\+Sets have an internal cursor that can be reset with \hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}. Every time \hyperlink{group__api_gae7d268f13dd89a6e126b3718b117996f}{ks\+Prev()} is called the cursor is decremented and the new current Key is returned.

You'll get a N\+U\+L\+L pointer if the key before begin of the Key\+Set was reached.

Don't delete the key, use \hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop()} if you want to delete it.

\begin{DoxyReturn}{Returns}
the new current Key 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}, \hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()} 
\end{DoxySeeAlso}
\hypertarget{group__api_ga7557d07db07649b9d81e6da63ce59376}{\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!ks\+Rename\+Keys@{ks\+Rename\+Keys}}
\index{ks\+Rename\+Keys@{ks\+Rename\+Keys}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection[{ks\+Rename\+Keys}]{\setlength{\rightskip}{0pt plus 5cm}Key\+Set$\ast$ ks\+Rename\+Keys (
\begin{DoxyParamCaption}
\item[{Key\+Set $\ast$}]{config, }
\item[{const Key $\ast$}]{name}
\end{DoxyParamCaption}
)}}\label{group__api_ga7557d07db07649b9d81e6da63ce59376}


Takes the first key and cuts off this common part for all other keys, instead name will be prepended. 

\begin{DoxyReturn}{Returns}
a new allocated keyset with keys in user namespace.
\end{DoxyReturn}
The first key is removed in the resulting keyset. 