\label{doc_dev_backend-plugins_md_md_doc_dev_backend_plugins}%
\Hypertarget{doc_dev_backend-plugins_md_md_doc_dev_backend_plugins}%
 \hypertarget{doc_dev_backend-plugins_md_autotoc_md2570}{}\doxysection{Backend Contract}\label{doc_dev_backend-plugins_md_autotoc_md2570}
There exists a {\itshape backend contract} between {\ttfamily libelektra-\/kdb} and any plugin acting as a backend plugin. This contract describes\+:


\begin{DoxyItemize}
\item the order of the phases (see \mbox{\hyperlink{doc_dev_kdb-operations_md}{kdb-\/operations.md}})
\item the interactions between a backend plugin and {\ttfamily libelektra-\/kdb}.
\end{DoxyItemize}


\begin{DoxyCode}{0}
\DoxyCodeLine{sequenceDiagram}
\DoxyCodeLine{    actor user}
\DoxyCodeLine{    participant kdb as libelektra-\/kdb}
\DoxyCodeLine{    participant backend as backend}
\DoxyCodeLine{    participant other as other-\/backend}
\DoxyCodeLine{    participant storage}
\DoxyCodeLine{    participant validation}
\DoxyCodeLine{    participant sa as storage-\/unit-\/a (e.g. file)}
\DoxyCodeLine{    participant sb as storage-\/unit-\/b (e.g. database)}
\DoxyCodeLine{}
\DoxyCodeLine{    user-\/>>+kdb: kdbGet}
\DoxyCodeLine{    kdb-\/>>backend: init}
\DoxyCodeLine{    kdb-\/>>other: init}
\DoxyCodeLine{    kdb-\/>>+backend: resolver}
\DoxyCodeLine{    backend-\/>>-\/kdb: "{}storage-\/unit-\/a"{}, update needed}
\DoxyCodeLine{    kdb-\/>>+other: resolver}
\DoxyCodeLine{    other-\/>>-\/kdb: "{}storage-\/unit-\/b"{}, no update needed}
\DoxyCodeLine{    kdb-\/>>backend: prestorage}
\DoxyCodeLine{    kdb-\/>>+backend: storage}
\DoxyCodeLine{    backend-\/>>+storage: \#}
\DoxyCodeLine{    storage-\/>>+sa: \#}
\DoxyCodeLine{    sa-\/-\/>>-\/storage: \#}
\DoxyCodeLine{    storage-\/-\/>>-\/backend: \#}
\DoxyCodeLine{    backend-\/-\/>>-\/kdb: \#}
\DoxyCodeLine{    kdb-\/>>+backend: poststorage}
\DoxyCodeLine{    backend-\/>>+validation: \#}
\DoxyCodeLine{    validation-\/-\/>>-\/backend: \#}
\DoxyCodeLine{    backend-\/-\/>>-\/kdb: \#}
\DoxyCodeLine{    kdb-\/>>kdb: merge backends}
\DoxyCodeLine{    kdb-\/-\/>>-\/user: \#}

\end{DoxyCode}



\begin{DoxyCode}{0}
\DoxyCodeLine{sequenceDiagram}
\DoxyCodeLine{    actor user}
\DoxyCodeLine{    participant kdb as libelektra-\/kdb}
\DoxyCodeLine{    participant backend as backend}
\DoxyCodeLine{    participant other as other-\/backend}
\DoxyCodeLine{    participant storage}
\DoxyCodeLine{    participant validation}
\DoxyCodeLine{    participant sa as storage-\/unit-\/a (e.g. file)}
\DoxyCodeLine{}
\DoxyCodeLine{    user-\/>>+kdb: kdbSet}
\DoxyCodeLine{    kdb-\/>>kdb: check backends initialized}
\DoxyCodeLine{    kdb-\/>>+backend: resolver}
\DoxyCodeLine{    backend-\/-\/>>-\/kdb: "{}storage-\/unit-\/a"{}}
\DoxyCodeLine{    critical try to store}
\DoxyCodeLine{      kdb-\/>>+backend: prestorage}
\DoxyCodeLine{      backend-\/>>+validation: \#}
\DoxyCodeLine{      validation-\/-\/>>-\/backend: \#}
\DoxyCodeLine{      backend-\/-\/>>-\/kdb: \#}
\DoxyCodeLine{      kdb-\/>>+backend: storage}
\DoxyCodeLine{      backend-\/>>+storage: \#}
\DoxyCodeLine{      storage-\/>>+sa: write to temp}
\DoxyCodeLine{      sa-\/-\/>>-\/storage: \#}
\DoxyCodeLine{      storage-\/-\/>>-\/backend: \#}
\DoxyCodeLine{      backend-\/-\/>>-\/kdb: \#}
\DoxyCodeLine{      kdb-\/>>backend: poststorage}
\DoxyCodeLine{      kdb-\/>>backend: precommit}
\DoxyCodeLine{      backend-\/>>sa: make changes permanent}
\DoxyCodeLine{      kdb-\/>>+backend: commit}
\DoxyCodeLine{      backend-\/-\/>-\/kdb: \#}
\DoxyCodeLine{      kdb-\/>>backend: postcommit}
\DoxyCodeLine{    option on failure}
\DoxyCodeLine{      kdb-\/>>backend: prerollback}
\DoxyCodeLine{      kdb-\/>>+backend: rollback}
\DoxyCodeLine{      backend-\/>>sa: revert changes}
\DoxyCodeLine{      backend-\/-\/>>-\/kdb: \#}
\DoxyCodeLine{      kdb-\/>>backend: postrollback}
\DoxyCodeLine{    end}
\DoxyCodeLine{    kdb-\/-\/>>-\/user: \#}

\end{DoxyCode}


The diagrams above show some typical sequences of phases during a {\ttfamily get} and a {\ttfamily set} operation. For each of the phases of a {\ttfamily get} operation {\ttfamily libelektra-\/kdb} calls the backend plugin\textquotesingle{}s {\ttfamily elektra$<$Plugin$>$Get} function once. Similarly, for the phases of a {\ttfamily set} operation {\ttfamily elektra$<$Plugin$>$Set} is called once. The backend plugin can also (optionally) delegate to other plugins.

The current phase is communicated to the backend plugin (and any other plugin) via the global keyset. It can be retrieved via the {\ttfamily elektra\+Plugin\+Get\+Phase} function.\hypertarget{doc_dev_backend-plugins_md_autotoc_md2571}{}\doxysubsection{$<$tt$>$parent\+Key$<$/tt$>$}\label{doc_dev_backend-plugins_md_autotoc_md2571}
The key {\ttfamily parent\+Key} that is given to the backend plugin as an input at various points, must be treated carefully. {\itshape All} modifications to this key will be propagated to the {\ttfamily parent\+Key} that was used to call {\ttfamily kdb\+Get}.

The name of the {\ttfamily parent\+Key} is marked read-\/only and therefore cannot be changed. The value and metadata can, and in some cases must be, changed. Importantly however, there are no guarantees that the metadata of {\ttfamily parent\+Key} can be changed arbitrarily.\hypertarget{doc_dev_backend-plugins_md_autotoc_md2572}{}\doxysubsection{Operation $<$tt$>$get$<$/tt$>$}\label{doc_dev_backend-plugins_md_autotoc_md2572}
The {\ttfamily get} operation is mandatory and all backend plugins must implement it.\hypertarget{doc_dev_backend-plugins_md_autotoc_md2573}{}\doxysubsubsection{Initialization Phase}\label{doc_dev_backend-plugins_md_autotoc_md2573}
During the {\ttfamily init} phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item A key {\ttfamily parent\+Key} whose name is the root of the mountpoint configuration (e.\+g. {\ttfamily system\+:/elektra/mountpoints/system\+:\textbackslash{}/hosts}) and whose value is an empty string. The key name and value of this key are read-\/only. The name of {\ttfamily parent\+Key} is chosen to make it easier for the plugin to produce good error messages.
\item A keyset {\ttfamily definition} containing the mountpoint definition. To make things easier for the plugin, keys in {\ttfamily definition} are renamed to be below {\ttfamily system\+:/}. For example, if the key {\ttfamily system\+:/elektra/mountpoints/system\+:\textbackslash{}/hosts/path} is set in the KDB, then {\ttfamily definition} will contain a key {\ttfamily system\+:/path}.
\item Additionally, the plugins for the current mountpoint are opened by {\ttfamily libelektra-\/kdb} and provided to the backend plugin via the global keyset. They can be accessed via the {\ttfamily elektra\+Plugin\+From\+Mountpoint} function.
\end{DoxyItemize}

The backend plugin then\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} parse the mountpoint definition and store the necessary information for later phases internally.
\item {\bfseries{SHOULD}} validate that the mountpoint definition {\itshape can be} valid.
\item {\bfseries{SHOULD NOT}} do other validation. For example a file-\/based backend, {\itshape should not} check whether the file(s) or path(s) referenced in the mountpoint definition exist. Such a check should be done in the {\ttfamily resolver} phase.
\item {\bfseries{MAY}} decide that the mountpoint should be read-\/only. If so, this must be indicated to {\ttfamily libelektra-\/kdb} via the return value.
\end{DoxyItemize}

This phase exists purely for the backend plugin to initialize and configure itself for the mountpoint.

\begin{quote}
{\bfseries{Note}}\+: This phase is only executed {\itshape once per instance of {\ttfamily KDB}}. Only the first {\ttfamily \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}} call will result in {\ttfamily libelektra-\/kdb} executing this phase, all future calls to {\ttfamily \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}} (and {\ttfamily \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}}) start with the {\ttfamily resolver} phase. The backend plugin must store the necessary information contained in the mountpoint definition internally to accommodate this. \end{quote}
\hypertarget{doc_dev_backend-plugins_md_autotoc_md2574}{}\doxysubsubsection{Resolver Phase}\label{doc_dev_backend-plugins_md_autotoc_md2574}
During the {\ttfamily resolver} phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item A key {\ttfamily parent\+Key} whose name is the parent key of the mountpoint and whose value is an empty string. The key name of this key is read-\/only.
\item An empty keyset {\ttfamily ks}.
\end{DoxyItemize}

The backend plugin then\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} set the value of the {\ttfamily parent\+Key} to a value identifying the storage unit (the {\itshape storage identifier}) that contains the data of the mountpoint. For file-\/based backend plugins, this means setting the value of {\ttfamily parent\+Key} to an absolute filename.
\item {\bfseries{MAY}} set additional metadata on {\ttfamily parent\+Key}, if it is not suitable to encode the information required for the following phases as a single string.
\end{DoxyItemize}

\begin{quote}
{\bfseries{Note}}\+: The backend plugin may also modify the keyset {\ttfamily ks}, but {\ttfamily libelektra-\/kdb} will discard this keyset after this phase, so these modifications won\textquotesingle{}t have any effects. \end{quote}
During a {\ttfamily set} operation, the backend plugin must ensure


\begin{DoxyItemize}
\item that errors in the storage phases can be safely rolled back and
\item that the {\ttfamily set} operation does not affect concurrent operations. For file-\/based backends, this means creating a temporary storage file and returning its absolute filename instead of the name of the actual storage file. In other words, in a {\ttfamily set} operation the {\ttfamily resolver} phase is also about preparing a transaction in addition to resolving the storage unit.
\end{DoxyItemize}\hypertarget{doc_dev_backend-plugins_md_autotoc_md2575}{}\doxysubsubsection{Cache-\/\+Check Phase}\label{doc_dev_backend-plugins_md_autotoc_md2575}
Implementing this phase is optional. If a backend plugin does not support caching, it should immediately return a value indicating that the cache is invalid. If there is no cache entry for this backend, {\ttfamily libelektra-\/kdb} skips this phase.

During the {\ttfamily cachecheck} phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily resolver} phase of this {\ttfamily get} operation. The key name and value of this key are read-\/only. Additionally, the metakey {\ttfamily internal/kdb/cachehandle} is set to a value indicating the cache handle (usually modification time) of the cache entry.
\item An empty keyset {\ttfamily ks}.
\end{DoxyItemize}

The backend plugin then\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} indicate via the return value, whether the cache entry for this backend is still valid.
\end{DoxyItemize}

\begin{quote}
{\bfseries{Note}}\+: The backend plugin may also modify the keyset {\ttfamily ks}, but {\ttfamily libelektra-\/kdb} will discard this keyset after this phase, so these modifications won\textquotesingle{}t have any effects. \end{quote}
\hypertarget{doc_dev_backend-plugins_md_autotoc_md2576}{}\doxysubsubsection{Storage Phases}\label{doc_dev_backend-plugins_md_autotoc_md2576}
These phases are responsible for reading and validating the actual data stored in the KDB.

In the {\ttfamily prestorage} phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily resolver} phase of this {\ttfamily get} operation. The key name and value of this key are read-\/only.
\item An empty keyset {\ttfamily ks}.
\end{DoxyItemize}

There are no restrictions on what the backend plugin may do in this phase, but just like in the {\ttfamily resolver} phase, change to {\ttfamily ks} will be discarded. This phase is useful for file-\/level manipulations, like file-\/based encryption, line ending conversion or verifying file signatures. In this sense, it is the counter-\/part of the {\ttfamily precommit} phase of the {\ttfamily set} operation.

The {\ttfamily storage} phase is for reading the actual data. In this phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily prestorage} phase of this {\ttfamily get} operation. The key name and value of this key are read-\/only.
\item An empty keyset {\ttfamily ks}.
\end{DoxyItemize}

The backend plugin then\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} read the data for the mountpoint from the storage unit that was selected in the {\ttfamily resolver} phase.
\item {\bfseries{MUST}} parse that data and insert it below {\ttfamily parent\+Key} into {\ttfamily ks}.
\end{DoxyItemize}

The last of the storage phases is the {\ttfamily poststorage} phase. In this phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily storage} phase of this {\ttfamily get} operation. The key name and value of this key are read-\/only.
\item The exact {\ttfamily ks} that was returned by the {\ttfamily storage} phase of this {\ttfamily get} operation.
\end{DoxyItemize}

Again there are no restrictions on what the backend plugin may do in this phase. However, unlike the {\ttfamily prestorage} phase, this phase is a very important one. It is where validation, generation of implicit values and similar tasks happen.

Finally, {\ttfamily libelektra-\/kdb} merges the keyset returned by the {\ttfamily poststorage} phase with the ones returned by other backend plugins for different mountpoints and then returns it to the user.\hypertarget{doc_dev_backend-plugins_md_autotoc_md2577}{}\doxysubsection{Operation $<$tt$>$set$<$/tt$>$}\label{doc_dev_backend-plugins_md_autotoc_md2577}
The {\ttfamily set} operation is optional. A mountpoint is automatically read-\/only and doesn\textquotesingle{}t support the {\ttfamily set} operation, if the backend plugin does not define a {\ttfamily elektra$<$Plugin$>$Set} function.

Alternatively, the read-\/only nature of the mountpoint may also be indicated by the backend plugin during the {\ttfamily init} phase of the {\ttfamily get} operation.\hypertarget{doc_dev_backend-plugins_md_autotoc_md2578}{}\doxysubsubsection{Resolver Phase}\label{doc_dev_backend-plugins_md_autotoc_md2578}
During the {\ttfamily resolver} phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily resolver} phase of the last {\ttfamily get} or {\ttfamily set} operation. The key name of this key is read-\/only.
\item An empty keyset {\ttfamily ks}.
\end{DoxyItemize}

The backend plugin then\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} set the value of the {\ttfamily parent\+Key} to a value identifying the storage unit that contains the data of the mountpoint. For file-\/based backend plugins, this means setting the value of {\ttfamily parent\+Key} to an absolute filename.
\item {\bfseries{MAY}} set metadata on {\ttfamily parent\+Key}, if it is not suitable to encode the information required for the following phases as a single string.
\item {\bfseries{MUST}} check whether the data was changed since the last {\ttfamily get} operation. The result of this check is given to {\ttfamily libelektra-\/kdb} via the return value of the {\ttfamily get} function.
\item {\bfseries{MUST}} ensure that errors in the storage phases can be safely rolled back and that the {\ttfamily set} operation does not affect concurrent operations. For file-\/based backends, this means creating a temporary storage file and returning its absolute filename instead of the name of the actual storage file.
\end{DoxyItemize}

\begin{quote}
{\bfseries{Note}}\+: The backend plugin may also modify the keyset {\ttfamily ks}, but {\ttfamily libelektra-\/kdb} will discard this keyset after this phase, so these modifications won\textquotesingle{}t have any effects. \end{quote}
\hypertarget{doc_dev_backend-plugins_md_autotoc_md2579}{}\doxysubsubsection{Storage Phases}\label{doc_dev_backend-plugins_md_autotoc_md2579}
These phases are responsible for validating and writing data to the KDB.

In the {\ttfamily prestorage} phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily resolver} phase of this {\ttfamily set} operation. The key name and value of this key are read-\/only.
\item The exact subset below {\ttfamily parent\+Key} of the keyset {\ttfamily ks} that was provided by the user.
\end{DoxyItemize}

There are no restrictions on what the backend plugin may do in this phase. This phase can be used for validation to avoid storing invalid configuration. However, it should not be used for generating keys or values implicitly defined by other keys. Such keys should be generated during the {\ttfamily poststorage} phase of a {\ttfamily get} operation and should actually be {\itshape removed} again in this phase. That way there cannot be conflicts, if a key that implies another keys value changes.

\begin{quote}
{\bfseries{Note}}\+: Just in case there is actually a use case, where keys have to be generated, removed or modified during this phase, we do {\itshape not} discard changes to {\ttfamily ks} (like we would do in a {\ttfamily get} operation). \end{quote}
The {\ttfamily storage} phase is for writing the actual data. In this phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily prestorage} phase of this {\ttfamily set} operation. The key name and value of this key are read-\/only.
\item The exact keyset {\ttfamily ks} that was returned by the {\ttfamily prestorage} phase of this {\ttfamily set} operation. All keys in this keyset and the keyset itself are fully read-\/only.
\end{DoxyItemize}

The backend plugin then\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} serialize the data at and below {\ttfamily parent\+Key} in {\ttfamily ks}.
\item {\bfseries{MUST}} write the data for the mountpoint into the storage unit that was selected in the {\ttfamily resolver} phase.
\item {\bfseries{MUST}} ensure that the data is written in such a way that
\begin{DoxyItemize}
\item it can be read, if the storage unit is mounted at another mountpoint
\item that reading such a mountpoint will result in the same data just below a different parent key
\end{DoxyItemize}

An important implication here is that all names inside storage units should be relative to the parent key.
\end{DoxyItemize}

The last of the storage phases is the {\ttfamily poststorage} phase. In this phase the backend plugin is called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the {\ttfamily storage} phase of this {\ttfamily set} operation. The key name and value of this key are read-\/only.
\item The exact keyset {\ttfamily ks} that was returned by the {\ttfamily storage} phase of this {\ttfamily set} operation. All keys in this keyset and the keyset itself are fully read-\/only.
\end{DoxyItemize}

There are no formal restrictions, other than those enforced by {\ttfamily parent\+Key} and {\ttfamily ks} being (partially) read-\/only. But the {\ttfamily poststorage} phase should not be used as a counter-\/part to the {\ttfamily prestorage} phase in the {\ttfamily get} operation. Use the {\ttfamily precommit} phase instead. Therefore, the {\ttfamily poststorage} phase has very little use cases other than logging and exists mostly because of symmetry.\hypertarget{doc_dev_backend-plugins_md_autotoc_md2580}{}\doxysubsubsection{Commit Phases ($<$tt$>$set$<$/tt$>$ only)}\label{doc_dev_backend-plugins_md_autotoc_md2580}
If all storage phases completed successfully, {\ttfamily libelektra-\/kdb} will continue with calling the {\ttfamily commit} phases. Even though the {\ttfamily commit} phases are part of the {\ttfamily set} operation, {\ttfamily libelektra-\/kdb} calls {\ttfamily elektra$<$Plugin$>$Commit} and not {\ttfamily elektra$<$Plugin$>$Set} for these phases.

All the {\ttfamily commit} phases ({\ttfamily precommit}, {\ttfamily commit}, {\ttfamily postcommit}) are called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the previous phase ({\ttfamily poststorage}, {\ttfamily precommit} or {\ttfamily commit}) of this {\ttfamily set} operation. The key name and value of this key are read-\/only.
\item The exact keyset {\ttfamily ks} that was returned by the {\ttfamily poststorage} phase of this {\ttfamily set} operation (which is the same one that was returned by the {\ttfamily prestorage} phase). All keys in this keyset and the keyset itself are fully read-\/only.
\end{DoxyItemize}

There are no restrictions on the {\ttfamily precommit} phase, other than those enforced by {\ttfamily parent\+Key} and {\ttfamily ks} being (partially) read-\/only. This phase can be used for file-\/level manipulations, like file-\/based encryption, line ending conversion or adding file signatures. In this sense, it is the counter-\/part of the {\ttfamily prestorage} phase of the {\ttfamily get} operation.

In the {\ttfamily commit} phase the backend plugin\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} make the changes done during the {\ttfamily storage} phase of this {\ttfamily set} operation permanent in such a way that a following {\ttfamily get} operation will be able to read them (assuming there is no other {\ttfamily set} operation in between).
\end{DoxyItemize}

There are no restrictions on what the backend plugin may do in the {\ttfamily postcommit} phase. However, it is important to keep in mind that an error in the {\ttfamily postcommit} phase will {\bfseries{not}} make the {\ttfamily set} operation fail. Once the {\ttfamily commit} phase completes successfully, the {\ttfamily set} operation is also deemed successful, since the changes were made permanent. If an error does occur in the {\ttfamily postcommit} phase, it is reported as warning. This makes the {\ttfamily postcommit} phase mostly useful for logging.

Finally, {\ttfamily libelektra-\/kdb} merges the keyset returned by the {\ttfamily postcommit} phase (still the same one that was returned by the {\ttfamily prestorage} phase) with the ones returned by other backend plugins for different mountpoints and then returns it to the user.\hypertarget{doc_dev_backend-plugins_md_autotoc_md2581}{}\doxysubsubsection{Rollback Phases ($<$tt$>$set$<$/tt$>$ only)}\label{doc_dev_backend-plugins_md_autotoc_md2581}
If any of the phases {\ttfamily prestorage}, {\ttfamily storage}, {\ttfamily poststorage}, {\ttfamily precommit} or {\ttfamily commit} fail, {\ttfamily libelektra-\/kdb} will continue with the rollback phases. Even though the {\ttfamily rollback} phases are part of the {\ttfamily set} operation, {\ttfamily libelektra-\/kdb} calls {\ttfamily elektra$<$Plugin$>$Error} and not {\ttfamily elektra$<$Plugin$>$Set} for these phases.

Similar to the commit phases, the rollback phases ({\ttfamily prerollback}, {\ttfamily rollback} and {\ttfamily postrollback}) are called with\+:


\begin{DoxyItemize}
\item The exact {\ttfamily parent\+Key} that was returned by the phase of this {\ttfamily set} operation that reported an error. The key name and value of this key are read-\/only.
\item The exact keyset {\ttfamily ks} that was returned by the phase of this {\ttfamily set} operation that reported an error. All keys in this keyset and the keyset itself are fully read-\/only.
\end{DoxyItemize}

Additionally, the phase that reported an error is communicated to the backend plugin via the global keyset (together with the current phase). The value of the key {\ttfamily system\+:/elektra/kdb/backend/failedphase} is set to the failed phase.

The {\ttfamily prerollback} and {\ttfamily postrollback} phases are mostly useful for logging. There are no restrictions on these phases, other than those enforced by {\ttfamily parent\+Key} and {\ttfamily ks} being (partially) read-\/only. However, they are similar to the {\ttfamily postcommit} phase, in that any errors they report will be ignored and reported as warnings. In particular, even if the {\ttfamily prerollback} phase fails, {\ttfamily libelektra-\/kdb} will continue with the {\ttfamily rollback} phase as if {\ttfamily prerollback} succeeded.

In the {\ttfamily rollback} phase the backend plugin\+:


\begin{DoxyItemize}
\item {\bfseries{MUST}} revert all changes made to the state of the storage unit chosen in the {\ttfamily resolver} phase of this {\ttfamily set} operation. For file-\/based backends, this means removing the temporary file.
\item {\bfseries{MUST}} ensure that a following {\ttfamily get} or {\ttfamily set} operation will act as if the failed {\ttfamily set} operation never happened.
\item {\bfseries{MAY}} act differently depending on which phase failed.
\end{DoxyItemize}

Finally, {\ttfamily libelektra-\/kdb} will restore {\ttfamily ks} to the state in which the user provided it and return. 