doc/elektra-api/latex/group__keyname.tex

   1 \section{Key :: Name Manipulation Methods}
   2 \label{group__keyname}\index{Key :: Name Manipulation Methods@{Key :: Name Manipulation Methods}}
   3 Methods to do various operations on Key names.
   4 \subsection*{Functions}
   5 \begin{CompactItemize}
   6 \item
   7 const char $\ast$ {\bf keyName} (const Key $\ast$key)
   8 \item
   9 ssize\_\-t {\bf keyGetNameSize} (const Key $\ast$key)
  10 \item
  11 ssize\_\-t {\bf keyGetName} (const Key $\ast$key, char $\ast$returnedName, size\_\-t maxSize)
  12 \item
  13 ssize\_\-t {\bf keySetName} (Key $\ast$key, const char $\ast$newName)
  14 \item
  15 ssize\_\-t {\bf keyGetFullNameSize} (const Key $\ast$key)
  16 \item
  17 ssize\_\-t {\bf keyGetFullName} (const Key $\ast$key, char $\ast$returnedName, size\_\-t maxSize)
  18 \item
  19 const char $\ast$ {\bf keyBaseName} (const Key $\ast$key)
  20 \item
  21 ssize\_\-t {\bf keyGetBaseNameSize} (const Key $\ast$key)
  22 \item
  23 ssize\_\-t {\bf keyGetBaseName} (const Key $\ast$key, char $\ast$returned, size\_\-t maxSize)
  24 \item
  25 ssize\_\-t {\bf keyAddBaseName} (Key $\ast$key, const char $\ast$baseName)
  26 \item
  27 ssize\_\-t {\bf keySetBaseName} (Key $\ast$key, const char $\ast$baseName)
  28 \item
  29 const char $\ast$ {\bf keyOwner} (const Key $\ast$key)
  30 \item
  31 ssize\_\-t {\bf keyGetOwnerSize} (const Key $\ast$key)
  32 \item
  33 ssize\_\-t {\bf keyGetOwner} (const Key $\ast$key, char $\ast$returned, size\_\-t maxSize)
  34 \item
  35 ssize\_\-t {\bf keySetOwner} (Key $\ast$key, const char $\ast$owner)
  36 \end{CompactItemize}
  37
  38
  39 \subsection{Detailed Description}
  40 Methods to do various operations on Key names.
  41
  42 To use them:
  43
  44 \begin{Code}\begin{verbatim}#include <kdb.h>
  45 \end{verbatim}
  46 \end{Code}
  47
  48
  49
  50 These functions make it easier for c programmers to work with key names. Everything here can also be done with keySetName, described in key.
  51
  52 \begin{Desc}
  53 \item[Rules for Key Names]\end{Desc}
  54 When using Elektra to store your application's configuration and state, please keep in mind the following rules:\begin{itemize}
  55 \item You are not allowed to create keys right under {\tt system} or {\tt user}.\item You are not allowed to create folder keys right under {\tt system} or {\tt user}. They are reserved for very essential OS subsystems.\item The keys for your application, called say {\em MyApp\/}, should be created under {\tt system/sw/MyApp} and/or {\tt user/sw/MyApp}.\item It is suggested to make your application look for default keys under {\tt system/sw/MyApp/current} and/or {\tt user/sw/MyApp/current}. This way, from a sysadmin perspective, it will be possible to copy the {\tt system/sw/MyApp/current} tree to something like {\tt system/sw/MyApp/old}, and keep system clean and organized.\item $\backslash$0 must not occur in names.\item / is the seperator. \end{itemize}
  56
  57
  58 \subsection{Function Documentation}
  59 \index{keyname@{keyname}!keyAddBaseName@{keyAddBaseName}}
  60 \index{keyAddBaseName@{keyAddBaseName}!keyname@{keyname}}
  61 \subsubsection[keyAddBaseName]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyAddBaseName (Key $\ast$ {\em key}, \/  const char $\ast$ {\em baseName})}\label{group__keyname_ga942091fc4bd5c2699e49ddc50829524}
  62
  63
  64 Adds {\tt baseName} to the current key name.
  65
  66 Assumes that {\tt key} is a directory. {\tt baseName} is appended to it. The function adds {\tt '/'} if needed while concatenating.
  67
  68 So if {\tt key} has name {\tt \char`\"{}system/dir1/dir2\char`\"{}} and this method is called with {\tt baseName} {\tt \char`\"{}mykey\char`\"{}}, the resulting key will have name {\tt \char`\"{}system/dir1/dir2/mykey\char`\"{}}.
  69
  70 When baseName is 0 or \char`\"{}\char`\"{} nothing will happen and the size of the name is returned.
  71
  72 \begin{Desc}
  73 \item[Warning:]You should not change a keys name once it belongs to a keyset. See \doxyref{ksSort()}{p.}{group__keyset_g023554d395ccf2319a3807b8b5d2530c} for more information.\end{Desc}
  74 \begin{Desc}
  75 \item[Parameters:]
  76 \begin{description}
  77 \item[{\em key}]the key object to work with \item[{\em baseName}]the string to append to the name \end{description}
  78 \end{Desc}
  79 \begin{Desc}
  80 \item[Returns:]the size in bytes of the new key name including the ending NULL
  81
  82 -1 if the key had no name
  83
  84 -1 on NULL pointers \end{Desc}
  85 \begin{Desc}
  86 \item[See also:]\doxyref{keySetBaseName()}{p.}{group__keyname_g6e804bd453f98c28b0ff51430d1df407}
  87
  88 \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9} to set a new name. \end{Desc}
  89 \index{keyname@{keyname}!keyBaseName@{keyBaseName}}
  90 \index{keyBaseName@{keyBaseName}!keyname@{keyname}}
  91 \subsubsection[keyBaseName]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ keyBaseName (const Key $\ast$ {\em key})}\label{group__keyname_gaff35e7ca8af5560c47e662ceb9465f5}
  92
  93
  94 Returns a pointer to the real internal key name where the {\tt basename} starts.
  95
  96 This is a much more efficient version of \doxyref{keyGetBaseName()}{p.}{group__keyname_g0992d26bcfca767cb8e77053a483eb64} 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 \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9}. If you need a copy of the basename consider to use \doxyref{keyGetBaseName()}{p.}{group__keyname_g0992d26bcfca767cb8e77053a483eb64}.
  97
  98 \doxyref{keyBaseName()}{p.}{group__keyname_gaff35e7ca8af5560c47e662ceb9465f5} returns \char`\"{}\char`\"{} when there is no keyBaseName. The reason is
  99
 100 \begin{Code}\begin{verbatim}key=keyNew(0);
 101 keySetName(key,"");
 102 keyName(key); // you would expect "" here
 103 keySetName(key,"user");
 104 keyName(key); // you would expect "" here
 105 keyDel(key);
 106 \end{verbatim}
 107 \end{Code}
 108
 109
 110
 111 \begin{Desc}
 112 \item[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 \doxyref{keyBaseName()}{p.}{group__keyname_gaff35e7ca8af5560c47e662ceb9465f5} method to set a new value. Use \doxyref{keySetBaseName()}{p.}{group__keyname_g6e804bd453f98c28b0ff51430d1df407} instead.\end{Desc}
 113 \begin{Desc}
 114 \item[Parameters:]
 115 \begin{description}
 116 \item[{\em key}]the object to obtain the basename from \end{description}
 117 \end{Desc}
 118 \begin{Desc}
 119 \item[Returns:]a pointer to the basename
 120
 121 \char`\"{}\char`\"{} on null pointer or when the key has no name
 122
 123 0 on NULL pointer \end{Desc}
 124 \begin{Desc}
 125 \item[See also:]\doxyref{keyGetBaseName()}{p.}{group__keyname_g0992d26bcfca767cb8e77053a483eb64}, \doxyref{keyGetBaseNameSize()}{p.}{group__keyname_g1a0b76c5d9e5367c7e72211e6c63d43a}
 126
 127 \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513} to get a pointer to the name
 128
 129 \doxyref{keyOwner()}{p.}{group__keyname_gf6485fb8599714b6bbd830cf915ffea5} to get a pointer to the owner \end{Desc}
 130 \index{keyname@{keyname}!keyGetBaseName@{keyGetBaseName}}
 131 \index{keyGetBaseName@{keyGetBaseName}!keyname@{keyname}}
 132 \subsubsection[keyGetBaseName]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetBaseName (const Key $\ast$ {\em key}, \/  char $\ast$ {\em returned}, \/  size\_\-t {\em maxSize})}\label{group__keyname_g0992d26bcfca767cb8e77053a483eb64}
 133
 134
 135 Calculate the basename of a key name and put it in {\tt returned} finalizing the string with NULL.
 136
 137 Some examples:\begin{itemize}
 138 \item basename of {\tt system/some/keyname} is {\tt keyname} \item basename of {\tt \char`\"{}user/tmp/some key\char`\"{}} is {\tt \char`\"{}some key\char`\"{}} \end{itemize}
 139
 140
 141 \begin{Desc}
 142 \item[Parameters:]
 143 \begin{description}
 144 \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 {\tt returned} buffer \end{description}
 145 \end{Desc}
 146 \begin{Desc}
 147 \item[Returns:]number of bytes copied to {\tt returned}
 148
 149 1 on empty name
 150
 151 -1 on NULL pointers
 152
 153 -1 when maxSize is 0 or larger than SSIZE\_\-MAX \end{Desc}
 154 \begin{Desc}
 155 \item[See also:]\doxyref{keyBaseName()}{p.}{group__keyname_gaff35e7ca8af5560c47e662ceb9465f5}, \doxyref{keyGetBaseNameSize()}{p.}{group__keyname_g1a0b76c5d9e5367c7e72211e6c63d43a}
 156
 157 \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513}, \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be}, \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9} \end{Desc}
 158 \index{keyname@{keyname}!keyGetBaseNameSize@{keyGetBaseNameSize}}
 159 \index{keyGetBaseNameSize@{keyGetBaseNameSize}!keyname@{keyname}}
 160 \subsubsection[keyGetBaseNameSize]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetBaseNameSize (const Key $\ast$ {\em key})}\label{group__keyname_g1a0b76c5d9e5367c7e72211e6c63d43a}
 161
 162
 163 Calculates number of bytes needed to store basename of {\tt key}.
 164
 165 Key names that have only root names (e.g. {\tt \char`\"{}system\char`\"{}} or {\tt \char`\"{}user\char`\"{}} or {\tt \char`\"{}user:domain\char`\"{}} ) does not have basenames, thus the function will return 1 bytes to store \char`\"{}\char`\"{}.
 166
 167 Basenames are denoted as:\begin{itemize}
 168 \item {\tt system/some/thing/basename} -$>$ {\tt basename} \item {\tt user:domain/some/thing/base$\backslash$/name} $>$ {\tt base$\backslash$/name} \end{itemize}
 169
 170
 171 \begin{Desc}
 172 \item[Parameters:]
 173 \begin{description}
 174 \item[{\em key}]the key object to work with \end{description}
 175 \end{Desc}
 176 \begin{Desc}
 177 \item[Returns:]size in bytes of {\tt key's} basename including ending NULL \end{Desc}
 178 \begin{Desc}
 179 \item[See also:]\doxyref{keyBaseName()}{p.}{group__keyname_gaff35e7ca8af5560c47e662ceb9465f5}, \doxyref{keyGetBaseName()}{p.}{group__keyname_g0992d26bcfca767cb8e77053a483eb64}
 180
 181 \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513}, \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be}, \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9} \end{Desc}
 182 \index{keyname@{keyname}!keyGetFullName@{keyGetFullName}}
 183 \index{keyGetFullName@{keyGetFullName}!keyname@{keyname}}
 184 \subsubsection[keyGetFullName]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetFullName (const Key $\ast$ {\em key}, \/  char $\ast$ {\em returnedName}, \/  size\_\-t {\em maxSize})}\label{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c}
 185
 186
 187 Get key full name, including the user domain name.
 188
 189 \begin{Desc}
 190 \item[Returns:]number of bytes written
 191
 192 1 on empty name
 193
 194 -1 on NULL pointers
 195
 196 -1 if maxSize is 0 or larger than SSIZE\_\-MAX \end{Desc}
 197 \begin{Desc}
 198 \item[Parameters:]
 199 \begin{description}
 200 \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{description}
 201 \end{Desc}
 202 \index{keyname@{keyname}!keyGetFullNameSize@{keyGetFullNameSize}}
 203 \index{keyGetFullNameSize@{keyGetFullNameSize}!keyname@{keyname}}
 204 \subsubsection[keyGetFullNameSize]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetFullNameSize (const Key $\ast$ {\em key})}\label{group__keyname_gb65dc9d43d3ee08d5e936a20ebbddd23}
 205
 206
 207 Bytes needed to store the key name including user domain and ending NULL.
 208
 209 \begin{Desc}
 210 \item[Parameters:]
 211 \begin{description}
 212 \item[{\em key}]the key object to work with \end{description}
 213 \end{Desc}
 214 \begin{Desc}
 215 \item[Returns:]number of bytes needed to store key name including user domain
 216
 217 1 on empty name
 218
 219 -1 on NULL pointer \end{Desc}
 220 \begin{Desc}
 221 \item[See also:]\doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c}, \doxyref{keyGetNameSize()}{p.}{group__keyname_gbdbcfa51ed8a387e47ead207affa2d2e} \end{Desc}
 222 \index{keyname@{keyname}!keyGetName@{keyGetName}}
 223 \index{keyGetName@{keyGetName}!keyname@{keyname}}
 224 \subsubsection[keyGetName]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetName (const Key $\ast$ {\em key}, \/  char $\ast$ {\em returnedName}, \/  size\_\-t {\em maxSize})}\label{group__keyname_gb29a850168d9b31c9529e90cf9ab68be}
 225
 226
 227 Get abbreviated key name (without owner name).
 228
 229 When there is not enough space to write the name, nothing will be written and -1 will be returned.
 230
 231 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.
 232
 233 \begin{Desc}
 234 \item[Returns:]number of bytes written to {\tt returnedName}
 235
 236 1 when only a null was written
 237
 238 -1 when keyname is longer then maxSize or 0 or any NULL pointer \end{Desc}
 239 \begin{Desc}
 240 \item[Parameters:]
 241 \begin{description}
 242 \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{description}
 243 \end{Desc}
 244 \begin{Desc}
 245 \item[See also:]\doxyref{keyGetNameSize()}{p.}{group__keyname_gbdbcfa51ed8a387e47ead207affa2d2e}, \doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c}, \doxyref{keyGetFullNameSize()}{p.}{group__keyname_gb65dc9d43d3ee08d5e936a20ebbddd23} \end{Desc}
 246 \index{keyname@{keyname}!keyGetNameSize@{keyGetNameSize}}
 247 \index{keyGetNameSize@{keyGetNameSize}!keyname@{keyname}}
 248 \subsubsection[keyGetNameSize]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetNameSize (const Key $\ast$ {\em key})}\label{group__keyname_gbdbcfa51ed8a387e47ead207affa2d2e}
 249
 250
 251 Bytes needed to store the key name without owner.
 252
 253 For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.
 254
 255 \begin{Desc}
 256 \item[Parameters:]
 257 \begin{description}
 258 \item[{\em key}]the key object to work with \end{description}
 259 \end{Desc}
 260 \begin{Desc}
 261 \item[Returns:]number of bytes needed, including ending NULL, to store key name without owner
 262
 263 1 if there is is no key Name
 264
 265 -1 on NULL pointer \end{Desc}
 266 \begin{Desc}
 267 \item[See also:]\doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be}, \doxyref{keyGetFullNameSize()}{p.}{group__keyname_gb65dc9d43d3ee08d5e936a20ebbddd23} \end{Desc}
 268 \index{keyname@{keyname}!keyGetOwner@{keyGetOwner}}
 269 \index{keyGetOwner@{keyGetOwner}!keyname@{keyname}}
 270 \subsubsection[keyGetOwner]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetOwner (const Key $\ast$ {\em key}, \/  char $\ast$ {\em returned}, \/  size\_\-t {\em maxSize})}\label{group__keyname_g6d612841c829a638a8fbbbd4a31cc54a}
 271
 272
 273 Return the owner of the key.\begin{itemize}
 274 \item Given {\tt user:someuser/}..... return {\tt someuser} \item Given {\tt user:some.user/}.... return {\tt some.user} \item Given {\tt user/}.... return the current user\end{itemize}
 275
 276
 277 Only {\tt user/}... keys have a owner. For {\tt system/}... keys (that doesn't have a key owner) an empty string (\char`\"{}\char`\"{}) is returned.
 278
 279 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.
 280
 281 \begin{Desc}
 282 \item[Parameters:]
 283 \begin{description}
 284 \item[{\em key}]the object to work with \item[{\em returned}]a pre-allocated space to store the owner \item[{\em maxSize}]maximum number of bytes that fit returned \end{description}
 285 \end{Desc}
 286 \begin{Desc}
 287 \item[Returns:]number of bytes written to buffer
 288
 289 1 if there is no owner
 290
 291 -1 on NULL pointers
 292
 293 -1 when maxSize is 0, larger than SSIZE\_\-MAX or too small for ownername \end{Desc}
 294 \begin{Desc}
 295 \item[See also:]\doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9}, \doxyref{keySetOwner()}{p.}{group__keyname_ga899d9f0251cb98a89761ef112910eca}, \doxyref{keyOwner()}{p.}{group__keyname_gf6485fb8599714b6bbd830cf915ffea5}, \doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c} \end{Desc}
 296 \index{keyname@{keyname}!keyGetOwnerSize@{keyGetOwnerSize}}
 297 \index{keyGetOwnerSize@{keyGetOwnerSize}!keyname@{keyname}}
 298 \subsubsection[keyGetOwnerSize]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetOwnerSize (const Key $\ast$ {\em key})}\label{group__keyname_g4a4561895741ba2ad10acf007c188593}
 299
 300
 301 Return the size of the owner of the Key with concluding 0.
 302
 303 The returned number can be used to allocate a string. 1 will returned on an empty owner to store the concluding 0 on using \doxyref{keyGetOwner()}{p.}{group__keyname_g6d612841c829a638a8fbbbd4a31cc54a}.
 304
 305
 306
 307 \begin{Code}\begin{verbatim}char * buffer;
 308 buffer = malloc (keyGetOwnerSize (key));
 309 // use buffer and keyGetOwnerSize (key) for maxSize
 310 \end{verbatim}
 311 \end{Code}
 312
 313
 314
 315 \begin{Desc}
 316 \item[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{Desc}
 317 \begin{Desc}
 318 \item[Parameters:]
 319 \begin{description}
 320 \item[{\em key}]the key object to work with \end{description}
 321 \end{Desc}
 322 \begin{Desc}
 323 \item[Returns:]number of bytes
 324
 325 1 if there is no owner
 326
 327 -1 on NULL pointer \end{Desc}
 328 \begin{Desc}
 329 \item[See also:]\doxyref{keyGetOwner()}{p.}{group__keyname_g6d612841c829a638a8fbbbd4a31cc54a} \end{Desc}
 330 \index{keyname@{keyname}!keyName@{keyName}}
 331 \index{keyName@{keyName}!keyname@{keyname}}
 332 \subsubsection[keyName]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ keyName (const Key $\ast$ {\em key})}\label{group__keyname_g8e805c726a60da921d3736cda7813513}
 333
 334
 335 Returns a pointer to the abbreviated real internal {\tt key} name.
 336
 337 This is a much more efficient version of \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be} 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 \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9} and similar functions. If you need a copy of the name, consider using \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be}.
 338
 339 The name will be without owner, see \doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c} if you need the name with its owner.
 340
 341 \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513} returns \char`\"{}\char`\"{} when there is no keyName. The reason is
 342
 343 \begin{Code}\begin{verbatim}key=keyNew(0);
 344 keySetName(key,"");
 345 keyName(key); // you would expect "" here
 346 keyDel(key);
 347 \end{verbatim}
 348 \end{Code}
 349
 350
 351
 352 \begin{Desc}
 353 \item[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 \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513} method to set a new value. Use \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9} instead.\end{Desc}
 354 \begin{Desc}
 355 \item[Parameters:]
 356 \begin{description}
 357 \item[{\em key}]the key object to work with \end{description}
 358 \end{Desc}
 359 \begin{Desc}
 360 \item[Returns:]a pointer to the keyname which must not be changed.
 361
 362 \char`\"{}\char`\"{} when there is no (a empty) keyname
 363
 364 0 on NULL pointer \end{Desc}
 365 \begin{Desc}
 366 \item[See also:]\doxyref{keyGetNameSize()}{p.}{group__keyname_gbdbcfa51ed8a387e47ead207affa2d2e} for the string length
 367
 368 \doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c}, \doxyref{keyGetFullNameSize()}{p.}{group__keyname_gb65dc9d43d3ee08d5e936a20ebbddd23} to get the full name
 369
 370 \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be} as alternative to get a copy
 371
 372 \doxyref{keyOwner()}{p.}{group__keyname_gf6485fb8599714b6bbd830cf915ffea5} to get a pointer to owner \end{Desc}
 373 \index{keyname@{keyname}!keyOwner@{keyOwner}}
 374 \index{keyOwner@{keyOwner}!keyname@{keyname}}
 375 \subsubsection[keyOwner]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ keyOwner (const Key $\ast$ {\em key})}\label{group__keyname_gf6485fb8599714b6bbd830cf915ffea5}
 376
 377
 378 Return a pointer to the real internal {\tt key} owner.
 379
 380 This is a much more efficient version of \doxyref{keyGetOwner()}{p.}{group__keyname_g6d612841c829a638a8fbbbd4a31cc54a} 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 \doxyref{keyGetOwner()}{p.}{group__keyname_g6d612841c829a638a8fbbbd4a31cc54a} instead.
 381
 382 \doxyref{keyOwner()}{p.}{group__keyname_gf6485fb8599714b6bbd830cf915ffea5} returns \char`\"{}\char`\"{} when there is no keyOwner. The reason is
 383
 384 \begin{Code}\begin{verbatim}key=keyNew(0);
 385 keySetOwner(key,"");
 386 keyOwner(key); // you would expect "" here
 387 keySetOwner(key,"system");
 388 keyOwner(key); // you would expect "" here
 389 \end{verbatim}
 390 \end{Code}
 391
 392
 393
 394 \begin{Desc}
 395 \item[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 \doxyref{keyOwner()}{p.}{group__keyname_gf6485fb8599714b6bbd830cf915ffea5} method to set a new value. Use \doxyref{keySetOwner()}{p.}{group__keyname_ga899d9f0251cb98a89761ef112910eca} instead.\end{Desc}
 396 \begin{Desc}
 397 \item[Parameters:]
 398 \begin{description}
 399 \item[{\em key}]the key object to work with \end{description}
 400 \end{Desc}
 401 \begin{Desc}
 402 \item[Returns:]a pointer to internal owner
 403
 404 \char`\"{}\char`\"{} when there is no (a empty) owner
 405
 406 0 on NULL pointer \end{Desc}
 407 \begin{Desc}
 408 \item[See also:]\doxyref{keyGetOwnerSize()}{p.}{group__keyname_g4a4561895741ba2ad10acf007c188593} for the size of the string with concluding 0
 409
 410 \doxyref{keyGetOwner()}{p.}{group__keyname_g6d612841c829a638a8fbbbd4a31cc54a}, \doxyref{keySetOwner()}{p.}{group__keyname_ga899d9f0251cb98a89761ef112910eca}
 411
 412 \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513} for name without owner
 413
 414 \doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c} for name with owner \end{Desc}
 415 \index{keyname@{keyname}!keySetBaseName@{keySetBaseName}}
 416 \index{keySetBaseName@{keySetBaseName}!keyname@{keyname}}
 417 \subsubsection[keySetBaseName]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetBaseName (Key $\ast$ {\em key}, \/  const char $\ast$ {\em baseName})}\label{group__keyname_g6e804bd453f98c28b0ff51430d1df407}
 418
 419
 420 Sets {\tt baseName} as the new basename for {\tt key}.
 421
 422 All text after the last {\tt '/'} in the {\tt key} keyname is erased and {\tt baseName} is appended.
 423
 424 So lets suppose {\tt key} has name {\tt \char`\"{}system/dir1/dir2/key1\char`\"{}}. If {\tt baseName} is {\tt \char`\"{}key2\char`\"{}}, the resulting key name will be {\tt \char`\"{}system/dir1/dir2/key2\char`\"{}}. If {\tt baseName} is empty or NULL, the resulting key name will be {\tt \char`\"{}system/dir1/dir2\char`\"{}}.
 425
 426 \begin{Desc}
 427 \item[Warning:]You should not change a keys name once it belongs to a keyset. See \doxyref{ksSort()}{p.}{group__keyset_g023554d395ccf2319a3807b8b5d2530c} for more information.\end{Desc}
 428 \begin{Desc}
 429 \item[Parameters:]
 430 \begin{description}
 431 \item[{\em key}]the key object to work with \item[{\em baseName}]the string used to overwrite the basename of the key \end{description}
 432 \end{Desc}
 433 \begin{Desc}
 434 \item[Returns:]the size in bytes of the new key name
 435
 436 -1 on NULL pointers \end{Desc}
 437 \begin{Desc}
 438 \item[See also:]\doxyref{keyAddBaseName()}{p.}{group__keyname_ga942091fc4bd5c2699e49ddc50829524}
 439
 440 \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9} to set a new name \end{Desc}
 441 \index{keyname@{keyname}!keySetName@{keySetName}}
 442 \index{keySetName@{keySetName}!keyname@{keyname}}
 443 \subsubsection[keySetName]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetName (Key $\ast$ {\em key}, \/  const char $\ast$ {\em newName})}\label{group__keyname_g7699091610e7f3f43d2949514a4b35d9}
 444
 445
 446 Set a new name to a key.
 447
 448 A valid name is of the forms:\begin{itemize}
 449 \item {\tt system/something} \item {\tt user/something} \item {\tt user:username/something} \end{itemize}
 450
 451
 452 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.
 453
 454 You should always follow the guidelines for key tree structure creation.
 455
 456 A private copy of the key name will be stored, and the {\tt newName} parameter can be freed after this call.
 457
 458 .., . 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
 459
 460 On invalid names, NULL or \char`\"{}\char`\"{} the name will be \char`\"{}\char`\"{} afterwards.
 461
 462 \begin{Desc}
 463 \item[Warning:]You should not change a keys name once it belongs to a keyset. See \doxyref{ksSort()}{p.}{group__keyset_g023554d395ccf2319a3807b8b5d2530c} for more information.\end{Desc}
 464 \begin{Desc}
 465 \item[Returns:]size in bytes of this new key name including ending NULL
 466
 467 -1 if {\tt newName} is empty or invalid or any NULL pointer \end{Desc}
 468 \begin{Desc}
 469 \item[Parameters:]
 470 \begin{description}
 471 \item[{\em key}]the key object to work with \item[{\em newName}]the new key name \end{description}
 472 \end{Desc}
 473 \begin{Desc}
 474 \item[See also:]\doxyref{keyNew()}{p.}{group__key_gf6893c038b3ebee90c73a9ea8356bebf}, \doxyref{keySetOwner()}{p.}{group__keyname_ga899d9f0251cb98a89761ef112910eca}
 475
 476 \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be}, \doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c}, \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513}
 477
 478 \doxyref{keySetBaseName()}{p.}{group__keyname_g6e804bd453f98c28b0ff51430d1df407}, \doxyref{keyAddBaseName()}{p.}{group__keyname_ga942091fc4bd5c2699e49ddc50829524} to manipulate a name \end{Desc}
 479 \index{keyname@{keyname}!keySetOwner@{keySetOwner}}
 480 \index{keySetOwner@{keySetOwner}!keyname@{keyname}}
 481 \subsubsection[keySetOwner]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetOwner (Key $\ast$ {\em key}, \/  const char $\ast$ {\em owner})}\label{group__keyname_ga899d9f0251cb98a89761ef112910eca}
 482
 483
 484 Set the owner of a key.
 485
 486 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.
 487
 488 A private copy is stored, so the passed parameter can be freed after the call.
 489
 490 \begin{Desc}
 491 \item[Parameters:]
 492 \begin{description}
 493 \item[{\em key}]the key object to work with \item[{\em owner}]the owner (or user name) \end{description}
 494 \end{Desc}
 495 \begin{Desc}
 496 \item[Returns:]the number of bytes actually saved including final NULL
 497
 498 1 when owner is freed (by setting 0 or \char`\"{}\char`\"{})
 499
 500 -1 on null pointer or memory problems \end{Desc}
 501 \begin{Desc}
 502 \item[See also:]\doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9}, \doxyref{keyGetOwner()}{p.}{group__keyname_g6d612841c829a638a8fbbbd4a31cc54a}, \doxyref{keyGetFullName()}{p.}{group__keyname_gaba1494a5ffc976e0e56c43f4334a23c} \end{Desc}