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


Methods for Key manipulation.  


{\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\+V\+New}} (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_gae6ec6a60cc4b8c1463fa08623d056ce3}{key\+Dup}} (const Key $\ast$source)
\begin{DoxyCompactList}\small\item\em Return a duplicate of a key. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__key_ga6a12cbbe656a1ad9f41b8c681d7a2f92}{key\+Copy}} (Key $\ast$dest, const Key $\ast$source)
\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 Key Object Cleaner. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__key_ga6970a6f254d67af7e39f8e469bb162f1}{key\+Inc\+Ref}} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Increment the viability 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 viability 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_ga2dd8d2650e59a90e933c631267bfbb85}{key\+Lock}} (Key $\ast$key, \mbox{\hyperlink{group__keyset_ga98a3d6a4016c9dad9cbd1a99a9c2a45a}{option\+\_\+t}} what)
\begin{DoxyCompactList}\small\item\em Permanently locks a part of the key. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__key_gae5d229b4843e3ad76c139bd887d81a35}{key\+Is\+Locked}} (const Key $\ast$key, \mbox{\hyperlink{group__keyset_ga98a3d6a4016c9dad9cbd1a99a9c2a45a}{option\+\_\+t}} what)
\begin{DoxyCompactList}\small\item\em Tests if a part of a key is locked. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Methods for Key manipulation. 

\begin{DoxyCopyright}{Copyright}
B\+SD License (see L\+I\+C\+E\+N\+S\+E.\+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\+V\+New (\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}}(0);}
\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 K\+E\+Y\+\_\+\+E\+ND 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_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{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_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{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 \mbox{\hyperlink{group__key_gae6ec6a60cc4b8c1463fa08623d056ce3}{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_ga91fb3178848bd682000958089abbaf40}{keyswitch\+\_\+t}} 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_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{K\+E\+Y\+\_\+\+V\+A\+L\+UE}} ~\newline
 Next parameter is a pointer to the value that will be used. If no \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{K\+E\+Y\+\_\+\+B\+I\+N\+A\+RY}} 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_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"some data"},    \textcolor{comment}{// set a string value}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}
\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{K\+E\+Y\+\_\+\+S\+I\+ZE}} ~\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_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 4,               \textcolor{comment}{// has no effect on strings}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"some data"},    \textcolor{comment}{// set a string value}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}
\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{K\+E\+Y\+\_\+\+M\+E\+TA}} ~\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_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"comment"}, \textcolor{stringliteral}{"a comment"},  \textcolor{comment}{// with a comment}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"owner"}, \textcolor{stringliteral}{"root"},         \textcolor{comment}{// and an owner}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"special"}, \textcolor{stringliteral}{"yes"},        \textcolor{comment}{// and any other metadata}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}
\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{K\+E\+Y\+\_\+\+E\+ND}} ~\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_gga91fb3178848bd682000958089abbaf40a4b83f86a07a7a0d6e24ecafe43cfea1b}{K\+E\+Y\+\_\+\+F\+L\+A\+GS}} ~\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_gga91fb3178848bd682000958089abbaf40a4b83f86a07a7a0d6e24ecafe43cfea1b}{KEY\_FLAGS}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY}} | \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \textcolor{comment}{// flags}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 7,                    \textcolor{comment}{// assume binary length 7}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"some data"},                \textcolor{comment}{// value that will be truncated in 7 bytes}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                        \textcolor{comment}{// end of args}}
\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{K\+E\+Y\+\_\+\+B\+I\+N\+A\+RY}} ~\newline
 Allows one to change the key to a binary key. Make sure that you also pass \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{K\+E\+Y\+\_\+\+S\+I\+ZE}} 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 N\+U\+LL 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_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY}},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 4,               \textcolor{comment}{// now the size is important}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"some data"},    \textcolor{comment}{// sets the binary value ("some")}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}
\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{K\+E\+Y\+\_\+\+C\+A\+S\+C\+A\+D\+I\+N\+G\+\_\+\+N\+A\+ME}} allow the name to start with / useful for \mbox{\hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\+Lookup()}} and \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} parent/lookup keys
\item \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a5205cbd2831bc881da3589a95c08e054}{K\+E\+Y\+\_\+\+M\+E\+T\+A\+\_\+\+N\+A\+ME}} allow the name to start with arbitrary namespaces useful to compare with metakeys

\begin{DoxyRefDesc}{Deprecated}
\item[\mbox{\hyperlink{deprecated__deprecated000010}{Deprecated}}]The flags below are deprecated and \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{K\+E\+Y\+\_\+\+M\+E\+TA}} should be preferred. They remain some time, however, for compatibility\+:\end{DoxyRefDesc}

\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key *k=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"user/tmp/ex3"},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"some data"},    \textcolor{comment}{// with a simple value}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1b0a91ff3a855d6993930ebf0abaa518}{KEY\_MODE}}, 0777,            \textcolor{comment}{// permissions}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                  \textcolor{comment}{// end of args}}
\end{DoxyCodeInclude}

\item \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac29427bb47cc31689d02912e36161ee3}{K\+E\+Y\+\_\+\+C\+O\+M\+M\+E\+NT}} ~\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_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY}},                   \textcolor{comment}{// key type}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}}, 7,                    \textcolor{comment}{// assume binary length 7}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"some data"},                \textcolor{comment}{// value that will be truncated in 7 bytes}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac29427bb47cc31689d02912e36161ee3}{KEY\_COMMENT}}, \textcolor{stringliteral}{"value is truncated"},}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a77ca60362fa8daca8d5347db4385068b}{KEY\_OWNER}}, \textcolor{stringliteral}{"root"},             \textcolor{comment}{// owner (not uid) is root}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a28f01a87d65f065172f734c9c9446c0e}{KEY\_UID}}, 0,                      \textcolor{comment}{// root uid}}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});                        \textcolor{comment}{// end of args}}
\end{DoxyCodeInclude}

\end{DoxyItemize}


\begin{DoxyParams}{Parameters}
{\em name} & a valid name to the key, or N\+U\+LL to get a simple initialized, but really empty, object \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del()}} 
\end{DoxySeeAlso}
\begin{DoxyReturn}{Returns}
a pointer to a new allocated and initialized Key object. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em N\+U\+LL} & on allocation error or if an invalid {\ttfamily name} was passed (see \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}}).\\
\hline
\end{DoxyRetVals}
\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}
