\hypertarget{key_8c}{}\doxysection{key.\+c File Reference}
\label{key_8c}\index{key.c@{key.c}}


Methods for Key manipulation.  


{\ttfamily \#include \char`\"{}kdblogger.\+h\char`\"{}}\newline
{\ttfamily \#include $<$stdio.\+h$>$}\newline
{\ttfamily \#include \char`\"{}kdb.\+h\char`\"{}}\newline
{\ttfamily \#include \char`\"{}kdbprivate.\+h\char`\"{}}\newline
{\ttfamily \#include $<$kdbassert.\+h$>$}\newline
Include dependency graph for key.\+c\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=350pt]{key_8c__incl}
\end{center}
\end{figure}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
Key $\ast$ \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New}} (const char $\ast$name,...)
\begin{DoxyCompactList}\small\item\em A practical way to fully create a Key object in one step. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{key_8c_a307cb9b84dec7fe607720a5eb4103226}{key\+VNew}} (const char $\ast$name, va\+\_\+list va)
\begin{DoxyCompactList}\small\item\em A practical way to fully create a Key object in one step. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__key_ga505575ebef060066984fe0f590081e37}{key\+Copy}} (Key $\ast$dest, const Key $\ast$source, \mbox{\hyperlink{group__key_ga9ff42b1e9a97222562bfda3dd1f8c735}{elektra\+Copy\+Flags}} flags)
\begin{DoxyCompactList}\small\item\em Copy or clear a key. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em A destructor for Key objects. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__key_gab2242311a36bbc0520e0d36895107ec1}{key\+Clear}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Will clear all internal data of a Key. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__key_ga6970a6f254d67af7e39f8e469bb162f1}{key\+Inc\+Ref}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Increment the reference counter of a Key object. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__key_ga2c6433ca22109e4e141946057eccb283}{key\+Dec\+Ref}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Decrement the reference counter of a Key object. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__key_ga4aabc4272506dd63161db2bbb42de8ae}{key\+Get\+Ref}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Return how many references the Key has. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__key_ga5e42b653a0f117be7f1f6eb06c569bb8}{key\+Lock}} (Key $\ast$key, \mbox{\hyperlink{group__key_gafa3306030b1d06b06c3cba24c516f5ec}{elektra\+Lock\+Flags}} what)
\begin{DoxyCompactList}\small\item\em Permanently lock parts of a Key. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__key_ga769882e86e34a95cefcf8f260ef97e06}{key\+Is\+Locked}} (const Key $\ast$key, \mbox{\hyperlink{group__key_gafa3306030b1d06b06c3cba24c516f5ec}{elektra\+Lock\+Flags}} what)
\begin{DoxyCompactList}\small\item\em Checks which parts of a Key are locked. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Methods for Key manipulation. 

\begin{DoxyCopyright}{Copyright}
BSD License (see LICENSE.\+md or \href{https://www.libelektra.org}{\texttt{ https\+://www.\+libelektra.\+org}}) 
\end{DoxyCopyright}


\doxysubsection{Function Documentation}
\mbox{\Hypertarget{key_8c_a307cb9b84dec7fe607720a5eb4103226}\label{key_8c_a307cb9b84dec7fe607720a5eb4103226}} 
\index{key.c@{key.c}!keyVNew@{keyVNew}}
\index{keyVNew@{keyVNew}!key.c@{key.c}}
\doxysubsubsection{\texorpdfstring{keyVNew()}{keyVNew()}}
{\footnotesize\ttfamily Key$\ast$ key\+VNew (\begin{DoxyParamCaption}\item[{const char $\ast$}]{name,  }\item[{va\+\_\+list}]{va }\end{DoxyParamCaption})}



A practical way to fully create a Key object in one step. 

To just get a key object, simple do\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key *k = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}/"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\textcolor{comment}{// work with it}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}} allocates memory for a key object and \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del()}} cleans everything up.

We can also give an empty key name and a KEY\+\_\+\+END tag with the same effect as before\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key *k =\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}); \textcolor{comment}{// Has the same effect as above}}
\DoxyCodeLine{\textcolor{comment}{// work with it}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 But we can also give the key a proper name right from the start\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{comment}{// Create and initialize a key with a name and nothing else}}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/some/example"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\textcolor{comment}{// work with it}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 If you want the key object to contain a name, value, comment and other meta info read on.

\begin{DoxyNote}{Note}
When you already have a key with similar properties its easier to key\+Dup() the key.
\end{DoxyNote}
You can call \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}} in many different ways depending on the attribute tags you pass as parameters. Tags are represented as \mbox{\hyperlink{group__key_ga9b703ca49f48b482def322b77d3e6bc8}{elektra\+Key\+Flags}} values, and tell \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}} which Key attribute comes next. The Key attribute tags are the following\+:
\begin{DoxyItemize}
\item \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\+\_\+\+VALUE}} ~\newline
 Next parameter is a pointer to the value that will be used. If no \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a1ca18d4e094ae7487d35ecedda2235ff}{KEY\+\_\+\+BINARY}} was used before, a string is assumed. 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{comment}{// Create and initialize a key with a name and nothing else}}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/tmp/ex0"{}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}some data"{}},    \textcolor{comment}{// set a string value}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}

\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a6d531b5c41445d19d0452eebdccbfa01}{KEY\+\_\+\+SIZE}} ~\newline
 Define a maximum length of the value. This is only used when setting a binary key. 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{comment}{// Create and initialize a key with a name and nothing else}}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/tmp/ex1"{}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 4,               \textcolor{comment}{// has no effect on strings}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}some data"{}},    \textcolor{comment}{// set a string value}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}

\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a040582834bb2d90049947d7ef74e87e2}{KEY\+\_\+\+META}} ~\newline
 Next two parameter is a metaname and a metavalue. See \mbox{\hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}}. 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/tmp/ex3"{}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"{}comment"{}}, \textcolor{stringliteral}{"{}a comment"{}},  \textcolor{comment}{// with a comment}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"{}owner"{}}, \textcolor{stringliteral}{"{}root"{}},         \textcolor{comment}{// and an owner}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"{}special"{}}, \textcolor{stringliteral}{"{}yes"{}},        \textcolor{comment}{// and any other metadata}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}

\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\+\_\+\+END}} ~\newline
 Must be the last parameter passed to \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}. It is always required, unless the {\ttfamily key\+Name} is 0.
\item \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a4b83f86a07a7a0d6e24ecafe43cfea1b}{KEY\+\_\+\+FLAGS}} ~\newline
 Bitwise disjunction of flags, which don\textquotesingle{}t require one or more values. recommended way to set multiple flags. overrides previously defined flags. 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/tmp/ex3"{}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY}},                   \textcolor{comment}{// binary key}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 7,                    \textcolor{comment}{// assume binary length 7}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}some data"{}},                \textcolor{comment}{// value that will be truncated in 7 bytes}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                        \textcolor{comment}{// end of args}}

\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a1ca18d4e094ae7487d35ecedda2235ff}{KEY\+\_\+\+BINARY}} ~\newline
 Allows one to change the key to a binary key. Make sure that you also pass \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a6d531b5c41445d19d0452eebdccbfa01}{KEY\+\_\+\+SIZE}} before you set the value. Otherwise it will be cut off with first \textbackslash{}0 in the string. So this flag toggle from \mbox{\hyperlink{group__keyvalue_ga622bde1eb0e0c4994728331326340ef2}{key\+Set\+String()}} to \mbox{\hyperlink{group__keyvalue_gaa50a5358fd328d373a45f395fa1b99e7}{key\+Set\+Binary()}}. If no value (nor size) is given, it will be a NULL key. 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{comment}{// Create and initialize a key with a name and nothing else}}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/tmp/ex2"{}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 4,               \textcolor{comment}{// now the size is important}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}some data"{}},    \textcolor{comment}{// sets the binary value ("{}some"{})}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}

\end{DoxyCodeInclude}


\begin{DoxyRefDesc}{Deprecated}
\item[\mbox{\hyperlink{deprecated__deprecated000002}{Deprecated}}]The flags below are deprecated and \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a040582834bb2d90049947d7ef74e87e2}{KEY\+\_\+\+META}} should be preferred. They remain some time, however, for compatibility\+: \end{DoxyRefDesc}

\begin{DoxyCodeInclude}{0}

\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac29427bb47cc31689d02912e36161ee3}{KEY\+\_\+\+COMMENT}} ~\newline
 Next parameter is a comment. See \mbox{\hyperlink{group__meta_ga8863a877a84fa46e6017fe72e49b89c1}{key\+Set\+Comment()}}. 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/tmp/ex4"{}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY}},                   \textcolor{comment}{// key type}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 7,                    \textcolor{comment}{// assume binary length 7}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}some data"{}},                \textcolor{comment}{// value that will be truncated in 7 bytes}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac29427bb47cc31689d02912e36161ee3}{KEY\_COMMENT}}, \textcolor{stringliteral}{"{}value is truncated"{}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                        \textcolor{comment}{// end of args}}

\end{DoxyCodeInclude}

\end{DoxyItemize}


\begin{DoxyParams}{Parameters}
{\em name} & a valid name to the key, or NULL to get a simple initialized, but really empty, object\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to a new allocated and initialized Key object. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em NULL} & on allocation error or if an invalid {\ttfamily name} was passed (see \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}}).\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del()}}
\end{DoxySeeAlso}
\begin{DoxyPrecond}{Precondition}
caller must use va\+\_\+start and va\+\_\+end on va 
\end{DoxyPrecond}

\begin{DoxyParams}{Parameters}
{\em va} & the variadic argument list \\
\hline
\end{DoxyParams}
