\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=348pt]{group__api}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
const void $\ast$ \hyperlink{group__api_ga6fe6af4c27b35d911a533f4ae4d698bb}{key\-Unescaped\-Name} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em This keyname is null separated and does not use backslash for escaping. \end{DoxyCompactList}\item 
ssize\-\_\-t \hyperlink{group__api_ga5e7eff0c77678420199d0d2e8729152b}{key\-Get\-Unescaped\-Name\-Size} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em return size of unescaped name \end{DoxyCompactList}\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_gafc46476b8d722d89e07a966e023df317}{elektra\-Array\-Inc\-Name} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Increment the name of the key by one. \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 
int \hyperlink{group__api_ga5e727c6d8197f5871a2075454b6214f2}{elektra\-Ks\-Filter} (Key\-Set $\ast$result, Key\-Set $\ast$input, int($\ast$filter)(const Key $\ast$k, void $\ast$argument), void $\ast$argument)
\begin{DoxyCompactList}\small\item\em return only those keys from the given keyset that pass the supplied filter function with the supplied argument \end{DoxyCompactList}\item 
Key\-Set $\ast$ \hyperlink{group__api_gab436b020c8292d4c40ea2b27dc70305d}{elektra\-Rename\-Keys} (Key\-Set $\ast$config, const char $\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 
\hyperlink{group__proposal_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\-Namespace} \hyperlink{group__api_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{key\-Get\-Namespace} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em For currently valid namespaces see \hyperlink{group__proposal_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\-Namespace}. \end{DoxyCompactList}\item 
int \hyperlink{group__api_ga43012281da2135034e405c7fc3303509}{key\-Lock} (Key $\ast$key, enum \hyperlink{group__proposal_ga824e384e248ed1e05448294bff7271c0}{elektra\-Lock\-Options} what)
\begin{DoxyCompactList}\small\item\em Permanently locks a part of the key. \end{DoxyCompactList}\item 
Key\-Set $\ast$ \hyperlink{group__api_gaee59442d3b1dea04454c7b93cd00c7ad}{elektra\-Array\-Get} (const Key $\ast$array\-Parent, Key\-Set $\ast$keys)
\begin{DoxyCompactList}\small\item\em Return all the array keys below the given arrayparent The arrayparent itself is not returned. \end{DoxyCompactList}\item 
Key $\ast$ \hyperlink{group__api_gaff4f7cbfc779e917ee41284d834231c6}{elektra\-Array\-Get\-Next\-Key} (Key\-Set $\ast$array\-Keys)
\begin{DoxyCompactList}\small\item\em Return the next key in the given array. \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_gaee59442d3b1dea04454c7b93cd00c7ad}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!elektra\-Array\-Get@{elektra\-Array\-Get}}
\index{elektra\-Array\-Get@{elektra\-Array\-Get}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{elektra\-Array\-Get}]{\setlength{\rightskip}{0pt plus 5cm}Key\-Set$\ast$ elektra\-Array\-Get (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{array\-Parent, }
\item[{Key\-Set $\ast$}]{keys}
\end{DoxyParamCaption}
)}}\label{group__api_gaee59442d3b1dea04454c7b93cd00c7ad}


Return all the array keys below the given arrayparent The arrayparent itself is not returned. 

For example, if user/config/\# is an array, user/config is the array parent. Only the direct array keys will be returned. This means that for example user/config/\#1/key will not be included, but only user/config/\#1.

A new keyset will be allocated for the resulting keys. This means that the caller must ks\-Del the resulting keyset.


\begin{DoxyParams}{Parameters}
{\em array\-Parent} & the parent of the array to be returned \\
\hline
{\em keys} & the keyset containing the array keys.\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a keyset containing the arraykeys (if any) 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em N\-U\-L\-L} & on N\-U\-L\-L pointers \\
\hline
\end{DoxyRetVals}
\hypertarget{group__api_gaff4f7cbfc779e917ee41284d834231c6}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!elektra\-Array\-Get\-Next\-Key@{elektra\-Array\-Get\-Next\-Key}}
\index{elektra\-Array\-Get\-Next\-Key@{elektra\-Array\-Get\-Next\-Key}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{elektra\-Array\-Get\-Next\-Key}]{\setlength{\rightskip}{0pt plus 5cm}Key$\ast$ elektra\-Array\-Get\-Next\-Key (
\begin{DoxyParamCaption}
\item[{Key\-Set $\ast$}]{array\-Keys}
\end{DoxyParamCaption}
)}}\label{group__api_gaff4f7cbfc779e917ee41284d834231c6}


Return the next key in the given array. 

The function will automatically allocate memory for a new key and name it accordingly.

\begin{DoxyPrecond}{Precondition}
The supplied keyset must contain only valid array keys.
\end{DoxyPrecond}
The caller has to key\-Del the resulting key.


\begin{DoxyParams}{Parameters}
{\em arraykeys} & the array where the new key will belong to\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the new array key on success 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em N\-U\-L\-L} & if the passed array is empty \\
\hline
{\em N\-U\-L\-L} & on N\-U\-L\-L pointers or if an error occurs \\
\hline
\end{DoxyRetVals}
\hypertarget{group__api_gafc46476b8d722d89e07a966e023df317}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!elektra\-Array\-Inc\-Name@{elektra\-Array\-Inc\-Name}}
\index{elektra\-Array\-Inc\-Name@{elektra\-Array\-Inc\-Name}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{elektra\-Array\-Inc\-Name}]{\setlength{\rightskip}{0pt plus 5cm}int elektra\-Array\-Inc\-Name (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__api_gafc46476b8d722d89e07a966e023df317}


Increment the name of the key by one. 

Alphabetical order will remain

e.\-g. user/abc/\#9 will be changed to user/abc/\#\-\_\-10

For the start\-: user/abc/\# will be changed to user/abc/\#0


\begin{DoxyParams}{Parameters}
{\em key} & which base name will be incremented\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on error (e.\-g. too large array, not validated array) \\
\hline
{\em 0} & on success \\
\hline
\end{DoxyRetVals}
\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}!API 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_ga5e727c6d8197f5871a2075454b6214f2}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!elektra\-Ks\-Filter@{elektra\-Ks\-Filter}}
\index{elektra\-Ks\-Filter@{elektra\-Ks\-Filter}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{elektra\-Ks\-Filter}]{\setlength{\rightskip}{0pt plus 5cm}int elektra\-Ks\-Filter (
\begin{DoxyParamCaption}
\item[{Key\-Set $\ast$}]{result, }
\item[{Key\-Set $\ast$}]{input, }
\item[{int($\ast$)(const Key $\ast$k, void $\ast$argument)}]{filter, }
\item[{void $\ast$}]{argument}
\end{DoxyParamCaption}
)}}\label{group__api_ga5e727c6d8197f5871a2075454b6214f2}


return only those keys from the given keyset that pass the supplied filter function with the supplied argument 


\begin{DoxyParams}{Parameters}
{\em result} & the keyset that should contain the filtered keys \\
\hline
{\em input} & the keyset whose keys should be filtered \\
\hline
{\em filter} & a function pointer to a function that will be used to filter the keyset. A key will be taken if the function returns a value greater than 0. \\
\hline
{\em argument} & an argument that will be passed to the filter function each time it is called \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the number of filtered keys if the filter function always returned a positive value, -\/1 otherwise 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em N\-U\-L\-L} & on N\-U\-L\-L pointer \\
\hline
\end{DoxyRetVals}
\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}!API 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}
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 ...
free (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_gab436b020c8292d4c40ea2b27dc70305d}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!elektra\-Rename\-Keys@{elektra\-Rename\-Keys}}
\index{elektra\-Rename\-Keys@{elektra\-Rename\-Keys}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{elektra\-Rename\-Keys}]{\setlength{\rightskip}{0pt plus 5cm}Key\-Set$\ast$ elektra\-Rename\-Keys (
\begin{DoxyParamCaption}
\item[{Key\-Set $\ast$}]{config, }
\item[{const char $\ast$}]{name}
\end{DoxyParamCaption}
)}}\label{group__api_gab436b020c8292d4c40ea2b27dc70305d}


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. \hypertarget{group__api_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!key\-Get\-Namespace@{key\-Get\-Namespace}}
\index{key\-Get\-Namespace@{key\-Get\-Namespace}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{key\-Get\-Namespace}]{\setlength{\rightskip}{0pt plus 5cm}{\bf elektra\-Namespace} key\-Get\-Namespace (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__api_gafc3ca03ed10f87eb59bdc02cf2a0de8d}


For currently valid namespaces see \hyperlink{group__proposal_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\-Namespace}. 

\begin{DoxySince}{Since}
0.\-8.\-10 Added method to kdbproposal.\-h
\end{DoxySince}
To handle every possible cases (including namespaces) a key can have\-: 
\begin{DoxyCodeInclude}
\textcolor{keywordflow}{switch} (\hyperlink{group__api_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{keyGetNamespace}(k))
\{
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68a2be047b124b1ca0e92b5ef124169f0d2}{KEY\_NS\_SPEC}:
        printf (\textcolor{stringliteral}{"spec namespace\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68a470ecc9254fcdfccf9923a3e526c9c11}{KEY\_NS\_PROC}:
        printf (\textcolor{stringliteral}{"proc namespace\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68aa0006cf27dbb2586bafba6ff1ae4f4ec}{KEY\_NS\_DIR}:
        printf (\textcolor{stringliteral}{"dir namespace\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68a8ce23c70010e8ac8bb540b0947e03a4e}{KEY\_NS\_USER}:
        printf (\textcolor{stringliteral}{"user namespace\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68a61adca2f9dff47e65dfcdb492ffa7a20}{KEY\_NS\_SYSTEM}:
        printf (\textcolor{stringliteral}{"system namespace\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68a33d6c53529b4e6921d0b1d6565df2f1f}{KEY\_NS\_EMPTY}:
        printf (\textcolor{stringliteral}{"empty name\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68a3659698b0a07454ca8055ab693e8efd1}{KEY\_NS\_NONE}:
        printf (\textcolor{stringliteral}{"no key\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68ac5fbf2c3a7ae79fa2d60c48ae3e72688}{KEY\_NS\_META}:
        printf (\textcolor{stringliteral}{"meta key\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\textcolor{keywordflow}{case} \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68a2c9133e3095dccbcde5ca3bb13987b5d}{KEY\_NS\_CASCADING}:
        printf (\textcolor{stringliteral}{"cascading key\(\backslash\)n"});
        \textcolor{keywordflow}{break};
\}
\end{DoxyCodeInclude}
 To loop over all valid namespaces use\-: 
\begin{DoxyCodeInclude}
\textcolor{keywordflow}{for} (\hyperlink{group__proposal_gaec3b8d6f430ae49b91bafe8a86310a68}{elektraNamespace} ns=\hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68ae06281f94c2b7a221115afbaa1e0ff45}{KEY\_NS\_FIRST}; ns<=
      \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68ad4d0f219a657517ddd50cd06c8190310}{KEY\_NS\_LAST}; ++ns)
\{
        \textcolor{comment}{// work with namespace}
        printf (\textcolor{stringliteral}{"%d\(\backslash\)n"}, ns);
\}
\end{DoxyCodeInclude}
 \begin{DoxyNote}{Note}
This method might be enhanced. You do not have any guarantee that, when for a specific name \hyperlink{group__proposal_ggaec3b8d6f430ae49b91bafe8a86310a68ac5fbf2c3a7ae79fa2d60c48ae3e72688}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-M\-E\-T\-A} is returned today, that it still will be returned after the next recompilation. So make sure that your compiler gives you a warning for unhandled switches (gcc\-: -\/\-Wswitch or -\/\-Wswitch-\/enum if you want to handle default) and look out for those warnings.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the namespace of a key. 
\end{DoxyReturn}
\hypertarget{group__api_ga5e7eff0c77678420199d0d2e8729152b}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!key\-Get\-Unescaped\-Name\-Size@{key\-Get\-Unescaped\-Name\-Size}}
\index{key\-Get\-Unescaped\-Name\-Size@{key\-Get\-Unescaped\-Name\-Size}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{key\-Get\-Unescaped\-Name\-Size}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Unescaped\-Name\-Size (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__api_ga5e7eff0c77678420199d0d2e8729152b}


return size of unescaped name 


\begin{DoxyParams}{Parameters}
{\em key} & the object to work with\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on null pointer \\
\hline
{\em 0} & if no name \\
\hline
\end{DoxyRetVals}
\hypertarget{group__api_ga43012281da2135034e405c7fc3303509}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!key\-Lock@{key\-Lock}}
\index{key\-Lock@{key\-Lock}!API 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[{enum {\bf elektra\-Lock\-Options}}]{what}
\end{DoxyParamCaption}
)}}\label{group__api_ga43012281da2135034e405c7fc3303509}


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}!API 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_ga6fe6af4c27b35d911a533f4ae4d698bb}{\index{A\-P\-I Proposals for Elektra@{A\-P\-I Proposals for Elektra}!key\-Unescaped\-Name@{key\-Unescaped\-Name}}
\index{key\-Unescaped\-Name@{key\-Unescaped\-Name}!API Proposals for Elektra@{A\-P\-I Proposals for Elektra}}
\subsubsection[{key\-Unescaped\-Name}]{\setlength{\rightskip}{0pt plus 5cm}const void$\ast$ key\-Unescaped\-Name (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__api_ga6fe6af4c27b35d911a533f4ae4d698bb}


This keyname is null separated and does not use backslash for escaping. 

This name is essential if you want to iterate over parts of the key name, want to compare keynames and want to check relations of keys in the hierarchy.


\begin{DoxyParams}{Parameters}
{\em key} & the object to work with\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on null pointers \\
\hline
\end{DoxyRetVals}
\begin{DoxyReturn}{Returns}
the name in its unescaped form 
\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}!API 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}
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\-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}!API 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}
