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


Methods to do various operations on Key names.  


\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
const char $\ast$ \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
ssize\_\-t \hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
ssize\_\-t \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName} (const \hyperlink{struct__Key}{Key} $\ast$key, char $\ast$returnedName, size\_\-t maxSize)
\item 
ssize\_\-t \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName} (\hyperlink{struct__Key}{Key} $\ast$key, const char $\ast$newName)
\item 
ssize\_\-t \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{keyGetFullNameSize} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
ssize\_\-t \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName} (const \hyperlink{struct__Key}{Key} $\ast$key, char $\ast$returnedName, size\_\-t maxSize)
\item 
const char $\ast$ \hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
ssize\_\-t \hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{keyGetBaseNameSize} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
ssize\_\-t \hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{keyGetBaseName} (const \hyperlink{struct__Key}{Key} $\ast$key, char $\ast$returned, size\_\-t maxSize)
\item 
ssize\_\-t \hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName} (\hyperlink{struct__Key}{Key} $\ast$key, const char $\ast$baseName)
\item 
ssize\_\-t \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName} (\hyperlink{struct__Key}{Key} $\ast$key, const char $\ast$baseName)
\item 
const char $\ast$ \hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{keyOwner} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
ssize\_\-t \hyperlink{group__keyname_ga4a4561895741ba2ad10acf007c188593}{keyGetOwnerSize} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
ssize\_\-t \hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{keyGetOwner} (const \hyperlink{struct__Key}{Key} $\ast$key, char $\ast$returnedOwner, size\_\-t maxSize)
\item 
ssize\_\-t \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner} (\hyperlink{struct__Key}{Key} $\ast$key, const char $\ast$newOwner)
\end{DoxyCompactItemize}


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


These functions make it easier for c programmers to work with key names. Everything here can also be done with keySetName, described in key.

\begin{DoxyParagraph}{Rules for Key Names}

\end{DoxyParagraph}
When using Elektra to store your application's configuration and state, please keep in mind the following rules:
\begin{DoxyItemize}
\item You are not allowed to create keys right under {\ttfamily system} or {\ttfamily user}.
\item You are not allowed to create folder keys right under {\ttfamily system} or {\ttfamily user}. They are reserved for very essential OS subsystems.
\item The keys for your application, called say {\itshape MyApp\/}, should be created under {\ttfamily system/sw/MyApp} and/or {\ttfamily user/sw/MyApp}.
\item It is suggested to make your application look for default keys under {\ttfamily system/sw/MyApp/current} and/or {\ttfamily user/sw/MyApp/current}. This way, from a sysadmin perspective, it will be possible to copy the {\ttfamily system/sw/MyApp/current} tree to something like {\ttfamily system/sw/MyApp/old}, and keep system clean and organized.
\item $\backslash$0 must not occur in names.
\item / is the seperator. 
\end{DoxyItemize}

\subsection{Function Documentation}
\hypertarget{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{
\index{keyname@{keyname}!keyAddBaseName@{keyAddBaseName}}
\index{keyAddBaseName@{keyAddBaseName}!keyname@{keyname}}
\subsubsection[{keyAddBaseName}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyAddBaseName (
\begin{DoxyParamCaption}
\item[{{\bf Key} $\ast$}]{ key, }
\item[{const char $\ast$}]{ baseName}
\end{DoxyParamCaption}
)}}
\label{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}
Adds {\ttfamily baseName} to the current key name.

Assumes that {\ttfamily key} is a directory. {\ttfamily baseName} is appended to it. The function adds {\ttfamily '/'} if needed while concatenating.

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

When baseName is 0 or \char`\"{}\char`\"{} nothing will happen and the size of the name is returned.

\begin{DoxyWarning}{Warning}
You should not change a keys name once it belongs to a keyset. See ksSort() for more information.
\end{DoxyWarning}
TODO: does not recognice .. and . in the string!


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \item[{\em baseName}]the string to append to the name \end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size in bytes of the new key name including the ending NULL 

-\/1 if the key had no name 

-\/1 on NULL pointers 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName()} 

\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()} to set a new name. 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{
\index{keyname@{keyname}!keyBaseName@{keyBaseName}}
\index{keyBaseName@{keyBaseName}!keyname@{keyname}}
\subsubsection[{keyBaseName}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ keyBaseName (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}
Returns a pointer to the real internal key name where the {\ttfamily basename} starts.

This is a much more efficient version of \hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{keyGetBaseName()} 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}{keySetName()}. If you need a copy of the basename consider to use \hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{keyGetBaseName()}.

\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName()} returns \char`\"{}\char`\"{} when there is no keyBaseName. The reason is 
\begin{DoxyCode}
key=keyNew(0);
keySetName(key,"");
keyName(key); // you would expect "" here
keySetName(key,"user");
keyName(key); // you would expect "" here
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_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName()} method to set a new value. Use \hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName()} instead.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the object to obtain the basename from \end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to the basename 

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

0 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{keyGetBaseName()}, \hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{keyGetBaseNameSize()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()} to get a pointer to the name 

\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{keyOwner()} to get a pointer to the owner 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{
\index{keyname@{keyname}!keyGetBaseName@{keyGetBaseName}}
\index{keyGetBaseName@{keyGetBaseName}!keyname@{keyname}}
\subsubsection[{keyGetBaseName}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetBaseName (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key, }
\item[{char $\ast$}]{ returned, }
\item[{size\_\-t}]{ maxSize}
\end{DoxyParamCaption}
)}}
\label{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}
Calculate the basename of a key name and put it in {\ttfamily returned} finalizing the string with NULL.

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}
\item[{\em key}]the key to extract basename from \item[{\em returned}]a pre-\/allocated buffer to store the basename \item[{\em maxSize}]size of the {\ttfamily returned} buffer \end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes copied to {\ttfamily returned} 

1 on empty name 

-\/1 on NULL pointers 

-\/1 when maxSize is 0 or larger than SSIZE\_\-MAX 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName()}, \hyperlink{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{keyGetBaseNameSize()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()}, \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()}, \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga1a0b76c5d9e5367c7e72211e6c63d43a}{
\index{keyname@{keyname}!keyGetBaseNameSize@{keyGetBaseNameSize}}
\index{keyGetBaseNameSize@{keyGetBaseNameSize}!keyname@{keyname}}
\subsubsection[{keyGetBaseNameSize}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetBaseNameSize (
\begin{DoxyParamCaption}
\item[{const {\bf 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$\backslash$/name} $>$ {\ttfamily base$\backslash$/name} 
\end{DoxyItemize}


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
size in bytes of {\ttfamily key's} basename including ending NULL 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_gaaff35e7ca8af5560c47e662ceb9465f5}{keyBaseName()}, \hyperlink{group__keyname_ga0992d26bcfca767cb8e77053a483eb64}{keyGetBaseName()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()}, \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()}, \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{
\index{keyname@{keyname}!keyGetFullName@{keyGetFullName}}
\index{keyGetFullName@{keyGetFullName}!keyname@{keyname}}
\subsubsection[{keyGetFullName}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetFullName (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key, }
\item[{char $\ast$}]{ returnedName, }
\item[{size\_\-t}]{ maxSize}
\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 NULL pointers 

-\/1 if maxSize is 0 or larger than SSIZE\_\-MAX 
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object \item[{\em returnedName}]pre-\/allocated memory to write the key name \item[{\em maxSize}]maximum number of bytes that will fit in returnedName, including the final NULL \end{DoxyParams}
\hypertarget{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{
\index{keyname@{keyname}!keyGetFullNameSize@{keyGetFullNameSize}}
\index{keyGetFullNameSize@{keyGetFullNameSize}!keyname@{keyname}}
\subsubsection[{keyGetFullNameSize}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetFullNameSize (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}
Bytes needed to store the key name including user domain and ending NULL.


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

1 on empty name 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()}, \hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{
\index{keyname@{keyname}!keyGetName@{keyGetName}}
\index{keyGetName@{keyGetName}!keyname@{keyname}}
\subsubsection[{keyGetName}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetName (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key, }
\item[{char $\ast$}]{ returnedName, }
\item[{size\_\-t}]{ maxSize}
\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.

maxSize 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. Of course malloc is not as failure tolerant and will try to allocate.


\begin{DoxyCode}
char *getBack = malloc (keyGetNameSize(key));
keyGetName(key, getBack, keyGetNameSize(key));
\end{DoxyCode}


\begin{DoxyReturn}{Returns}
number of bytes written to {\ttfamily returnedName} 

1 when only a null was written 

-\/1 when keyname is longer then maxSize or 0 or any NULL pointer 
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \item[{\em returnedName}]pre-\/allocated memory to write the key name \item[{\em maxSize}]maximum number of bytes that will fit in returnedName, including the final NULL \end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()}, \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{keyGetFullNameSize()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{
\index{keyname@{keyname}!keyGetNameSize@{keyGetNameSize}}
\index{keyGetNameSize@{keyGetNameSize}!keyname@{keyname}}
\subsubsection[{keyGetNameSize}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetNameSize (
\begin{DoxyParamCaption}
\item[{const {\bf 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 NULL. For that reason 1 is returned.


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes needed, including ending NULL, to store key name without owner 

1 if there is is no key Name 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()}, \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{keyGetFullNameSize()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{
\index{keyname@{keyname}!keyGetOwner@{keyGetOwner}}
\index{keyGetOwner@{keyGetOwner}!keyname@{keyname}}
\subsubsection[{keyGetOwner}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetOwner (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key, }
\item[{char $\ast$}]{ returnedOwner, }
\item[{size\_\-t}]{ maxSize}
\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 UID. Owner are related to WHERE the key is stored on disk, while UIDs are related to mode controls of a key.


\begin{DoxyParams}{Parameters}
\item[{\em key}]the object to work with \item[{\em returnedOwner}]a pre-\/allocated space to store the owner \item[{\em maxSize}]maximum number of bytes that fit returned \end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes written to buffer 

1 if there is no owner 

-\/1 on NULL pointers 

-\/1 when maxSize is 0, larger than SSIZE\_\-MAX or too small for ownername 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()}, \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner()}, \hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{keyOwner()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga4a4561895741ba2ad10acf007c188593}{
\index{keyname@{keyname}!keyGetOwnerSize@{keyGetOwnerSize}}
\index{keyGetOwnerSize@{keyGetOwnerSize}!keyname@{keyname}}
\subsubsection[{keyGetOwnerSize}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetOwnerSize (
\begin{DoxyParamCaption}
\item[{const {\bf 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}{keyGetOwner()}.


\begin{DoxyCode}
char * buffer;
buffer = malloc (keyGetOwnerSize (key));
// 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}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes 

1 if there is no owner 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{keyGetOwner()} 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga8e805c726a60da921d3736cda7813513}{
\index{keyname@{keyname}!keyName@{keyName}}
\index{keyName@{keyName}!keyname@{keyname}}
\subsubsection[{keyName}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ keyName (
\begin{DoxyParamCaption}
\item[{const {\bf 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}{keyGetName()} 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}{keySetName()} and similar functions. If you need a copy of the name, consider using \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()}.

The name will be without owner, see \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()} if you need the name with its owner.

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

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \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 NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_gabdbcfa51ed8a387e47ead207affa2d2e}{keyGetNameSize()} for the string length 

\hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()}, \hyperlink{group__keyname_gab65dc9d43d3ee08d5e936a20ebbddd23}{keyGetFullNameSize()} to get the full name 

\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()} as alternative to get a copy 

\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{keyOwner()} to get a pointer to owner 
\end{DoxySeeAlso}
\hypertarget{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{
\index{keyname@{keyname}!keyOwner@{keyOwner}}
\index{keyOwner@{keyOwner}!keyname@{keyname}}
\subsubsection[{keyOwner}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ keyOwner (
\begin{DoxyParamCaption}
\item[{const {\bf 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}{keyGetOwner()} 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}{keyGetOwner()} instead.

\hyperlink{group__keyname_gaf6485fb8599714b6bbd830cf915ffea5}{keyOwner()} returns \char`\"{}\char`\"{} when there is no keyOwner. The reason is 
\begin{DoxyCode}
key=keyNew(0);
keySetOwner(key,"");
keyOwner(key); // you would expect "" here
keySetOwner(key,"system");
keyOwner(key); // 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}{keyOwner()} method to set a new value. Use \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner()} instead.
\end{DoxyNote}

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

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

0 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga4a4561895741ba2ad10acf007c188593}{keyGetOwnerSize()} for the size of the string with concluding 0 

\hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{keyGetOwner()}, \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner()} 

\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()} for name without owner 

\hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()} for name with owner 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{
\index{keyname@{keyname}!keySetBaseName@{keySetBaseName}}
\index{keySetBaseName@{keySetBaseName}!keyname@{keyname}}
\subsubsection[{keySetBaseName}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetBaseName (
\begin{DoxyParamCaption}
\item[{{\bf Key} $\ast$}]{ key, }
\item[{const char $\ast$}]{ baseName}
\end{DoxyParamCaption}
)}}
\label{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}
Sets {\ttfamily baseName} as the new basename for {\ttfamily key}.

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

So lets suppose {\ttfamily key} has name {\ttfamily \char`\"{}system/dir1/dir2/key1\char`\"{}}. If {\ttfamily baseName} is {\ttfamily \char`\"{}key2\char`\"{}}, the resulting key name will be {\ttfamily \char`\"{}system/dir1/dir2/key2\char`\"{}}. If {\ttfamily baseName} is empty or NULL, the resulting key name will be {\ttfamily \char`\"{}system/dir1/dir2\char`\"{}}.

\begin{DoxyWarning}{Warning}
You should not change a keys name once it belongs to a keyset. See ksSort() for more information.
\end{DoxyWarning}
TODO: does not work with .. and .


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \item[{\em baseName}]the string used to overwrite the basename of the key \end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size in bytes of the new key name 

-\/1 on NULL pointers 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName()} 

\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()} to set a new name 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{
\index{keyname@{keyname}!keySetName@{keySetName}}
\index{keySetName@{keySetName}!keyname@{keyname}}
\subsubsection[{keySetName}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetName (
\begin{DoxyParamCaption}
\item[{{\bf Key} $\ast$}]{ key, }
\item[{const char $\ast$}]{ newName}
\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 not defined (the second form) current user is calculated and used as default.

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

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

.., . and / will be handled correctly. A valid name will be build out of the (valid) name what you pass, e.g. user///sw/../sw//././MyApp -\/$>$ user/sw/MyApp

On invalid names, NULL or \char`\"{}\char`\"{} the name will be \char`\"{}\char`\"{} afterwards.

\begin{DoxyWarning}{Warning}
You should not change a keys name once it belongs to a keyset. See ksSort() for more information.
\end{DoxyWarning}
\begin{DoxyReturn}{Returns}
size in bytes of this new key name including ending NULL 

-\/1 if {\ttfamily newName} is empty or invalid or any NULL pointer 
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \item[{\em newName}]the new key name \end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__key_gaf6893c038b3ebee90c73a9ea8356bebf}{keyNew()}, \hyperlink{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{keySetOwner()} 

\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()}, \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()} 

\hyperlink{group__keyname_ga6e804bd453f98c28b0ff51430d1df407}{keySetBaseName()}, \hyperlink{group__keyname_gaa942091fc4bd5c2699e49ddc50829524}{keyAddBaseName()} to manipulate a name 
\end{DoxySeeAlso}
\hypertarget{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}{
\index{keyname@{keyname}!keySetOwner@{keySetOwner}}
\index{keySetOwner@{keySetOwner}!keyname@{keyname}}
\subsubsection[{keySetOwner}]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetOwner (
\begin{DoxyParamCaption}
\item[{{\bf Key} $\ast$}]{ key, }
\item[{const char $\ast$}]{ newOwner}
\end{DoxyParamCaption}
)}}
\label{group__keyname_ga88d6ec200ba0707b7c1b4a88133d2be4}
Set the owner of a key.

A owner is a name of a system user related to a UID. 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}
\item[{\em key}]the key object to work with \item[{\em newOwner}]the string which describes the owner of the key \end{DoxyParams}
\begin{DoxyReturn}{Returns}
the number of bytes actually saved including final NULL 

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}{keySetName()}, \hyperlink{group__keyname_ga35922a017bee8b4bcb493bbdfad9d6f5}{keyGetOwner()}, \hyperlink{group__keyname_gaaba1494a5ffc976e0e56c43f4334a23c}{keyGetFullName()} 
\end{DoxySeeAlso}
