<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="gconf-gconf-error">
<refmeta>
<refentrytitle>GError</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GCONF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GError</refname><refpurpose>
error reporting.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



enum        <link linkend="GConfError">GConfError</link>;
<link linkend="GError">GError</link>*     <link linkend="gconf-error-new">gconf_error_new</link>                 (<link linkend="GConfError">GConfError</link> en,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);
<link linkend="void">void</link>        <link linkend="gconf-set-error">gconf_set_error</link>                 (<link linkend="GError">GError</link> **err,
                                             <link linkend="GConfError">GConfError</link> en,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);
<link linkend="GError">GError</link>*     <link linkend="gconf-compose-errors">gconf_compose_errors</link>            (<link linkend="GError">GError</link> *err1,
                                             <link linkend="GError">GError</link> *err2);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>
The <link linkend="GError"><type>GError</type></link> object is used to report errors that occur in GConf
library routines. All functions that report errors work the same way:
<itemizedlist>
<listitem>
<para>
The last argument to the function is a <link linkend="GError"><type>GError</type></link>**, a pointer to a
location where a <link linkend="GError"><type>GError</type></link>* can be placed.
</para>
</listitem>
<listitem>
<para>
This last argument may be <symbol>NULL</symbol>, in which case no
error will be returned.
</para>
</listitem>
<listitem>
<para>
If non-<symbol>NULL</symbol>, the argument should be the address of a 
<link linkend="GError"><type>GError</type></link>* variable, which should be initialized to
<symbol>NULL</symbol>. 
</para>
</listitem>
<listitem>
<para>
If an error occurs, a <link linkend="GError"><type>GError</type></link> will be allocated and placed in the
return location; the caller must free the <link linkend="GError"><type>GError</type></link> with
<link linkend="g-error-free"><function>g_error_free()</function></link>. If no error occurs, the return location will be
left untouched. That is, the test <literal>error != NULL</literal> 
should always be a reliable indicator of whether the operation failed.
</para>
</listitem>
</itemizedlist>
</para>

<para>
It's also common that the return value of a function indicates whether
or not an error occurred. Typically, <symbol>TRUE</symbol> is returned
on success. In some cases, a <symbol>NULL</symbol> return value
indicates failure. Either way, if the return value indicates failure
and you passed a non-<symbol>NULL</symbol> value for the last argument
to the function, a <link linkend="GError"><type>GError</type></link> will be returned. If the return value
indicates success, then a <link linkend="GError"><type>GError</type></link> will never be returned.  These
relationships are guaranteed; that is, you can reliably use the return
value to decide whether a <link linkend="GError"><type>GError</type></link> was placed in the return
location. If a function does <emphasis>not</emphasis> indicate
success/failure by return value, you must check whether the
<link linkend="GError"><type>GError</type></link> is <symbol>NULL</symbol> to detect errors.
</para>

<para>
Here's a short error handling example:
<programlisting>
  GError* err = NULL;

  if (!gconf_init(&amp;err))
    {
      fprintf(stderr, _("Failed to init GConf: <literal>s</literal>\n"), err->message);
      g_error_free(err); 
      err = NULL;
    }
</programlisting>
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GConfError"/>enum GConfError</title>
<indexterm><primary>GConfError</primary></indexterm><programlisting>typedef enum { /*&lt; prefix=GCONF_ERROR &gt;*/
  GCONF_ERROR_SUCCESS = 0,
  GCONF_ERROR_FAILED = 1,        /* Something didn't work, don't know why, probably unrecoverable
                                    so there's no point having a more specific errno */

  GCONF_ERROR_NO_SERVER = 2,     /* Server can't be launched/contacted */
  GCONF_ERROR_NO_PERMISSION = 3, /* don't have permission for that */
  GCONF_ERROR_BAD_ADDRESS = 4,   /* Address couldn't be resolved */
  GCONF_ERROR_BAD_KEY = 5,       /* directory or key isn't valid (contains bad
                                    characters, or malformed slash arrangement) */
  GCONF_ERROR_PARSE_ERROR = 6,   /* Syntax error when parsing */
  GCONF_ERROR_CORRUPT = 7,       /* Fatal error parsing/loading information inside the backend */
  GCONF_ERROR_TYPE_MISMATCH = 8, /* Type requested doesn't match type found */
  GCONF_ERROR_IS_DIR = 9,        /* Requested key operation on a dir */
  GCONF_ERROR_IS_KEY = 10,       /* Requested dir operation on a key */
  GCONF_ERROR_OVERRIDDEN = 11,   /* Read-only source at front of path has set the value */
  GCONF_ERROR_OAF_ERROR = 12,    /* liboaf error */
  GCONF_ERROR_LOCAL_ENGINE = 13, /* Tried to use remote operations on a local engine */
  GCONF_ERROR_LOCK_FAILED = 14,  /* Failed to get a lockfile */
  GCONF_ERROR_NO_WRITABLE_DATABASE = 15, /* nowhere to write a value */
  GCONF_ERROR_IN_SHUTDOWN = 16   /* server is shutting down */
} GConfError;
</programlisting>
<para>
The <link linkend="GConfError"><type>GConfError</type></link> enumeration allows client applications to
differentiate between different kinds of error. You may wish to take
specific actions depending on the error type.
</para><variablelist role="enum">
<varlistentry>
<term><literal>GCONF_ERROR_SUCCESS</literal></term>
<listitem><simpara>indicates that no error occurred, won't be returned in a <link linkend="GError"><type>GError</type></link>.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_FAILED</literal></term>
<listitem><simpara>indicates failure, but no more specific <link linkend="GConfError"><type>GConfError</type></link> applied.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_NO_SERVER</literal></term>
<listitem><simpara>indicates that the GConf server couldn't be contacted, probably a CORBA problem.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_NO_PERMISSION</literal></term>
<listitem><simpara>indicates that permission to access some resource was denied.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_BAD_ADDRESS</literal></term>
<listitem><simpara>indicates that a configuration source address was syntactically invalid or impossible to resolve.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_BAD_KEY</literal></term>
<listitem><simpara>indicates that a key was malformed.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_PARSE_ERROR</literal></term>
<listitem><simpara>indicates that some parsing was done (perhaps in a backend) and it failed.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_CORRUPT</literal></term>
<listitem><simpara>indicates that some part of the database is corrupt.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_TYPE_MISMATCH</literal></term>
<listitem><simpara>indicates that a specific type was required, and another type was found.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_IS_DIR</literal></term>
<listitem><simpara>indicates that an operation only applicable to keys was performed on a directory.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_IS_KEY</literal></term>
<listitem><simpara>indicates that an operation only applicable to directories was performed on a key.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_OVERRIDDEN</literal></term>
<listitem><simpara>indicates that the administrator has imposed a mandatory value, and it could not be changed.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_OAF_ERROR</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_LOCAL_ENGINE</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_LOCK_FAILED</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_NO_WRITABLE_DATABASE</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>GCONF_ERROR_IN_SHUTDOWN</literal></term>
<listitem><simpara>

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gconf-error-new"/>gconf_error_new ()</title>
<indexterm><primary>gconf_error_new</primary></indexterm><programlisting><link linkend="GError">GError</link>*     gconf_error_new                 (<link linkend="GConfError">GConfError</link> en,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<para>
Creates a new error. Normally the GConf library does this, but you
might find a reason to do it as well. <parameter>en</parameter> is the error number, <parameter>format</parameter>
is a <link linkend="printf"><function>printf()</function></link>-style format for the error message, and the variable
argument list is the same as in <link linkend="printf"><function>printf()</function></link>. 
</para><variablelist role="params">
<varlistentry><term><parameter>en</parameter>&nbsp;:</term>
<listitem><simpara>the error number.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara><link linkend="printf"><function>printf()</function></link>-style format for error description.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>arguments required by the <parameter>format</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>newly-allocated <link linkend="GError"><type>GError</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gconf-set-error"/>gconf_set_error ()</title>
<indexterm><primary>gconf_set_error</primary></indexterm><programlisting><link linkend="void">void</link>        gconf_set_error                 (<link linkend="GError">GError</link> **err,
                                             <link linkend="GConfError">GConfError</link> en,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<para>
Internal function.
</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>en</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gconf-compose-errors"/>gconf_compose_errors ()</title>
<indexterm><primary>gconf_compose_errors</primary></indexterm><programlisting><link linkend="GError">GError</link>*     gconf_compose_errors            (<link linkend="GError">GError</link> *err1,
                                             <link linkend="GError">GError</link> *err2);</programlisting>
<para>
Internal function.
</para><variablelist role="params">
<varlistentry><term><parameter>err1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err2</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
