doc/elektra-api/latex/group__keytest.tex

   1 \section{Key :: Methods for Making Tests}
   2 \label{group__keytest}\index{Key :: Methods for Making Tests@{Key :: Methods for Making Tests}}
   3 Methods to do various tests on Keys.
   4 \subsection*{Functions}
   5 \begin{CompactItemize}
   6 \item
   7 int {\bf keyNeedStat} (const Key $\ast$key)
   8 \item
   9 int {\bf keyNeedSync} (const Key $\ast$key)
  10 \item
  11 int {\bf keyNeedRemove} (const Key $\ast$key)
  12 \item
  13 int {\bf keyIsSystem} (const Key $\ast$key)
  14 \item
  15 int {\bf keyIsUser} (const Key $\ast$key)
  16 \item
  17 int {\bf keyIsBelow} (const Key $\ast$key, const Key $\ast$check)
  18 \item
  19 int {\bf keyIsDirectBelow} (const Key $\ast$key, const Key $\ast$check)
  20 \item
  21 int {\bf keyIsInactive} (const Key $\ast$key)
  22 \item
  23 int {\bf keyIsDir} (const Key $\ast$key)
  24 \item
  25 int {\bf keyIsBinary} (const Key $\ast$key)
  26 \item
  27 int {\bf keyIsString} (const Key $\ast$key)
  28 \end{CompactItemize}
  29
  30
  31 \subsection{Detailed Description}
  32 Methods to do various tests on Keys.
  33
  34 To use them:
  35
  36 \begin{Code}\begin{verbatim}#include <kdb.h>
  37 \end{verbatim}
  38 \end{Code}
  39
  40
  41
  42 \subsection{Function Documentation}
  43 \index{keytest@{keytest}!keyIsBelow@{keyIsBelow}}
  44 \index{keyIsBelow@{keyIsBelow}!keytest@{keytest}}
  45 \subsubsection[keyIsBelow]{\setlength{\rightskip}{0pt plus 5cm}int keyIsBelow (const Key $\ast$ {\em key}, \/  const Key $\ast$ {\em check})}\label{group__keytest_g03332b5d97c76a4fd2640aca4762b8df}
  46
  47
  48 Check if the key check is below the key key or not.
  49
  50
  51
  52 \begin{Code}\begin{verbatim}Example:
  53 key user/sw/app
  54 check user/sw/app/key
  55
  56 returns true because check is below key
  57
  58 Example:
  59 key user/sw/app
  60 check user/sw/app/folder/key
  61
  62 returns also true because check is indirect below key
  63 \end{verbatim}
  64 \end{Code}
  65
  66
  67
  68 \begin{Desc}
  69 \item[Parameters:]
  70 \begin{description}
  71 \item[{\em key}]the key object to work with \item[{\em check}]the key to find the relative position of \end{description}
  72 \end{Desc}
  73 \begin{Desc}
  74 \item[Returns:]1 if check is below key
  75
  76 0 if it is not below or if it is the same key \end{Desc}
  77 \begin{Desc}
  78 \item[See also:]\doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9}, \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be}, \doxyref{keyIsDirectBelow()}{p.}{group__keytest_g4f175aafd98948ce6c774f3bd92b72ca} \end{Desc}
  79 \index{keytest@{keytest}!keyIsBinary@{keyIsBinary}}
  80 \index{keyIsBinary@{keyIsBinary}!keytest@{keytest}}
  81 \subsubsection[keyIsBinary]{\setlength{\rightskip}{0pt plus 5cm}int keyIsBinary (const Key $\ast$ {\em key})}\label{group__keytest_g9526b371087564e43e3dff8ad0dac949}
  82
  83
  84 Check if a key is binary type.
  85
  86 The function checks if the keytype is in the range between KEY\_\-TYPE\_\-BINARY and less than excluding KEY\_\-TYPE\_\-STRING. Then it will be interpreted as binary.
  87
  88 Make sure to use this function and don't test the binary type another way to ensure compatibility and to write less error prone programs.
  89
  90 \begin{Desc}
  91 \item[Returns:]1 if it is binary
  92
  93 0 if it is not
  94
  95 -1 on NULL pointer \end{Desc}
  96 \begin{Desc}
  97 \item[See also:]\doxyref{keySetType()}{p.}{group__keymeta_gb92003db4b938594df48807c16766bf7} for more information on types
  98
  99 \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84}, \doxyref{keySetBinary()}{p.}{group__keyvalue_ga50a5358fd328d373a45f395fa1b99e7} \end{Desc}
 100 \begin{Desc}
 101 \item[Parameters:]
 102 \begin{description}
 103 \item[{\em key}]the key to check \end{description}
 104 \end{Desc}
 105 \index{keytest@{keytest}!keyIsDir@{keyIsDir}}
 106 \index{keyIsDir@{keyIsDir}!keytest@{keytest}}
 107 \subsubsection[keyIsDir]{\setlength{\rightskip}{0pt plus 5cm}int keyIsDir (const Key $\ast$ {\em key})}\label{group__keytest_gc0a10c602d52a35f81347e8a32312017}
 108
 109
 110 Check if a key is directory key.
 111
 112 Folder keys may also have value and comment. They are discern by having a executable bit set.
 113
 114 If any executable bit is set it will be recognized as a directory.
 115
 116 \begin{Desc}
 117 \item[Note:]keyIsDir may return true even though you can't access the directory.\end{Desc}
 118 To know if you can access the directory, you need to check, if your\begin{itemize}
 119 \item user ID is equal the key's user ID and the mode \& 100 is true\item group ID is equal the key's group ID and the mode \& 010 is true\item mode \& 001 is true\end{itemize}
 120
 121
 122 Accessing does not mean that you can get any value or comments below, see \doxyref{Mode}{p.}{group__backend_mode} for more information.
 123
 124 \begin{Desc}
 125 \item[Parameters:]
 126 \begin{description}
 127 \item[{\em key}]the key object to work with \end{description}
 128 \end{Desc}
 129 \begin{Desc}
 130 \item[Returns:]1 if key is a directory, 0 otherwise
 131
 132 -1 on NULL pointer \end{Desc}
 133 \begin{Desc}
 134 \item[See also:]\doxyref{keySetDir()}{p.}{group__keymeta_gae575bd86a628a15ee45baa860522e75}, \doxyref{keySetMode()}{p.}{group__keymeta_g8803037e35b9da1ce492323a88ff6bc3} \end{Desc}
 135 \index{keytest@{keytest}!keyIsDirectBelow@{keyIsDirectBelow}}
 136 \index{keyIsDirectBelow@{keyIsDirectBelow}!keytest@{keytest}}
 137 \subsubsection[keyIsDirectBelow]{\setlength{\rightskip}{0pt plus 5cm}int keyIsDirectBelow (const Key $\ast$ {\em key}, \/  const Key $\ast$ {\em check})}\label{group__keytest_g4f175aafd98948ce6c774f3bd92b72ca}
 138
 139
 140 Check if the key check is direct below the key key or not.
 141
 142
 143
 144 \begin{Code}\begin{verbatim}Example:
 145 key user/sw/app
 146 check user/sw/app/key
 147
 148 returns true because check is below key
 149
 150 Example:
 151 key user/sw/app
 152 check user/sw/app/folder/key
 153
 154 does not return true, because there is only a indirect relation
 155 \end{verbatim}
 156 \end{Code}
 157
 158
 159
 160 \begin{Desc}
 161 \item[Parameters:]
 162 \begin{description}
 163 \item[{\em key}]the key object to work with \item[{\em check}]the key to find the relative position of \end{description}
 164 \end{Desc}
 165 \begin{Desc}
 166 \item[Returns:]1 if check is below key
 167
 168 0 if it is not below or if it is the same key
 169
 170 -1 on null pointer \end{Desc}
 171 \begin{Desc}
 172 \item[See also:]\doxyref{keyIsBelow()}{p.}{group__keytest_g03332b5d97c76a4fd2640aca4762b8df}, \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9}, \doxyref{keyGetName()}{p.}{group__keyname_gb29a850168d9b31c9529e90cf9ab68be} \end{Desc}
 173 \index{keytest@{keytest}!keyIsInactive@{keyIsInactive}}
 174 \index{keyIsInactive@{keyIsInactive}!keytest@{keytest}}
 175 \subsubsection[keyIsInactive]{\setlength{\rightskip}{0pt plus 5cm}int keyIsInactive (const Key $\ast$ {\em key})}\label{group__keytest_ga25f699f592031c1a0abc1504d14e13e}
 176
 177
 178 Check whether a key is inactive or not.
 179
 180 In elektra terminology any key is inactive if the it's basename starts with '.'. Inactive keys must not have any meaning to applications, they are reserved for users and administrators.
 181
 182 To remove a whole hierarchy in elektra, don't forget to pass option\_\-t::KDB\_\-O\_\-INACTIVE to \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} to receive the inactive keys in order to remove them.
 183
 184 Otherwise you should not fetch these keys.
 185
 186 \begin{Desc}
 187 \item[Parameters:]
 188 \begin{description}
 189 \item[{\em key}]the key object to work with \end{description}
 190 \end{Desc}
 191 \begin{Desc}
 192 \item[Returns:]1 if the key is inactive, 0 otherwise
 193
 194 -1 on NULL pointer or when key has no name \end{Desc}
 195 \index{keytest@{keytest}!keyIsString@{keyIsString}}
 196 \index{keyIsString@{keyIsString}!keytest@{keytest}}
 197 \subsubsection[keyIsString]{\setlength{\rightskip}{0pt plus 5cm}int keyIsString (const Key $\ast$ {\em key})}\label{group__keytest_gea7670778abd07fee0fe8ac12a149190}
 198
 199
 200 Check if a key is string type.
 201
 202 The function checks if the keytype is larger or equal KEY\_\-TYPE\_\-STRING. Then it will be considered as string type.
 203
 204 Make sure to use this function and don't test the string type another way to ensure compatibility and to write less error prone programs.
 205
 206 \begin{Desc}
 207 \item[Returns:]1 if it is string
 208
 209 0 if it is not
 210
 211 -1 on NULL pointer \end{Desc}
 212 \begin{Desc}
 213 \item[See also:]\doxyref{keySetType}{p.}{group__keymeta_gb92003db4b938594df48807c16766bf7} for more information on types
 214
 215 \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778}, \doxyref{keySetString()}{p.}{group__keyvalue_g622bde1eb0e0c4994728331326340ef2} \end{Desc}
 216 \begin{Desc}
 217 \item[Parameters:]
 218 \begin{description}
 219 \item[{\em key}]the key to check \end{description}
 220 \end{Desc}
 221 \index{keytest@{keytest}!keyIsSystem@{keyIsSystem}}
 222 \index{keyIsSystem@{keyIsSystem}!keytest@{keytest}}
 223 \subsubsection[keyIsSystem]{\setlength{\rightskip}{0pt plus 5cm}int keyIsSystem (const Key $\ast$ {\em key})}\label{group__keytest_gfe49cfb61c2accb3073131c23a56fb14}
 224
 225
 226 Check whether a key is under the {\tt system} namespace or not
 227
 228 \begin{Desc}
 229 \item[Parameters:]
 230 \begin{description}
 231 \item[{\em key}]the key object to work with \end{description}
 232 \end{Desc}
 233 \begin{Desc}
 234 \item[Returns:]1 if key name begins with {\tt system}, 0 otherwise
 235
 236 -1 on NULL pointer \end{Desc}
 237 \begin{Desc}
 238 \item[See also:]\doxyref{keyIsUser()}{p.}{group__keytest_g373acc20c6209357045891f4b0c70041}, \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9}, \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513} \end{Desc}
 239 \index{keytest@{keytest}!keyIsUser@{keyIsUser}}
 240 \index{keyIsUser@{keyIsUser}!keytest@{keytest}}
 241 \subsubsection[keyIsUser]{\setlength{\rightskip}{0pt plus 5cm}int keyIsUser (const Key $\ast$ {\em key})}\label{group__keytest_g373acc20c6209357045891f4b0c70041}
 242
 243
 244 Check whether a key is under the {\tt user} namespace or not.
 245
 246 \begin{Desc}
 247 \item[Parameters:]
 248 \begin{description}
 249 \item[{\em key}]the key object to work with \end{description}
 250 \end{Desc}
 251 \begin{Desc}
 252 \item[Returns:]1 if key name begins with {\tt user}, 0 otherwise
 253
 254 -1 on NULL pointer \end{Desc}
 255 \begin{Desc}
 256 \item[See also:]\doxyref{keyIsSystem()}{p.}{group__keytest_gfe49cfb61c2accb3073131c23a56fb14}, \doxyref{keySetName()}{p.}{group__keyname_g7699091610e7f3f43d2949514a4b35d9}, \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513} \end{Desc}
 257 \index{keytest@{keytest}!keyNeedRemove@{keyNeedRemove}}
 258 \index{keyNeedRemove@{keyNeedRemove}!keytest@{keytest}}
 259 \subsubsection[keyNeedRemove]{\setlength{\rightskip}{0pt plus 5cm}int keyNeedRemove (const Key $\ast$ {\em key})}\label{group__keytest_gae91159815480fbb3b3d9d7fa85e77b9}
 260
 261
 262 Ask if key is marked for permanent remove.
 263
 264 Ask if the key will be removed instead of writing in the key database when doing \doxyref{kdbSetKey()}{p.}{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20} or \doxyref{kdbSet()}{p.}{group__kdb_g953cf29721e6000c2516cd6b5d36f571}.
 265
 266 \begin{Desc}
 267 \item[See also:]\doxyref{keyRemove()}{p.}{group__keymeta_g6e14e5f1de26e1318100631a149f2984}
 268
 269 \doxyref{kdbSet()}{p.}{group__kdb_g953cf29721e6000c2516cd6b5d36f571}, \doxyref{kdbSetKey()}{p.}{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20}, \doxyref{kdbRemove()}{p.}{group__kdbhighlevel_gf9adbbeb3f49c63fb2f89930445c8060} \end{Desc}
 270 \begin{Desc}
 271 \item[Parameters:]
 272 \begin{description}
 273 \item[{\em key}]the key object to work with \end{description}
 274 \end{Desc}
 275 \begin{Desc}
 276 \item[Returns:]1 if it is marked, 0 otherwise
 277
 278 -1 on NULL pointer \end{Desc}
 279 \index{keytest@{keytest}!keyNeedStat@{keyNeedStat}}
 280 \index{keyNeedStat@{keyNeedStat}!keytest@{keytest}}
 281 \subsubsection[keyNeedStat]{\setlength{\rightskip}{0pt plus 5cm}int keyNeedStat (const Key $\ast$ {\em key})}\label{group__keytest_g3908b6511648a950f37cd0005bfea5d5}
 282
 283
 284 Ask if key is marked for stat only.
 285
 286 Ask if the key will be stat instead of get it from the key database completely doing \doxyref{kdbGetKey()}{p.}{group__kdbhighlevel_ga62877888f0cad395898859395e6635f} or \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5}. This is useful if you are not interested in the value, comment or key type.
 287
 288 \begin{Desc}
 289 \item[See also:]\doxyref{keyStat()}{p.}{group__keymeta_gb8189add5e562bdb148675ee595bd95b}, \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} \end{Desc}
 290 \begin{Desc}
 291 \item[Parameters:]
 292 \begin{description}
 293 \item[{\em key}]the key object to work with \end{description}
 294 \end{Desc}
 295 \begin{Desc}
 296 \item[Returns:]1 if it is marked, 0 otherwise
 297
 298 -1 on NULL pointer \end{Desc}
 299 \index{keytest@{keytest}!keyNeedSync@{keyNeedSync}}
 300 \index{keyNeedSync@{keyNeedSync}!keytest@{keytest}}
 301 \subsubsection[keyNeedSync]{\setlength{\rightskip}{0pt plus 5cm}int keyNeedSync (const Key $\ast$ {\em key})}\label{group__keytest_gf247df0de7aca04b32ef80e39ef12950}
 302
 303
 304 Test if a key needs to be synced to backend storage.
 305
 306 If any key modification took place the key will be flagged with KEY\_\-FLAG\_\-SYNC so that \doxyref{kdbSet()}{p.}{group__kdb_g953cf29721e6000c2516cd6b5d36f571} knows which keys were modified and which not.
 307
 308 After \doxyref{keyNew()}{p.}{group__key_gf6893c038b3ebee90c73a9ea8356bebf} the flag will normally be set, but after \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} and \doxyref{kdbSet()}{p.}{group__kdb_g953cf29721e6000c2516cd6b5d36f571} the flag will be removed. When you modify the key the flag will be set again.
 309
 310 In your application you can make use of that flag to know if you changed something in a key after a \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} or \doxyref{kdbSet()}{p.}{group__kdb_g953cf29721e6000c2516cd6b5d36f571}.
 311
 312 \begin{Desc}
 313 \item[Note:]Note that also changes in the meta data will set that flag.\end{Desc}
 314 \begin{Desc}
 315 \item[See also:]\doxyref{keyNew()}{p.}{group__key_gf6893c038b3ebee90c73a9ea8356bebf} \end{Desc}
 316 \begin{Desc}
 317 \item[Parameters:]
 318 \begin{description}
 319 \item[{\em key}]the key object to work with \end{description}
 320 \end{Desc}
 321 \begin{Desc}
 322 \item[Returns:]1 if {\tt key} was changed in memory, 0 otherwise
 323
 324 -1 on NULL pointer \end{Desc}