\hypertarget{group__keyname}{\section{Name Manipulation Methods}
\label{group__keyname}\index{Name Manipulation Methods@{Name Manipulation Methods}}
}


Methods to do various operations on Key names.  


Collaboration diagram for Name Manipulation Methods\-:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=290pt]{group__keyname}
\end{center}
\end{figure}
\subsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
enum \hyperlink{group__keyname_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\-Namespace} \{ \\*
\hyperlink{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a3659698b0a07454ca8055ab693e8efd1}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-N\-O\-N\-E} =0, 
\hyperlink{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a33d6c53529b4e6921d0b1d6565df2f1f}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-E\-M\-P\-T\-Y} =1, 
\hyperlink{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68ac5fbf2c3a7ae79fa2d60c48ae3e72688}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-M\-E\-T\-A} =1$<$$<$1, 
\hyperlink{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a2c9133e3095dccbcde5ca3bb13987b5d}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-C\-A\-S\-C\-A\-D\-I\-N\-G} =1$<$$<$2, 
\\*
\hyperlink{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a8ce23c70010e8ac8bb540b0947e03a4e}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-U\-S\-E\-R} =1$<$$<$3, 
\hyperlink{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a61adca2f9dff47e65dfcdb492ffa7a20}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-S\-Y\-S\-T\-E\-M} =1$<$$<$4
 \}
\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
const char $\ast$ \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name} (const Key $\ast$key)
\item 
ssize\-\_\-t \hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\-Get\-Name\-Size} (const Key $\ast$key)
\item 
ssize\-\_\-t \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name} (const Key $\ast$key, char $\ast$returned\-Name, size\-\_\-t max\-Size)
\item 
ssize\-\_\-t \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name} (Key $\ast$key, const char $\ast$new\-Name)
\item 
ssize\-\_\-t \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{key\-Get\-Full\-Name\-Size} (const Key $\ast$key)
\item 
ssize\-\_\-t \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name} (const Key $\ast$key, char $\ast$returned\-Name, size\-\_\-t max\-Size)
\item 
\hyperlink{group__keyname_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\-Namespace} \hyperlink{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{key\-Get\-Namespace} (const Key $\ast$key)
\item 
const char $\ast$ \hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\-Base\-Name} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns a pointer to the internal unescaped key name where the {\ttfamily basename} starts. \end{DoxyCompactList}\item 
ssize\-\_\-t \hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{key\-Get\-Base\-Name\-Size} (const Key $\ast$key)
\item 
ssize\-\_\-t \hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\-Get\-Base\-Name} (const Key $\ast$key, char $\ast$returned, size\-\_\-t max\-Size)
\item 
ssize\-\_\-t \hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\-Add\-Base\-Name} (Key $\ast$key, const char $\ast$base\-Name)
\item 
ssize\-\_\-t \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name} (Key $\ast$key, const char $\ast$base\-Name)
\item 
const char $\ast$ \hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{key\-Owner} (const Key $\ast$key)
\item 
ssize\-\_\-t \hyperlink{group__keyname_ga4a4561895741ba2ad10acf007c188593}{key\-Get\-Owner\-Size} (const Key $\ast$key)
\item 
ssize\-\_\-t \hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{key\-Get\-Owner} (const Key $\ast$key, char $\ast$returned\-Owner, size\-\_\-t max\-Size)
\item 
ssize\-\_\-t \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{key\-Set\-Owner} (Key $\ast$key, const char $\ast$new\-Owner)
\end{DoxyCompactItemize}


\subsection{Detailed Description}
Methods to do various operations on Key names. To use them\-: 
\begin{DoxyCode}
\textcolor{preprocessor}{#include <kdb.h>}
\end{DoxyCode}


These functions make it easier for C programmers to work with key names.

\begin{DoxyParagraph}{Terminology of Key Names}

\begin{DoxyItemize}
\item A {\itshape key name} (see \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} and \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name()}) defines the place of a key within the key database. To be unique, it is always absolute and canonical.
\item Key names are composed out of many {\itshape key name parts} split by a separator. These {\itshape key name parts} do not contain a unescaped separator.
\item A {\itshape key base name} (see \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name()} and \hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\-Add\-Base\-Name()}) is the last part of the key name.
\item A namespace denotes the place the key comes from\-:
\begin{DoxyItemize}
\item {\itshape user} keys come from user's home directories
\item {\itshape system} keys come from systems etc directories
\end{DoxyItemize}
\item A {\itshape C-\/\-String} is a null terminated sequence of characters. So \textbackslash{}0 (null-\/character) must not occur within a C-\/\-String.
\end{DoxyItemize}
\end{DoxyParagraph}
\begin{DoxyNote}{Note}
The rules are currently not formally specified and are subject of change in the next major release. So, always prefer\-:
\begin{DoxyItemize}
\item To use \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} and key\-Add\-Name() to get the canonified version of the keyname
\item To use \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name()} and \hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\-Add\-Base\-Name()} to get an escaped key name part.
\item Not to escape or canonify with your own algorithms!
\item To use key\-Unescaped\-Name() and \hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\-Base\-Name()} to have access to the key name without escape sequences (key name parts are null terminated)
\item Not to unescape the strings yourself!
\end{DoxyItemize}
\end{DoxyNote}
\begin{DoxyParagraph}{Syntax for Key Names}
Key names and key name parts have following goals\-:
\begin{DoxyItemize}
\item The C-\/\-String passed to \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} and key\-Add\-Name() may be any C-\/\-String.
\item The {\itshape key name parts} (e.\-g. \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name()}, \hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\-Base\-Name()}) may be any C-\/\-String. Escaping is needed to achieve both goals.
\end{DoxyItemize}
\end{DoxyParagraph}
\begin{DoxyParagraph}{Semantics for Key Name Parts}

\begin{DoxyItemize}
\item \% denotes an empty key name part.
\end{DoxyItemize}
\end{DoxyParagraph}
\begin{DoxyParagraph}{Canonicalization for Key Names}

\begin{DoxyItemize}
\item / (slash) is the separator between key name parts.
\item // is shortened to /
\item trailing / (slashes) are removed
\item . (dot) and .. (dot-\/dot) is removed in an canonical key name, with following rules\-:
\begin{DoxyItemize}
\item /./ is shortened to /
\item \-\_\-/../ is shortened to \-\_\-
\end{DoxyItemize}
\end{DoxyItemize}
\end{DoxyParagraph}
\begin{DoxyParagraph}{Conventions for key names}

\begin{DoxyItemize}
\item Key name parts starting with \# are array elements. Then only \-\_\- (underscore) followed by 0-\/9 is allowed. So we have the regular expression \#\mbox{[}\-\_\-\mbox{]}$\ast$\mbox{[}0-\/9\mbox{]}+ with the further limitation that the number of \-\_\- is defined by the number of digits-\/1.
\item Key name parts starting with \-\_\- are reserved for special purposes (if you use this within a plugin you still have to make sure \-\_\- is escaped properly)
\item Key name parts starting with @ are reserved for special purposes (if you use this within a plugin you still have to make sure @ is escaped properly)
\item If any key name part starts with . (dot) it means the key is inactive, see \hyperlink{group__keytest_gaa25f699f592031c1a0abc1504d14e13e}{key\-Is\-Inactive()}.
\end{DoxyItemize}
\end{DoxyParagraph}
\begin{DoxyParagraph}{Escaping rules}

\begin{DoxyItemize}
\item \textbackslash{} (backslash) is the escape character for the situations as described here (and only these). The \textbackslash{} character must only be escaped, when one of the following rules apply. So there is no stray escape character possible.
\item \textbackslash{}/ allows to escape /
\item \textbackslash{}\textbackslash{}/ allows to use \textbackslash{} as character before / (and so on)
\item Use  and . if you want your key name part to represent . and ..
\item \textbackslash{} and \textbackslash{}. allows to use \textbackslash{} as character before . and .. (and so on)
\item Use \textbackslash{}\% if you want your key name part to start with \% (and does not represent an empty name)
\item Use \textbackslash{}\textbackslash{}\% allows to use \textbackslash{} as character before \% (and so on)
\end{DoxyItemize}
\end{DoxyParagraph}
\begin{DoxyParagraph}{Semantics for Key Name Specifications}

\begin{DoxyItemize}
\item \-\_\- denotes that the key name part is arbitrary (syntax as described above).
\item \# denotes that the key name part has array syntax.
\item names surrounded by \% (e.\-g. \%profile\%) denotes a placeholder.
\end{DoxyItemize}
\end{DoxyParagraph}
\begin{DoxyParagraph}{Usage of Key Names}
When using Elektra to store your application's configuration and state, please keep in mind the following rules\-:
\begin{DoxyItemize}
\item Avoid to have your applications root right under {\ttfamily system} or {\ttfamily user}. (rationale\-: it would make the hierarchy too flat.)
\item Avoid the usage of characters other then a-\/z, 0-\/9 and \-\_\-. (rationale\-: it would allow too many similar, confusing names.) (exceptions\-: if the user or a technology, decide about parts of the key name, this restriction does not apply, e.\-g. if the wlan essid is used as part of the key name)
\item It is suggested to make your application look for default keys under {\ttfamily /sw/myapp/\#/\%/} where \# is a major version number, e.\-g. \#3 for the 4th version and \% is a profile (\% for default profile). This way, from a sysadmin perspective, it will be possible to copy the {\ttfamily system/sw/myapp/\#3/\%/} tree to something like {\ttfamily system/sw/myapp/\#3/old/} and keep system clean and organized. Additionally, it is possible to start the old version of the app, using {\ttfamily /sw/myapp/\#2}. 
\end{DoxyItemize}
\end{DoxyParagraph}


\subsection{Enumeration Type Documentation}
\hypertarget{group__keyname_gaec3b8d6f430ae49b91bafe8a86310a68}{\index{Name Manipulation Methods@{Name Manipulation Methods}!elektra\-Namespace@{elektra\-Namespace}}
\index{elektra\-Namespace@{elektra\-Namespace}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{elektra\-Namespace}]{\setlength{\rightskip}{0pt plus 5cm}enum {\bf elektra\-Namespace}}}\label{group__keyname_gaec3b8d6f430ae49b91bafe8a86310a68}
Elektra currently supported Key namespaces.

\begin{DoxySeeAlso}{See Also}
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\-Get()}, \hyperlink{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{key\-Get\-Namespace()} 
\end{DoxySeeAlso}
\begin{Desc}
\item[Enumerator\-: ]\par
\begin{description}
\index{K\-E\-Y\-\_\-\-N\-S\-\_\-\-N\-O\-N\-E@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-N\-O\-N\-E}!Name Manipulation Methods@{Name Manipulation Methods}}\index{Name Manipulation Methods@{Name Manipulation Methods}!K\-E\-Y\-\_\-\-N\-S\-\_\-\-N\-O\-N\-E@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-N\-O\-N\-E}}\item[{\em 
\hypertarget{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a3659698b0a07454ca8055ab693e8efd1}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-N\-O\-N\-E}\label{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a3659698b0a07454ca8055ab693e8efd1}
}]no key given as parameter to \hyperlink{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{key\-Get\-Namespace()} \index{K\-E\-Y\-\_\-\-N\-S\-\_\-\-E\-M\-P\-T\-Y@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-E\-M\-P\-T\-Y}!Name Manipulation Methods@{Name Manipulation Methods}}\index{Name Manipulation Methods@{Name Manipulation Methods}!K\-E\-Y\-\_\-\-N\-S\-\_\-\-E\-M\-P\-T\-Y@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-E\-M\-P\-T\-Y}}\item[{\em 
\hypertarget{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a33d6c53529b4e6921d0b1d6565df2f1f}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-E\-M\-P\-T\-Y}\label{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a33d6c53529b4e6921d0b1d6565df2f1f}
}]key name was empty, e.\-g. invalid key name \index{K\-E\-Y\-\_\-\-N\-S\-\_\-\-M\-E\-T\-A@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-M\-E\-T\-A}!Name Manipulation Methods@{Name Manipulation Methods}}\index{Name Manipulation Methods@{Name Manipulation Methods}!K\-E\-Y\-\_\-\-N\-S\-\_\-\-M\-E\-T\-A@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-M\-E\-T\-A}}\item[{\em 
\hypertarget{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68ac5fbf2c3a7ae79fa2d60c48ae3e72688}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-M\-E\-T\-A}\label{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68ac5fbf2c3a7ae79fa2d60c48ae3e72688}
}]meta key, i.\-e. any key name not under other categories \index{K\-E\-Y\-\_\-\-N\-S\-\_\-\-C\-A\-S\-C\-A\-D\-I\-N\-G@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-C\-A\-S\-C\-A\-D\-I\-N\-G}!Name Manipulation Methods@{Name Manipulation Methods}}\index{Name Manipulation Methods@{Name Manipulation Methods}!K\-E\-Y\-\_\-\-N\-S\-\_\-\-C\-A\-S\-C\-A\-D\-I\-N\-G@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-C\-A\-S\-C\-A\-D\-I\-N\-G}}\item[{\em 
\hypertarget{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a2c9133e3095dccbcde5ca3bb13987b5d}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-C\-A\-S\-C\-A\-D\-I\-N\-G}\label{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a2c9133e3095dccbcde5ca3bb13987b5d}
}]cascading key, starts with /, abstract name for any of the namespaces below \index{K\-E\-Y\-\_\-\-N\-S\-\_\-\-U\-S\-E\-R@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-U\-S\-E\-R}!Name Manipulation Methods@{Name Manipulation Methods}}\index{Name Manipulation Methods@{Name Manipulation Methods}!K\-E\-Y\-\_\-\-N\-S\-\_\-\-U\-S\-E\-R@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-U\-S\-E\-R}}\item[{\em 
\hypertarget{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a8ce23c70010e8ac8bb540b0947e03a4e}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-U\-S\-E\-R}\label{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a8ce23c70010e8ac8bb540b0947e03a4e}
}]user key in the home directory of the current user \index{K\-E\-Y\-\_\-\-N\-S\-\_\-\-S\-Y\-S\-T\-E\-M@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-S\-Y\-S\-T\-E\-M}!Name Manipulation Methods@{Name Manipulation Methods}}\index{Name Manipulation Methods@{Name Manipulation Methods}!K\-E\-Y\-\_\-\-N\-S\-\_\-\-S\-Y\-S\-T\-E\-M@{K\-E\-Y\-\_\-\-N\-S\-\_\-\-S\-Y\-S\-T\-E\-M}}\item[{\em 
\hypertarget{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a61adca2f9dff47e65dfcdb492ffa7a20}{K\-E\-Y\-\_\-\-N\-S\-\_\-\-S\-Y\-S\-T\-E\-M}\label{group__keyname_ggaec3b8d6f430ae49b91bafe8a86310a68a61adca2f9dff47e65dfcdb492ffa7a20}
}]system key not in the home directory, shared for a computer system \end{description}
\end{Desc}



\subsection{Function Documentation}
\hypertarget{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Add\-Base\-Name@{key\-Add\-Base\-Name}}
\index{key\-Add\-Base\-Name@{key\-Add\-Base\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Add\-Base\-Name}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Add\-Base\-Name (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{key, }
\item[{const char $\ast$}]{base\-Name}
\end{DoxyParamCaption}
)}}\label{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}
Adds {\ttfamily base\-Name} (that will be escaped) to the current key name.

A new base\-Name will be added, no other part of the key name will be affected.

Assumes that {\ttfamily key} is a directory and will append {\ttfamily base\-Name} to it. The function adds the path separator for concatenating.

So if {\ttfamily key} has name {\ttfamily \char`\"{}system/dir1/dir2\char`\"{}} and this method is called with {\ttfamily base\-Name} {\ttfamily \char`\"{}mykey\char`\"{}}, the resulting key will have the name {\ttfamily \char`\"{}system/dir1/dir2/mykey\char`\"{}}.

When {\ttfamily base\-Name} is 0 nothing will happen and the size of the name is returned.

The escaping rules apply as in \hyperlink{group__keyname}{above }.

A simple example is\-: 
\begin{DoxyCodeInclude}
Key * k = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/my/long"}, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName}(k, \textcolor{stringliteral}{"myname"});
printf (\textcolor{stringliteral}{"%s\(\backslash\)n"}, \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}(k)); \textcolor{comment}{// will print user/my/long/myname}
\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}(k);
\end{DoxyCodeInclude}
 E.\-g. if you add . it will be escaped\-: 
\begin{DoxyCodeInclude}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName} (k, \textcolor{stringliteral}{"system/valid"});
succeed\_if (\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName} (k, \textcolor{stringliteral}{"."}) >= 0, \textcolor{stringliteral}{"could not add a base
       name"});
succeed\_if\_same\_string(\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}(k), \textcolor{stringliteral}{"system/valid/\(\backslash\)\(\backslash\)."});
succeed\_if\_same\_string(\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}(k), \textcolor{stringliteral}{"."});
\end{DoxyCodeInclude}
 \begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name()} to set a base name 

\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} to set a new name.
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
{\em base\-Name} & the string to append to the name \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size in bytes of the new key name including the ending N\-U\-L\-L 

-\/1 if the key had no name 

-\/1 on N\-U\-L\-L pointers 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if key was inserted to a keyset before \\
\hline
\end{DoxyRetVals}
\hypertarget{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Base\-Name@{key\-Base\-Name}}
\index{key\-Base\-Name@{key\-Base\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Base\-Name}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ key\-Base\-Name (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}


Returns a pointer to the internal unescaped key name where the {\ttfamily basename} starts. 

This is a much more efficient version of \hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\-Get\-Base\-Name()} and you should use it if you are responsible enough to not mess up things. The name might change or even point to a wrong place after a \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()}. So make sure to copy the memory before the name changes.

\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\-Base\-Name()} returns \char`\"{}\char`\"{} when there is no key\-Base\-Name. The reason is 
\begin{DoxyCodeInclude}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}(k,\textcolor{stringliteral}{""});
succeed\_if\_same\_string(\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}(k), \textcolor{stringliteral}{""});
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}(k,\textcolor{stringliteral}{"user"});
succeed\_if\_same\_string(\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}(k), \textcolor{stringliteral}{""});
\end{DoxyCodeInclude}
 And there is also support for really empty basenames\-: 
\begin{DoxyCodeInclude}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName} (k, \textcolor{stringliteral}{"system/valid"});
succeed\_if (\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName} (k, \textcolor{stringliteral}{""}) >= 0, \textcolor{stringliteral}{"could not add a base
       name"});
succeed\_if\_same\_string(\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}(k), \textcolor{stringliteral}{"system/valid/%"});
succeed\_if\_same\_string(\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}(k), \textcolor{stringliteral}{""});
\end{DoxyCodeInclude}
 \begin{DoxyNote}{Note}
You must never use the pointer returned by \hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\-Base\-Name()} method to change the name, but you should use \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name()} instead.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the object to obtain the basename from \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to the basename 

\char`\"{}\char`\"{} when the key has no (base)name 

0 on N\-U\-L\-L pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\-Get\-Base\-Name()}, \hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{key\-Get\-Base\-Name\-Size()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name()} to get a pointer to the name 

\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{key\-Owner()} to get a pointer to the owner 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Base\-Name@{key\-Get\-Base\-Name}}
\index{key\-Get\-Base\-Name@{key\-Get\-Base\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Base\-Name}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Base\-Name (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key, }
\item[{char $\ast$}]{returned, }
\item[{size\-\_\-t}]{max\-Size}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}
Calculate the basename of a key name and put it in {\ttfamily returned} finalizing the string with N\-U\-L\-L.

Some examples\-:
\begin{DoxyItemize}
\item basename of {\ttfamily system/some/keyname} is {\ttfamily keyname} 
\item basename of {\ttfamily \char`\"{}user/tmp/some key\char`\"{}} is {\ttfamily \char`\"{}some key\char`\"{}} 
\end{DoxyItemize}


\begin{DoxyParams}{Parameters}
{\em key} & the key to extract basename from \\
\hline
{\em returned} & a pre-\/allocated buffer to store the basename \\
\hline
{\em max\-Size} & size of the {\ttfamily returned} buffer \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes copied to {\ttfamily returned} 

1 on empty name 

-\/1 on N\-U\-L\-L pointers 

-\/1 when max\-Size is 0 or larger than S\-S\-I\-Z\-E\-\_\-\-M\-A\-X 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\-Base\-Name()}, \hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{key\-Get\-Base\-Name\-Size()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name()}, \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name()}, \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Base\-Name\-Size@{key\-Get\-Base\-Name\-Size}}
\index{key\-Get\-Base\-Name\-Size@{key\-Get\-Base\-Name\-Size}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Base\-Name\-Size}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Base\-Name\-Size (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}
Calculates number of bytes needed to store basename of {\ttfamily key}.

Key names that have only root names (e.\-g. {\ttfamily \char`\"{}system\char`\"{}} or {\ttfamily \char`\"{}user\char`\"{}} or {\ttfamily \char`\"{}user\-:domain\char`\"{}} ) does not have basenames, thus the function will return 1 bytes to store \char`\"{}\char`\"{}.

Basenames are denoted as\-:
\begin{DoxyItemize}
\item {\ttfamily system/some/thing/basename} -\/$>$ {\ttfamily basename} 
\item {\ttfamily user\-:domain/some/thing/base\textbackslash{}/name} $>$ {\ttfamily base\textbackslash{}/name} 
\end{DoxyItemize}


\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
size in bytes of {\ttfamily key's} basename including ending N\-U\-L\-L 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\-Base\-Name()}, \hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\-Get\-Base\-Name()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name()}, \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name()}, \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Full\-Name@{key\-Get\-Full\-Name}}
\index{key\-Get\-Full\-Name@{key\-Get\-Full\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Full\-Name}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Full\-Name (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key, }
\item[{char $\ast$}]{returned\-Name, }
\item[{size\-\_\-t}]{max\-Size}
\end{DoxyParamCaption}
)}}\label{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}
Get key full name, including the user domain name.

\begin{DoxyReturn}{Returns}
number of bytes written 

1 on empty name 

-\/1 on N\-U\-L\-L pointers 

-\/1 if max\-Size is 0 or larger than S\-S\-I\-Z\-E\-\_\-\-M\-A\-X 
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
{\em key} & the key object \\
\hline
{\em returned\-Name} & pre-\/allocated memory to write the key name \\
\hline
{\em max\-Size} & maximum number of bytes that will fit in returned\-Name, including the final N\-U\-L\-L \\
\hline
\end{DoxyParams}
\hypertarget{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Full\-Name\-Size@{key\-Get\-Full\-Name\-Size}}
\index{key\-Get\-Full\-Name\-Size@{key\-Get\-Full\-Name\-Size}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Full\-Name\-Size}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Full\-Name\-Size (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}
Bytes needed to store the key name including user domain and ending N\-U\-L\-L.


\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes needed to store key name including user domain 

1 on empty name 

-\/1 on N\-U\-L\-L pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name()}, \hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\-Get\-Name\-Size()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Name@{key\-Get\-Name}}
\index{key\-Get\-Name@{key\-Get\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Name}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Name (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key, }
\item[{char $\ast$}]{returned\-Name, }
\item[{size\-\_\-t}]{max\-Size}
\end{DoxyParamCaption}
)}}\label{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}
Get abbreviated key name (without owner name).

When there is not enough space to write the name, nothing will be written and -\/1 will be returned.

max\-Size is limited to S\-S\-I\-Z\-E\-\_\-\-M\-A\-X. When this value is exceeded -\/1 will be returned. The reason for that is that any value higher is just a negative return value passed by accident. Of course malloc is not as failure tolerant and will try to allocate.


\begin{DoxyCode}
\textcolor{keywordtype}{char} *getBack = malloc (\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize}(key));
\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName}(key, getBack, \hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize}(key));
\end{DoxyCode}


\begin{DoxyReturn}{Returns}
number of bytes written to {\ttfamily returned\-Name} 

1 when only a null was written 

-\/1 when keyname is longer then max\-Size or 0 or any N\-U\-L\-L pointer 
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
{\em returned\-Name} & pre-\/allocated memory to write the key name \\
\hline
{\em max\-Size} & maximum number of bytes that will fit in returned\-Name, including the final N\-U\-L\-L \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\-Get\-Name\-Size()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name()}, \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{key\-Get\-Full\-Name\-Size()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Name\-Size@{key\-Get\-Name\-Size}}
\index{key\-Get\-Name\-Size@{key\-Get\-Name\-Size}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Name\-Size}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Name\-Size (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}
Bytes needed to store the key name without owner.

For an empty key name you need one byte to store the ending N\-U\-L\-L. For that reason 1 is returned.


\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes needed, including ending N\-U\-L\-L, to store key name without owner 

1 if there is is no key Name 

-\/1 on N\-U\-L\-L pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name()}, \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{key\-Get\-Full\-Name\-Size()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Namespace@{key\-Get\-Namespace}}
\index{key\-Get\-Namespace@{key\-Get\-Namespace}!Name Manipulation Methods@{Name Manipulation Methods}}
\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__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}
For currently valid namespaces see \hyperlink{group__keyname_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\-Namespace}.

\begin{DoxyVersion}{Version}
0.\-8.\-10 Added method to kdbproposal.\-h
\end{DoxyVersion}
\begin{DoxyNote}{Note}
This method might be enhanced. You do not have any guarantee that, when for a specific name \hyperlink{group__keyname_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__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Owner@{key\-Get\-Owner}}
\index{key\-Get\-Owner@{key\-Get\-Owner}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Owner}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Owner (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key, }
\item[{char $\ast$}]{returned\-Owner, }
\item[{size\-\_\-t}]{max\-Size}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}
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 a owner. For {\ttfamily system/}... keys (that doesn'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\-I\-D. Owner are related to W\-H\-E\-R\-E 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 

1 if there is no owner 

-\/1 on N\-U\-L\-L pointers 

-\/1 when max\-Size is 0, larger than S\-S\-I\-Z\-E\-\_\-\-M\-A\-X or too small for ownername 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()}, \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{key\-Set\-Owner()}, \hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{key\-Owner()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga4a4561895741ba2ad10acf007c188593}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Get\-Owner\-Size@{key\-Get\-Owner\-Size}}
\index{key\-Get\-Owner\-Size@{key\-Get\-Owner\-Size}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Get\-Owner\-Size}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Get\-Owner\-Size (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga4a4561895741ba2ad10acf007c188593}
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{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{key\-Get\-Owner()}.


\begin{DoxyCode}
\textcolor{keywordtype}{char} * buffer;
buffer = malloc (\hyperlink{group__keyname_ga4a4561895741ba2ad10acf007c188593}{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 

1 if there is no owner 

-\/1 on N\-U\-L\-L pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{key\-Get\-Owner()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga8e805c726a60da921d3736cda7813513}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Name@{key\-Name}}
\index{key\-Name@{key\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Name}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ key\-Name (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga8e805c726a60da921d3736cda7813513}
Returns a pointer to the abbreviated real internal {\ttfamily key} name.

This is a much more efficient version of \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name()} and can use it if you are responsible enough to not mess up things. You are not allowed to change anything in the returned array. The content of that string may change after \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} and similar functions. If you need a copy of the name, consider using \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name()}.

The name will be without owner, see \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name()} if you need the name with its owner.

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name()} returns \char`\"{}\char`\"{} when there is no key\-Name. The reason is 
\begin{DoxyCode}
key=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(0);
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}(key,\textcolor{stringliteral}{""});
\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}(key); \textcolor{comment}{// you would expect "" here}
\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}(key);
\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{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name()} method to set a new value. Use \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} instead.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to the keyname which must not be changed. 

\char`\"{}\char`\"{} when there is no (a empty) keyname 

0 on N\-U\-L\-L pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\-Get\-Name\-Size()} for the string length 

\hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name()}, \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{key\-Get\-Full\-Name\-Size()} to get the full name 

\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name()} as alternative to get a copy 

\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{key\-Owner()} to get a pointer to owner 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Owner@{key\-Owner}}
\index{key\-Owner@{key\-Owner}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Owner}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ key\-Owner (
\begin{DoxyParamCaption}
\item[{const Key $\ast$}]{key}
\end{DoxyParamCaption}
)}}\label{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}
Return a pointer to the real internal {\ttfamily key} owner.

This is a much more efficient version of \hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{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{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{key\-Get\-Owner()} instead.

\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{key\-Owner()} returns \char`\"{}\char`\"{} when there is no key\-Owner. The reason is 
\begin{DoxyCode}
key=\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(0);
\hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner}(key,\textcolor{stringliteral}{""});
\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{keyOwner}(key); \textcolor{comment}{// you would expect "" here}
\hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner}(key,\textcolor{stringliteral}{"system"});
\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{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{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{key\-Owner()} method to set a new value. Use \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{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 (a empty) owner \\
\hline
{\em 0} & iff key is a N\-U\-L\-L pointer \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_ga4a4561895741ba2ad10acf007c188593}{key\-Get\-Owner\-Size()} for the size of the string with concluding 0 

\hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{key\-Get\-Owner()}, \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{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}
\hypertarget{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Set\-Base\-Name@{key\-Set\-Base\-Name}}
\index{key\-Set\-Base\-Name@{key\-Set\-Base\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Set\-Base\-Name}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Set\-Base\-Name (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{key, }
\item[{const char $\ast$}]{base\-Name}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}
Sets {\ttfamily base\-Name} as the new basename for {\ttfamily key}.

Only the base\-Name will be affected and no other part of the key.

All text after the last {\ttfamily '/'} in the {\ttfamily key} keyname is erased and {\ttfamily base\-Name} is appended.

So let us suppose {\ttfamily key} has name {\ttfamily \char`\"{}system/dir1/dir2/key1\char`\"{}}. If {\ttfamily base\-Name} is {\ttfamily \char`\"{}key2\char`\"{}}, the resulting key name will be {\ttfamily \char`\"{}system/dir1/dir2/key2\char`\"{}}. If {\ttfamily base\-Name} is empty or N\-U\-L\-L, the resulting key name will be {\ttfamily \char`\"{}system/dir1/dir2\char`\"{}}.

This function does proper escaping on the supplied name argument.

You can use all names to set as basename (e.\-g. . (dot), .. (dot-\/dot), \% and \char`\"{}\char`\"{} (empty)). They will be properly escaped.

A simple example is\-: 
\begin{DoxyCodeInclude}
Key * k = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}(\textcolor{stringliteral}{"user/my/long/name"}, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName}(k, \textcolor{stringliteral}{"myname"});
printf (\textcolor{stringliteral}{"%s\(\backslash\)n"}, \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}(k)); \textcolor{comment}{// will print user/my/long/myname}
\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}(k);
\end{DoxyCodeInclude}
 If you do not want escaping, use \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name()} instead. E.\-g. if you want to add an inactive key, use\-: 
\begin{DoxyCodeInclude}
        \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName} (k, \textcolor{stringliteral}{"system/valid"});
        \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName}(k, \textcolor{stringliteral}{".hiddenkey"});
        succeed\_if\_same\_string(\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}(k), \textcolor{stringliteral}{"system/.hiddenkey"});
        succeed\_if\_same\_string(\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}(k), \textcolor{stringliteral}{".hiddenkey"});
\end{DoxyCodeInclude}
 or when you want to add an array item, use\-: 
\begin{DoxyCodeInclude}
        \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName} (k, \textcolor{stringliteral}{"system/valid"});
        \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName}(k, \textcolor{stringliteral}{""});
        succeed\_if\_same\_string(\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}(k), \textcolor{stringliteral}{"system/%"});
        succeed\_if\_same\_string(\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}(k), \textcolor{stringliteral}{""});
\end{DoxyCodeInclude}
 \begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname}{Name Manipulation Methods} for more details on special names
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
{\em base\-Name} & the string used to overwrite the basename of the key \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size in bytes of the new key name 

-\/1 on N\-U\-L\-L pointers 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if key was inserted to a keyset before \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\-Add\-Base\-Name()} 

\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()} to set a new name 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Set\-Name@{key\-Set\-Name}}
\index{key\-Set\-Name@{key\-Set\-Name}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Set\-Name}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Set\-Name (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{key, }
\item[{const char $\ast$}]{new\-Name}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}
Set a new name to a key.

A valid name is of the forms\-:
\begin{DoxyItemize}
\item {\ttfamily system/something} 
\item {\ttfamily user/something} 
\item {\ttfamily user\-:username/something} 
\end{DoxyItemize}

The last form has explicitly set the owner, to let the library know in which user folder to save the key. A owner is a user name. If it is not defined (the second form) current user is used.

You should always follow the guidelines for key tree structure creation.

A private copy of the key name will be stored, and the {\ttfamily new\-Name} parameter can be freed after this call.

.., . and / will be handled as in filesystem pathes. A valid name will be build out of the (valid) name what you pass, e.\-g. user///sw/../sw//././\-My\-App -\/$>$ user/sw/\-My\-App

On invalid names, N\-U\-L\-L or \char`\"{}\char`\"{} the name will be \char`\"{}\char`\"{} afterwards.


\begin{DoxyRetVals}{Return values}
{\em size} & in bytes of this new key name including ending N\-U\-L\-L \\
\hline
{\em 0} & if new\-Name is an empty string or a N\-U\-L\-L pointer (name will be empty afterwards) \\
\hline
{\em -\/1} & if new\-Name is invalid (name will be empty afterwards) \\
\hline
{\em -\/1} & if key was inserted to a keyset before \\
\hline
\end{DoxyRetVals}

\begin{DoxyParams}{Parameters}
{\em key} & the key object to work with \\
\hline
{\em new\-Name} & the new key name \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\-New()}, \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{key\-Set\-Owner()} 

\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\-Get\-Name()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name()}, \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\-Name()} 

\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\-Set\-Base\-Name()}, \hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\-Add\-Base\-Name()} to manipulate a name 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{\index{Name Manipulation Methods@{Name Manipulation Methods}!key\-Set\-Owner@{key\-Set\-Owner}}
\index{key\-Set\-Owner@{key\-Set\-Owner}!Name Manipulation Methods@{Name Manipulation Methods}}
\subsubsection[{key\-Set\-Owner}]{\setlength{\rightskip}{0pt plus 5cm}ssize\-\_\-t key\-Set\-Owner (
\begin{DoxyParamCaption}
\item[{Key $\ast$}]{key, }
\item[{const char $\ast$}]{new\-Owner}
\end{DoxyParamCaption}
)}}\label{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}
Set the owner of a key.

A owner is a name of a system user related to a U\-I\-D. 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\-L\-L 

1 when owner is freed (by setting 0 or \char`\"{}\char`\"{}) 

-\/1 on null pointer or memory problems 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See Also}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\-Set\-Name()}, \hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{key\-Get\-Owner()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{key\-Get\-Full\-Name()} 
\end{DoxySeeAlso}
