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