\section{choices.c File Reference}
\label{choices_8c}\index{choices.c@{choices.c}}
Code for handling loading and saving of user choices. 

{\tt \#include \char`\"{}rox-clib.h\char`\"{}}\par
{\tt \#include $<$stdio.h$>$}\par
{\tt \#include $<$stdlib.h$>$}\par
{\tt \#include $<$sys/param.h$>$}\par
{\tt \#include $<$sys/stat.h$>$}\par
{\tt \#include $<$fcntl.h$>$}\par
{\tt \#include $<$errno.h$>$}\par
{\tt \#include $<$glib.h$>$}\par
{\tt \#include \char`\"{}rox\_\-debug.h\char`\"{}}\par
{\tt \#include \char`\"{}choices.h\char`\"{}}\par
{\tt \#include \char`\"{}basedir.h\char`\"{}}\par
\subsection*{Functions}
\begin{CompactItemize}
\item 
void {\bf choices\_\-init} (void)
\item 
GPtr\-Array $\ast$ {\bf choices\_\-list\_\-dirs} (const char $\ast$dir)
\item 
void {\bf choices\_\-free\_\-list} (GPtr\-Array $\ast$list)
\item 
gchar $\ast$ {\bf choices\_\-find\_\-path\_\-load} (const char $\ast$leaf, const char $\ast$dir)
\item 
gchar $\ast$ {\bf choices\_\-find\_\-path\_\-save} (const char $\ast$leaf, const char $\ast$dir, gboolean create)
\item 
void {\bf rox\_\-choices\_\-init} (void)
\item 
gchar $\ast$ {\bf rox\_\-choices\_\-save} (const char $\ast$leaf, const char $\ast$dir, const char $\ast$domain)
\item 
gchar $\ast$ {\bf rox\_\-choices\_\-load} (const char $\ast$leaf, const char $\ast$dir, const char $\ast$domain)
\item 
GPtr\-Array $\ast$ {\bf rox\_\-choices\_\-list\_\-dirs} (const char $\ast$domain, const char $\ast$dir)
\item 
void {\bf rox\_\-choices\_\-free\_\-list} (GPtr\-Array $\ast$list)
\end{CompactItemize}


\subsection{Detailed Description}
Code for handling loading and saving of user choices. 

The current versions use a parameter \char`\"{}domain\char`\"{} to ensure that two programs from different sources but with the same name do not clash. domain is optional and may be NULL. If given it should be a domain name identifying the software, i.e. I use kerofin.demon.co.uk. If you don't have a domain name, use an email address, e.g. {\tt me@my-isp.org}

These functions are deprecated and should not be used in new code:\begin{itemize}
\item \doxyref{choices\_\-init()}{p.}{choices_8c_ff60d2e869ba539004144074bab30edd}\item \doxyref{choices\_\-list\_\-dirs()}{p.}{choices_8c_7cda6785ae3346bfb254a82001fa642d}\item \doxyref{choices\_\-free\_\-list()}{p.}{choices_8c_3bc8eaad84cebfa6d65f6ce903f9290f}\item \doxyref{choices\_\-find\_\-path\_\-load()}{p.}{choices_8c_ab33e2e4cec249ae39c681b181c6964d}\item \doxyref{choices\_\-find\_\-path\_\-save()}{p.}{choices_8c_7c9dd9cb0c923ce497841b863d7b5146}\end{itemize}


\begin{Desc}
\item[Version:]\begin{Desc}
\item[Id]\doxyref{choices.c}{p.}{choices_8c},v 1.13 2006/11/06 20:22:42 stephen Exp \end{Desc}
\end{Desc}
\begin{Desc}
\item[Author:]Thomas Leonard, Stephen Watson. Borrowed from: ROX-Filer, filer for the ROX desktop project Copyright (C) 2000, Thomas Leonard, $<${\tt tal197@users.sourceforge.net}$>$.\end{Desc}
\begin{Desc}
\item[Version:]\begin{Desc}
\item[Id]\doxyref{choices.c}{p.}{choices_8c},v 1.13 2006/11/06 20:22:42 stephen Exp \end{Desc}
\end{Desc}
\begin{Desc}
\item[Author:]Thomas Leonard, Stephen Watson. \end{Desc}


\subsection{Function Documentation}
\index{choices.c@{choices.c}!choices_find_path_load@{choices\_\-find\_\-path\_\-load}}
\index{choices_find_path_load@{choices\_\-find\_\-path\_\-load}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}gchar$\ast$ choices\_\-find\_\-path\_\-load (const char $\ast$ {\em leaf}, const char $\ast$ {\em dir})}\label{choices_8c_ab33e2e4cec249ae39c681b181c6964d}


Get the pathname of a choices file to load. Eg:

choices\_\-find\_\-path\_\-load(\char`\"{}menus\char`\"{}, \char`\"{}ROX-Filer\char`\"{}) -$>$ \char`\"{}/usr/local/share/Choices/ROX-Filer/menus\char`\"{}.

The return values may be NULL - use built-in defaults - otherwise g\_\-free() the result.

\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-choices\_\-load()}{p.}{choices_8c_77c1b00169bd5a57c8b8409e67b0b94b} instead.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em leaf}]last part of file name (may include a relative directory part) \item[\mbox{$\leftarrow$} {\em dir}]directory to locate in \$CHOICESPATH, normally the name of the program \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]path to file (pass to g\_\-free() when done) or NULL \end{Desc}
\index{choices.c@{choices.c}!choices_find_path_save@{choices\_\-find\_\-path\_\-save}}
\index{choices_find_path_save@{choices\_\-find\_\-path\_\-save}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}gchar$\ast$ choices\_\-find\_\-path\_\-save (const char $\ast$ {\em leaf}, const char $\ast$ {\em dir}, gboolean {\em create})}\label{choices_8c_7c9dd9cb0c923ce497841b863d7b5146}


Returns the pathname of a file to save to, or NULL if saving is disabled. If 'create' is TRUE then intermediate directories will be created (set this to FALSE if you just want to find out where a saved file would go without actually altering the filesystem).

g\_\-free() the result.

\begin{Desc}
\item[{\bf Deprecated}]Use \doxyref{rox\_\-choices\_\-save()}{p.}{choices_8c_2ff85a50cc89bf1f1f12fa492b5d9572} instead\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em leaf}]last part of file name (may include a relative directory part) \item[\mbox{$\leftarrow$} {\em dir}]directory to locate in \$CHOICESPATH, normally the name of the program \item[\mbox{$\leftarrow$} {\em create}]if non-zero create missing directories\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]path to file (pass to g\_\-free() when done) or NULL \end{Desc}
\index{choices.c@{choices.c}!choices_free_list@{choices\_\-free\_\-list}}
\index{choices_free_list@{choices\_\-free\_\-list}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void choices\_\-free\_\-list (GPtr\-Array $\ast$ {\em list})}\label{choices_8c_3bc8eaad84cebfa6d65f6ce903f9290f}


Free the data returned by \doxyref{choices\_\-list\_\-dirs()}{p.}{choices_8c_7cda6785ae3346bfb254a82001fa642d}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em list}]Return value from \doxyref{choices\_\-list\_\-dirs()}{p.}{choices_8c_7cda6785ae3346bfb254a82001fa642d}.\end{description}
\end{Desc}
\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{rox\_\-choices\_\-free\_\-list()}{p.}{choices_8c_26b91b81a6b7532cd91d1f9dcaee3747} instead. \end{Desc}
\index{choices.c@{choices.c}!choices_init@{choices\_\-init}}
\index{choices_init@{choices\_\-init}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void choices\_\-init (void)}\label{choices_8c_ff60d2e869ba539004144074bab30edd}


Checks \$CHOICESPATH to construct the directory list table for the old choices\_\-system. You must call this before using any other choices\_\-$\ast$ functions.

If the environment variable does not exist then the defaults are used.

\begin{Desc}
\item[{\bf Deprecated}]This is called by \doxyref{rox\_\-init\_\-with\_\-domain()}{p.}{rox_8c_74e2d8a486c8aedc955851dc7b71b660} and you should call that in preference to this. \end{Desc}
\index{choices.c@{choices.c}!choices_list_dirs@{choices\_\-list\_\-dirs}}
\index{choices_list_dirs@{choices\_\-list\_\-dirs}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}GPtr\-Array$\ast$ choices\_\-list\_\-dirs (const char $\ast$ {\em dir})}\label{choices_8c_7cda6785ae3346bfb254a82001fa642d}


Returns an array of the directories in CHOICESPATH which contain a subdirectory called 'dir'.

Lower-indexed results should override higher-indexed ones.

Free the list using \doxyref{choices\_\-free\_\-list()}{p.}{choices_8c_3bc8eaad84cebfa6d65f6ce903f9290f}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em dir}]directory to search for. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]pointer array of results.\end{Desc}
\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{rox\_\-choices\_\-list\_\-dirs()}{p.}{choices_8c_ddf1643a1ba143b7b1c0ef4c933c6b81} instead. \end{Desc}
\index{choices.c@{choices.c}!rox_choices_free_list@{rox\_\-choices\_\-free\_\-list}}
\index{rox_choices_free_list@{rox\_\-choices\_\-free\_\-list}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-choices\_\-free\_\-list (GPtr\-Array $\ast$ {\em list})}\label{choices_8c_26b91b81a6b7532cd91d1f9dcaee3747}


Free the data returned by \doxyref{rox\_\-choices\_\-list\_\-dirs()}{p.}{choices_8c_ddf1643a1ba143b7b1c0ef4c933c6b81}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em list}]Return value from \doxyref{rox\_\-choices\_\-list\_\-dirs()}{p.}{choices_8c_ddf1643a1ba143b7b1c0ef4c933c6b81}. \end{description}
\end{Desc}
\index{choices.c@{choices.c}!rox_choices_init@{rox\_\-choices\_\-init}}
\index{rox_choices_init@{rox\_\-choices\_\-init}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-choices\_\-init (void)}\label{choices_8c_489ab066f3a211002f8d2c6d6e52d97a}


Checks \$CHOICESPATH to construct the directory list table for the old choices\_\-system. This is called to support the old choices system and should not be used in new code.

If the environment variable does not exist then the defaults are used.

\begin{Desc}
\item[{\bf Deprecated}]This is called by \doxyref{rox\_\-init\_\-with\_\-domain()}{p.}{rox_8c_74e2d8a486c8aedc955851dc7b71b660} and you should call that in preference to this. \end{Desc}
\index{choices.c@{choices.c}!rox_choices_list_dirs@{rox\_\-choices\_\-list\_\-dirs}}
\index{rox_choices_list_dirs@{rox\_\-choices\_\-list\_\-dirs}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}GPtr\-Array$\ast$ rox\_\-choices\_\-list\_\-dirs (const char $\ast$ {\em domain}, const char $\ast$ {\em dir})}\label{choices_8c_ddf1643a1ba143b7b1c0ef4c933c6b81}


Returns an array of the directories in XDG\_\-CONFIG\_\-DIRS which contain a subdirectory called 'domain/dir'.

Lower-indexed results should override higher-indexed ones.

Free the list using \doxyref{rox\_\-choices\_\-free\_\-list()}{p.}{choices_8c_26b91b81a6b7532cd91d1f9dcaee3747}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em dir}]directory to search for. \item[\mbox{$\leftarrow$} {\em domain}]domain of the programs author, or email address. Used to uniquely identify programs with similar names. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]pointer array of results. \end{Desc}
\index{choices.c@{choices.c}!rox_choices_load@{rox\_\-choices\_\-load}}
\index{rox_choices_load@{rox\_\-choices\_\-load}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}gchar$\ast$ rox\_\-choices\_\-load (const char $\ast$ {\em leaf}, const char $\ast$ {\em dir}, const char $\ast$ {\em domain})}\label{choices_8c_77c1b00169bd5a57c8b8409e67b0b94b}


Get the pathname of a choices file to load. Eg:

{\tt  rox\_\-choices\_\-load(\char`\"{}menus\char`\"{}, \char`\"{}ROX-Filer\char`\"{}, \char`\"{}rox.sourceforge.net\char`\"{}) -$>$ \char`\"{}/etc/xdg/rox.sourceforge.net/ROX-Filer/menus\char`\"{} } or {\tt  \char`\"{}/home/user/.config/rox.sourceforge.net/ROX-Filer/menus\char`\"{}. }

The return values may be NULL - use built-in defaults - otherwise g\_\-free() the result.

This uses \doxyref{rox\_\-basedir\_\-load\_\-config\_\-path()}{p.}{basedir_8c_1ec7ba0d619f63e4ed3004dd8e6a01a6}, falling back on \doxyref{choices\_\-find\_\-path\_\-load()}{p.}{choices_8c_ab33e2e4cec249ae39c681b181c6964d} if that does not return a result.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em leaf}]last part of file name (may include a relative directory part) \item[\mbox{$\leftarrow$} {\em dir}]directory to locate in \$XDG\_\-CONFIG\_\-HOME, \$XDG\_\-CONFIG\_\-DIRS or \$CHOICESPATH, normally the name of the program \item[\mbox{$\leftarrow$} {\em domain}]domain of the programs author, or email address. Used to uniquely identify programs with similar names. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]path to file (pass to g\_\-free() when done) or NULL \end{Desc}
\index{choices.c@{choices.c}!rox_choices_save@{rox\_\-choices\_\-save}}
\index{rox_choices_save@{rox\_\-choices\_\-save}!choices.c@{choices.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}gchar$\ast$ rox\_\-choices\_\-save (const char $\ast$ {\em leaf}, const char $\ast$ {\em dir}, const char $\ast$ {\em domain})}\label{choices_8c_2ff85a50cc89bf1f1f12fa492b5d9572}


Returns the pathname of a file to save to, or NULL if saving is disabled.

g\_\-free() the result.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em leaf}]last part of file name (may include a relative directory part) \item[\mbox{$\leftarrow$} {\em dir}]directory to locate in \$XDG\_\-CONFIG\_\-HOME or \$XDG\_\-CONFIG\_\-DIRS, normally the name of the program \item[\mbox{$\leftarrow$} {\em domain}]domain of the programs author, or email address. Used to uniquly identify programs with similar names.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]path to file (pass to g\_\-free() when done) or NULL \end{Desc}
