The Elektra API

Elektra Initiative Overview

Elektra provides a universal and secure framework to store configuration parameters in a global, hierarchical key database. The core is a small library implemented in C. The plugin-based framework fulfills many configuration-related tasks to avoid any unnecessary code duplication across applications while it still allows the core to stay without any external dependency. Elektra abstracts from cross-platform-related issues with an consistent API, and allows applications to be aware of other applications' configurations, leveraging easy application integration.

See the website for more information http://www.libelektra.org

API docu

This document occupies with the API implementation, documentation, internals and plugins. On the one hand it gives an overview and an introduction for developers using Elektra, on the other hand it gives an informal descriptions what methods must and may provide to allow an alternative implementation of the API.

The current version (for stable releases) of this document can be found at http://doc.libelektra.org/api/current/html

The latest version (from git master) of this document can be found at http://doc.libelektra.org/api/latest/html

Using the Elektra Library

A C or C++ source file that wants to use Elektra should include:

#include <kdb.h>

To link an executable with the Elektra library, one way is to use the pkg-config tool:

$ gcc -o application `pkg-config --cflags --libs elektra` application.c

Another way is to use CMake:

find_package(Elektra REQUIRED)
include_directories (${ELEKTRA_INCLUDE_DIR})
target_link_libraries (application ${ELEKTRA_LIBRARIES})

Elektra API

The API was written in pure C because Elektra was designed to be useful even for the most basic system programs.

The API follows an object-oriented design, and there are 3 main classes as shown by the figure:

Elektra Classes

Some general things you can do with each class are:

KDB (Key Database)

• Open and Close the Key Database
• Get and Set KeySet in the Key Database
• See class documentation for more

Key

• Create and Delete
• Get and Set key the name
• Get and Set string or binary values
• Get and Set Meta Data
• See class documentation for more

KeySet

• Create and Delete
• Append a single key or an entire KeySet
• Work with its internal cursor
• See class documentation for more

Namespaces

There are 5 trees (=namespaces) of keys: spec, proc, dir, user and system that are all unified (in the given order) in one cascading tree starting with /.

The cascading tree is the logical tree to be used in applications. The other trees are the physical ones that stem from configuration sources. When using cascading key the best key will be searched at runtime, which appears like a tree on its own. See Cascading in the documentation of ksLookupByName() how the selection of keys works.

• The spec tree
  This tree specifies how the lookup should take place and also allows us to define defaults or document a key. The metadata of a key contains this information:
  • override/#: use these keys in favour of the key itself (note that # is the syntax for arrays, e.g. #0 for the first element, #_10 for the 11th and so on)
  • namespace/#: instead of using all namespaces in the predefined order, one can specify which namespaces should be searched in which order
  • fallback/#: when no key was found in any of the (specified) namespaces the fallback-keys will be searched
  • default: this value will be used if nothing else was found

• The proc tree
  Is the only read-only tree. The configuration does not stem from the KDB (Key Database) , but any other source, e.g. command-line arguments or environment.

• The dir tree
  Allows us to have a per-directory overwrite of configuration files, e.g. for project specific settings.

• The user" tree
  Used to store user-specific configurations, like the personal settings of a user to certain programs. The user subtree will always be favoured if present (except for security concerns the user subtree may not be considered).

• The system tree
  It is provided to store system-wide configuration keys, that is, the last fallback for applications but the only resort for daemons and system services.

Rules for Key Names

When using Elektra to store your application's configuration and state, please keep in mind the following rules:

• You are not allowed to create keys right under the root. They are reserved for more generic purposes.
• The keys for your application, called say myapp, should be created under /sw/org/myapp/#0/current
  • sw is for software
  • org is the organisation. For uniqueness a full reverse url encoded with '/' instead of '.' is useful.
  • #0 is the major version of the configuration
  • current is the default configuration profile.
  • That means you just need to kdbGet() /sw/org/myapp/#0/profile and then ksLookupByName() in /sw/org/myapp/#0/profile/key where profile is from command-line arguments and defaults to current.

Backend Overview

The core of Elektra does not store configuration itself to the harddisk. Instead this work is delegated to backends.

If you want to develop a backend, you should already have some experience with Elektra from the user point of view. You should be familiar with the data structures: Key and KeySet Then you can start reading about Backends that are composed out of Plugins. To get started with writing plugins, first read our plugin tutorial in doc/tutorials!

Glossary

• pop, used in ksPop() and KDB_O_POP means to remove a key from a keyset.
• delete, or abbr. del, used in keyDel(), ksDel() and KDB_O_DEL means to free a key or keyset. The memory can be used for something else afterwards.
• remove means that the key/value information in the physical database will be removed permanently.