
\begin{DoxyItemize}
\item infos = All information you want to know is in keys below
\item infos/author = Markus Raab \href{mailto:elektra@markus-raab.org}{\tt elektra@markus-\/raab.\+org}
\item infos/licence = B\+SD
\item infos/provides = resolver
\item infos/needs =
\item infos/placements = rollback getresolver setresolver commit
\item infos/status = productive maintained specific unittest tested libc nodep configurable
\item infos/description = system independent resolver
\end{DoxyItemize}

The @ handles operating system dependent tasks. One task is the resolving of the filenames for user and system (hence its name).

Use following command to see to which file is resolved to\+: \begin{DoxyVerb}kdb file <Elektra path you are interested in>
\end{DoxyVerb}


See the constants of this plugin for further information, they are\+: \begin{DoxyVerb}system/elektra/modules/@PLUGIN_SHORT_NAME@/constants
system/elektra/modules/@PLUGIN_SHORT_NAME@/constants/ELEKTRA_VARIANT_SYSTEM
system/elektra/modules/@PLUGIN_SHORT_NAME@/constants/ELEKTRA_VARIANT_USER
system/elektra/modules/@PLUGIN_SHORT_NAME@/constants/KDB_DB_HOME
system/elektra/modules/@PLUGIN_SHORT_NAME@/constants/KDB_DB_SYSTEM
system/elektra/modules/@PLUGIN_SHORT_NAME@/constants/KDB_DB_USER
system/elektra/modules/@PLUGIN_SHORT_NAME@/constants/KDB_DB_SPEC
system/elektra/modules/@PLUGIN_SHORT_NAME@/constants/KDB_DB_DIR
\end{DoxyVerb}


The build-\/in resolving considers following cases\+:


\begin{DoxyItemize}
\item for spec with absolute path\+: path
\item for spec with relative path\+: K\+D\+B\+\_\+\+D\+B\+\_\+\+S\+P\+EC + path
\item for dir with absolute path\+: {\ttfamily pwd} + path (or above when path is found)
\item for dir with relative path\+: {\ttfamily pwd} + K\+D\+B\+\_\+\+D\+B\+\_\+\+D\+IR + path (or above when path is found)
\item for user with absolute path\+: $\sim$ + path
\item for user with relative path\+: $\sim$ + K\+D\+B\+\_\+\+D\+B\+\_\+\+U\+S\+ER + path
\item for system with absolute path\+: path
\item for system with relative path\+: K\+D\+B\+\_\+\+D\+B\+\_\+\+S\+Y\+S\+T\+EM + path
\end{DoxyItemize}

($\sim$ and {\ttfamily pwd} are resolved from system)

\subsection*{Example}

For an absolute path /example.ini, you might get following values\+:


\begin{DoxyItemize}
\item for spec\+: /example.ini
\item for dir\+: {\ttfamily pwd}/example.ini
\item for user\+: $\sim$/example.ini
\item for system\+: /example.ini
\end{DoxyItemize}

For an relative path example.\+ini, you might get following values\+:


\begin{DoxyItemize}
\item for spec\+: /usr/share/elektra/specification/example.ini
\item for dir\+: {\ttfamily pwd}/.dir/example.\+ini
\item for user\+: $\sim$/.config/example.\+ini
\item for system\+: /etc/kdb/example.ini
\end{DoxyItemize}

See \hyperlink{doc_tutorials_mount_md}{the mount tutorial} for more examples.

\subsection*{Variants}

Many variants exist that additionally influence the resolving process, typically by using environment variables.

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.

Note that the file permissions apply, so it might be possible for non-\/root to modify keys in {\ttfamily system}.

See \hyperlink{doc_COMPILE_md}{C\+O\+M\+P\+I\+LE.md} for a documentation of possible variants.

\subsubsection*{X\+DG Compatibility}

The resolver is fully \href{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}{\tt X\+DG compatible} if configured with the variant\+:


\begin{DoxyItemize}
\item xp, xh or xu for user (either using passwd, H\+O\+ME or U\+S\+ER as fallback or any combination of these fallbacks)
\item x for system, no fallback necessary
\end{DoxyItemize}

Additionally {\ttfamily K\+D\+B\+\_\+\+D\+B\+\_\+\+U\+S\+ER} needs to be left unchanged as {\ttfamily .config}.

{\ttfamily X\+D\+G\+\_\+\+C\+O\+N\+F\+I\+G\+\_\+\+D\+I\+RS} will be used to resolve system paths the following way\+:


\begin{DoxyItemize}
\item if unset or empty {\ttfamily /etc/xdg} will be used instead
\item all elements are searched in order of importance
\begin{DoxyItemize}
\item if a file was found, the search process is stopped
\item if no file was found, the least important element will be used for potential write attempts.
\end{DoxyItemize}
\end{DoxyItemize}

\subsection*{Reading Configuration}


\begin{DoxyEnumerate}
\item If no update needed (unchanged modification time)\+: quit successfully
\item Otherwise call (storage) plugin(s) to read configuration
\item remember the last stat time (last update)
\end{DoxyEnumerate}

\subsection*{Writing Configuration}

0. On unchanged configuration\+: quit successfully
\begin{DoxyEnumerate}
\item On empty configuration\+: remove the configuration file and quit successfully
\item Otherwise, open the configuration file If not available recursively create directories and retry. \#ifdef E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+C\+K\+\_\+\+M\+U\+T\+EX
\item Try to lock a global mutex, if not possible -\/$>$ conflict \#endif \#ifdef E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+C\+K\+\_\+\+F\+I\+LE
\item Try to lock the configuration file, if not possible -\/$>$ conflict \#endif
\item Check the update time -\/$>$ might lead to conflict
\item Update the update time (in order to not self-\/conflict)
\end{DoxyEnumerate}

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, however, very unlikely on file systems with nanosecond precision.

\subsection*{Exported Functions and Data}

The resolver provides 2 functions for other plugins to use.

\subsubsection*{filename}

resolves {\ttfamily path} in with namespace {\ttfamily namespace}, creates a temporary file to work on and returns a struct containing the resolved data.

Signature\+: {\ttfamily Elektra\+Resolved $\ast$ filename (elektra\+Namespace namespace, const char $\ast$ path, Elektra\+Resolve\+Tempfile temp\+File, Key $\ast$ warnings\+Key)}

{\ttfamily Elektra\+Resolved} and {\ttfamily Elektra\+Resolve\+Tempfile} are both defined in \href{/home/markus/Projekte/Elektra/current/src/plugins/resolver/shared.h}{\tt shared.\+h}.

{\ttfamily Elektra\+Resolved} is a struct with the following members\+:
\begin{DoxyItemize}
\item {\ttfamily rel\+Path}\+: contains the path relative to the namespace.
\item {\ttfamily dirname}\+: contains the parent directory of the resolved file.
\item {\ttfamily full\+Path}\+: contains the full path of the resolved file.
\item {\ttfamily tmp\+File}\+: contains the full path of the created temporary file.
\end{DoxyItemize}

{\ttfamily Elektra\+Resolve\+Tempfile} dictates if and where a temporarey file should be created. Possible values\+:
\begin{DoxyItemize}
\item {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+S\+O\+L\+V\+E\+R\+\_\+\+T\+E\+M\+P\+F\+I\+L\+E\+\_\+\+N\+O\+NE}\+: don\textquotesingle{}t create a temporary file.
\item {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+S\+O\+L\+V\+E\+R\+\_\+\+T\+E\+M\+P\+F\+I\+L\+E\+\_\+\+S\+A\+M\+E\+D\+IR}\+: create a temporary file in the same directory as the resolved file.
\item {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+S\+O\+L\+V\+E\+R\+\_\+\+T\+E\+M\+P\+F\+I\+L\+E\+\_\+\+T\+M\+P\+D\+IR}\+: create a temporary file in {\ttfamily /tmp}.
\end{DoxyItemize}

\subsubsection*{free\+Handle}

frees the handle returned by {\ttfamily filename}.

Signature\+: {\ttfamily void $\ast$ free\+Handle (Elektra\+Resolved $\ast$ handle)}

where {\ttfamily handle} is the handle returned by {\ttfamily filename}. 