<!-- ##### SECTION Title ##### -->
mate-config

<!-- ##### SECTION Short_Description ##### -->
Access to configuration files.

<!-- ##### SECTION Long_Description ##### -->
<para>
This module provides a simple method of retrieving and storing configuration
data that resides in files. It also provides the ability to supply default
values for the configuration parameters to simply client code.
</para>
<note>
	<para>
	The purpose of this module is different in MATE 2 from what it was in
	MATE 1. General applications should use the #mate-mateconf module for
	their configuration requirements.
	</para>
	<para>
	The mate-config module exists for applications that
		<itemizedlist>
			<listitem>
				<para>need to provide a backwards-compatible
				version of their configuration files, or</para>
			</listitem>
			<listitem>
				<para>need to run independently of a user and
				access configuration files at absolute
				locations (for example, a login manager), or
				</para>
			</listitem>
			<listitem>
				<para>need to parse
				<wordasword>.desktop</wordasword>-style files,
				or</para>
			</listitem>
			<listitem>
				<para>need to parse user- or
				shell-editable/readable files.</para>
			</listitem>
		</itemizedlist>
	</para>
</note>

<formalpara>
   <title>Definitions</title>

  <para>
    <itemizedlist>
      <listitem><para><emphasis>config path:</emphasis> a string that
        specifies which item to retrieve from the configuration
        database.  The config path is composed of three elements: the
        first one is the filename where the information is stored, the
        second component is the section and the third one is the key
        inside the section</para>

        <para>For example, a config path of "/myapp/toolbox/showit"
        could be used to retrieve the setting for whether 'myapp'
        should display its toolbox or not.  In this example "myapp" is
        the file name (which is stored in
        <filename>~/.mate2</filename> directory), "toolbox" is the
        section and "showit" is the key.</para>

        <para>If you want to access an absolute file instead of a
        <filename>~/.mate2</filename>-relative file, then you need to
        surround the filename with equal signs, for example, to access
        the key "mykey" from the section "mysection" in a
        configuration file located in
        <filename>/mate/var/myconfig</filename> you need to use this
        path: "=/mate/var/myconfig=/mysection/mykey".</para></listitem>

      <listitem><para><emphasis>default:</emphasis> when retrieving a
        config item, specifies the value to be used if the item is not
        found.</para></listitem>

      <listitem><para><emphasis>private configuration data:</emphasis>
        Normally, config item data is located in files under the
	<filename>~user/.mate2</filename> directory in a .ini-like format.
	These files are world-readable. Items that have security or privacy
	implications are stored and retrieved using the "private" versions of
	the mate-config routines, and the data for these items is stored in
	files under the <filename>~user/.config/mate/private</filename> directory,
	which is not accessable by anyone except that user and the system
	administrator.</para></listitem>

      <listitem><para><emphasis>translated strings:</emphasis> MATE's
      multilingual support means that multiple languages must be supported for
      configuration items.  The mate_config_*get_translated_string() and
      mate_config_*set_translated_string() routines allow you to specify which
      language a string item should be accessed for.
       	</para></listitem>

      <listitem><para><emphasis>section:</emphasis> a group of config items and
      other config sections</para></listitem>
    </itemizedlist>
   </para>
</formalpara>


<formalpara>
  <title>How Config Items are Read</title>

<para>
    The mate-config module has a versatile method of storing config items.
    When a config item is written by a program, it is written to a file under
    the <filename>~/.mate2</filename> hierarchy.  However, when config items
    are read, the process is a little more complicated.  There are a number of
    places that are searched.  If the config item is not found in one, then the
    next place is checked, finally falling back to the default value provided
    by the application.  The locations are as follows:
    <itemizedlist>
      <listitem><para><filename>$(sysconfdir)/mate/config-override</filename>
        - a system administrator would put config items in this directory
        that they don't want to be configurable.</para></listitem>
      <listitem><para><filename>~/.mate</filename> - this is where the
        user's config items are written to and is the next place that is
        searched</para></listitem>
      <listitem><para><filename>$(sysconfdir)/mate/config</filename>
        - this directory would hold system wide default configuration values.
        </para></listitem>
    </itemizedlist>
  </para>
</formalpara>

<para>
    Possible uses for this are setting system wide defaults such as
    proxy servers for the system (either using
    <filename>config-override</filename> to enforce such a policy or
    the <filename>config</filename> directory to suggest such a
    default).  It is also possible to configure the application
    through its graphical interface, and then copy the configuration
    file accross to the appropriate system-wide directory.
    The <filename>config-override</filename> directory should be used
    sparingly, as it could annoy or confuse some users.  Note also
    that some applications will not read the config items every time
    they are needed, so putting defaults into the
    <filename>config-override</filename> directory will not always
    completely enforce a setting.
</para>

<para>
Every function in this module comes in at least two forms. There is the
<function>mate_config_get_foo()</function> version which retrieves the
configuration data from the <filename>~/.mate2</filename> directory (unless an
absolute configuration key is given, as defined above). Then there is the
<function>mate_config_private_get_foo()</function> version, which retrieves
the information from the user's <filename>~/.mate2-private</filename>
directory.
</para>

<para>
For functions dealing with strings, there is a third form of each function
which returns the translated version of the string for the current locale.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### MACRO mate_config_get_string ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_get_string_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_get_translated_string ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_get_translated_string_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_private_get_string ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_get_string_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_private_get_translated_string ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_get_translated_string_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_set_string ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_set_translated_string ##### -->
<para>

</para>

@path:
@value:


<!-- ##### MACRO mate_config_private_set_string ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_private_set_translated_string ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_get_int ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_get_int_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_private_get_int ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_get_int_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_set_int ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_private_set_int ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_get_float ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_get_float_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_private_get_float ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_get_float_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_set_float ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_private_set_float ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_get_bool ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_get_bool_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_private_get_bool ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_get_bool_with_default ##### -->
<para>

</para>

@path:
@def:
@Returns:


<!-- ##### MACRO mate_config_set_bool ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_private_set_bool ##### -->
<para>

</para>

@path:
@new_value:


<!-- ##### MACRO mate_config_get_vector ##### -->
<para>

</para>

@path:
@argcp:
@argvp:


<!-- ##### MACRO mate_config_get_vector_with_default ##### -->
<para>

</para>

@path:
@argcp:
@argvp:
@def:


<!-- ##### MACRO mate_config_private_get_vector ##### -->
<para>

</para>

@path:
@argcp:
@argvp:


<!-- ##### MACRO mate_config_private_get_vector_with_default ##### -->
<para>

</para>

@path:
@argcp:
@argvp:
@def:


<!-- ##### MACRO mate_config_set_vector ##### -->
<para>

</para>

@path:
@argc:
@argv:


<!-- ##### MACRO mate_config_private_set_vector ##### -->
<para>

</para>

@path:
@argc:
@argv:


<!-- ##### FUNCTION mate_config_assemble_vector ##### -->
<para>

</para>

@argc:
@argv:
@Returns:


<!-- ##### MACRO mate_config_has_section ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_has_section ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_init_iterator ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_init_iterator ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_init_iterator_sections ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_init_iterator_sections ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### FUNCTION mate_config_iterator_next ##### -->
<para>

</para>

@iterator_handle:
@key:
@value:
@Returns:


<!-- ##### FUNCTION mate_config_drop_all ##### -->
<para>

</para>

@void:


<!-- ##### FUNCTION mate_config_sync ##### -->
<para>

</para>

@void:
@Returns:


<!-- ##### MACRO mate_config_sync_file ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_private_sync_file ##### -->
<para>

</para>

@path:
@Returns:


<!-- ##### MACRO mate_config_drop_file ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_private_drop_file ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_clean_file ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_private_clean_file ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_clean_section ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_private_clean_section ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_clean_key ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_private_clean_key ##### -->
<para>

</para>

@path:


<!-- ##### MACRO mate_config_get_real_path ##### -->
<para>
Retrieves the full (absolute) path to a configuration file.
</para>

@path: A configuration file (this should only be the file, not the section or
key).
@Returns: An absolute path to the config file.


<!-- ##### MACRO mate_config_private_get_real_path ##### -->
<para>
Retrieves the full (absolute) path to a configuration file in the user's
private configuration storage area.
</para>

@path: A configuration file (this should only be the file, not the section or
key).
@Returns: An absolute path to the config file.


<!-- ##### FUNCTION mate_config_push_prefix ##### -->
<para>

</para>

@path:


<!-- ##### FUNCTION mate_config_pop_prefix ##### -->
<para>

</para>

@void:


<!-- ##### FUNCTION mate_config_make_vector ##### -->
<para>

</para>

@string:
@argcp:
@argvp:


