doc/elektra-api/man/man3/keytest.3

   1 .TH "Key :: Methods for Making Tests" 3 "30 Jun 2009" "Elektra Projekt" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Key :: Methods for Making Tests \- Methods to do various tests on Keys.
   6
   7 .PP
   8 .SS "Functions"
   9
  10 .in +1c
  11 .ti -1c
  12 .RI "int \fBkeyNeedStat\fP (const Key *key)"
  13 .br
  14 .ti -1c
  15 .RI "int \fBkeyNeedSync\fP (const Key *key)"
  16 .br
  17 .ti -1c
  18 .RI "int \fBkeyNeedRemove\fP (const Key *key)"
  19 .br
  20 .ti -1c
  21 .RI "int \fBkeyIsSystem\fP (const Key *key)"
  22 .br
  23 .ti -1c
  24 .RI "int \fBkeyIsUser\fP (const Key *key)"
  25 .br
  26 .ti -1c
  27 .RI "int \fBkeyIsBelow\fP (const Key *key, const Key *check)"
  28 .br
  29 .ti -1c
  30 .RI "int \fBkeyIsDirectBelow\fP (const Key *key, const Key *check)"
  31 .br
  32 .ti -1c
  33 .RI "int \fBkeyIsInactive\fP (const Key *key)"
  34 .br
  35 .ti -1c
  36 .RI "int \fBkeyIsDir\fP (const Key *key)"
  37 .br
  38 .ti -1c
  39 .RI "int \fBkeyIsBinary\fP (const Key *key)"
  40 .br
  41 .ti -1c
  42 .RI "int \fBkeyIsString\fP (const Key *key)"
  43 .br
  44 .in -1c
  45 .SH "Detailed Description"
  46 .PP
  47 Methods to do various tests on Keys.
  48 .PP
  49 To use them:
  50 .PP
  51 .nf
  52 #include <kdb.h>
  53
  54 .fi
  55 .PP
  56
  57 .SH "Function Documentation"
  58 .PP
  59 .SS "int keyIsBelow (const Key * key, const Key * check)"
  60 .PP
  61 Check if the key check is below the key key or not.
  62 .PP
  63 .PP
  64 .nf
  65 Example:
  66 key user/sw/app
  67 check user/sw/app/key
  68
  69 returns true because check is below key
  70
  71 Example:
  72 key user/sw/app
  73 check user/sw/app/folder/key
  74
  75 returns also true because check is indirect below key
  76 .fi
  77 .PP
  78 .PP
  79 \fBParameters:\fP
  80 .RS 4
  81 \fIkey\fP the key object to work with
  82 .br
  83 \fIcheck\fP the key to find the relative position of
  84 .RE
  85 .PP
  86 \fBReturns:\fP
  87 .RS 4
  88 1 if check is below key
  89 .PP
  90 0 if it is not below or if it is the same key
  91 .RE
  92 .PP
  93 \fBSee also:\fP
  94 .RS 4
  95 \fBkeySetName()\fP, \fBkeyGetName()\fP, \fBkeyIsDirectBelow()\fP
  96 .RE
  97 .PP
  98
  99 .SS "int keyIsBinary (const Key * key)"
 100 .PP
 101 Check if a key is binary type.
 102 .PP
 103 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.
 104 .PP
 105 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.
 106 .PP
 107 \fBReturns:\fP
 108 .RS 4
 109 1 if it is binary
 110 .PP
 111 0 if it is not
 112 .PP
 113 -1 on NULL pointer
 114 .RE
 115 .PP
 116 \fBSee also:\fP
 117 .RS 4
 118 \fBkeySetType()\fP for more information on types
 119 .PP
 120 \fBkeyGetBinary()\fP, \fBkeySetBinary()\fP
 121 .RE
 122 .PP
 123 \fBParameters:\fP
 124 .RS 4
 125 \fIkey\fP the key to check
 126 .RE
 127 .PP
 128
 129 .SS "int keyIsDir (const Key * key)"
 130 .PP
 131 Check if a key is directory key.
 132 .PP
 133 Folder keys may also have value and comment. They are discern by having a executable bit set.
 134 .PP
 135 If any executable bit is set it will be recognized as a directory.
 136 .PP
 137 \fBNote:\fP
 138 .RS 4
 139 keyIsDir may return true even though you can't access the directory.
 140 .RE
 141 .PP
 142 To know if you can access the directory, you need to check, if your
 143 .IP "\(bu" 2
 144 user ID is equal the key's user ID and the mode & 100 is true
 145 .IP "\(bu" 2
 146 group ID is equal the key's group ID and the mode & 010 is true
 147 .IP "\(bu" 2
 148 mode & 001 is true
 149 .PP
 150 .PP
 151 Accessing does not mean that you can get any value or comments below, see \fBMode\fP for more information.
 152 .PP
 153 \fBParameters:\fP
 154 .RS 4
 155 \fIkey\fP the key object to work with
 156 .RE
 157 .PP
 158 \fBReturns:\fP
 159 .RS 4
 160 1 if key is a directory, 0 otherwise
 161 .PP
 162 -1 on NULL pointer
 163 .RE
 164 .PP
 165 \fBSee also:\fP
 166 .RS 4
 167 \fBkeySetDir()\fP, \fBkeySetMode()\fP
 168 .RE
 169 .PP
 170
 171 .SS "int keyIsDirectBelow (const Key * key, const Key * check)"
 172 .PP
 173 Check if the key check is direct below the key key or not.
 174 .PP
 175 .PP
 176 .nf
 177 Example:
 178 key user/sw/app
 179 check user/sw/app/key
 180
 181 returns true because check is below key
 182
 183 Example:
 184 key user/sw/app
 185 check user/sw/app/folder/key
 186
 187 does not return true, because there is only a indirect relation
 188 .fi
 189 .PP
 190 .PP
 191 \fBParameters:\fP
 192 .RS 4
 193 \fIkey\fP the key object to work with
 194 .br
 195 \fIcheck\fP the key to find the relative position of
 196 .RE
 197 .PP
 198 \fBReturns:\fP
 199 .RS 4
 200 1 if check is below key
 201 .PP
 202 0 if it is not below or if it is the same key
 203 .PP
 204 -1 on null pointer
 205 .RE
 206 .PP
 207 \fBSee also:\fP
 208 .RS 4
 209 \fBkeyIsBelow()\fP, \fBkeySetName()\fP, \fBkeyGetName()\fP
 210 .RE
 211 .PP
 212
 213 .SS "int keyIsInactive (const Key * key)"
 214 .PP
 215 Check whether a key is inactive or not.
 216 .PP
 217 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.
 218 .PP
 219 To remove a whole hierarchy in elektra, don't forget to pass option_t::KDB_O_INACTIVE to \fBkdbGet()\fP to receive the inactive keys in order to remove them.
 220 .PP
 221 Otherwise you should not fetch these keys.
 222 .PP
 223 \fBParameters:\fP
 224 .RS 4
 225 \fIkey\fP the key object to work with
 226 .RE
 227 .PP
 228 \fBReturns:\fP
 229 .RS 4
 230 1 if the key is inactive, 0 otherwise
 231 .PP
 232 -1 on NULL pointer or when key has no name
 233 .RE
 234 .PP
 235
 236 .SS "int keyIsString (const Key * key)"
 237 .PP
 238 Check if a key is string type.
 239 .PP
 240 The function checks if the keytype is larger or equal KEY_TYPE_STRING. Then it will be considered as string type.
 241 .PP
 242 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.
 243 .PP
 244 \fBReturns:\fP
 245 .RS 4
 246 1 if it is string
 247 .PP
 248 0 if it is not
 249 .PP
 250 -1 on NULL pointer
 251 .RE
 252 .PP
 253 \fBSee also:\fP
 254 .RS 4
 255 \fBkeySetType\fP for more information on types
 256 .PP
 257 \fBkeyGetString()\fP, \fBkeySetString()\fP
 258 .RE
 259 .PP
 260 \fBParameters:\fP
 261 .RS 4
 262 \fIkey\fP the key to check
 263 .RE
 264 .PP
 265
 266 .SS "int keyIsSystem (const Key * key)"
 267 .PP
 268 Check whether a key is under the \fCsystem\fP namespace or not
 269 .PP
 270 \fBParameters:\fP
 271 .RS 4
 272 \fIkey\fP the key object to work with
 273 .RE
 274 .PP
 275 \fBReturns:\fP
 276 .RS 4
 277 1 if key name begins with \fCsystem\fP, 0 otherwise
 278 .PP
 279 -1 on NULL pointer
 280 .RE
 281 .PP
 282 \fBSee also:\fP
 283 .RS 4
 284 \fBkeyIsUser()\fP, \fBkeySetName()\fP, \fBkeyName()\fP
 285 .RE
 286 .PP
 287
 288 .SS "int keyIsUser (const Key * key)"
 289 .PP
 290 Check whether a key is under the \fCuser\fP namespace or not.
 291 .PP
 292 \fBParameters:\fP
 293 .RS 4
 294 \fIkey\fP the key object to work with
 295 .RE
 296 .PP
 297 \fBReturns:\fP
 298 .RS 4
 299 1 if key name begins with \fCuser\fP, 0 otherwise
 300 .PP
 301 -1 on NULL pointer
 302 .RE
 303 .PP
 304 \fBSee also:\fP
 305 .RS 4
 306 \fBkeyIsSystem()\fP, \fBkeySetName()\fP, \fBkeyName()\fP
 307 .RE
 308 .PP
 309
 310 .SS "int keyNeedRemove (const Key * key)"
 311 .PP
 312 Ask if key is marked for permanent remove.
 313 .PP
 314 Ask if the key will be removed instead of writing in the key database when doing \fBkdbSetKey()\fP or \fBkdbSet()\fP.
 315 .PP
 316 \fBSee also:\fP
 317 .RS 4
 318 \fBkeyRemove()\fP
 319 .PP
 320 \fBkdbSet()\fP, \fBkdbSetKey()\fP, \fBkdbRemove()\fP
 321 .RE
 322 .PP
 323 \fBParameters:\fP
 324 .RS 4
 325 \fIkey\fP the key object to work with
 326 .RE
 327 .PP
 328 \fBReturns:\fP
 329 .RS 4
 330 1 if it is marked, 0 otherwise
 331 .PP
 332 -1 on NULL pointer
 333 .RE
 334 .PP
 335
 336 .SS "int keyNeedStat (const Key * key)"
 337 .PP
 338 Ask if key is marked for stat only.
 339 .PP
 340 Ask if the key will be stat instead of get it from the key database completely doing \fBkdbGetKey()\fP or \fBkdbGet()\fP. This is useful if you are not interested in the value, comment or key type.
 341 .PP
 342 \fBSee also:\fP
 343 .RS 4
 344 \fBkeyStat()\fP, \fBkdbGet()\fP
 345 .RE
 346 .PP
 347 \fBParameters:\fP
 348 .RS 4
 349 \fIkey\fP the key object to work with
 350 .RE
 351 .PP
 352 \fBReturns:\fP
 353 .RS 4
 354 1 if it is marked, 0 otherwise
 355 .PP
 356 -1 on NULL pointer
 357 .RE
 358 .PP
 359
 360 .SS "int keyNeedSync (const Key * key)"
 361 .PP
 362 Test if a key needs to be synced to backend storage.
 363 .PP
 364 If any key modification took place the key will be flagged with KEY_FLAG_SYNC so that \fBkdbSet()\fP knows which keys were modified and which not.
 365 .PP
 366 After \fBkeyNew()\fP the flag will normally be set, but after \fBkdbGet()\fP and \fBkdbSet()\fP the flag will be removed. When you modify the key the flag will be set again.
 367 .PP
 368 In your application you can make use of that flag to know if you changed something in a key after a \fBkdbGet()\fP or \fBkdbSet()\fP.
 369 .PP
 370 \fBNote:\fP
 371 .RS 4
 372 Note that also changes in the meta data will set that flag.
 373 .RE
 374 .PP
 375 \fBSee also:\fP
 376 .RS 4
 377 \fBkeyNew()\fP
 378 .RE
 379 .PP
 380 \fBParameters:\fP
 381 .RS 4
 382 \fIkey\fP the key object to work with
 383 .RE
 384 .PP
 385 \fBReturns:\fP
 386 .RS 4
 387 1 if \fCkey\fP was changed in memory, 0 otherwise
 388 .PP
 389 -1 on NULL pointer
 390 .RE
 391 .PP
 392