Elektra Projekt
Functions
KDB Backends :: Backend Helper for Elektra

Backend helper Methods for Elektra and Backends. More...

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)

Detailed Description

Backend helper Methods for Elektra and Backends.

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.

Function Documentation

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.

Parameters
kdbbEncodedthe source of ASCII hexadecimal digits.
returnedpreallocated destination for the kdbbDecoded data.
Returns
the amount of bytes kdbbDecoded
-1 on failure
See Also
kdbbEncode()
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.

Parameters
fromString containing sequence to decode
intoDecoded char
Returns
: Positive size of byte read from "from" for decoding the sequence if sucess or -1 if error (into untouched)
See Also
kdbbEncodeChar

NOTE: No '\0' is added at the end of buffer.

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.

Parameters
kdbbDecodedthe source buffer.
sizethe size of the source buffer in bytes.
returnedthe preallocated destination for the ASCII-kdbbEncoded data.
Returns
the amount of bytes used in the resulting kdbbEncoded buffer.
See Also
kdbbDecode()
int kdbbEncodeChar ( char  c,
char *  buffer,
size_t  bufSize 
)

Char encoding.

Encode '/', '\', '', '+', ' ' char following RFC 2396 or copy char untouched if different.

Parameters
cChar to kdbbEncode
bufferstring wich will contain kdbbEncoded char
bufSizeSize of the buffer
Returns
: Size of the kdbbEncoded string if success or -1 if error * (then buffer is untouched)
See Also
kdbiDecodeChar

NOTE: No '\0' is added at the end of buffer.

int kdbbFilenameToKeyName ( const char *  string,
char *  buffer,
int  bufSize 
)

Translate a relative file name to a key name applying decoding.

Parameters
stringFilename
bufferdecoded keyName
bufSizeSize of buffer
Returns
0 on success
-1 on failure
See Also
kdbbKeyNameToRelativeFilename
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

Parameters
forKeythe key object to work with
handlethe kdb handle to work with
returnedthe buffer to return the calculated filename
maxSizemaximum number of bytes that fit the buffer
See Also
kdbCalcRelativeFilename()
Returns
number of bytes written to the buffer, or 0 on error
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.

Parameters
handleThe kdb handle to work with
forFilenameneeds to be the a null terminated string containing the relative filename
parentKeyis the key above the key which will be returned
returnedThe proper keyname and owner will be stored in returned. A valid key must be passed.
Returns
number of bytes written to the buffer, or 0 on error
length of returned string on success
-1 on failure
See Also
kdbbKeyNameToRelativeFilename()
ssize_t kdbbKeyCalcRelativeFilename ( const Key *  key,
char *  relativeFilename,
size_t  maxSize 
)

This is a helper to kdbGetFullFilename()

Parameters
keyhas the relevant name for the relative filename
relativeFilenamethe buffer to return the calculated filename
maxSizemaximum number of bytes that fit the buffer
See Also
kdbGetFullFilename()
Returns
number of bytes written to 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.

Parameters
stringKeyname
bufferkdbbEncoded filename
bufSizeSize of buffer
Returns
Number of byte written in buffer on success,
-1 on failure
See Also
kdbbKeyNameToRelativeFilename
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.

Returns
0 if not needed
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.

Parameters
fis a valid filedescriptor
Returns
0 on success
-1 on failure
Error:
sets KDB_ERR_NOLOCK when locking failed
int kdbbUnlock ( FILE *  f)

Unlocks file.

Parameters
fis a valid filedescriptor
Returns
0 on success
-1 on failure
Error:
sets KDB_ERR_NOLOCK when locking failed
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.

Parameters
directionmust be UTF8_TO (convert from current non-UTF-8 to UTF-8) or UTF8_FROM (convert from UTF-8 to current non-UTF-8)
stringbefore the call: the string to be converted; after the call: reallocated to carry the converted string
inputOutputByteSizebefore the call: the size of the string including leading NULL; after the call: the size of the converted string including leading NULL
Returns
0 on success
-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.

Parameters
fis a valid filedescriptor
Returns
0 on success
-1 on failure
Error:
sets KDB_ERR_NOLOCK when locking failed