.TH "md_doc_help_elektra-namespaces" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
md_doc_help_elektra-namespaces \- elektra-namespaces(7) -- namespaces 
Every key in Elektra has a unique name\&. Sometimes, multiple keys denote the same configuration item from different sources, e\&.g\&.:
.PP
.IP "\(bu" 2
by a commandline argument
.IP "\(bu" 2
by a configuration file found below the home directory
.IP "\(bu" 2
by a configuration file found below /etc
.PP
.PP
To allow such keys to exist in parallel, Elektra uses namespaces\&.
.PP
A namespace has following properties:
.PP
.IP "\(bu" 2
in-memory Keys can start with this name
.IP "\(bu" 2
these keys stem from a specific configuration source
.IP "\(bu" 2
\fBksLookup()\fP uses namespaces in a specific default order unless specified otherwise
.PP
.PP
Following parts of Elektra are affected by namespaces:
.PP
.IP "\(bu" 2
the key name validation in \fBkeySetName()\fP
.IP "\(bu" 2
\fBkeyGetNamespace()\fP which enumerates all namespaces
.IP "\(bu" 2
_Backend and split\&.c for correct distribution to plugins (note that not all namespaces actually are distributed to configuration files)
.IP "\(bu" 2
mount\&.c for cascading and root backends
.IP "\(bu" 2
and of course many unit tests
.PP
.PP
In the rest of this document all currently available namespaces in the default order are described\&.
.PP
.SS "spec"
.PP
Unlike the other namespaces, the specification namespace does not contain values of the keys, but instead meta data as described in [METADATA\&.ini]\&.
.PP
When a key is looked up, keys from the spec-namespace are the first to be searched\&. When a spec-key is found, the rest of the lookup will be done as specified, probably in a different order than the namespaces enlisted here\&.
.PP
Usually, the spec-keys do not directly contribute to the value, with one notable exception: the default value (meta data \fCdefault\fP, see in cascading below) might be used if every other way as specified in the spec-key failed\&.
.PP
Spec-keys typically include a explanation and description for the key itself (but not comments which are specific for individual keys)\&.
.PP
The spec configuration files are below CMAKE_INSTALL_PREFIX/KDB_DB_SPEC\&.
.PP
spec is not part of cascading mounts, because the specifications often are written in different syntax than the configuration files\&.
.PP
.SS "proc"
.PP
Derived from the process (e\&.g\&. by parsing /proc/self or by arguments passed from the main method):
.PP
.IP "\(bu" 2
program name
.IP "\(bu" 2
arguments
.IP "\(bu" 2
environment
.PP
.PP
Keys in the namespace proc can not be stored by their nature\&. They might be different for every invocation of an application\&.
.PP
.SS "dir"
.PP
Keys from the namespace \fCdir\fP are derived from a directory special to the user starting/using the application, e\&.g\&.:
.PP
.IP "\(bu" 2
the current working directory for project specific settings, e\&.g\&. \&.git
.IP "\(bu" 2
the directory a server wants to present to the user, e\&.g\&. \&.htaccess
.PP
.PP
Note that Elektra only supports a single special directory per KDB instance\&. Start a new KDB instance if you need different special directories for different parts of your application\&. How to change the directory may be different dependent on the resolver, e\&.g\&. by using chdir or by setting the environment variable PWD
.PP
.SS "user"
.PP
On multi-user operating systems obviously every user wants her/his own configuration\&. The user configuration is located in the users home directory typically below the folder KDB_DB_USER\&. Other pathes below the home directory are possible too (absolute path for resolver)\&.
.PP
Note that Elektra only supports a user directory per KDB instance\&. Start a new KDB instance if you need different user configuration for different parts of your application\&. How to change the user may be different dependent on the resolver, e\&.g\&. by seteuid() or by environment variables like HOME, USER
.PP
.SS "system"
.PP
The system configuration is the same for every chroot\&.
.PP
The configuration is typically located below KDB_DB_SYSTEM\&. Other absolut pathes, e\&.g\&. below /opt or /usr/local/etc are possible too\&.
.PP
.SS "cascading"
.PP
Keys that are not in a namespace (i\&.e\&. start with an \fC/\fP) are called cascading keys\&. Cascading keys do not stem from a configuration source, but are used by applications to lookup a key in different namespaces\&. So, multiple keys can contribute to each cascading key name\&.
.PP
Cascading is the same as a name resolution and provides a namespace unification as described in \fCVersatility and Unix semantics in namespace unification\fP\&.
.PP
Keys without a namespace can not be stored by their nature\&. So they are transient: after a restart they are forgotten\&.
.PP
Keys of that namespace are only used by ksLookup when no other suitable key was found\&. So they have the lowest possible priority, even fallback keys are preferred\&.
.PP
\fBRead more about cascading\&.\fP