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:

kdbbEncoded	the source of ASCII hexadecimal digits.
returned	preallocated 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:

from	String containing sequence to decode
into	Decoded 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:

kdbbDecoded	the source buffer.
size	the size of the source buffer in bytes.
returned	the 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:

c	Char to kdbbEncode
buffer	string wich will contain kdbbEncoded char
bufSize	Size 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:

string	Filename
buffer	decoded keyName
bufSize	Size 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:

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

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:

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.

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:

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

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:

string	Keyname
buffer	kdbbEncoded filename
bufSize	Size 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:

f	is 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:

f	is 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:

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

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:

f	is a valid filedescriptor

Returns:: 0 on success; -1 on failure

Error:: sets KDB_ERR_NOLOCK when locking failed

Functions

Detailed Description

Function Documentation