.TH "md_src_plugins_resolver_README" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
md_src_plugins_resolver_README \- README 

.IP "\(bu" 2
infos = All information you want to know are in keys below
.IP "\(bu" 2
infos/author = Markus Raab elektra@markus-raab.org
.IP "\(bu" 2
infos/licence = BSD
.IP "\(bu" 2
infos/provides = resolver
.IP "\(bu" 2
infos/placements = rollback getresolver setresolver commit
.IP "\(bu" 2
infos/needs =
.IP "\(bu" 2
infos/description = 
.PP
.PP
The @ handles operating system dependent tasks\&. One task is the resolving of the filenames for user and system (hence its name)
.PP
We have an optimistic approach\&. Locking is only used to detect concurrent cooperative processes in the short moment between prepare and commit\&. A conflict will be raised in that situation\&. When processes do not lock the file it might be overwritten\&. This is unavoidable because such problems can only be detected in the commit phase when it is too late for rollbacks\&.
.PP
.SS "Resolving Files"
.PP
Use following command to see to which file is resolved to: 
.PP
.nf
kdb file <Elektra path you are interested in>

.fi
.PP
.PP
See the constants of this plugin for further information, that are: 
.PP
.nf
system/elektra/modules/resolver/constants
system/elektra/modules/resolver/constants/ELEKTRA_VARIANT_SYSTEM
system/elektra/modules/resolver/constants/ELEKTRA_VARIANT_USER
system/elektra/modules/resolver/constants/KDB_DB_HOME
system/elektra/modules/resolver/constants/KDB_DB_SYSTEM
system/elektra/modules/resolver/constants/KDB_DB_USER
system/elektra/modules/resolver/constants/KDB_DB_SPEC
system/elektra/modules/resolver/constants/KDB_DB_DIR

.fi
.PP
.PP
The build-in resolving works like (with ~ and \fCpwd\fP resolved from system):
.PP
.IP "\(bu" 2
for spec with absolute path: path
.IP "\(bu" 2
for spec with relative path: KDB_DB_SPEC + path
.IP "\(bu" 2
for dir with absolute path: \fCpwd\fP + path (or above when path is found)
.IP "\(bu" 2
for dir with relative path: \fCpwd\fP + KDB_DB_DIR + path (or above when path is found)
.IP "\(bu" 2
for user with absolute path: ~ + path
.IP "\(bu" 2
for user with relative path: ~ + KDB_DB_USER + path
.IP "\(bu" 2
for system with absolute path: path
.IP "\(bu" 2
for system with relative path: KDB_DB_SYSTEM + path
.PP
.PP
.SS "Example"
.PP
For an absolute path /example\&.ini, you might get following values:
.PP
.IP "\(bu" 2
for spec: /example\&.ini
.IP "\(bu" 2
for dir: \fCpwd\fP/example\&.ini
.IP "\(bu" 2
for user: ~/example\&.ini
.IP "\(bu" 2
for system: /example\&.ini
.PP
.PP
For an relative path example\&.ini, you might get following values:
.PP
.IP "\(bu" 2
for spec: /usr/share/elektra/specification/example\&.ini
.IP "\(bu" 2
for dir: \fCpwd\fP/\&.dir/example\&.ini
.IP "\(bu" 2
for user: ~/\&.config/example\&.ini
.IP "\(bu" 2
for system: /etc/kdb/example\&.ini
.PP
.PP
.SS "Variants"
.PP
Many variants exist that additionally influence the lookup process, typically by using environment variables\&.
.PP
Environment variables are very simple for one-time usage but their maintenance in start-up scripts is problematic\&. Additionally, they are controlled by the user, so they cannot be trusted\&. So it is not recommended to use environment variables\&.
.PP
Note that the file permissions apply, so it might be possible for non-root to modify keys in system\&.
.PP
.SS "XDG Compatibility"
.PP
The resolver is fully \fCXDG compatible\fP if configured with the variant:
.PP
.IP "\(bu" 2
xp, xh or xu for user (either using passwd, HOME or USER as fallback or any combination of these fallbacks)
.IP "\(bu" 2
x for system, no fallback necessary
.PP
.PP
Additionally KDB_DB_USER needs to be left unchanged as \fC\&.config\fP\&.
.PP
XDG_CONFIG_DIRS will be used to resolve system pathes the following way:
.PP
.IP "\(bu" 2
if unset or empty /etc/xdg will be used instead
.IP "\(bu" 2
all elements are searched in order of importance
.IP "  \(bu" 4
if a file was found, the search process is stopped
.IP "  \(bu" 4
if no file was found, the least important element will be used for potential write attempts\&.
.PP

.PP
.PP
.SS "Reading Configuration"
.PP
1\&.) If no update needed (unchanged modification time): ABORT 2\&.) remember the last stat time (last update)
.PP
.SS "Writing Configuration"
.PP
0\&.) On empty configuration: remove the configuration file and ABORT 1\&.) Open the configuration file If not available recursively create directories and retry\&. #ifdef ELEKTRA_LOCK_MUTEX 1\&.) Try to lock a global mutex, if not possible -> conflict #endif #ifdef ELEKTRA_LOCK_FILE 1\&.) Try to lock the configuration file, if not possible -> conflict #endif 2\&.) Check the update time -> conflict 3\&.) Update the update time (in order to not self-conflict)