\hypertarget{group__api}{}\section{A\+PI 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\+PI 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\+StringF} (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 metadata 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}\item 
\mbox{\Hypertarget{group__api_gae62f02c136b4fdcd3bd5cf27305c66ce}\label{group__api_gae62f02c136b4fdcd3bd5cf27305c66ce}} 
Key $\ast$ \hyperlink{group__api_gae62f02c136b4fdcd3bd5cf27305c66ce}{key\+As\+Cascading} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em key\+Rel replacement \end{DoxyCompactList}\item 
int \hyperlink{group__api_ga6e151fb2c313e51d2a1a20588fc9aa92}{key\+Rel2} (const Key $\ast$key, const Key $\ast$check, Key\+Rel\+Type which)
\begin{DoxyCompactList}\small\item\em Replacement proposal for key\+Rel. \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\+PI.

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\+BI compatible. 

\subsection{Function Documentation}
\mbox{\Hypertarget{group__api_ga48120f254e09e0c5cceff4864f110ceb}\label{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{\texorpdfstring{elektra\+Key\+Get\+Meta\+Key\+Set()}{elektraKeyGetMetaKeySet()}}
{\footnotesize\ttfamily Key\+Set$\ast$ elektra\+Key\+Get\+Meta\+Key\+Set (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Return metadata 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 metadata 
\end{DoxyReturn}
\mbox{\Hypertarget{group__api_gac3e995819383f904369c260f212125f5}\label{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{\texorpdfstring{elektra\+Ks\+To\+Mem\+Array()}{elektraKsToMemArray()}}
{\footnotesize\ttfamily int elektra\+Ks\+To\+Mem\+Array (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{Key $\ast$$\ast$}]{buffer }\end{DoxyParamCaption})}



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}
KeySet *ks = somekeyset;
Key **keyArray = calloc (\hyperlink{group__keyset_ga7474ad6b0a0fa969dbdf267ba5770eee}{ksGetSize}(ks), \textcolor{keyword}{sizeof} (Key *));
\hyperlink{group__api_gac3e995819383f904369c260f212125f5}{elektraKsToMemArray} (ks, keyArray);
... work with the array ...
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}
\mbox{\Hypertarget{group__api_ga2dd8d2650e59a90e933c631267bfbb85}\label{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{\texorpdfstring{key\+Lock()}{keyLock()}}
{\footnotesize\ttfamily int key\+Lock (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{\hyperlink{group__keyset_ga98a3d6a4016c9dad9cbd1a99a9c2a45a}{option\+\_\+t}}]{what }\end{DoxyParamCaption})}



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\+ME to lock the name
\item K\+E\+Y\+\_\+\+F\+L\+A\+G\+\_\+\+L\+O\+C\+K\+\_\+\+V\+A\+L\+UE to lock the value
\item K\+E\+Y\+\_\+\+F\+L\+A\+G\+\_\+\+L\+O\+C\+K\+\_\+\+M\+E\+TA to lock the metadata
\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}
\mbox{\Hypertarget{group__api_ga6e151fb2c313e51d2a1a20588fc9aa92}\label{group__api_ga6e151fb2c313e51d2a1a20588fc9aa92}} 
\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!key\+Rel2@{key\+Rel2}}
\index{key\+Rel2@{key\+Rel2}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection{\texorpdfstring{key\+Rel2()}{keyRel2()}}
{\footnotesize\ttfamily int key\+Rel2 (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{const Key $\ast$}]{check,  }\item[{Key\+Rel\+Type}]{which }\end{DoxyParamCaption})}



Replacement proposal for key\+Rel. 

\begin{DoxyReturn}{Returns}
depending on relation type 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & usage error \\
\hline
{\em 0} & test failed \\
\hline
{\em $>$1} & true for binary tests, number of levels below for other relation tests\\
\hline
\end{DoxyRetVals}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
{\em check} & the second key object to check the relation with \\
\hline
{\em which} & what kind of relationship test should be done \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{group__api_ga812eb6c4f506dafa5733bf531c52199c}\label{group__api_ga812eb6c4f506dafa5733bf531c52199c}} 
\index{A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}!key\+Set\+StringF@{key\+Set\+StringF}}
\index{key\+Set\+StringF@{key\+Set\+StringF}!A\+P\+I Proposals for Elektra@{A\+P\+I Proposals for Elektra}}
\subsubsection{\texorpdfstring{key\+Set\+String\+F()}{keySetStringF()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Set\+StringF (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const char $\ast$}]{format,  }\item[{}]{... }\end{DoxyParamCaption})}



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}
\mbox{\Hypertarget{group__api_ga32f8e3258033e970589f23d9d7102bd1}\label{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{\texorpdfstring{ks\+Pop\+At\+Cursor()}{ksPopAtCursor()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Pop\+At\+Cursor (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{cursor\+\_\+t}]{pos }\end{DoxyParamCaption})}



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}
cursor\_t c = \hyperlink{group__keyset_gaffe507ab9281c322eb16c3e992075d29}{ksGetCursor}(ks);
\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel} (\hyperlink{group__api_ga32f8e3258033e970589f23d9d7102bd1}{ksPopAtCursor}(ks, c));
\hyperlink{group__keyset_gad94c9ffaa3e8034564c0712fd407c345}{ksSetCursor}(ks, c);
\hyperlink{group__api_gae7d268f13dd89a6e126b3718b117996f}{ksPrev}(ks); \textcolor{comment}{// to have correct key after next ksNext()}
\end{DoxyCode}


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

\begin{DoxyRetVals}{Return values}
{\em 0} & if ks is 0 \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__api_gae7d268f13dd89a6e126b3718b117996f}\label{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{\texorpdfstring{ks\+Prev()}{ksPrev()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Prev (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



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\textquotesingle{}ll get a N\+U\+LL pointer if the key before begin of the Key\+Set was reached.

Don\textquotesingle{}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}
\mbox{\Hypertarget{group__api_ga7557d07db07649b9d81e6da63ce59376}\label{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{\texorpdfstring{ks\+Rename\+Keys()}{ksRenameKeys()}}
{\footnotesize\ttfamily Key\+Set$\ast$ ks\+Rename\+Keys (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{config,  }\item[{const Key $\ast$}]{name }\end{DoxyParamCaption})}



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. 