Functions | |
| int | kdbbWriteLock (FILE *f) |
| int | kdbbReadLock (FILE *f) |
| int | kdbbUnlock (FILE *f) |
| ssize_t | kdbbEncode (void *kdbbDecoded, size_t size, char *returned) |
| ssize_t | kdbbDecode (char *kdbbEncoded, void *returned) |
| int | kdbbNeedsUTF8Conversion () |
| int | kdbbUTF8Engine (int direction, char **string, size_t *inputOutputByteSize) |
| int | kdbbEncodeChar (char c, char *buffer, size_t bufSize) |
| int | kdbbDecodeChar (const char *from, char *into) |
| int | kdbbFilenameToKeyName (const char *string, char *buffer, int bufSize) |
| ssize_t | kdbbGetFullKeyName (KDB *handle, const char *forFilename, const Key *parentKey, Key *returned) |
| int | kdbbKeyNameToRelativeFilename (const char *string, char *buffer, size_t bufSize) |
| ssize_t | kdbbKeyCalcRelativeFilename (const Key *key, char *relativeFilename, size_t maxSize) |
| ssize_t | kdbbGetFullFilename (KDB *handle, const Key *forKey, char *returned, size_t maxSize) |
To use them:
#include <kdbbackend.h>
These backend helper methods provide functionality commonly used by backends to make backend development easier and to provide the same behaviour between backends.
| ssize_t kdbbDecode | ( | char * | kdbbEncoded, | |
| void * | returned | |||
| ) |
UnkdbbEncodes a buffer of ASCII hexadecimal values into a byte stream.
The allowed format for the hexadecimal values is just a stream of pairs of plain hex-digits, all together or space-separated.
The returned data won't be bigger than half the size of the source kdbbEncoded data.
| kdbbEncoded | the source of ASCII hexadecimal digits. | |
| returned | preallocated destination for the kdbbDecoded data. |
-1 on failure
| int kdbbDecodeChar | ( | const char * | from, | |
| char * | into | |||
| ) |
Char decoding.
Decode one char from 25, 2B, 2F, 2C following RFC 2396 or copy char untouched if different.
| from | String containing sequence to decode | |
| into | Decoded char |
| ssize_t kdbbEncode | ( | void * | kdbbDecoded, | |
| size_t | size, | |||
| char * | returned | |||
| ) |
Encodes a buffer of data onto hexadecimal ASCII.
The resulting data is made up of pairs of ASCII hex-digits, space- and newline-separated. This is the counterpart of kdbbDecode().
The returned must allocated prior you call this function and won't be bigger than 3 times the size of the source kdbbDecoded + 1 byte.
| kdbbDecoded | the source buffer. | |
| size | the size of the source buffer in bytes. | |
| returned | the preallocated destination for the ASCII-kdbbEncoded data. |
| int kdbbEncodeChar | ( | char | c, | |
| char * | buffer, | |||
| size_t | bufSize | |||
| ) |
Char encoding.
Encode '/', '\', '', '+', ' ' char following RFC 2396 or copy char untouched if different.
| c | Char to kdbbEncode | |
| buffer | string wich will contain kdbbEncoded char | |
| bufSize | Size of the buffer |
| int kdbbFilenameToKeyName | ( | const char * | string, | |
| char * | buffer, | |||
| int | bufSize | |||
| ) |
Translate a relative file name to a key name applying decoding.
| string | Filename | |
| buffer | decoded keyName | |
| bufSize | Size of buffer |
-1 on failure
| ssize_t kdbbGetFullFilename | ( | KDB * | handle, | |
| const Key * | forKey, | |||
| char * | returned, | |||
| size_t | maxSize | |||
| ) |
Calculate the real file name for a key.
system/ keys will get the prefix KDB_DB_SYSTEM
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
| forKey | the key object to work with | |
| handle | the kdb handle to work with | |
| returned | the buffer to return the calculated filename | |
| maxSize | maximum number of bytes that fit the buffer |
length of returned string on success
-1 on failure
| ssize_t kdbbGetFullKeyName | ( | KDB * | handle, | |
| const char * | forFilename, | |||
| const Key * | parentKey, | |||
| Key * | returned | |||
| ) |
Calculates the keyname out of a relative filename.
| handle | The kdb handle to work with | |
| forFilename | needs to be the a null terminated string containing the relative filename | |
| parentKey | is the key above the key which will be returned | |
| returned | The proper keyname and owner will be stored in returned. A valid key must be passed. |
length of returned string on success
-1 on failure
| ssize_t kdbbKeyCalcRelativeFilename | ( | const Key * | key, | |
| char * | relativeFilename, | |||
| size_t | maxSize | |||
| ) |
This is a helper to kdbGetFullFilename()
| key | has the relevant name for the relative filename | |
| relativeFilename | the buffer to return the calculated filename | |
| maxSize | maximum number of bytes that fit the buffer |
-1 on failure
| int kdbbKeyNameToRelativeFilename | ( | const char * | string, | |
| char * | buffer, | |||
| size_t | bufSize | |||
| ) |
Translate a key name to a relative file name applying encoding.
| string | Keyname | |
| buffer | kdbbEncoded filename | |
| bufSize | Size of buffer |
-1 on failure
| int kdbbNeedsUTF8Conversion | ( | void | ) |
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 kdbbUTF8Engine() function for more information.
anything else if needed
| int kdbbReadLock | ( | FILE * | f | ) |
Locks file for read mode.
Other processes and threads are allowed to read the file too simultaneous.
| f | is a valid filedescriptor |
-1 on failure
| int kdbbUnlock | ( | FILE * | f | ) |
Unlocks file.
| f | is a valid filedescriptor |
-1 on failure
| int kdbbUTF8Engine | ( | int | direction, | |
| char ** | string, | |||
| size_t * | inputOutputByteSize | |||
| ) |
Converts string to (direction = UTF8_TO) and from (direction = UTF8_FROM) UTF-8.
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.
Broken locales in applications can cause problems too. Make sure to load the environment locales in your application using
setlocale (LC_ALL, "");
Otherwise kdbbUTF8Engine will quit with -1 leading that backends return with error when non-ascii characters appear. Binary values are not effected.
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.
| direction | must be UTF8_TO (convert from current non-UTF-8 to UTF-8) or UTF8_FROM (convert from UTF-8 to current non-UTF-8) | |
| string | before the call: the string to be converted; after the call: reallocated to carry the converted string | |
| inputOutputByteSize | before the call: the size of the string including leading NULL; after the call: the size of the converted string including leading NULL |
-1 on failure
| int kdbbWriteLock | ( | FILE * | f | ) |
Locks file for exclusive write mode.
This function will block until all reader and writer have left the file.
| f | is a valid filedescriptor |
-1 on failure
1.5.6