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


Methods for Key manipulation.  


{\ttfamily \#include \char`\"{}kdb.\+h\char`\"{}}\\*
{\ttfamily \#include \char`\"{}kdbprivate.\+h\char`\"{}}\\*
Include dependency graph for key.\+c\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=350pt]{key_8c__incl}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
Key $\ast$ \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$ \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$ \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 \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 \hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em A destructor for Key objects. \end{DoxyCompactList}\item 
int \hyperlink{group__key_gab2242311a36bbc0520e0d36895107ec1}{key\+Clear} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Key Object Cleaner. \end{DoxyCompactList}\item 
ssize\+\_\+t \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 \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 \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}\end{DoxyCompactItemize}


\subsection{Detailed Description}
Methods for Key manipulation. 

\begin{DoxyCopyright}{Copyright}
B\+S\+D License (see doc/\+L\+I\+C\+E\+N\+S\+E.\+md or \href{http://www.libelektra.org}{\tt http\+://www.\+libelektra.\+org}) 
\end{DoxyCopyright}


\subsection{Function Documentation}
\hypertarget{key_8c_a307cb9b84dec7fe607720a5eb4103226}{\index{key.\+c@{key.\+c}!key\+V\+New@{key\+V\+New}}
\index{key\+V\+New@{key\+V\+New}!key.\+c@{key.\+c}}
\subsubsection[{key\+V\+New}]{\setlength{\rightskip}{0pt plus 5cm}Key$\ast$ key\+V\+New (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{name, }
\item[{va\+\_\+list}]{va}
\end{DoxyParamCaption}
)}}\label{key_8c_a307cb9b84dec7fe607720a5eb4103226}


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

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


\begin{DoxyCodeInclude}
Key *k = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(0);
\textcolor{comment}{// work with it}
\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 \hyperlink{group__key_gae6ec6a60cc4b8c1463fa08623d056ce3}{key\+Dup()} the key.
\end{DoxyNote}
You can call it in many different ways depending on the attribute tags you pass as parameters. Tags are represented as \hyperlink{group__key_ga91fb3178848bd682000958089abbaf40}{keyswitch\+\_\+t} values, and tell \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()} which Key attribute comes next.

We can also give an empty key name and a K\+E\+Y\+\_\+\+E\+N\+D tag with the same effect as before\+:


\begin{DoxyCodeInclude}
Key *k =\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{""}, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}); \textcolor{comment}{// Has the same effect as above}
\textcolor{comment}{// work with it}
\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel} (k);
\end{DoxyCodeInclude}
 But we can also give the key a proper name right from the start\+:


\begin{DoxyCodeInclude}
\textcolor{comment}{// Create and initialize a key with a name and nothing else}
Key *k=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/some/example"}, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
\textcolor{comment}{// work with it}
\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel} (k);
\end{DoxyCodeInclude}
 So, \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()} allocates memory for a key object and \hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del()} cleans everything up.

\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()} processes the given argument list even further. The Key attribute tags are the following\+:
\begin{DoxyItemize}
\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{K\+E\+Y\+\_\+\+V\+A\+L\+U\+E} ~\newline
 Next parameter is a pointer to the value that will be used. If no \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{K\+E\+Y\+\_\+\+B\+I\+N\+A\+R\+Y} was used before, a string is assumed. 
\begin{DoxyCodeInclude}
\textcolor{comment}{// Create and initialize a key with a name and nothing else}
Key *k=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/tmp/ex0"},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, \textcolor{stringliteral}{"some data"},    \textcolor{comment}{// set a string value}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});                  \textcolor{comment}{// end of args}
\end{DoxyCodeInclude}

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

\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{K\+E\+Y\+\_\+\+M\+E\+T\+A} ~\newline
 Next two parameter is a metaname and a metavalue. See \hyperlink{group__keymeta_gae1f15546b234ffb6007d8a31178652b9}{key\+Set\+Meta()}. 
\begin{DoxyCodeInclude}
Key *k=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/tmp/ex3"},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{KEY\_META}, \textcolor{stringliteral}{"comment"}, \textcolor{stringliteral}{"a comment"},  \textcolor{comment}{// with a comment}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{KEY\_META}, \textcolor{stringliteral}{"owner"}, \textcolor{stringliteral}{"root"},         \textcolor{comment}{// and an owner}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{KEY\_META}, \textcolor{stringliteral}{"special"}, \textcolor{stringliteral}{"yes"},        \textcolor{comment}{// and any other metadata}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});                  \textcolor{comment}{// end of args}
\end{DoxyCodeInclude}

\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{K\+E\+Y\+\_\+\+E\+N\+D} ~\newline
 Must be the last parameter passed to \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}. It is always required, unless the {\ttfamily key\+Name} is 0.
\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a4b83f86a07a7a0d6e24ecafe43cfea1b}{K\+E\+Y\+\_\+\+F\+L\+A\+G\+S} ~\newline
 Bitwise disjunction of flags, which don't require one or more values. recommended way to set multiple flags. overrides previously defined flags. 
\begin{DoxyCodeInclude}
Key *k=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/tmp/ex3"},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a4b83f86a07a7a0d6e24ecafe43cfea1b}{KEY\_FLAGS}, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY} | \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}, \textcolor{comment}{// flags}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}, 7,                    \textcolor{comment}{// assume binary length 7}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, \textcolor{stringliteral}{"some data"},                \textcolor{comment}{// value that will be truncated in 7 bytes}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});                        \textcolor{comment}{// end of args}
\end{DoxyCodeInclude}

\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{K\+E\+Y\+\_\+\+B\+I\+N\+A\+R\+Y} ~\newline
 Allows one to change the key to a binary key. Make sure that you also pass \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{K\+E\+Y\+\_\+\+S\+I\+Z\+E} before you set the value. Otherwise it will be cut off with first \textbackslash{}0 in the string. So this flag toggle from \hyperlink{group__keyvalue_ga622bde1eb0e0c4994728331326340ef2}{key\+Set\+String()} to \hyperlink{group__keyvalue_gaa50a5358fd328d373a45f395fa1b99e7}{key\+Set\+Binary()}. If no value (nor size) is given, it will be a N\+U\+L\+L key. 
\begin{DoxyCodeInclude}
\textcolor{comment}{// Create and initialize a key with a name and nothing else}
Key *k=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/tmp/ex2"},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}, 4,               \textcolor{comment}{// now the size is important}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, \textcolor{stringliteral}{"some data"},    \textcolor{comment}{// sets the binary value ("some")}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});                  \textcolor{comment}{// end of args}
\end{DoxyCodeInclude}

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

\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000010}{Deprecated}]These other flags deprecated and \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a040582834bb2d90049947d7ef74e87e2}{K\+E\+Y\+\_\+\+M\+E\+T\+A} should be preferred. They remain some time, however, for compatibility\+:
\begin{DoxyItemize}
\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a9e43e47c8a21478538e2d20e049981d5}{K\+E\+Y\+\_\+\+D\+I\+R} ~\newline
 Define that the key is a directory rather than a ordinary key. This means its executable bits in its mode are set. But even without this option the key can have subkeys. See \hyperlink{group__meta_gaae575bd86a628a15ee45baa860522e75}{key\+Set\+Dir()}.
\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a77ca60362fa8daca8d5347db4385068b}{K\+E\+Y\+\_\+\+O\+W\+N\+E\+R} ~\newline
 Next parameter is the owner. See \hyperlink{owner_8c_a88d6ec200ba0707b7c1b4a88133d2be4}{key\+Set\+Owner()}.
\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a28f01a87d65f065172f734c9c9446c0e}{K\+E\+Y\+\_\+\+U\+I\+D}, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac0628bbaba7c837ca73323681393d15f}{K\+E\+Y\+\_\+\+G\+I\+D} ~\newline
 Next parameter is taken as the U\+I\+D (uid\+\_\+t) or G\+I\+D (gid\+\_\+t) that will be defined on the key. See \hyperlink{group__meta_gab5f284f5ecd261e0a290095f50ba1af7}{key\+Set\+U\+I\+D()} and \hyperlink{group__meta_ga9e3d0fb3f7ba906e067727b9155d22e3}{key\+Set\+G\+I\+D()}.
\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1b0a91ff3a855d6993930ebf0abaa518}{K\+E\+Y\+\_\+\+M\+O\+D\+E} ~\newline
 Next parameter is taken as mode permissions (int) to the key. See \hyperlink{group__meta_ga8803037e35b9da1ce492323a88ff6bc3}{key\+Set\+Mode()}. 
\begin{DoxyCodeInclude}
Key *k=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/tmp/ex3"},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, \textcolor{stringliteral}{"some data"},    \textcolor{comment}{// with a simple value}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1b0a91ff3a855d6993930ebf0abaa518}{KEY\_MODE}, 0777,            \textcolor{comment}{// permissions}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});                  \textcolor{comment}{// end of args}
\end{DoxyCodeInclude}

\item \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac29427bb47cc31689d02912e36161ee3}{K\+E\+Y\+\_\+\+C\+O\+M\+M\+E\+N\+T} ~\newline
 Next parameter is a comment. See \hyperlink{group__meta_ga8863a877a84fa46e6017fe72e49b89c1}{key\+Set\+Comment()}. 
\begin{DoxyCodeInclude}
Key *k=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/tmp/ex4"},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1ca18d4e094ae7487d35ecedda2235ff}{KEY\_BINARY},                   \textcolor{comment}{// key type}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a6d531b5c41445d19d0452eebdccbfa01}{KEY\_SIZE}, 7,                    \textcolor{comment}{// assume binary length 7}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, \textcolor{stringliteral}{"some data"},                \textcolor{comment}{// value that will be truncated in 7 bytes}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac29427bb47cc31689d02912e36161ee3}{KEY\_COMMENT}, \textcolor{stringliteral}{"value is truncated"},
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a77ca60362fa8daca8d5347db4385068b}{KEY\_OWNER}, \textcolor{stringliteral}{"root"},             \textcolor{comment}{// owner (not uid) is root}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a28f01a87d65f065172f734c9c9446c0e}{KEY\_UID}, 0,                      \textcolor{comment}{// root uid}
        \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});                        \textcolor{comment}{// end of args}
\end{DoxyCodeInclude}

\end{DoxyItemize}\end{DoxyRefDesc}



\begin{DoxyParams}{Parameters}
{\em name} & a valid name to the key, or N\+U\+L\+L to get a simple initialized, but really empty, object \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\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\+L\+L} & on allocation error or if an invalid {\ttfamily name} was passed (see \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}
