
\begin{DoxyItemize}
\item infos = Information about elektrify getenv below
\end{DoxyItemize}

infos/author = Markus Raab \href{mailto:elektra@libelektra.org}{\texttt{ elektra@libelektra.\+org}}
\begin{DoxyItemize}
\item infos/status = maintained
\item infos/provides = intercept
\item infos/description =
\end{DoxyItemize}\hypertarget{md_src_bindings_intercept_env_README_src_bindings_intercept_env_README_md}{}\doxysection{kdb-\/elektrify-\/getenv(1) – elektrify the environment of applications}\label{md_src_bindings_intercept_env_README_src_bindings_intercept_env_README_md}
\hypertarget{md_src_bindings_intercept_env_README_autotoc_md49}{}\doxysubsection{SYNOPSIS}\label{md_src_bindings_intercept_env_README_autotoc_md49}

\begin{DoxyCode}{0}
\DoxyCodeLine{kdb elektrify-\/getenv <application> <options>}

\end{DoxyCode}
\hypertarget{md_src_bindings_intercept_env_README_autotoc_md50}{}\doxysubsection{EXAMPLE}\label{md_src_bindings_intercept_env_README_autotoc_md50}

\begin{DoxyCode}{0}
\DoxyCodeLine{kdb elektrify-\/getenv curl -\/-\/elektra-\/version}
\DoxyCodeLine{kdb elektrify-\/getenv curl https://www.libelektra.org}
\DoxyCodeLine{kdb set system:/elektra/intercept/getenv/override/http\_proxy http://www.example.com/}
\DoxyCodeLine{kdb elektrify-\/getenv curl https://www.libelektra.org}

\end{DoxyCode}


By using {\ttfamily kdb elektrify-\/getenv} the last curl invocation will use a different http proxy. Or you can also reload while the application is running\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{ELEKTRA\_RELOAD\_TIMEOUT=100 kdb elektrify-\/getenv firefox}
\DoxyCodeLine{kdb set system:/elektra/intercept/getenv/override/http\_proxy http://www.example.com}

\end{DoxyCode}
\hypertarget{md_src_bindings_intercept_env_README_autotoc_md51}{}\doxysubsection{DESCRIPTION}\label{md_src_bindings_intercept_env_README_autotoc_md51}
When an application is elektrified using libelektragetenv, it does not only request {\ttfamily environ}, but also Elektra for every getenv(3) and secure\+\_\+getenv(3) library call.

Its main purpose is to\+:


\begin{DoxyItemize}
\item have a standard ways to modify the environment
\item make relogin (or even restart!) of applications unnecessary
\item allow a hierarchical structure for environment
\item allow settings to only apply for individual applications or only in special context
\item still preserve the advantages (inheriting of environment to subprocesses)
\item availability of same environment in at, cron and similar scripts
\end{DoxyItemize}

It is implemented using a LD\+\_\+\+PRELOAD technique, see \href{\#USAGE}{\texttt{ USAGE}} below for global activation.\hypertarget{md_src_bindings_intercept_env_README_autotoc_md52}{}\doxysubsection{LOOKUPS}\label{md_src_bindings_intercept_env_README_autotoc_md52}
The main purpose of this approach is to finally have a well-\/defined way to set and get environment variables. Elektra’s variables will be in use immediately for every newly started application (no relogin necessary).

To do so, getenv(3) will lookup multiple sources next to searching in the environment (environ). As running example will use {\ttfamily getenv(\char`\"{}\+HOME\char`\"{}) -\/$>$ /path/to/home}\+:


\begin{DoxyEnumerate}
\item Given commandline parameters will always be preferred (see \href{\#OPTIONS}{\texttt{ OPTIONS}} below).

E.\+g. {\ttfamily kdb elektrify-\/getenv $<$app$>$ -\/-\/elektra\+:HOME=/path/to/home}
\item Then {\ttfamily /elektra/intercept/getenv/override/$<$key$>$} will be looked up, where $<$key$>$ is the parameter to {\ttfamily getenv}. If found, the key will be returned, if it is a null keys, {\ttfamily getenv} will return {\ttfamily NULL}.

E.\+g. {\ttfamily kdb set user\+:/elektra/intercept/getenv/override/\+HOME /path/to/home}
\item Then environment will be requested.

E.\+g. {\ttfamily HOME=/path/to/home kdb elektrify-\/getenv $<$application$>$}
\item Then {\ttfamily /elektra/intercept/getenv/fallback/$<$key$>$} will be looked up. If found, the key will be returned, if it is a null keys, {\ttfamily getenv} will return {\ttfamily NULL}.

E.\+g. {\ttfamily kdb set user\+:/elektra/intercept/getenv/fallback/\+HOME /path/to/home}
\end{DoxyEnumerate}\hypertarget{md_src_bindings_intercept_env_README_autotoc_md53}{}\doxysubsection{OPTIONS}\label{md_src_bindings_intercept_env_README_autotoc_md53}
When {\ttfamily elektrify-\/getenv} is active, every application additionally accepts Elektra’s getenv options. Interleaving Elektra’s and the application\textquotesingle{}s options is allowed. Elektra will parse its options (starting with --elektra) first and discard them before the other application is started. Therefore the application will not see that they even existed, e.\+g.\+: given {\ttfamily kdb elektrify-\/getenv $<$application$>$ -\/V -\/-\/elektra-\/debug -\/L} the application will be called with {\ttfamily $<$application$>$ -\/V -\/L}.\hypertarget{md_src_bindings_intercept_env_README_autotoc_md54}{}\doxysubsubsection{Internal Options}\label{md_src_bindings_intercept_env_README_autotoc_md54}

\begin{DoxyItemize}
\item {\ttfamily -\/-\/elektra-\/help}\+: Outputs this help.
\item {\ttfamily -\/-\/elektra-\/version}\+: Gives version information.
\item {\ttfamily -\/-\/elektra-\/debug=file}, {\ttfamily ELEKTRA\+\_\+\+DEBUG} or {\ttfamily /elektra/intercept/getenv/option/debug}\+: Trace all getenv(3) calls to a file. stderr if no file is given, e.\+g. {\ttfamily kdb set user\+:/elektra/intercept/getenv/option/debug \char`\"{}\char`\"{}}. Note that null values (no forth argument), will disable debug messages. See examples below.
\item {\ttfamily -\/-\/elektra-\/clearenv}, {\ttfamily ELEKTRA\+\_\+\+CLEARENV} or {\ttfamily /elektra/intercept/getenv/option/clearenv}\+: Call clearenv(3) before entering main. This is a recommended security feature. Elektra itself, if configured that way, will still be able to use the environment.
\item {\ttfamily -\/-\/elektra-\/reload-\/timeout=time\+\_\+in\+\_\+ms}, {\ttfamily ELEKTRA\+\_\+\+RELOAD\+\_\+\+TIMEOUT} or {\ttfamily /elektra/intercept/getenv/option/reload\+\_\+timeout}\+: Activate a timeout based feature when a time is given in ms (and is not 0).
\end{DoxyItemize}

Internal Options are available in three different variants\+:


\begin{DoxyEnumerate}
\item as commandline parameter\+: {\ttfamily -\/-\/elektra-\/$<$option$>$}, which are {\itshape not} passed through exec(3) calls.
\item as environment variable\+: {\ttfamily ELEKTRA\+\_\+$<$OPTION$>$}. which might be passed through exec(3) calls, but are removed by clearenv(3) calls.
\item as Elektra KDB entry\+: {\ttfamily /elektra/intercept/getenv/option/$<$option$>$}, which are the way to achieve an option to be enabled for every application.

E.\+g. {\ttfamily kdb set user\+:/elektra/intercept/getenv/option/clearenv \char`\"{}\char`\"{}} to clear the environment for all applications started by that user (note that at least {\ttfamily PATH} should to be set using {\ttfamily kdb set user\+:/elektra/intercept/getenv/fallback/\+PATH \char`\"{}/bin\+:/usr/bin\char`\"{}} then).

Note, that null keys are equal to non-\/set options. E.\+g. {\ttfamily kdb set system\+:/elektra/intercept/getenv/option/debug \char`\"{}/tmp/elektra.\+log\char`\"{}} and {\ttfamily kdb set user\+:/elektra/intercept/getenv/option/debug} will activate logging for the system, except for the current user.
\end{DoxyEnumerate}\hypertarget{md_src_bindings_intercept_env_README_autotoc_md55}{}\doxysubsubsection{Contextual Options}\label{md_src_bindings_intercept_env_README_autotoc_md55}

\begin{DoxyItemize}
\item {\ttfamily -\/-\/elektra\%$<$name$>$\%=$<$value$>$} or {\ttfamily /elektra/intercept/getenv/layer/$<$name$>$}\+: Add the contextual information (=layer) {\ttfamily \%$<$name$>$\%} with its value {\ttfamily $<$value$>$}. Note that {\ttfamily name\%} is predefined with {\ttfamily argv\mbox{[}0\mbox{]}} and {\ttfamily basename\%} with {\ttfamily basename(argv\mbox{[}0\mbox{]})}.
\end{DoxyItemize}

Values can contain / to form hierarchies, e.\+g. {\ttfamily -\/-\/elektraname\%=app/profile}\hypertarget{md_src_bindings_intercept_env_README_autotoc_md56}{}\doxysubsubsection{Options for Applications}\label{md_src_bindings_intercept_env_README_autotoc_md56}

\begin{DoxyItemize}
\item {\ttfamily -\/-\/elektra\+:key=value}, {\ttfamily /elektra/intercept/getenv/override/$<$key$>$} or {\ttfamily /elektra/intercept/getenv/fallback/$<$key$>$}\+: set a key-\/value to be preferred, i.\+e. the first to considered as explained in \href{\#LOOKUP}{\texttt{ LOOKUP}}.
\end{DoxyItemize}

Keys can contain / to form hierarchies, e.\+g. {\ttfamily -\/-\/elektra\+:my/\+HOME=/path/to/home}.\hypertarget{md_src_bindings_intercept_env_README_autotoc_md57}{}\doxysubsection{USAGE}\label{md_src_bindings_intercept_env_README_autotoc_md57}
To always use Elektra’s getenv environment, simply add the output to the file\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb elektrify-\/getenv | tail -\/1 | sudo tee -\/a /etc/ld.so.preload}

\end{DoxyCode}


Or in a more Elektra-\/like way with mounting\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{sudo kdb mount /etc/ld.so.preload system:/ld/preload line null}
\DoxyCodeLine{sudo kdb set "{}system:/ld/preload/new"{}  `kdb elektrify-\/getenv | tail -\/1`}

\end{DoxyCode}
\hypertarget{md_src_bindings_intercept_env_README_autotoc_md58}{}\doxysubsection{CONTEXT}\label{md_src_bindings_intercept_env_README_autotoc_md58}
The metadata {\ttfamily context} in the specification can be used to facilitate a context-\/dependent lookup. In its metavalue all replacements of {\ttfamily \%$<$name$>$\%} will be replaced by the given contextual options {\ttfamily -\/-\/elektra\%$<$name$>$\%=$<$value$>$} and {\ttfamily /elektra/intercept/getenv/layer/$<$name$>$} keys.

E.\+g. to have a different home directory for any user and application\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/elektra/intercept/getenv/layer/user markus}
\DoxyCodeLine{kdb set user:/users/markus/konqueror/HOME /home/download}
\DoxyCodeLine{kdb meta-\/set spec:/elektra/intercept/getenv/override/HOME context  /users/\%user\%/\%name\%/HOME}

\end{DoxyCode}


Or to have a different lock/suspend program per computer (that all have the same config)\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb mount-\/info system:/elektra/intercept/getenv/info            \# must be below /elektra/intercept/getenv to be available}
\DoxyCodeLine{kdb meta-\/set spec:/elektra/intercept/getenv/layer/hostname override/\#0 system:/elektra/intercept/getenv/info/uname/nodename}
\DoxyCodeLine{kdb meta-\/set spec:/elektra/intercept/getenv/override/lock context /elektra/intercept/getenv/info/lock/\%hostname\%}
\DoxyCodeLine{kdb set user:/elektra/intercept/getenv/info/lock/computer1 "{}systemctl suspend -\/i"{}}
\DoxyCodeLine{kdb set user:/elektra/intercept/getenv/info/lock/computer2 "{}xset dpms force off \&\& xtrlock"{}}
\DoxyCodeLine{`kdb getenv lock`  \# call the appropriate lock method for the current computer}

\end{DoxyCode}
\hypertarget{md_src_bindings_intercept_env_README_autotoc_md59}{}\doxysubsection{BUGS}\label{md_src_bindings_intercept_env_README_autotoc_md59}
Some applications do not use {\ttfamily getenv(3)} or {\ttfamily secure\+\_\+getenv(3)} for requesting the environment, e.\+g. shells. This approach cannot work for them.

In the startup-\/phase (before main is even entered), {\ttfamily getenv(3)} will not consider {\ttfamily /elektra/intercept/getenv/override/} or {\ttfamily /elektra/intercept/getenv/fallback}.

Elektra internally tries to avoid using the environment. Some resolvers, however, use it to conform to some specifications, e.\+g. XDG. Depending on the setup you use, these parameters might be used. For more information see\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb plugin-\/info resolver}

\end{DoxyCode}


For these parameters, {\ttfamily /elektra/intercept/getenv/override/} or {\ttfamily /elektra/intercept/getenv/fallback} will {\itshape not} be used internally, but will be used if applications request them, too.

If you use the standard resolvers, the bug won\textquotesingle{}t have any effect.

Also note that {\ttfamily -\/-\/elektra-\/debug} or {\ttfamily ELEKTRA\+\_\+\+DEBUG} does {\itshape not} log {\ttfamily getenv(3)} used by plugins during the startup-\/phase.

Command line arguments apply always to the outmost command, e.\+g. {\ttfamily nice ls -\/-\/elektra\+:COLUMNS=20} won\textquotesingle{}t have any effect because only for {\ttfamily nice} {\ttfamily COLUMNS} will be set.\hypertarget{md_src_bindings_intercept_env_README_autotoc_md60}{}\doxysubsection{EXAMPLES}\label{md_src_bindings_intercept_env_README_autotoc_md60}
For illustration this section gives some more examples.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb elektrify-\/getenv man man -\/-\/elektra:MANWIDTH=40}

\end{DoxyCode}


Will use MANWIDTH 40 for this invocation of man man. This feature is handy, if an option is only available by environment, but not by command-\/line arguments, because sometimes environment variables are not trivial to set (e.\+g. in Makefiles).

Debugging\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\# system wide to stderr (not recommended!):}
\DoxyCodeLine{sudo kdb set system:/elektra/intercept/getenv/option/debug "{}"{}}
\DoxyCodeLine{\# system wide to /var/log/elektra.log:}
\DoxyCodeLine{sudo kdb set system:/elektra/intercept/getenv/option/debug "{}/var/log/error.log"{}}
\DoxyCodeLine{\# but for my user to \string~/.elektra.log:}
\DoxyCodeLine{kdb set user:/elektra/intercept/getenv/option/debug "{}\$HOME/.elektra.log"{}}
\DoxyCodeLine{\# or disable it for my user:}
\DoxyCodeLine{kdb set user:/elektra/intercept/getenv/option/debug}

\end{DoxyCode}


Some more examples\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/elektra/intercept/getenv/override/MANOPT -\/-\/ "{}-\/-\/regex -\/LC"{}}
\DoxyCodeLine{kdb elektrify-\/getenv getenv MANOPT   \# to check if it is set as expected}
\DoxyCodeLine{kdb getenv MANOPT   \# if /etc/ld.so.preload is active}

\end{DoxyCode}


Will permanently and user-\/wide change MANOPT to include --regex, and -\/LC so that regular expressions will be used (note {\ttfamily man echo} will return many man pages then) and that they will be shown in English. This feature is handy to change the default behavior of applications (either system, user or directory-\/wide).


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set system:/elektra/intercept/getenv/override/HTTP\_PROXY http://proxy.hogege.com:8000/}

\end{DoxyCode}


Will permanently and system-\/wide change the proxy for all applications that honor HTTP\+\_\+\+PROXY, e.\+g. w3m. We can also link {\ttfamily http\+\_\+proxy} to the value of {\ttfamily HTTP\+\_\+\+PROXY}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb meta-\/set spec:/elektra/intercept/getenv/override/http\_proxy "{}override/\#0"{} /elektra/intercept/getenv/override/HTTP\_PROXY}
\DoxyCodeLine{kdb get /elektra/intercept/getenv/override/http\_proxy}

\end{DoxyCode}
 