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

   1 .TH "KDB Backends :: Backend Helper for Elektra" 3 "30 Jun 2009" "Elektra Projekt" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 KDB Backends :: Backend Helper for Elektra \- Backend helper Methods for Elektra and Backends.
   6
   7 .PP
   8 .SS "Functions"
   9
  10 .in +1c
  11 .ti -1c
  12 .RI "int \fBkdbbWriteLock\fP (FILE *f)"
  13 .br
  14 .ti -1c
  15 .RI "int \fBkdbbReadLock\fP (FILE *f)"
  16 .br
  17 .ti -1c
  18 .RI "int \fBkdbbUnlock\fP (FILE *f)"
  19 .br
  20 .ti -1c
  21 .RI "ssize_t \fBkdbbEncode\fP (void *kdbbDecoded, size_t size, char *returned)"
  22 .br
  23 .ti -1c
  24 .RI "ssize_t \fBkdbbDecode\fP (char *kdbbEncoded, void *returned)"
  25 .br
  26 .ti -1c
  27 .RI "int \fBkdbbNeedsUTF8Conversion\fP ()"
  28 .br
  29 .ti -1c
  30 .RI "int \fBkdbbUTF8Engine\fP (int direction, char **string, size_t *inputOutputByteSize)"
  31 .br
  32 .ti -1c
  33 .RI "int \fBkdbbEncodeChar\fP (char c, char *buffer, size_t bufSize)"
  34 .br
  35 .ti -1c
  36 .RI "int \fBkdbbDecodeChar\fP (const char *from, char *into)"
  37 .br
  38 .ti -1c
  39 .RI "int \fBkdbbFilenameToKeyName\fP (const char *string, char *buffer, int bufSize)"
  40 .br
  41 .ti -1c
  42 .RI "ssize_t \fBkdbbGetFullKeyName\fP (KDB *handle, const char *forFilename, const Key *parentKey, Key *returned)"
  43 .br
  44 .ti -1c
  45 .RI "int \fBkdbbKeyNameToRelativeFilename\fP (const char *string, char *buffer, size_t bufSize)"
  46 .br
  47 .ti -1c
  48 .RI "ssize_t \fBkdbbKeyCalcRelativeFilename\fP (const Key *key, char *relativeFilename, size_t maxSize)"
  49 .br
  50 .ti -1c
  51 .RI "ssize_t \fBkdbbGetFullFilename\fP (KDB *handle, const Key *forKey, char *returned, size_t maxSize)"
  52 .br
  53 .in -1c
  54 .SH "Detailed Description"
  55 .PP
  56 Backend helper Methods for Elektra and Backends.
  57 .PP
  58 To use them:
  59 .PP
  60 .nf
  61  #include <kdbbackend.h>
  62
  63 .fi
  64 .PP
  65 .PP
  66 These backend helper methods provide functionality commonly used by backends to make backend development easier and to provide the same behaviour between backends.
  67 .SH "Function Documentation"
  68 .PP
  69 .SS "ssize_t kdbbDecode (char * kdbbEncoded, void * returned)"
  70 .PP
  71 UnkdbbEncodes a buffer of ASCII hexadecimal values into a byte stream.
  72 .PP
  73 The allowed format for the hexadecimal values is just a stream of pairs of plain hex-digits, all together or space-separated.
  74 .PP
  75 The \fCreturned\fP data won't be bigger than half the size of the source \fCkdbbEncoded\fP data.
  76 .PP
  77 \fBParameters:\fP
  78 .RS 4
  79 \fIkdbbEncoded\fP the source of ASCII hexadecimal digits.
  80 .br
  81 \fIreturned\fP preallocated destination for the kdbbDecoded data.
  82 .RE
  83 .PP
  84 \fBReturns:\fP
  85 .RS 4
  86 the amount of bytes kdbbDecoded
  87 .PP
  88 -1 on failure
  89 .RE
  90 .PP
  91 \fBSee also:\fP
  92 .RS 4
  93 \fBkdbbEncode()\fP
  94 .RE
  95 .PP
  96
  97 .SS "int kdbbDecodeChar (const char * from, char * into)"
  98 .PP
  99 Char decoding.
 100 .PP
 101 Decode one char from 25, 2B, 2F, 2C following RFC 2396 or copy char untouched if different.
 102 .PP
 103 \fBParameters:\fP
 104 .RS 4
 105 \fIfrom\fP String containing sequence to decode
 106 .br
 107 \fIinto\fP Decoded char
 108 .RE
 109 .PP
 110 \fBReturns:\fP
 111 .RS 4
 112 : Positive size of byte read from 'from' for decoding the sequence if sucess or -1 if error (into untouched)
 113 .RE
 114 .PP
 115 \fBSee also:\fP
 116 .RS 4
 117 \fBkdbbEncodeChar\fP
 118 .RE
 119 .PP
 120 NOTE: No '\\0' is added at the end of buffer.
 121 .SS "ssize_t kdbbEncode (void * kdbbDecoded, size_t size, char * returned)"
 122 .PP
 123 Encodes a buffer of data onto hexadecimal ASCII.
 124 .PP
 125 The resulting data is made up of pairs of ASCII hex-digits, space- and newline-separated. This is the counterpart of \fBkdbbDecode()\fP.
 126 .PP
 127 The \fCreturned\fP must allocated prior you call this function and won't be bigger than 3 times the size of the source \fCkdbbDecoded\fP + 1 byte.
 128 .PP
 129 \fBParameters:\fP
 130 .RS 4
 131 \fIkdbbDecoded\fP the source buffer.
 132 .br
 133 \fIsize\fP the size of the source buffer in bytes.
 134 .br
 135 \fIreturned\fP the preallocated destination for the ASCII-kdbbEncoded data.
 136 .RE
 137 .PP
 138 \fBReturns:\fP
 139 .RS 4
 140 the amount of bytes used in the resulting kdbbEncoded buffer.
 141 .RE
 142 .PP
 143 \fBSee also:\fP
 144 .RS 4
 145 \fBkdbbDecode()\fP
 146 .RE
 147 .PP
 148
 149 .SS "int kdbbEncodeChar (char c, char * buffer, size_t bufSize)"
 150 .PP
 151 Char encoding.
 152 .PP
 153 Encode '/', '\\', '', '+', ' ' char following RFC 2396 or copy char untouched if different.
 154 .PP
 155 \fBParameters:\fP
 156 .RS 4
 157 \fIc\fP Char to kdbbEncode
 158 .br
 159 \fIbuffer\fP string wich will contain kdbbEncoded char
 160 .br
 161 \fIbufSize\fP Size of the buffer
 162 .RE
 163 .PP
 164 \fBReturns:\fP
 165 .RS 4
 166 : Size of the kdbbEncoded string if success or -1 if error * (then buffer is untouched)
 167 .RE
 168 .PP
 169 \fBSee also:\fP
 170 .RS 4
 171 kdbiDecodeChar
 172 .RE
 173 .PP
 174 NOTE: No '\\0' is added at the end of buffer.
 175 .SS "int kdbbFilenameToKeyName (const char * string, char * buffer, int bufSize)"
 176 .PP
 177 Translate a relative file name to a key name applying decoding.
 178 .PP
 179 \fBParameters:\fP
 180 .RS 4
 181 \fIstring\fP Filename
 182 .br
 183 \fIbuffer\fP decoded keyName
 184 .br
 185 \fIbufSize\fP Size of buffer
 186 .RE
 187 .PP
 188 \fBReturns:\fP
 189 .RS 4
 190 0 on success
 191 .PP
 192 -1 on failure
 193 .RE
 194 .PP
 195 \fBSee also:\fP
 196 .RS 4
 197 \fBkdbbKeyNameToRelativeFilename\fP
 198 .RE
 199 .PP
 200
 201 .SS "ssize_t kdbbGetFullFilename (KDB * handle, const Key * forKey, char * returned, size_t maxSize)"
 202 .PP
 203 Calculate the real file name for a key.
 204 .PP
 205 system/ keys will get the prefix KDB_DB_SYSTEM
 206 .PP
 207 For the user/ keys the algorithm works as follow: 1.) When the override environment KDB_HOME exists the configuration will be searched below KDB_HOME/KDB_DB_USER 2.) When the owner of the key exists in the elektra user database steps a.) and b.) will be tested: a.) The specific value for configuration storage of the user below system/users/<owner>/kdb b.) The home variable in system/users/<owner>/home will be merged together with KDB_DB_USER 3.) When the environment HOME exists the configuration will be searched below HOME/KDB_DB_USER 4.) Otherwise the KDB_DB_HOME/<owner>/KDB_DB_USER will be used
 208 .PP
 209 \fBParameters:\fP
 210 .RS 4
 211 \fIforKey\fP the key object to work with
 212 .br
 213 \fIhandle\fP the kdb handle to work with
 214 .br
 215 \fIreturned\fP the buffer to return the calculated filename
 216 .br
 217 \fImaxSize\fP maximum number of bytes that fit the buffer
 218 .RE
 219 .PP
 220 \fBSee also:\fP
 221 .RS 4
 222 kdbCalcRelativeFilename()
 223 .RE
 224 .PP
 225 \fBReturns:\fP
 226 .RS 4
 227 number of bytes written to the buffer, or 0 on error
 228 .PP
 229 length of returned string on success
 230 .PP
 231 -1 on failure
 232 .RE
 233 .PP
 234
 235 .SS "ssize_t kdbbGetFullKeyName (KDB * handle, const char * forFilename, const Key * parentKey, Key * returned)"
 236 .PP
 237 Calculates the keyname out of a relative filename.
 238 .PP
 239 \fBParameters:\fP
 240 .RS 4
 241 \fIhandle\fP The kdb handle to work with
 242 .br
 243 \fIforFilename\fP needs to be the a null terminated string containing the relative filename
 244 .br
 245 \fIparentKey\fP is the key above the key which will be returned
 246 .br
 247 \fIreturned\fP The proper keyname and owner will be stored in returned. A valid key must be passed.
 248 .RE
 249 .PP
 250 \fBReturns:\fP
 251 .RS 4
 252 number of bytes written to the buffer, or 0 on error
 253 .PP
 254 length of returned string on success
 255 .PP
 256 -1 on failure
 257 .RE
 258 .PP
 259 \fBSee also:\fP
 260 .RS 4
 261 \fBkdbbKeyNameToRelativeFilename()\fP
 262 .RE
 263 .PP
 264
 265 .SS "ssize_t kdbbKeyCalcRelativeFilename (const Key * key, char * relativeFilename, size_t maxSize)"
 266 .PP
 267 This is a helper to kdbGetFullFilename()
 268 .PP
 269 \fBParameters:\fP
 270 .RS 4
 271 \fIkey\fP has the relevant name for the relative filename
 272 .br
 273 \fIrelativeFilename\fP the buffer to return the calculated filename
 274 .br
 275 \fImaxSize\fP maximum number of bytes that fit the buffer
 276 .RE
 277 .PP
 278 \fBSee also:\fP
 279 .RS 4
 280 kdbGetFullFilename()
 281 .RE
 282 .PP
 283 \fBReturns:\fP
 284 .RS 4
 285 number of bytes written to the buffer
 286 .PP
 287 -1 on failure
 288 .RE
 289 .PP
 290
 291 .SS "int kdbbKeyNameToRelativeFilename (const char * string, char * buffer, size_t bufSize)"
 292 .PP
 293 Translate a key name to a relative file name applying encoding.
 294 .PP
 295 \fBParameters:\fP
 296 .RS 4
 297 \fIstring\fP Keyname
 298 .br
 299 \fIbuffer\fP kdbbEncoded filename
 300 .br
 301 \fIbufSize\fP Size of buffer
 302 .RE
 303 .PP
 304 \fBReturns:\fP
 305 .RS 4
 306 Number of byte written in buffer on success,
 307 .PP
 308 -1 on failure
 309 .RE
 310 .PP
 311 \fBSee also:\fP
 312 .RS 4
 313 \fBkdbbKeyNameToRelativeFilename\fP
 314 .RE
 315 .PP
 316
 317 .SS "int kdbbNeedsUTF8Conversion (void)"
 318 .PP
 319 Checks if UTF-8 conversion is needed in current context. if nl_langinfo() is not available, no conversion is ever needed. If iconv usage is disabled there is no need to check if we need to convert. Furthermore, some systems have nl_langinfo(), but lacks ability to get CODESET through it. Look at the comments by the \fBkdbbUTF8Engine()\fP function for more information.
 320 .PP
 321 \fBReturns:\fP
 322 .RS 4
 323 0 if not needed
 324 .PP
 325 anything else if needed
 326 .RE
 327 .PP
 328
 329 .SS "int kdbbReadLock (FILE * f)"
 330 .PP
 331 Locks file for read mode.
 332 .PP
 333 Other processes and threads are allowed to read the file too simultaneous.
 334 .PP
 335 \fBParameters:\fP
 336 .RS 4
 337 \fIf\fP is a valid filedescriptor
 338 .RE
 339 .PP
 340 \fBReturns:\fP
 341 .RS 4
 342 0 on success
 343 .PP
 344 -1 on failure
 345 .RE
 346 .PP
 347 \fBError\fP
 348 .RS 4
 349 sets KDB_ERR_NOLOCK when locking failed
 350 .RE
 351 .PP
 352
 353 .SS "int kdbbUnlock (FILE * f)"
 354 .PP
 355 Unlocks file.
 356 .PP
 357 \fBParameters:\fP
 358 .RS 4
 359 \fIf\fP is a valid filedescriptor
 360 .RE
 361 .PP
 362 \fBReturns:\fP
 363 .RS 4
 364 0 on success
 365 .PP
 366 -1 on failure
 367 .RE
 368 .PP
 369 \fBError\fP
 370 .RS 4
 371 sets KDB_ERR_NOLOCK when locking failed
 372 .RE
 373 .PP
 374
 375 .SS "int kdbbUTF8Engine (int direction, char ** string, size_t * inputOutputByteSize)"
 376 .PP
 377 Converts string to (\fCdirection\fP = \fCUTF8_TO\fP) and from (\fCdirection\fP = \fCUTF8_FROM\fP) UTF-8.
 378 .PP
 379 Since Elektra provides portability for key names and string values between different codesets, you should use this helper in your backend to convert to and from universal UTF-8 strings, when storing key names, values and comments.
 380 .PP
 381 Broken locales in applications can cause problems too. Make sure to load the environment locales in your application using
 382 .PP
 383 .nf
 384 setlocale (LC_ALL, '');
 385
 386 .fi
 387 .PP
 388 .PP
 389 Otherwise kdbbUTF8Engine will quit with -1 leading that backends return with error when non-ascii characters appear. Binary values are not effected.
 390 .PP
 391 If iconv() or nl_langinfo() is not available on your system, or if iconv() usage is disabled (--disable-iconv on build time) simply return 0 immediately.
 392 .PP
 393 \fBParameters:\fP
 394 .RS 4
 395 \fIdirection\fP must be \fCUTF8_TO\fP (convert from current non-UTF-8 to UTF-8) or \fCUTF8_FROM\fP (convert from UTF-8 to current non-UTF-8)
 396 .br
 397 \fIstring\fP before the call: the string to be converted; after the call: reallocated to carry the converted string
 398 .br
 399 \fIinputOutputByteSize\fP before the call: the size of the string including leading NULL; after the call: the size of the converted string including leading NULL
 400 .RE
 401 .PP
 402 \fBReturns:\fP
 403 .RS 4
 404 0 on success
 405 .PP
 406 -1 on failure
 407 .RE
 408 .PP
 409
 410 .SS "int kdbbWriteLock (FILE * f)"
 411 .PP
 412 Locks file for exclusive write mode.
 413 .PP
 414 This function will block until all reader and writer have left the file.
 415 .PP
 416 \fBParameters:\fP
 417 .RS 4
 418 \fIf\fP is a valid filedescriptor
 419 .RE
 420 .PP
 421 \fBReturns:\fP
 422 .RS 4
 423 0 on success
 424 .PP
 425 -1 on failure
 426 .RE
 427 .PP
 428 \fBError\fP
 429 .RS 4
 430 sets KDB_ERR_NOLOCK when locking failed
 431 .RE
 432 .PP
 433