\hypertarget{group__keyname}{}\doxysection{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=309pt]{group__keyname}
\end{center}
\end{figure}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
const char $\ast$ \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns a pointer to the abbreviated real internal {\ttfamily key} name. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\+Get\+Name\+Size}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Bytes needed to store the Key\textquotesingle{}s name (excluding owner). \end{DoxyCompactList}\item 
const void $\ast$ \mbox{\hyperlink{group__keyname_ga6fe6af4c27b35d911a533f4ae4d698bb}{key\+Unescaped\+Name}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns a Key\textquotesingle{}s name, separated by NULL bytes and without backslashes for escaping. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_ga5e7eff0c77678420199d0d2e8729152b}{key\+Get\+Unescaped\+Name\+Size}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns the size of the Key\textquotesingle{}s unescaped name including embedded and terminating NULL characters. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name}} (const Key $\ast$key, char $\ast$returned\+Name, size\+\_\+t max\+Size)
\begin{DoxyCompactList}\small\item\em Get abbreviated Key name (excluding owner). \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_ga44a576c7919d5b03f28d3ed3afaa7cd1}{key\+Get\+Unescaped\+Name}} (const Key $\ast$key, char $\ast$returned\+Name, size\+\_\+t max\+Size)
\begin{DoxyCompactList}\small\item\em Copies the unescaped name of a Key into {\ttfamily returned\+Name}. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name}} (Key $\ast$key, const char $\ast$new\+Name)
\begin{DoxyCompactList}\small\item\em Set a new name to a Key. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{key\+Add\+Name}} (Key $\ast$key, const char $\ast$new\+Name)
\begin{DoxyCompactList}\small\item\em Add an already escaped name part to the Key\textquotesingle{}s name. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keyname_gae22037aad3f76f4454de4e6400637b39}{key\+Replace\+Prefix}} (Key $\ast$key, const Key $\ast$old\+Prefix, const Key $\ast$new\+Prefix)
\begin{DoxyCompactList}\small\item\em Replaces a prefix of the key name of {\ttfamily key}. \end{DoxyCompactList}\item 
bool \mbox{\hyperlink{group__keyname_ga26bacb092ebca8f69f3fee72069733d8}{elektra\+Key\+Name\+Validate}} (const char $\ast$name, bool is\+Complete)
\begin{DoxyCompactList}\small\item\em Takes an escaped key name and validates it. \end{DoxyCompactList}\item 
void \mbox{\hyperlink{group__keyname_ga99ef3765a0ea0887c8ab72859ae2592e}{elektra\+Key\+Name\+Canonicalize}} (const char $\ast$name, char $\ast$$\ast$canonical\+Name, size\+\_\+t $\ast$canonical\+Size\+Ptr, size\+\_\+t offset, size\+\_\+t $\ast$usize\+Ptr)
\begin{DoxyCompactList}\small\item\em Takes a valid (non-\/)canonical key name and produces its canonical form. \end{DoxyCompactList}\item 
void \mbox{\hyperlink{group__keyname_ga85dd2a5169e900c6c8371c54c7944edb}{elektra\+Key\+Name\+Unescape}} (const char $\ast$canonical\+Name, char $\ast$unescaped\+Name)
\begin{DoxyCompactList}\small\item\em Takes a canonical key name and unescapes it. \end{DoxyCompactList}\item 
const char $\ast$ \mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\+Base\+Name}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns a pointer to the unescaped Key\textquotesingle{}s name where the basename starts. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{key\+Get\+Base\+Name\+Size}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Calculates number of bytes needed to store basename of {\ttfamily key} (including NULL terminator). \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\+Get\+Base\+Name}} (const Key $\ast$key, char $\ast$returned, size\+\_\+t max\+Size)
\begin{DoxyCompactList}\small\item\em Copy the Key\textquotesingle{}s basename to {\ttfamily returned}. \end{DoxyCompactList}\item 
size\+\_\+t \mbox{\hyperlink{group__keyname_ga35ac22f466de1a74ca72b05e8252980d}{elektra\+Key\+Name\+Escape\+Part}} (const char $\ast$part, char $\ast$$\ast$escaped\+Part)
\begin{DoxyCompactList}\small\item\em Takes a single key name part and produces its escaped form. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\+Add\+Base\+Name}} (Key $\ast$key, const char $\ast$base\+Name)
\begin{DoxyCompactList}\small\item\em Adds {\ttfamily base\+Name} to the name of {\ttfamily key}. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name}} (Key $\ast$key, const char $\ast$base\+Name)
\begin{DoxyCompactList}\small\item\em Sets {\ttfamily base\+Name} as the new basename for {\ttfamily key}. \end{DoxyCompactList}\item 
\mbox{\hyperlink{group__key_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\+Namespace}} \mbox{\hyperlink{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{key\+Get\+Namespace}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Returns the \mbox{\hyperlink{group__key_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\+Namespace}} for a Key. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyname_ga98c1c1307419e689c98e556e5c542073}{key\+Set\+Namespace}} (Key $\ast$key, \mbox{\hyperlink{group__key_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\+Namespace}} ns)
\begin{DoxyCompactList}\small\item\em Changes the namespace of a Key. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Methods to do various operations on Key names. 

To use them\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{\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 \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} and \mbox{\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 an unescaped separator.
\item A {\itshape key base name} (see \mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name()}} and \mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\+Add\+Base\+Name()}}) is the last part of the key name.
\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{DoxyParagraph}{Namespaces}
A namespace denotes the place the key comes from\+:
\end{DoxyParagraph}

\begin{DoxyItemize}
\item {\ttfamily spec\+:/something} for specification of other keys.
\item {\ttfamily proc\+:/something} for in-\/memory keys, e.\+g. commandline.
\item {\ttfamily dir\+:/something} for dir keys in current working directory
\item {\ttfamily system\+:/something} for system keys in /etc or /
\item {\ttfamily user\+:/something} for user keys in home directory
\item {\ttfamily user\+:username/something} for other users (deprecated\+: \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} + \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} currently unsupported)
\item {\ttfamily /something} for cascading keys (actually refers to one of the above, see also \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}})

\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 \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} and \mbox{\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{key\+Add\+Name()}} to get the canonified version of the keyname
\item To use \mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name()}} and \mbox{\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 \mbox{\hyperlink{group__keyname_ga6fe6af4c27b35d911a533f4ae4d698bb}{key\+Unescaped\+Name()}} and \mbox{\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 \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} and \mbox{\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{key\+Add\+Name()}} may be any C-\/\+String.
\item The {\itshape key name parts} (e.\+g. \mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name()}}, \mbox{\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)
\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.
\item Stray escape characters are only possible in the end of the string.
\item \textbackslash{}/ allows one to escape / (any uneven number of \textbackslash{}). Does not introduce a new part.
\item Any uneven number N of \textbackslash{} before / allows you to escape / with the N/2 of \textbackslash{} prefixed. Does not introduce a new part.
\item \textbackslash{}\textbackslash{}/ allows one to use \textbackslash{} as character before / and introduces a new part.
\item Any even number N of \textbackslash{} before / allows you to have N/2 of \textbackslash{} prefixed before a / which introduces a new part.
\item Use \textbackslash{}. and \textbackslash{}.. if you want your key name part to represent . and ..
\item \textbackslash{}\textbackslash{}. and \textbackslash{}\textbackslash{}.. allows us 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 Using \textbackslash{}\textbackslash{}\% allows one 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}

\end{DoxyItemize}

\doxysubsection{Function Documentation}
\mbox{\Hypertarget{group__keyname_ga99ef3765a0ea0887c8ab72859ae2592e}\label{group__keyname_ga99ef3765a0ea0887c8ab72859ae2592e}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!elektraKeyNameCanonicalize@{elektraKeyNameCanonicalize}}
\index{elektraKeyNameCanonicalize@{elektraKeyNameCanonicalize}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{elektraKeyNameCanonicalize()}{elektraKeyNameCanonicalize()}}
{\footnotesize\ttfamily void elektra\+Key\+Name\+Canonicalize (\begin{DoxyParamCaption}\item[{const char $\ast$}]{name,  }\item[{char $\ast$$\ast$}]{canonical\+Name,  }\item[{size\+\_\+t $\ast$}]{canonical\+Size\+Ptr,  }\item[{size\+\_\+t}]{offset,  }\item[{size\+\_\+t $\ast$}]{usize\+Ptr }\end{DoxyParamCaption})}



Takes a valid (non-\/)canonical key name and produces its canonical form. 

As a side-\/effect it can also calculate the size of the corresponding unescaped key name.


\begin{DoxyParams}{Parameters}
{\em name} & The key name that is processed \\
\hline
{\em canonical\+Name} & Output buffer for the canonical name \\
\hline
{\em canonical\+Size\+Ptr} & Pointer to size of {\ttfamily canonical\+Name} \\
\hline
{\em offset} & Offset into {\ttfamily canonical\+Name} \\
\hline
{\em usize\+Ptr} & Output variable for the size of the unescaped name\\
\hline
\end{DoxyParams}
\begin{DoxyPrecond}{Precondition}
{\ttfamily name} MUST be a valid (non-\/)canonical key name. If it is not, the result is undefined 

{\ttfamily canonical\+Name} MUST be a valid first argument for \mbox{\hyperlink{internal_8c_ab0432d6765c40a5408a204c43747f4d4}{elektra\+Realloc()}} when cast to void$\ast$$\ast$ 

{\ttfamily canonical\+Size\+Ptr} $>$= {\ttfamily offset} 

{\ttfamily offset} MUST be 0 or {\ttfamily $\ast$canonical\+Name + offset} MUST point to the zero-\/termintor of a valid canonical key name that starts at {\ttfamily $\ast$canonical\+Name} 

if {\ttfamily offset} is 0 then {\ttfamily $\ast$usize\+Ptr} MUST 0, otherwise {\ttfamily $\ast$usize\+Ptr} MUST be the correct unescaped size of the existing canonical name in {\ttfamily $\ast$canonical\+Name}
\end{DoxyPrecond}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga26bacb092ebca8f69f3fee72069733d8}{elektra\+Key\+Name\+Validate}} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga35ac22f466de1a74ca72b05e8252980d}\label{group__keyname_ga35ac22f466de1a74ca72b05e8252980d}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!elektraKeyNameEscapePart@{elektraKeyNameEscapePart}}
\index{elektraKeyNameEscapePart@{elektraKeyNameEscapePart}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{elektraKeyNameEscapePart()}{elektraKeyNameEscapePart()}}
{\footnotesize\ttfamily size\+\_\+t elektra\+Key\+Name\+Escape\+Part (\begin{DoxyParamCaption}\item[{const char $\ast$}]{part,  }\item[{char $\ast$$\ast$}]{escaped\+Part }\end{DoxyParamCaption})}



Takes a single key name part and produces its escaped form. 


\begin{DoxyParams}{Parameters}
{\em part} & A single key name part, i.\+e. contained \textquotesingle{}/\textquotesingle{} will be escaped, \textquotesingle{}\textbackslash{}0\textquotesingle{} terminates part \\
\hline
{\em escaped\+Part} & Output buffer for the escaped form\\
\hline
\end{DoxyParams}
\begin{DoxyPrecond}{Precondition}
{\ttfamily escaped\+Part} MUST be a valid first argument for \mbox{\hyperlink{internal_8c_ab0432d6765c40a5408a204c43747f4d4}{elektra\+Realloc()}} when cast to {\ttfamily void$\ast$$\ast$}
\end{DoxyPrecond}
\begin{DoxyReturn}{Returns}
The size of the escaped form excluding the zero terminator 
\end{DoxyReturn}
\mbox{\Hypertarget{group__keyname_ga85dd2a5169e900c6c8371c54c7944edb}\label{group__keyname_ga85dd2a5169e900c6c8371c54c7944edb}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!elektraKeyNameUnescape@{elektraKeyNameUnescape}}
\index{elektraKeyNameUnescape@{elektraKeyNameUnescape}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{elektraKeyNameUnescape()}{elektraKeyNameUnescape()}}
{\footnotesize\ttfamily void elektra\+Key\+Name\+Unescape (\begin{DoxyParamCaption}\item[{const char $\ast$}]{canonical\+Name,  }\item[{char $\ast$}]{unescaped\+Name }\end{DoxyParamCaption})}



Takes a canonical key name and unescapes it. 


\begin{DoxyParams}{Parameters}
{\em canonical\+Name} & The canonical name to unescape \\
\hline
{\em unescaped\+Name} & Output buffer for the unescaped name\\
\hline
\end{DoxyParams}
\begin{DoxyPrecond}{Precondition}
{\ttfamily canonical\+Name} MUST be a canonical key name. If this is not the case, the result is undefined. 

{\ttfamily unescaped\+Name} MUST be allocated to the correct size.
\end{DoxyPrecond}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga99ef3765a0ea0887c8ab72859ae2592e}{elektra\+Key\+Name\+Canonicalize}} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga26bacb092ebca8f69f3fee72069733d8}\label{group__keyname_ga26bacb092ebca8f69f3fee72069733d8}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!elektraKeyNameValidate@{elektraKeyNameValidate}}
\index{elektraKeyNameValidate@{elektraKeyNameValidate}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{elektraKeyNameValidate()}{elektraKeyNameValidate()}}
{\footnotesize\ttfamily bool elektra\+Key\+Name\+Validate (\begin{DoxyParamCaption}\item[{const char $\ast$}]{name,  }\item[{bool}]{is\+Complete }\end{DoxyParamCaption})}



Takes an escaped key name and validates it. 

Complete key names must inlcude a namespace or a leading slash.


\begin{DoxyParams}{Parameters}
{\em name} & The escaped key name to check \\
\hline
{\em is\+Complete} & Whether or not {\ttfamily name} is supposed to be a complete key name\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em \#true} & If {\ttfamily name} is a valid key name. \\
\hline
{\em \#false} & Otherwise \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}\label{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyAddBaseName@{keyAddBaseName}}
\index{keyAddBaseName@{keyAddBaseName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyAddBaseName()}{keyAddBaseName()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Add\+Base\+Name (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const char $\ast$}]{base\+Name }\end{DoxyParamCaption})}



Adds {\ttfamily base\+Name} to the name of {\ttfamily key}. 

{\ttfamily base\+Name} will be escaped before adding it to the name of {\ttfamily key}. No other part of the Key\textquotesingle{}s 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.

If {\ttfamily key} has the 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 \mbox{\hyperlink{group__keyname}{above }}.

A simple example is\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key * k = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/my/long"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName}} (k, \textcolor{stringliteral}{"{}myname"{}});}
\DoxyCodeLine{printf (\textcolor{stringliteral}{"{}\%s\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (k)); \textcolor{comment}{// will print user:/my/long/myname}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 E.\+g. if you add . it will be escaped\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}} (k, \textcolor{stringliteral}{"{}system:/valid"{}});}
\DoxyCodeLine{        succeed\_if (\mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName}} (k, \textcolor{stringliteral}{"{}."{}}) >= 0, \textcolor{stringliteral}{"{}could not add a base name"{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (k), \textcolor{stringliteral}{"{}system:/valid/\(\backslash\)\(\backslash\)."{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}} (k), \textcolor{stringliteral}{"{}."{}});}

\end{DoxyCodeInclude}
 
\begin{DoxyParams}{Parameters}
{\em key} & the Key to add the basename to \\
\hline
{\em base\+Name} & the string to append to the Key\textquotesingle{}s name\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size in bytes of the Key\textquotesingle{}s new name including the NULL terminator 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if the Key has no name \\
\hline
{\em -\/1} & on NULL pointers \\
\hline
{\em -\/1} & if Key was inserted into Key\+Set before \\
\hline
{\em -\/1} & if the Key was read-\/only \\
\hline
{\em -\/1} & on memory allocation errors\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name()}} for setting the basename of a Key 

\mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} for setting the name of a \mbox{\hyperlink{group__key}{Key}} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}\label{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyAddName@{keyAddName}}
\index{keyAddName@{keyAddName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyAddName()}{keyAddName()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Add\+Name (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const char $\ast$}]{new\+Name }\end{DoxyParamCaption})}



Add an already escaped name part to the Key\textquotesingle{}s name. 

The same way as in \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} this method finds the canonical pathname\+:
\begin{DoxyItemize}
\item it will ignore /./
\item it will remove a level when /../ is used
\item it will remove multiple slashes ////
\end{DoxyItemize}

For example\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key * k = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/x/r"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{keyAddName}} (k, \textcolor{stringliteral}{"{}../y/a//././z"{}});}
\DoxyCodeLine{assert (!strcmp (\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (k), \textcolor{stringliteral}{"{}user:/x/y/a/z"{}}));}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 Unlike \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} it adds relative to the previous name and cannot change the namespace of a Key. For example\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key * n = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/away"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{keyAddName}} (n, \textcolor{stringliteral}{"{}../../../new/name"{}});}
\DoxyCodeLine{assert (!strcmp (\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (n), \textcolor{stringliteral}{"{}user:/new/name"{}}));}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (n);}

\end{DoxyCodeInclude}
 The passed name needs to be valid according the \mbox{\hyperlink{group__keyname}{key name rules }}. It is not allowed to\+:
\begin{DoxyItemize}
\item be empty
\item end with unequal number of \textbackslash{}
\end{DoxyItemize}

\begin{DoxyPrecond}{Precondition}
{\ttfamily key} MUST be a valid \#\+Key
\end{DoxyPrecond}

\begin{DoxyParams}{Parameters}
{\em key} & the Key where a name should be added \\
\hline
{\em new\+Name} & the new name to add to the name of {\ttfamily key} \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
new size of the escaped name of {\ttfamily key} 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if {\ttfamily key == NULL} or {\ttfamily new\+Name == NULL} \\
\hline
{\em -\/1} & {\ttfamily new\+Name} is not a valid escaped name \\
\hline
{\em -\/1} & {\ttfamily key} is read-\/only\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} for setting a Key\textquotesingle{}s name 

\mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\+Add\+Base\+Name()}} for adding a basename to a Key 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}\label{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyBaseName@{keyBaseName}}
\index{keyBaseName@{keyBaseName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyBaseName()}{keyBaseName()}}
{\footnotesize\ttfamily const char$\ast$ key\+Base\+Name (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns a pointer to the unescaped Key\textquotesingle{}s name where the basename starts. 

This is a much more efficient version of \mbox{\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 \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}}. So make sure to copy the memory before the name changes.

\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\+Base\+Name()}} returns \char`\"{}\char`\"{} when the Key has no basename. The reason is 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}} (k, \textcolor{stringliteral}{"{}"{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}} (k), \textcolor{stringliteral}{"{}"{}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}} (k, \textcolor{stringliteral}{"{}user:/"{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}} (k), \textcolor{stringliteral}{"{}"{}});}

\end{DoxyCodeInclude}
 There is also support for really empty basenames\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}} (k, \textcolor{stringliteral}{"{}system:/valid"{}});}
\DoxyCodeLine{        succeed\_if (\mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName}} (k, \textcolor{stringliteral}{"{}"{}}) >= 0, \textcolor{stringliteral}{"{}could not add a base name"{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (k), \textcolor{stringliteral}{"{}system:/valid/\%"{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}} (k), \textcolor{stringliteral}{"{}"{}});}

\end{DoxyCodeInclude}
 \begin{DoxyNote}{Note}
You must never use the pointer returned by \mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\+Base\+Name()}} method to change the name. You should use \mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name()}} instead.

Do not assume that \mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\+Base\+Name()}} points to the same region as \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}} does.
\end{DoxyNote}

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

\begin{DoxyRetVals}{Return values}
{\em \char`\"{}\char`\"{}} & when the Key has no (base)name \\
\hline
{\em 0} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\+Get\+Base\+Name()}} for getting a copy of the Key\textquotesingle{}s basename 

\mbox{\hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{key\+Get\+Base\+Name\+Size()}} for getting the size of the Key\textquotesingle{}s basename 

\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}} for getting a pointer to the Key\textquotesingle{}s name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}\label{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyGetBaseName@{keyGetBaseName}}
\index{keyGetBaseName@{keyGetBaseName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetBaseName()}{keyGetBaseName()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Base\+Name (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{char $\ast$}]{returned,  }\item[{size\+\_\+t}]{max\+Size }\end{DoxyParamCaption})}



Copy the Key\textquotesingle{}s basename to {\ttfamily returned}. 

The copy will include a NULL terminator which will be considered for the returned size. Nothing will be copied if {\ttfamily max\+Size} is smaller than the size of the basename.

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 for storing the basename \\
\hline
{\em max\+Size} & size of the buffer {\ttfamily returned} \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes copied to {\ttfamily returned} 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 1} & when Key\textquotesingle{}s name is empty \\
\hline
{\em -\/1} & on NULL pointers \\
\hline
{\em -\/1} & when max\+Size is 0 or larger than SSIZE\+\_\+\+MAX \\
\hline
{\em -\/1} & when max\+Size is smaller than the size of the Key\textquotesingle{}s basename\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\+Base\+Name()}} for getting a pointer to the Key\textquotesingle{}s basename 

\mbox{\hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{key\+Get\+Base\+Name\+Size()}} for getting the size of a Key\textquotesingle{}s basename 

\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}}, \mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}} for getting a pointer / copy of the whole name 

\mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} for setting a Key\textquotesingle{}s name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}\label{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyGetBaseNameSize@{keyGetBaseNameSize}}
\index{keyGetBaseNameSize@{keyGetBaseNameSize}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetBaseNameSize()}{keyGetBaseNameSize()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Base\+Name\+Size (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Calculates number of bytes needed to store basename of {\ttfamily key} (including NULL terminator). 

Key names consisting of only root names (e.\+g. {\ttfamily \char`\"{}system\+:/\char`\"{}} or {\ttfamily \char`\"{}user\+:/\char`\"{}} or {\ttfamily \char`\"{}user\+:domain\char`\"{}} ) do not have basenames. In this case the function will return 1, because only a NULL terminator is needed for storage.

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 to get the size of the basename from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
size in bytes of the Key\textquotesingle{}s basename including NULL terminator 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if the Key\textquotesingle{}s basename is NULL\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{key\+Base\+Name()}} for getting a pointer to a Key\textquotesingle{}s basename 

\mbox{\hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\+Get\+Base\+Name()}} for getting a copy of a Key\textquotesingle{}s basename 

\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}}, \mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}} for getting a pointer / copy of the whole name 

\mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} for setting a Key\textquotesingle{}s name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}\label{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyGetName@{keyGetName}}
\index{keyGetName@{keyGetName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetName()}{keyGetName()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Name (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{char $\ast$}]{returned\+Name,  }\item[{size\+\_\+t}]{max\+Size }\end{DoxyParamCaption})}



Get abbreviated Key name (excluding owner). 

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

{\ttfamily max\+Size} is limited to SSIZE\+\_\+\+MAX. 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. \mbox{\hyperlink{internal_8c_a35cdc2e5caed3454cb73b4fc7f37858c}{elektra\+Malloc()}} is not as failure tolerant and would try to allocate memory accordingly.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{char} *getBack = \mbox{\hyperlink{internal_8c_a35cdc2e5caed3454cb73b4fc7f37858c}{elektraMalloc}} (\mbox{\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize}}(key));}
\DoxyCodeLine{\mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName}}(key, getBack, \mbox{\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize}}(key));}

\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em key} & the Key to get the name from \\
\hline
{\em returned\+Name} & pre-\/allocated buffer to write the Key\textquotesingle{}s name \\
\hline
{\em max\+Size} & maximum number of bytes that will fit in returned\+Name, including the NULL terminator\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes written to {\ttfamily returned\+Name} 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 1} & when only NULL terminator was written \\
\hline
{\em -\/1} & when Key\textquotesingle{}s name is longer than max\+Size or max\+Size is 0 or max\+Size is greater than SSIZE\+\_\+\+MAX \\
\hline
{\em -\/1} & {\ttfamily key} or {\ttfamily returned\+Name} is NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\+Get\+Name\+Size()}} for getting the size of a Key\textquotesingle{}s name 

\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}} for getting a pointer to a Key\textquotesingle{}s name 

\mbox{\hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{key\+Get\+Base\+Name()}} for getting a Key\textquotesingle{}s base name 

\mbox{\hyperlink{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{key\+Get\+Namespace()}} for getting the namespace of a Key\textquotesingle{}s name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}\label{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyGetNameSize@{keyGetNameSize}}
\index{keyGetNameSize@{keyGetNameSize}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetNameSize()}{keyGetNameSize()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Name\+Size (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Bytes needed to store the Key\textquotesingle{}s name (excluding owner). 

For an empty Key name you need one byte to store the ending NULL. For that reason, 1 is returned when the name is empty.


\begin{DoxyParams}{Parameters}
{\em key} & the Key to get the name size from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes needed, including NULL terminator, to store Key\textquotesingle{}s name (excluding owner) 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 1} & if Key has no name \\
\hline
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}} for getting the Key\textquotesingle{}s name 

\mbox{\hyperlink{group__keyname_ga5e7eff0c77678420199d0d2e8729152b}{key\+Get\+Unescaped\+Name\+Size()}} for getting the size of the unescaped name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}\label{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyGetNamespace@{keyGetNamespace}}
\index{keyGetNamespace@{keyGetNamespace}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetNamespace()}{keyGetNamespace()}}
{\footnotesize\ttfamily \mbox{\hyperlink{group__key_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\+Namespace}} key\+Get\+Namespace (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns the \mbox{\hyperlink{group__key_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\+Namespace}} for a Key. 

To handle every namespace a Key could have, you can use the following snippet\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordflow}{switch} (\mbox{\hyperlink{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{keyGetNamespace}} (k))}
\DoxyCodeLine{\{}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68a2be047b124b1ca0e92b5ef124169f0d2}{KEY\_NS\_SPEC}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}spec namespace\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68a470ecc9254fcdfccf9923a3e526c9c11}{KEY\_NS\_PROC}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}proc namespace\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68aa0006cf27dbb2586bafba6ff1ae4f4ec}{KEY\_NS\_DIR}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}dir namespace\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68a8ce23c70010e8ac8bb540b0947e03a4e}{KEY\_NS\_USER}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}user namespace\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68a61adca2f9dff47e65dfcdb492ffa7a20}{KEY\_NS\_SYSTEM}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}system namespace\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68a3659698b0a07454ca8055ab693e8efd1}{KEY\_NS\_NONE}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}no key\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68ac5fbf2c3a7ae79fa2d60c48ae3e72688}{KEY\_NS\_META}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}metakey\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\textcolor{keywordflow}{case} \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68a2c9133e3095dccbcde5ca3bb13987b5d}{KEY\_NS\_CASCADING}}:}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}cascading key\(\backslash\)n"{}});}
\DoxyCodeLine{        \textcolor{keywordflow}{break};}
\DoxyCodeLine{\}}

\end{DoxyCodeInclude}
 To loop over all valid namespaces use\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordflow}{for} (\mbox{\hyperlink{group__key_gaec3b8d6f430ae49b91bafe8a86310a68}{elektraNamespace}} ns = KEY\_NS\_FIRST; ns <= KEY\_NS\_LAST; ++ns)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \textcolor{comment}{// work with namespace}}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}\%d\(\backslash\)n"{}}, ns);}
\DoxyCodeLine{\}}

\end{DoxyCodeInclude}
 \begin{DoxyNote}{Note}
This method might be extended. There is no guarantee that a Key with a specific namespace will retain that namespace after recompilation. 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 when recompiling.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the Key to get the namespace from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the namespace of the Key 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em KEY\+\_\+\+NS\+\_\+\+NONE} & if Key is NULL\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga98c1c1307419e689c98e556e5c542073}{key\+Set\+Namespace()}} for setting a Key\textquotesingle{}s namespace 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga44a576c7919d5b03f28d3ed3afaa7cd1}\label{group__keyname_ga44a576c7919d5b03f28d3ed3afaa7cd1}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyGetUnescapedName@{keyGetUnescapedName}}
\index{keyGetUnescapedName@{keyGetUnescapedName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetUnescapedName()}{keyGetUnescapedName()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Unescaped\+Name (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{char $\ast$}]{returned\+Name,  }\item[{size\+\_\+t}]{max\+Size }\end{DoxyParamCaption})}



Copies the unescaped name of a Key into {\ttfamily returned\+Name}. 

It will only copy the whole name. If the buffer is too small, an error code will be returned.

To ensure the buffer is big enough, you can use \mbox{\hyperlink{group__keyname_ga5e7eff0c77678420199d0d2e8729152b}{key\+Get\+Unescaped\+Name\+Size()}} to get the correct size.


\begin{DoxyParams}{Parameters}
{\em key} & the Key to extract the unescaped name from \\
\hline
{\em returned\+Name} & the buffer to write the unescaped name into \\
\hline
{\em max\+Size} & maximum number of bytes that can be copied into {\ttfamily returned\+Name} \\
\hline
\end{DoxyParams}
\begin{DoxyPrecond}{Precondition}
{\ttfamily key} MUST be a valid \#\+Key and {\ttfamily key != NULL} 

{\ttfamily returned\+Name} MUST be allocated to be at least {\ttfamily max\+Size} bytes big 

{\ttfamily returned\+Name} must not be NULL
\end{DoxyPrecond}
\begin{DoxyReturn}{Returns}
the actual size of the Key\textquotesingle{}s unescaped name, i.\+e. the number of bytes copied into {\ttfamily returned\+Name} 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & Precondition error \\
\hline
{\em -\/2} & the size of the unescaped name is greater than {\ttfamily max\+Size} \\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga5e7eff0c77678420199d0d2e8729152b}{key\+Get\+Unescaped\+Name\+Size()}} for getting the size of the unescaped name 

\mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}} for getting the Key\textquotesingle{}s escaped name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga5e7eff0c77678420199d0d2e8729152b}\label{group__keyname_ga5e7eff0c77678420199d0d2e8729152b}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyGetUnescapedNameSize@{keyGetUnescapedNameSize}}
\index{keyGetUnescapedNameSize@{keyGetUnescapedNameSize}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyGetUnescapedNameSize()}{keyGetUnescapedNameSize()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Get\+Unescaped\+Name\+Size (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns the size of the Key\textquotesingle{}s unescaped name including embedded and terminating NULL characters. 


\begin{DoxyParams}{Parameters}
{\em key} & the Key where to get the size of the unescaped name from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The size of the Key\textquotesingle{}s unescaped name 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on NULL pointer \\
\hline
{\em 0} & if Key has no name\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga6fe6af4c27b35d911a533f4ae4d698bb}{key\+Unescaped\+Name()}} for getting a pointer to the unescaped name 

\mbox{\hyperlink{group__keyname_ga44a576c7919d5b03f28d3ed3afaa7cd1}{key\+Get\+Unescaped\+Name()}} for getting a copy of the unescaped name 

\mbox{\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\+Get\+Name\+Size()}} for getting the size of the escaped name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga8e805c726a60da921d3736cda7813513}\label{group__keyname_ga8e805c726a60da921d3736cda7813513}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyName@{keyName}}
\index{keyName@{keyName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyName()}{keyName()}}
{\footnotesize\ttfamily const char$\ast$ key\+Name (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns a pointer to the abbreviated real internal {\ttfamily key} name. 

This is a much more efficient version of \mbox{\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 \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} and similar functions. If you need a copy of the name, consider using \mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}}.


\begin{DoxyRetVals}{Return values}
{\em \char`\"{}\char`\"{}} & when there is no key\+Name. The reason is 
\begin{DoxyCode}{1}
\DoxyCodeLine{key=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(0);}
\DoxyCodeLine{\mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}}(key,\textcolor{stringliteral}{"{}"{}});}
\DoxyCodeLine{\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}}(key); \textcolor{comment}{// you would expect "{}"{} here}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}}(key);}

\end{DoxyCode}
\\
\hline
\end{DoxyRetVals}
Valid key names are\+:


\begin{DoxyItemize}
\item {\ttfamily spec\+:/something} for specification of other keys.
\item {\ttfamily proc\+:/something} for in-\/memory keys, e.\+g. commandline.
\item {\ttfamily dir\+:/something} for dir keys in current working directory
\item {\ttfamily system\+:/something} for system keys in /etc or /
\item {\ttfamily user\+:/something} for user keys in home directory
\item {\ttfamily user\+:username/something} for other users (deprecated\+: \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} + \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} currently unsupported)
\item {\ttfamily /something} for cascading keys (actually refers to one of the above, see also \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}})

\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 \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}} method to set a new value. Use \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} instead.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em key} & the Key you want to get the name from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to the Key\textquotesingle{}s name which must not be changed. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em \char`\"{}\char`\"{}} & when Key\textquotesingle{}s name is empty \\
\hline
{\em 0} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{key\+Get\+Name\+Size()}} for the string length 

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

\mbox{\hyperlink{group__keyname_ga6fe6af4c27b35d911a533f4ae4d698bb}{key\+Unescaped\+Name}} to get an unescaped \mbox{\hyperlink{group__key}{Key}} name 
\end{DoxySeeAlso}

\end{DoxyItemize}\mbox{\Hypertarget{group__keyname_gae22037aad3f76f4454de4e6400637b39}\label{group__keyname_gae22037aad3f76f4454de4e6400637b39}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyReplacePrefix@{keyReplacePrefix}}
\index{keyReplacePrefix@{keyReplacePrefix}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyReplacePrefix()}{keyReplacePrefix()}}
{\footnotesize\ttfamily int key\+Replace\+Prefix (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const Key $\ast$}]{old\+Prefix,  }\item[{const Key $\ast$}]{new\+Prefix }\end{DoxyParamCaption})}



Replaces a prefix of the key name of {\ttfamily key}. 

The function only modifies {\ttfamily key}, if is is below (or same as) {\ttfamily old\+Prefix} (see \mbox{\hyperlink{keytest_8c_a6250a0bad75aa9abb20a98e69ad2d299}{key\+Is\+Below\+Or\+Same()}}) and they both have the same namespace (this is not always the case with \mbox{\hyperlink{keytest_8c_a6250a0bad75aa9abb20a98e69ad2d299}{key\+Is\+Below\+Or\+Same()}}).

In simple terms this function operates as follows\+:
\begin{DoxyEnumerate}
\item If before calling this function {\ttfamily key} and {\ttfamily old\+Prefix} had the same name, then afterwards {\ttfamily key} will have the same name as {\ttfamily new\+Prefix}.
\item If {\ttfamily key} was in the same namespace as and below {\ttfamily old\+Prefix}, then after calling this function {\ttfamily key} will be in the same namespace as and below {\ttfamily new\+Prefix}.
\item Otherwise {\ttfamily key} will not be modified.
\end{DoxyEnumerate}

Note\+: We use {\ttfamily const Key $\ast$} arguments for the prefixes instead of {\ttfamily const char $\ast$} to ensure only valid key names can be passed as arguments.


\begin{DoxyParams}{Parameters}
{\em key} & The key that will be manipulated. \\
\hline
{\em old\+Prefix} & The name of this key will be removed from the front of the name of {\ttfamily key}. \\
\hline
{\em new\+Prefix} & The name of this key will be added to the front of {\ttfamily key}, after the name of {\ttfamily old\+Prefix} is removed.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if {\ttfamily key}, {\ttfamily old\+Prefix} or {\ttfamily new\+Prefix} are NULL or the name of {\ttfamily key} is marked as read-\/only \\
\hline
{\em 0} & if {\ttfamily key} is not below (or same as) {\ttfamily old\+Prefix}, i.\+e. there is no prefix to replace \\
\hline
{\em 1} & if the prefix was sucessfully replaced \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}\label{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keySetBaseName@{keySetBaseName}}
\index{keySetBaseName@{keySetBaseName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keySetBaseName()}{keySetBaseName()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Set\+Base\+Name (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const char $\ast$}]{base\+Name }\end{DoxyParamCaption})}



Sets {\ttfamily base\+Name} as the new basename for {\ttfamily key}. 

Only the basename of the Key will be affected.

A simple example is\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key * k = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/my/long/name"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName}} (k, \textcolor{stringliteral}{"{}myname"{}});}
\DoxyCodeLine{printf (\textcolor{stringliteral}{"{}\%s\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (k)); \textcolor{comment}{// will print user:/my/long/myname}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 All text after the last {\ttfamily \textquotesingle{}/\textquotesingle{}} in the Key\textquotesingle{}s name is erased and {\ttfamily base\+Name} is appended. If {\ttfamily base\+Name} is 0 (NULL), then the last part of the Key\textquotesingle{}s name is removed without replacement. The root name of the Key will not be removed though.

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 0 (NULL), the resulting key name will be {\ttfamily \char`\"{}system\+:/dir1/dir2\char`\"{}}. If {\ttfamily base\+Name} is empty, the resulting key name will be {\ttfamily \char`\"{}system\+:/dir1/dir2/\%\char`\"{}}, where {\ttfamily \char`\"{}\%\char`\"{}} denotes an empty base name, as also shown in the following code\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName}} (k, \textcolor{stringliteral}{"{}system:/valid"{}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName}} (k, \textcolor{stringliteral}{"{}"{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (k), \textcolor{stringliteral}{"{}system:/\%"{}});}
\DoxyCodeLine{        succeed\_if\_same\_string (\mbox{\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName}} (k), \textcolor{stringliteral}{"{}"{}});}

\end{DoxyCodeInclude}
 \mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name()}} does proper escaping on the supplied name argument.

You can use character sequences as {\ttfamily base\+Name} (e.\+g. {\ttfamily \char`\"{}.\char`\"{}} (dot), {\ttfamily \char`\"{}..\char`\"{}} (dot-\/dot), {\ttfamily \char`\"{}\%\char`\"{}} (empty basename)). They will be properly escaped and will not have their usual meaning.

If you want to add to the basename instead of changing it, use \mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\+Add\+Base\+Name()}}. If you do not want any escaping, use \mbox{\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{key\+Add\+Name()}}.


\begin{DoxyParams}{Parameters}
{\em key} & the Key whose basename to set \\
\hline
{\em base\+Name} & the new basename for the Key\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size in bytes of the new key name 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on NULL pointers \\
\hline
{\em -\/1} & if Key was inserted into Key\+Set before \\
\hline
{\em -\/1} & if Key is read-\/only \\
\hline
{\em -\/1} & on allocation errors\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\+Add\+Base\+Name()}} for adding a basename instead of changing it 

\mbox{\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{key\+Add\+Name()}} for adding a name without escaping 

\mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} for setting a completely new name 

\mbox{\hyperlink{group__keyname}{Name Manipulation Methods}} for more details on special names 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}\label{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keySetName@{keySetName}}
\index{keySetName@{keySetName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keySetName()}{keySetName()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Set\+Name (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{const char $\ast$}]{new\+Name }\end{DoxyParamCaption})}



Set a new name to a Key. 

A valid name is one of the forms\+:
\begin{DoxyItemize}
\item {\ttfamily spec\+:/something} for specification of other keys.
\item {\ttfamily proc\+:/something} for in-\/memory keys, e.\+g. commandline.
\item {\ttfamily dir\+:/something} for dir keys in current working directory
\item {\ttfamily system\+:/something} for system keys in /etc or /
\item {\ttfamily user\+:/something} for user keys in home directory
\item {\ttfamily user\+:username/something} for other users (deprecated\+: \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} + \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} currently unsupported)
\item {\ttfamily /something} for cascading keys (actually refers to one of the above, see also \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}})
\end{DoxyItemize}

An invalid name either has an invalid namespace or a wrongly escaped \textbackslash{} at the end of the name.

See \mbox{\hyperlink{group__keyname}{key names }} for the exact rules.

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 paths. 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, NULL or \char`\"{}\char`\"{} the name will be \char`\"{}\char`\"{} afterwards.

\begin{DoxyReturn}{Returns}
size of the new Key name in bytes, including NULL terminator 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if {\ttfamily key} or {\ttfamily key\+Name} is NULL or {\ttfamily key\+Name} is empty or invalid \\
\hline
{\em -\/1} & if Key was inserted to a Key\+Set before \\
\hline
{\em -\/1} & if Key name is read-\/only\\
\hline
\end{DoxyRetVals}

\begin{DoxyParams}{Parameters}
{\em key} & the Key whose name to set \\
\hline
{\em new\+Name} & the new name for the Key\\
\hline
\end{DoxyParams}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}} for getting a copy of the Key\textquotesingle{}s name 

\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}} for getting a pointer to the Key\textquotesingle{}s name 

\mbox{\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{key\+Set\+Base\+Name()}}, \mbox{\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{key\+Add\+Base\+Name()}} for manipulating the base name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga98c1c1307419e689c98e556e5c542073}\label{group__keyname_ga98c1c1307419e689c98e556e5c542073}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keySetNamespace@{keySetNamespace}}
\index{keySetNamespace@{keySetNamespace}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keySetNamespace()}{keySetNamespace()}}
{\footnotesize\ttfamily ssize\+\_\+t key\+Set\+Namespace (\begin{DoxyParamCaption}\item[{Key $\ast$}]{key,  }\item[{\mbox{\hyperlink{group__key_gaec3b8d6f430ae49b91bafe8a86310a68}{elektra\+Namespace}}}]{ns }\end{DoxyParamCaption})}



Changes the namespace of a Key. 

The rest of the Key\textquotesingle{}s name remains unchanged.

\begin{DoxyPrecond}{Precondition}
{\ttfamily ns} MUST be a valid namespace and not \mbox{\hyperlink{group__key_ggaec3b8d6f430ae49b91bafe8a86310a68a3659698b0a07454ca8055ab693e8efd1}{KEY\+\_\+\+NS\+\_\+\+NONE}} 

{\ttfamily key} MUST be a valid \#\+Key, especially {\ttfamily key != NULL}
\end{DoxyPrecond}

\begin{DoxyParams}{Parameters}
{\em key} & The \#\+Key whose namespace will be changed \\
\hline
{\em ns} & The new namespace of for {\ttfamily key} \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the new size in bytes of the Key\textquotesingle{}s namespace 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & precondition error\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_gafc3ca03ed10f87eb59bdc02cf2a0de8d}{key\+Get\+Namespace()}} for getting a Key\textquotesingle{}s namespace 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyname_ga6fe6af4c27b35d911a533f4ae4d698bb}\label{group__keyname_ga6fe6af4c27b35d911a533f4ae4d698bb}} 
\index{Name Manipulation Methods@{Name Manipulation Methods}!keyUnescapedName@{keyUnescapedName}}
\index{keyUnescapedName@{keyUnescapedName}!Name Manipulation Methods@{Name Manipulation Methods}}
\doxysubsubsection{\texorpdfstring{keyUnescapedName()}{keyUnescapedName()}}
{\footnotesize\ttfamily const void$\ast$ key\+Unescaped\+Name (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Returns a Key\textquotesingle{}s name, separated by NULL bytes and without backslashes for escaping. 

Slashes are replaced with NULL bytes. Therefore unescaped names of cascading Keys start with a NULL byte. Otherwise escaped characters, e.\+g. non-\/hierarchy slashes, will be unescaped.

This name is essential if you want to iterate over parts of the Key\textquotesingle{}s name, compare Key names or check relations of Keys in the hierarchy.


\begin{DoxyParams}{Parameters}
{\em key} & the Key whose unescaped name to get\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the name in its unescaped form 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on NULL pointers \\
\hline
{\em \char`\"{}\char`\"{}} & if Key\textquotesingle{}s name is empty\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyname_ga44a576c7919d5b03f28d3ed3afaa7cd1}{key\+Get\+Unescaped\+Name()}} for getting a copy of the unescaped name 

\mbox{\hyperlink{group__keyname_ga5e7eff0c77678420199d0d2e8729152b}{key\+Get\+Unescaped\+Name\+Size()}} for getting the size of the unescaped name 

\mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}} for getting the escaped name of the Key 
\end{DoxySeeAlso}
