\hypertarget{kdbmeta_8h}{}\section{kdbmeta.\+h File Reference}
\label{kdbmeta_8h}\index{kdbmeta.\+h@{kdbmeta.\+h}}


metadata functions  


{\ttfamily \#include \char`\"{}kdb.\+h\char`\"{}}\newline
Include dependency graph for kdbmeta.\+h\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=142pt]{kdbmeta_8h__incl}
\end{center}
\end{figure}
This graph shows which files directly or indirectly include this file\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=350pt]{kdbmeta_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
const char $\ast$ \hyperlink{kdbmeta_8h_af6485fb8599714b6bbd830cf915ffea5}{key\+Owner} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Return a pointer to the real internal {\ttfamily key} owner. \end{DoxyCompactList}\item 
ssize\+\_\+t \hyperlink{kdbmeta_8h_a4a4561895741ba2ad10acf007c188593}{key\+Get\+Owner\+Size} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Return the size of the owner of the Key with concluding 0. \end{DoxyCompactList}\item 
ssize\+\_\+t \hyperlink{kdbmeta_8h_a6d612841c829a638a8fbbbd4a31cc54a}{key\+Get\+Owner} (const Key $\ast$key, char $\ast$returned, size\+\_\+t max\+Size)
\begin{DoxyCompactList}\small\item\em Return the owner of the key. \end{DoxyCompactList}\item 
ssize\+\_\+t \hyperlink{kdbmeta_8h_aa899d9f0251cb98a89761ef112910eca}{key\+Set\+Owner} (Key $\ast$key, const char $\ast$owner)
\begin{DoxyCompactList}\small\item\em Set the owner of a key. \end{DoxyCompactList}\item 
const char $\ast$ \hyperlink{group__meta_gac89fd319783b3457db45b4c09e55274a}{key\+Comment} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Return a pointer to the real internal {\ttfamily key} comment. \end{DoxyCompactList}\item 
ssize\+\_\+t \hyperlink{group__meta_ga0dd737fadc16d4cf16720d17f066a9d3}{key\+Get\+Comment\+Size} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Calculates number of bytes needed to store a key comment, including final N\+U\+LL. \end{DoxyCompactList}\item 
ssize\+\_\+t \hyperlink{group__meta_gafb89735689929ff717cc9f2d0d0b46a2}{key\+Get\+Comment} (const Key $\ast$key, char $\ast$returned\+Desc, size\+\_\+t max\+Size)
\begin{DoxyCompactList}\small\item\em Get the key comment. \end{DoxyCompactList}\item 
ssize\+\_\+t \hyperlink{group__meta_ga8863a877a84fa46e6017fe72e49b89c1}{key\+Set\+Comment} (Key $\ast$key, const char $\ast$new\+Desc)
\begin{DoxyCompactList}\small\item\em Set a comment for a key. \end{DoxyCompactList}\item 
uid\+\_\+t \hyperlink{group__meta_gacaa5060e67b03f50ae49a3620c54bc46}{key\+Get\+U\+ID} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Get the user ID of a key. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_gab5f284f5ecd261e0a290095f50ba1af7}{key\+Set\+U\+ID} (Key $\ast$key, uid\+\_\+t uid)
\begin{DoxyCompactList}\small\item\em Set the user ID of a key. \end{DoxyCompactList}\item 
gid\+\_\+t \hyperlink{group__meta_ga46a95e81d7d7f4e3eb59e60e5f3738c0}{key\+Get\+G\+ID} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Get the group ID of a key. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_ga9e3d0fb3f7ba906e067727b9155d22e3}{key\+Set\+G\+ID} (Key $\ast$key, gid\+\_\+t gid)
\begin{DoxyCompactList}\small\item\em Set the group ID of a key. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_gaae575bd86a628a15ee45baa860522e75}{key\+Set\+Dir} (Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Set mode so that key will be recognized as directory. \end{DoxyCompactList}\item 
mode\+\_\+t \hyperlink{group__meta_gabc0cec592ce3b77e9bc33dbc8e8f6bdc}{key\+Get\+Mode} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Return the key mode permissions. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_ga8803037e35b9da1ce492323a88ff6bc3}{key\+Set\+Mode} (Key $\ast$key, mode\+\_\+t mode)
\begin{DoxyCompactList}\small\item\em Set the key mode permissions. \end{DoxyCompactList}\item 
time\+\_\+t \hyperlink{group__meta_ga6b05da399c3c78904969ef39f191b0eb}{key\+Get\+A\+Time} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Get last time the key data was read from disk. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_ga995d8b84731673c88c7c01f3fed538b9}{key\+Set\+A\+Time} (Key $\ast$key, time\+\_\+t atime)
\begin{DoxyCompactList}\small\item\em Update the atime information for a key. \end{DoxyCompactList}\item 
time\+\_\+t \hyperlink{group__meta_ga57689eb5691679071463b777ae786ae9}{key\+Get\+M\+Time} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Get last modification time of the key on disk. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_ga481d8997187992fe4bbf288bc8ef4db7}{key\+Set\+M\+Time} (Key $\ast$key, time\+\_\+t mtime)
\begin{DoxyCompactList}\small\item\em Update the mtime information for a key. \end{DoxyCompactList}\item 
time\+\_\+t \hyperlink{group__meta_ga2c213c120cbe02201278ef7fb8cd94be}{key\+Get\+C\+Time} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Get last time the key metadata was changed from disk. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_ga9f502ecab8ab43f0b17220fcc95f3fa5}{key\+Set\+C\+Time} (Key $\ast$key, time\+\_\+t ctime)
\begin{DoxyCompactList}\small\item\em Update the ctime information for a key. \end{DoxyCompactList}\item 
int \hyperlink{group__meta_gab8b30dfabb0867bd6899e60e7bd193a2}{elektra\+Key\+Cmp\+Order} (const Key $\ast$a, const Key $\ast$b)
\begin{DoxyCompactList}\small\item\em Compare the order metadata of two keys. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \hyperlink{group__meta_ga57e189e739d942d60bb83765ced5cef2}{elektra\+Meta\+Array\+To\+KS} (const Key $\ast$, const char $\ast$)
\begin{DoxyCompactList}\small\item\em Create a {\ttfamily Key\+Set} from a metakey array. \end{DoxyCompactList}\item 
void \hyperlink{group__meta_ga166c65c4eb2d758ced57b0bd74fb9a57}{elektra\+Meta\+Array\+Add} (Key $\ast$, const char $\ast$, const char $\ast$)
\begin{DoxyCompactList}\small\item\em creates an metadata array or appends another element to an existing metadata array e.\+g. \end{DoxyCompactList}\item 
char $\ast$ \hyperlink{group__meta_ga40469799e2c6e9937eaf013bfc05d014}{elektra\+Meta\+Array\+To\+String} (const Key $\ast$, const char $\ast$, const char $\ast$)
\begin{DoxyCompactList}\small\item\em returns the metakey array as a string separated by delim \end{DoxyCompactList}\item 
int \hyperlink{group__meta_gaadfae80314be2415a7654fe8a0d2ee82}{elektra\+Sort\+Topology} (Key\+Set $\ast$, Key $\ast$$\ast$)
\begin{DoxyCompactList}\small\item\em topological sorting \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
metadata functions 

These functions might be removed in a later version.

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


\subsection{Function Documentation}
\mbox{\Hypertarget{kdbmeta_8h_a6d612841c829a638a8fbbbd4a31cc54a}\label{kdbmeta_8h_a6d612841c829a638a8fbbbd4a31cc54a}} 
\index{kdbmeta.\+h@{kdbmeta.\+h}!key\+Get\+Owner@{key\+Get\+Owner}}
\index{key\+Get\+Owner@{key\+Get\+Owner}!kdbmeta.\+h@{kdbmeta.\+h}}
\subsubsection{\texorpdfstring{key\+Get\+Owner()}{keyGetOwner()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Owner (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{char $\ast$}]{returned\+Owner,  }\item[{size\+\_\+t}]{max\+Size }\end{DoxyParamCaption})}



Return the owner of the key. 


\begin{DoxyItemize}
\item Given {\ttfamily user\+:someuser/}..... return {\ttfamily someuser} 
\item Given {\ttfamily user\+:some.\+user/}.... return {\ttfamily some.\+user} 
\item Given {\ttfamily user/}.... return the current user
\end{DoxyItemize}

Only {\ttfamily user/}... keys have an owner. For {\ttfamily system/}... keys (that doesn\textquotesingle{}t have a key owner) an empty string (\char`\"{}\char`\"{}) is returned.

Although usually the same, the owner of a key is not related to its U\+ID. Owner are related to W\+H\+E\+RE the key is stored on disk, while U\+I\+Ds are related to mode controls of a key.


\begin{DoxyParams}{Parameters}
{\em key} & the object to work with \\
\hline
{\em returned\+Owner} & a pre-\/allocated space to store the owner \\
\hline
{\em max\+Size} & maximum number of bytes that fit returned \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes written to buffer 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 1} & if there is no owner \\
\hline
{\em -\/1} & on N\+U\+LL pointers \\
\hline
{\em -\/1} & when max\+Size is 0, larger than S\+S\+I\+Z\+E\+\_\+\+M\+AX or too small for ownername \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}, \hyperlink{owner_8c_a88d6ec200ba0707b7c1b4a88133d2be4}{key\+Set\+Owner()}, \hyperlink{owner_8c_af6485fb8599714b6bbd830cf915ffea5}{key\+Owner()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\+Get\+Full\+Name()} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{kdbmeta_8h_a4a4561895741ba2ad10acf007c188593}\label{kdbmeta_8h_a4a4561895741ba2ad10acf007c188593}} 
\index{kdbmeta.\+h@{kdbmeta.\+h}!key\+Get\+Owner\+Size@{key\+Get\+Owner\+Size}}
\index{key\+Get\+Owner\+Size@{key\+Get\+Owner\+Size}!kdbmeta.\+h@{kdbmeta.\+h}}
\subsubsection{\texorpdfstring{key\+Get\+Owner\+Size()}{keyGetOwnerSize()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Owner\+Size (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Return the size of the owner of the Key with concluding 0. 

The returned number can be used to allocate a string. 1 will returned on an empty owner to store the concluding 0 on using \hyperlink{owner_8c_a35922a017bee8b4bcb493bbdfad9d6f5}{key\+Get\+Owner()}.


\begin{DoxyCode}
\textcolor{keywordtype}{char} * buffer;
buffer = \hyperlink{internal_8c_a35cdc2e5caed3454cb73b4fc7f37858c}{elektraMalloc} (\hyperlink{owner_8c_a4a4561895741ba2ad10acf007c188593}{keyGetOwnerSize} (key));
\textcolor{comment}{// use buffer and keyGetOwnerSize (key) for maxSize}
\end{DoxyCode}


\begin{DoxyNote}{Note}
that -\/1 might be returned on null pointer, so when you directly allocate afterwards its best to check if you will pass a null pointer before.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 1} & if there is no owner \\
\hline
{\em -\/1} & on N\+U\+LL pointer \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\hyperlink{owner_8c_a35922a017bee8b4bcb493bbdfad9d6f5}{key\+Get\+Owner()} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{kdbmeta_8h_af6485fb8599714b6bbd830cf915ffea5}\label{kdbmeta_8h_af6485fb8599714b6bbd830cf915ffea5}} 
\index{kdbmeta.\+h@{kdbmeta.\+h}!key\+Owner@{key\+Owner}}
\index{key\+Owner@{key\+Owner}!kdbmeta.\+h@{kdbmeta.\+h}}
\subsubsection{\texorpdfstring{key\+Owner()}{keyOwner()}}
{\footnotesize\ttfamily const char$\ast$ key\+Owner (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Return a pointer to the real internal {\ttfamily key} owner. 

This is a much more efficient version of \hyperlink{owner_8c_a35922a017bee8b4bcb493bbdfad9d6f5}{key\+Get\+Owner()} and you should use it if you are responsible enough to not mess up things. You are not allowed to modify the returned string in any way. If you need a copy of the string, consider to use \hyperlink{owner_8c_a35922a017bee8b4bcb493bbdfad9d6f5}{key\+Get\+Owner()} instead.

\hyperlink{owner_8c_af6485fb8599714b6bbd830cf915ffea5}{key\+Owner()} returns \char`\"{}\char`\"{} when there is no key\+Owner. The reason is 
\begin{DoxyCode}
key=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(0);
\hyperlink{owner_8c_a88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner}(key,\textcolor{stringliteral}{""});
\hyperlink{owner_8c_af6485fb8599714b6bbd830cf915ffea5}{keyOwner}(key); \textcolor{comment}{// you would expect "" here}
\hyperlink{owner_8c_a88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner}(key,\textcolor{stringliteral}{"system"});
\hyperlink{owner_8c_af6485fb8599714b6bbd830cf915ffea5}{keyOwner}(key); \textcolor{comment}{// you would expect "" here}
\end{DoxyCode}


\begin{DoxyNote}{Note}
Note that the Key structure keeps its own size field that is calculated by library internal calls, so to avoid inconsistencies, you must never use the pointer returned by \hyperlink{owner_8c_af6485fb8599714b6bbd830cf915ffea5}{key\+Owner()} method to set a new value. Use \hyperlink{owner_8c_a88d6ec200ba0707b7c1b4a88133d2be4}{key\+Set\+Owner()} instead.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to internal owner 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em \char`\"{}\char`\"{}} & when there is no (an empty) owner \\
\hline
{\em 0} & iff key is a N\+U\+LL pointer \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\hyperlink{owner_8c_a4a4561895741ba2ad10acf007c188593}{key\+Get\+Owner\+Size()} for the size of the string with concluding 0 

\hyperlink{owner_8c_a35922a017bee8b4bcb493bbdfad9d6f5}{key\+Get\+Owner()}, \hyperlink{owner_8c_a88d6ec200ba0707b7c1b4a88133d2be4}{key\+Set\+Owner()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()} for name without owner 

\hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\+Get\+Full\+Name()} for name with owner 
\end{DoxySeeAlso}
\mbox{\Hypertarget{kdbmeta_8h_aa899d9f0251cb98a89761ef112910eca}\label{kdbmeta_8h_aa899d9f0251cb98a89761ef112910eca}} 
\index{kdbmeta.\+h@{kdbmeta.\+h}!key\+Set\+Owner@{key\+Set\+Owner}}
\index{key\+Set\+Owner@{key\+Set\+Owner}!kdbmeta.\+h@{kdbmeta.\+h}}
\subsubsection{\texorpdfstring{key\+Set\+Owner()}{keySetOwner()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Set\+Owner (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const char $\ast$}]{new\+Owner }\end{DoxyParamCaption})}



Set the owner of a key. 

an owner is a name of a system user related to a U\+ID. The owner decides on which location on the disc the key goes.

A private copy is stored, so the passed parameter can be freed after the call.


\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
{\em new\+Owner} & the string which describes the owner of the key \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the number of bytes actually saved including final N\+U\+LL 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 1} & when owner is freed (by setting 0 or \char`\"{}\char`\"{}) \\
\hline
{\em -\/1} & on null pointer or memory problems \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}, \hyperlink{owner_8c_a35922a017bee8b4bcb493bbdfad9d6f5}{key\+Get\+Owner()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\+Get\+Full\+Name()} 
\end{DoxySeeAlso}
