| Elektra 0.11.0

Macros | Typedefs | Functions
kdbprivate.h File Reference

Private declarations. More...

`#include <elektra.h>`
`#include <elektra/error.h>`
`#include <kdb.h>`
`#include <kdbextension.h>`
`#include <kdbhelper.h>`
`#include <kdbio.h>`
`#include <kdbmacros.h>`
`#include <kdbnotificationinternal.h>`
`#include <kdbplugin.h>`
`#include <kdbtypes.h>`
`#include <limits.h>`

## Macros
#define | KEYSET_SIZE 16
| The minimal allocation size of a keyset inclusive NULL byte.
#define | APPROXIMATE_NR_OF_BACKENDS 16
| Trie optimization.
#define | KDB_MAX_UCHAR (UCHAR_MAX + 1)
| The maximum value of unsigned char+1, needed for iteration over trie children/values:
#define | MAX_LEN_INT 31
| The maximum of how many characters an integer needs as decimal number.
#define | KDB_SYSTEM_ELEKTRA "system:/elektra"
| Backend mounting information.
#define | KDB_CACHE_PREFIX "system:/elektra/cache"
| All keys below this are used for cache metadata in the global keyset.
#define | test_bit(var, bit) (((unsigned long long) (var)) & ((unsigned long long) (bit)))
| Test a bit.
#define | set_bit(var, bit) ((var) |= ((unsigned long long) (bit)))
| Set a bit.
#define | clear_bit(var, bit) ((var) &= ~((unsigned long long) (bit)))
| Clear a bit.

## Typedefs
typedef struct _BackendData | BackendData
| Holds all data for one backend.

## Functions
struct _ElektraDiff * | elektraDiffNew (KeySet *addedKeys, KeySet *removedKeys, KeySet *modifiedKeys, KeySet *modifiedNewKeys, Key *parentKey)
| Create an ElektraDiff.
Plugin * | elektraPluginOpen (const char *backendname, KeySet *modules, KeySet *config, Key *errorKey)
| Opens a plugin.
size_t | elektraPluginGetFunction (Plugin *plugin, const char *name)
| Retrieves a function exported by a plugin.
int | initHooks (KDB *kdb, const KeySet *config, KeySet *modules, const KeySet *contract, Key *errorKey)
| Initializes the hooks stored in the passed KDB handle.
void | freeHooks (KDB *kdb, Key *errorKey)
| Uninitializes and frees all hooks in the passed KDB handle.
Plugin * | elektraFindInternalNotificationPlugin (KDB *kdb)
| This method looks for the hook plugin 'internalnotification'.
int | keyReplacePrefix (Key *key, const Key *oldPrefix, const Key *newPrefix)
| Replaces a prefix of the key name of `key`.
Key * | elektraKsPopAtCursor (KeySet *ks, elektraCursor pos)
| Pop key at given cursor position.
KeySet * | ksRenameKeys (KeySet *config, const char *name)
| Takes the first key and cuts off this common part for all other keys, instead name will be prepended.
ssize_t | ksRename (KeySet *ks, const Key *root, const Key *newRoot)
| Moves all keys below `root` to below `newRoot`.
elektraCursor | ksFindHierarchy (const KeySet *ks, const Key *root, elektraCursor *end)
| Searches for the start and optionally end of the key hierarchy rooted at `root` in `ks`.
KeySet * | ksBelow (const KeySet *ks, const Key *root)
| Retrieves all Keys from KeySet `ks` that are below or at `root`.
ssize_t | ksSubtract (KeySet *total, const KeySet *sub)
| Remove all the keys in `sub` from `total`.
ssize_t | elektraMemcpy (Key **array1, Key **array2, size_t size)
| Internal Methods for Elektra.
ssize_t | elektraMemmove (Key **array1, Key **array2, size_t size)
| Copies the key array2 into where array1 points.
bool | elektraKeyNameValidate (const char *name, bool isComplete)
| Takes an escaped key name and validates it.
void | elektraKeyNameCanonicalize (const char *name, char **canonicalName, size_t *canonicalSizePtr, size_t offset, size_t *usizePtr)
| Takes a valid (non-)canonical key name and produces its canonical form.
void | elektraKeyNameUnescape (const char *name, char *unescapedName)
| Takes a canonical key name and unescapes it.
size_t | elektraKeyNameEscapePart (const char *part, char **escapedPart)
| Takes a single key name part and produces its escaped form.
int | elektraIsArrayPart (const char *namePart)
| Checks if the given key name part is an array part.
ElektraError * | elektraErrorCreate (const char *code, const char *description, const char *module, const char *file, kdb_long_t line)
| Creates a new ElektraError using the provided values.
void | elektraErrorAddWarning (ElektraError *error, ElektraError *warning)
| Adds a warning to an existing ElektraError struct.
ElektraError * | elektraErrorFromKey (Key *key)
| Extracts the error and all warnings from the given key.
ElektraError * | elektraErrorKeyNotFound (const char *keyname)
| Creates a "Key not found" error.
ElektraError * | elektraErrorWrongType (const char *keyname, KDBType expectedType, KDBType actualType)
| Creates a "Wrong type" error.
ElektraError * | elektraErrorNullError (const char *function)
| Creates a "Null error argument" error.

## Detailed Description

Private declarations.

Copyright
  BSD License (see LICENSE.md or https://www.libelektra.org)

## Macro Definition Documentation

## ◆ clear_bit

#define clear_bit | ( |  | var,
|  |  | bit
| ) |  | ((var) &= ~((unsigned long long) (bit)))

Clear a bit.

See also
  set_bit()

## ◆ KDB_MAX_UCHAR

#define KDB_MAX_UCHAR (UCHAR_MAX + 1)

The maximum value of unsigned char+1, needed for iteration over trie children/values:

for (i=0; i<KDB_MAX_UCHAR; ++i)

## ◆ KDB_SYSTEM_ELEKTRA

#define KDB_SYSTEM_ELEKTRA "system:/elektra"

Backend mounting information.

This key directory tells you where each backend is mounted to which mountpoint.

## ◆ KEYSET_SIZE

#define KEYSET_SIZE 16

The minimal allocation size of a keyset inclusive NULL byte.

ksGetAlloc() will return one less because it says how much can actually be stored.

## ◆ set_bit

#define set_bit | ( |  | var,
|  |  | bit
| ) |  | ((var) |= ((unsigned long long) (bit)))

Set a bit.

See also
  clear_bit()

## ◆ test_bit

#define test_bit | ( |  | var,
|  |  | bit
| ) |  | (((unsigned long long) (var)) & ((unsigned long long) (bit)))

Test a bit.

See also
  set_bit(), clear_bit()

## Typedef Documentation

## ◆ BackendData

typedef struct _BackendData BackendData

Holds all data for one backend.

This struct is used for the key values in _KDB.backends

## Function Documentation

## ◆ elektraDiffNew()

struct _ElektraDiff * elektraDiffNew | ( | KeySet * | addedKeys,
|  | KeySet * | removedKeys,
|  | KeySet * | modifiedKeys,
|  | KeySet * | modifiedNewKeys,
|  | Key * | parentKey
| ) |  |

Create an ElektraDiff.

The returned ElektraDiff contains the same KeySets that are passed in, so be sure to `ksIncRef` them if you plan to use them after deleting the ElektraDiff.

Same goes for the parent key, please use `keyIncRef` if you plan to use it after deleting the ElektraDiff

Parameters

  addedKeys | the added keys
  removedKeys | the removed keys
  modifiedKeys | the modified keys
  modifiedNewKeys | the modified keys with the new values
  parentKey | the parent key

Returns
  ElektraDiff with the provided parameters

## ◆ elektraErrorAddWarning()

void elektraErrorAddWarning | ( | ElektraError * | error,
|  | ElektraError * | warning
| ) |  |

Adds a warning to an existing ElektraError struct.

If you want to report a warning without an error, create a dummy error with elektraErrorPureWarning() and then add a warning to it.

Parameters

  error | The error to which `warning` shall be added.
  warning | The warning to add. Once added it is owned by `error`. DO NOT call elektraErrorReset() on it afterwards.

## ◆ elektraErrorCreate()

ElektraError * elektraErrorCreate | ( | const char * | code,
|  | const char * | description,
|  | const char * | module,
|  | const char * | file,
|  | kdb_long_t | line
| ) |  |

Creates a new ElektraError using the provided values.

The returned value will be allocated with elektraCalloc().

Parameters

  code | The error code of the error. Will be copied and stored in the struct.
  description | The description of the error. Will be copied and stored in the struct.
  module | The module that raised the error. Will be copied and stored in the struct.
  file | The file that raised the error. Will be copied and stored in the struct.
  line | The line in which the error was raised.

Returns
  A newly allocated ElektraError (free with elektraErrorReset()).

## ◆ elektraErrorFromKey()

ElektraError * elektraErrorFromKey | ( | Key * | key | ) |

Extracts the error and all warnings from the given key.

If no error exists, a pure warning error will be used.

See also
  elektraErrorPureWarning

Note
  Use the functions in src/libs/elektra/errors.c to add errors to a key.

Parameters

  key | The to extract error and warnings from.

Returns
  A newly allocated ElektraError (free with elektraErrorReset()).

## ◆ elektraErrorKeyNotFound()

ElektraError * elektraErrorKeyNotFound | ( | const char * | keyname | ) |

Creates a "Key not found" error.

Parameters

  keyname | The name of the key that wasn't found.

Returns
  A newly allocated ElektraError (free with elektraErrorReset()).

## ◆ elektraErrorNullError()

ElektraError * elektraErrorNullError | ( | const char * | function | ) |

Creates a "Null error argument" error.

Parameters

  function | The name of the function that was called with a null pointer error argument.

Returns
  A newly allocated ElektraError (free with elektraErrorReset()).

## ◆ elektraErrorWrongType()

ElektraError * elektraErrorWrongType | ( | const char * | keyname,
|  | KDBType | expectedType,
|  | KDBType | actualType
| ) |  |

Creates a "Wrong type" error.

Parameters

  keyname | The name of the key that had the wrong type.
  expectedType | The type that was expected.
  actualType | The type that was actually found.

Returns
  A newly allocated ElektraError (free with elektraErrorReset()).

## ◆ elektraFindInternalNotificationPlugin()

Plugin * elektraFindInternalNotificationPlugin | ( | KDB * | kdb | ) |

This method looks for the hook plugin 'internalnotification'.

Parameters

  kdb | the KDB instance in which to search

Returns
  NULL if not loaded, pointer to the plugin otherwise

## ◆ elektraKsPopAtCursor()

Key * elektraKsPopAtCursor | ( | KeySet * | ks,
|  | elektraCursor | pos
| ) |  |

Pop key at given cursor position.

Parameters

  ks | the keyset to pop key from
  c | where to pop

Returns
  the popped key

Return values

  0 | if ks is 0

## ◆ elektraMemcpy()

ssize_t elektraMemcpy | ( | Key ** | array1,
|  | Key ** | array2,
|  | size_t | size
| ) |  |

Internal Methods for Elektra.

To use them:

#include <kdbinternal.h>
kdbinternal.h
Includes most internal header files.

There are some areas where libraries have to reimplement some basic functions to archive support for non-standard systems, for testing purposes or to provide a little more convenience. Copies the key array2 into where array1 points. It copies size elements.

Overlapping is prohibited, use elektraMemmove() instead.

Parameters

  array1 | the destination
  array2 | the source
  size | how many pointer to Keys to copy

Return values

  -1 | on null pointers
  0 | if nothing was done

Returns
  size how many keys were copied

## ◆ elektraMemmove()

ssize_t elektraMemmove | ( | Key ** | array1,
|  | Key ** | array2,
|  | size_t | size
| ) |  |

Copies the key array2 into where array1 points.

It copies size elements.

Overlapping is ok. If they do not overlap consider elektraMemcpy() instead.

Parameters

  array1 | the destination
  array2 | the source
  size | how many pointer to Keys to copy

Return values

  -1 | on null pointers
  0 | if nothing was done

Returns
  size how many keys were copied

## ◆ elektraPluginGetFunction()

size_t elektraPluginGetFunction | ( | Plugin * | plugin,
|  | const char * | name
| ) |  |

Retrieves a function exported by a plugin.

Parameters

  plugin | Plugin handle
  name | Function name. Must be a valid key name suffix. May not contain the sequence '..'

Returns
  Pointer to function. NULL if function not found or not enough memory available

## ◆ elektraPluginOpen()

Plugin * elektraPluginOpen | ( | const char * | name,
|  | KeySet * | modules,
|  | KeySet * | config,
|  | Key * | errorKey
| ) |  |

Opens a plugin.

The config will be used as is. So be sure to transfer ownership of the config to it, with e.g. ksDup(). elektraPluginClose() will delete the config.

Returns
  a pointer to a new created plugin or 0 on error

## ◆ freeHooks()

void freeHooks | ( | KDB * | kdb,
|  | Key * | errorKey
| ) |  |

Uninitializes and frees all hooks in the passed KDB handle.

Parameters

  kdb | the KDB handle where the hooks should be freed
  errorKey | the key which holds errors and warnings which were issued

## ◆ initHooks()

int initHooks | ( | KDB * | kdb,
|  | const KeySet * | config,
|  | KeySet * | modules,
|  | const KeySet * | contract,
|  | Key * | errorKey
| ) |  |

Initializes the hooks stored in the passed KDB handle.

If the handle already contains initialized hooks, they will be reinitialized, including unloading and loading of their plugins. Parameters `config` and `contract` will be used to determine which hooks to populate.

Parameters

  kdb | the KDB instance where the hooks should be initialized
  config | KeySet containing the current config in `system:/elektra` namespace
  modules | the current list of loaded modules
  contract | the contract passed to `kdbOpen`
  errorKey | the key which holds errors and warnings which were issued

Returns
  0 on success, -1 on failure