doc/gconf/xml/gconf-error.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id="gconf-gconf-error">
   5 <refmeta>
   6 <refentrytitle role="top_of_page">GError</refentrytitle>
   7 <manvolnum>3</manvolnum>
   8 <refmiscinfo>GCONF Library</refmiscinfo>
   9 </refmeta>
  10
  11 <refnamediv>
  12 <refname>GError</refname>
  13 <refpurpose>
  14 error reporting.</refpurpose>
  15 <!--[<xref linkend="desc" endterm="desc.title"/>]-->
  16 </refnamediv>
  17
  18 <refsynopsisdiv role="synopsis">
  19 <title role="synopsis.title">Synopsis</title>
  20
  21 <synopsis>
  22
  23
  24
  25 enum                <link linkend="GConfError">GConfError</link>;
  26 <link linkend="GError">GError</link>*             <link linkend="gconf-error-new">gconf_error_new</link>                     (<link linkend="GConfError">GConfError</link> en,
  27                                                          const <link linkend="gchar">gchar</link> *format,
  28                                                          ...);
  29 <link linkend="GQuark">GQuark</link>              <link linkend="gconf-error-quark">gconf_error_quark</link>                   (void);
  30 <link linkend="void">void</link>                <link linkend="gconf-set-error">gconf_set_error</link>                     (<link linkend="GError">GError</link> **err,
  31                                                          <link linkend="GConfError">GConfError</link> en,
  32                                                          const <link linkend="gchar">gchar</link> *format,
  33                                                          ...);
  34 <link linkend="GError">GError</link>*             <link linkend="gconf-compose-errors">gconf_compose_errors</link>                (<link linkend="GError">GError</link> *err1,
  35                                                          <link linkend="GError">GError</link> *err2);
  36 </synopsis>
  37 </refsynopsisdiv>
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47 <refsect1 role="desc">
  48 <title role="desc.title">Description</title>
  49 <para>
  50 The <link linkend="GError"><type>GError</type></link> object is used to report errors that occur in GConf
  51 library routines. All functions that report errors work the same way:
  52 <itemizedlist>
  53 <listitem>
  54 <para>
  55 The last argument to the function is a <link linkend="GError"><type>GError</type></link>**, a pointer to a
  56 location where a <link linkend="GError"><type>GError</type></link>* can be placed.
  57 </para>
  58 </listitem>
  59 <listitem>
  60 <para>
  61 This last argument may be <symbol>NULL</symbol>, in which case no
  62 error will be returned.
  63 </para>
  64 </listitem>
  65 <listitem>
  66 <para>
  67 If non-<symbol>NULL</symbol>, the argument should be the address of a
  68 <link linkend="GError"><type>GError</type></link>* variable, which should be initialized to
  69 <symbol>NULL</symbol>.
  70 </para>
  71 </listitem>
  72 <listitem>
  73 <para>
  74 If an error occurs, a <link linkend="GError"><type>GError</type></link> will be allocated and placed in the
  75 return location; the caller must free the <link linkend="GError"><type>GError</type></link> with
  76 <link linkend="g-error-free"><function>g_error_free()</function></link>. If no error occurs, the return location will be
  77 left untouched. That is, the test <literal>error != NULL</literal>
  78 should always be a reliable indicator of whether the operation failed.
  79 </para>
  80 </listitem>
  81 </itemizedlist>
  82 </para>
  83
  84 <para>
  85 It's also common that the return value of a function indicates whether
  86 or not an error occurred. Typically, <symbol>TRUE</symbol> is returned
  87 on success. In some cases, a <symbol>NULL</symbol> return value
  88 indicates failure. Either way, if the return value indicates failure
  89 and you passed a non-<symbol>NULL</symbol> value for the last argument
  90 to the function, a <link linkend="GError"><type>GError</type></link> will be returned. If the return value
  91 indicates success, then a <link linkend="GError"><type>GError</type></link> will never be returned.  These
  92 relationships are guaranteed; that is, you can reliably use the return
  93 value to decide whether a <link linkend="GError"><type>GError</type></link> was placed in the return
  94 location. If a function does <emphasis>not</emphasis> indicate
  95 success/failure by return value, you must check whether the
  96 <link linkend="GError"><type>GError</type></link> is <symbol>NULL</symbol> to detect errors.
  97 </para>
  98
  99 <para>
 100 Here's a short error handling example:
 101 <programlisting>
 102   GError* err = NULL;
 103
 104   if (!gconf_init(&amp;err))
 105     {
 106       fprintf(stderr, _("Failed to init GConf: %s\n"), err->message);
 107       g_error_free(err);
 108       err = NULL;
 109     }
 110 </programlisting>
 111 </para>
 112 </refsect1>
 113
 114 <refsect1 role="details">
 115 <title role="details.title">Details</title>
 116 <refsect2>
 117 <title><anchor id="GConfError" role="enum"/>enum GConfError</title>
 118 <indexterm><primary>GConfError</primary></indexterm><programlisting>typedef enum {
 119   GCONF_ERROR_SUCCESS = 0,
 120   GCONF_ERROR_FAILED = 1,        /* Something didn't work, don't know why, probably unrecoverable
 121                                     so there's no point having a more specific errno */
 122
 123   GCONF_ERROR_NO_SERVER = 2,     /* Server can't be launched/contacted */
 124   GCONF_ERROR_NO_PERMISSION = 3, /* don't have permission for that */
 125   GCONF_ERROR_BAD_ADDRESS = 4,   /* Address couldn't be resolved */
 126   GCONF_ERROR_BAD_KEY = 5,       /* directory or key isn't valid (contains bad
 127                                     characters, or malformed slash arrangement) */
 128   GCONF_ERROR_PARSE_ERROR = 6,   /* Syntax error when parsing */
 129   GCONF_ERROR_CORRUPT = 7,       /* Fatal error parsing/loading information inside the backend */
 130   GCONF_ERROR_TYPE_MISMATCH = 8, /* Type requested doesn't match type found */
 131   GCONF_ERROR_IS_DIR = 9,        /* Requested key operation on a dir */
 132   GCONF_ERROR_IS_KEY = 10,       /* Requested dir operation on a key */
 133   GCONF_ERROR_OVERRIDDEN = 11,   /* Read-only source at front of path has set the value */
 134   GCONF_ERROR_OAF_ERROR = 12,    /* liboaf error */
 135   GCONF_ERROR_LOCAL_ENGINE = 13, /* Tried to use remote operations on a local engine */
 136   GCONF_ERROR_LOCK_FAILED = 14,  /* Failed to get a lockfile */
 137   GCONF_ERROR_NO_WRITABLE_DATABASE = 15, /* nowhere to write a value */
 138   GCONF_ERROR_IN_SHUTDOWN = 16   /* server is shutting down */
 139 } GConfError;
 140 </programlisting>
 141 <para>
 142 The <link linkend="GConfError"><type>GConfError</type></link> enumeration allows client applications to
 143 differentiate between different kinds of error. You may wish to take
 144 specific actions depending on the error type.
 145 </para><variablelist role="enum">
 146 <varlistentry>
 147 <term><anchor id="GCONF-ERROR-SUCCESS:CAPS" role="constant"/><literal>GCONF_ERROR_SUCCESS</literal></term>
 148 <listitem><simpara>indicates that no error occurred, won't be returned in a <link linkend="GError"><type>GError</type></link>.
 149 </simpara></listitem>
 150 </varlistentry>
 151 <varlistentry>
 152 <term><anchor id="GCONF-ERROR-FAILED:CAPS" role="constant"/><literal>GCONF_ERROR_FAILED</literal></term>
 153 <listitem><simpara>indicates failure, but no more specific <link linkend="GConfError"><type>GConfError</type></link> applied.
 154 </simpara></listitem>
 155 </varlistentry>
 156 <varlistentry>
 157 <term><anchor id="GCONF-ERROR-NO-SERVER:CAPS" role="constant"/><literal>GCONF_ERROR_NO_SERVER</literal></term>
 158 <listitem><simpara>indicates that the GConf server couldn't be contacted, probably a CORBA problem.
 159 </simpara></listitem>
 160 </varlistentry>
 161 <varlistentry>
 162 <term><anchor id="GCONF-ERROR-NO-PERMISSION:CAPS" role="constant"/><literal>GCONF_ERROR_NO_PERMISSION</literal></term>
 163 <listitem><simpara>indicates that permission to access some resource was denied.
 164 </simpara></listitem>
 165 </varlistentry>
 166 <varlistentry>
 167 <term><anchor id="GCONF-ERROR-BAD-ADDRESS:CAPS" role="constant"/><literal>GCONF_ERROR_BAD_ADDRESS</literal></term>
 168 <listitem><simpara>indicates that a configuration source address was syntactically invalid or impossible to resolve.
 169 </simpara></listitem>
 170 </varlistentry>
 171 <varlistentry>
 172 <term><anchor id="GCONF-ERROR-BAD-KEY:CAPS" role="constant"/><literal>GCONF_ERROR_BAD_KEY</literal></term>
 173 <listitem><simpara>indicates that a key was malformed.
 174 </simpara></listitem>
 175 </varlistentry>
 176 <varlistentry>
 177 <term><anchor id="GCONF-ERROR-PARSE-ERROR:CAPS" role="constant"/><literal>GCONF_ERROR_PARSE_ERROR</literal></term>
 178 <listitem><simpara>indicates that some parsing was done (perhaps in a backend) and it failed.
 179 </simpara></listitem>
 180 </varlistentry>
 181 <varlistentry>
 182 <term><anchor id="GCONF-ERROR-CORRUPT:CAPS" role="constant"/><literal>GCONF_ERROR_CORRUPT</literal></term>
 183 <listitem><simpara>indicates that some part of the database is corrupt.
 184 </simpara></listitem>
 185 </varlistentry>
 186 <varlistentry>
 187 <term><anchor id="GCONF-ERROR-TYPE-MISMATCH:CAPS" role="constant"/><literal>GCONF_ERROR_TYPE_MISMATCH</literal></term>
 188 <listitem><simpara>indicates that a specific type was required, and another type was found.
 189 </simpara></listitem>
 190 </varlistentry>
 191 <varlistentry>
 192 <term><anchor id="GCONF-ERROR-IS-DIR:CAPS" role="constant"/><literal>GCONF_ERROR_IS_DIR</literal></term>
 193 <listitem><simpara>indicates that an operation only applicable to keys was performed on a directory.
 194 </simpara></listitem>
 195 </varlistentry>
 196 <varlistentry>
 197 <term><anchor id="GCONF-ERROR-IS-KEY:CAPS" role="constant"/><literal>GCONF_ERROR_IS_KEY</literal></term>
 198 <listitem><simpara>indicates that an operation only applicable to directories was performed on a key.
 199 </simpara></listitem>
 200 </varlistentry>
 201 <varlistentry>
 202 <term><anchor id="GCONF-ERROR-OVERRIDDEN:CAPS" role="constant"/><literal>GCONF_ERROR_OVERRIDDEN</literal></term>
 203 <listitem><simpara>indicates that the administrator has imposed a mandatory value, and it could not be changed.
 204 </simpara></listitem>
 205 </varlistentry>
 206 <varlistentry>
 207 <term><anchor id="GCONF-ERROR-OAF-ERROR:CAPS" role="constant"/><literal>GCONF_ERROR_OAF_ERROR</literal></term>
 208 <listitem><simpara>
 209 </simpara></listitem>
 210 </varlistentry>
 211 <varlistentry>
 212 <term><anchor id="GCONF-ERROR-LOCAL-ENGINE:CAPS" role="constant"/><literal>GCONF_ERROR_LOCAL_ENGINE</literal></term>
 213 <listitem><simpara>
 214 </simpara></listitem>
 215 </varlistentry>
 216 <varlistentry>
 217 <term><anchor id="GCONF-ERROR-LOCK-FAILED:CAPS" role="constant"/><literal>GCONF_ERROR_LOCK_FAILED</literal></term>
 218 <listitem><simpara>
 219 </simpara></listitem>
 220 </varlistentry>
 221 <varlistentry>
 222 <term><anchor id="GCONF-ERROR-NO-WRITABLE-DATABASE:CAPS" role="constant"/><literal>GCONF_ERROR_NO_WRITABLE_DATABASE</literal></term>
 223 <listitem><simpara>
 224 </simpara></listitem>
 225 </varlistentry>
 226 <varlistentry>
 227 <term><anchor id="GCONF-ERROR-IN-SHUTDOWN:CAPS" role="constant"/><literal>GCONF_ERROR_IN_SHUTDOWN</literal></term>
 228 <listitem><simpara>
 229
 230 </simpara></listitem>
 231 </varlistentry>
 232 </variablelist></refsect2>
 233 <refsect2>
 234 <title><anchor id="gconf-error-new" role="function"/>gconf_error_new ()</title>
 235 <indexterm><primary>gconf_error_new</primary></indexterm><programlisting><link linkend="GError">GError</link>*             gconf_error_new                     (<link linkend="GConfError">GConfError</link> en,
 236                                                          const <link linkend="gchar">gchar</link> *format,
 237                                                          ...);</programlisting>
 238 <para>
 239 Creates a new error. Normally the GConf library does this, but you
 240 might find a reason to do it as well. <parameter>en</parameter> is the error number, <parameter>format</parameter>
 241 is a <link linkend="printf"><function>printf()</function></link>-style format for the error message, and the variable
 242 argument list is the same as in <link linkend="printf"><function>printf()</function></link>.
 243 </para><variablelist role="params">
 244 <varlistentry><term><parameter>en</parameter>&nbsp;:</term>
 245 <listitem><simpara>the error number.
 246 </simpara></listitem></varlistentry>
 247 <varlistentry><term><parameter>format</parameter>&nbsp;:</term>
 248 <listitem><simpara><link linkend="printf"><function>printf()</function></link>-style format for error description.
 249 </simpara></listitem></varlistentry>
 250 <varlistentry><term><parameter>...</parameter>&nbsp;:</term>
 251 <listitem><simpara>arguments required by the <parameter>format</parameter>.
 252 </simpara></listitem></varlistentry>
 253 <varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>newly-allocated <link linkend="GError"><type>GError</type></link>.
 254
 255
 256 </simpara></listitem></varlistentry>
 257 </variablelist></refsect2>
 258 <refsect2>
 259 <title><anchor id="gconf-error-quark" role="function"/>gconf_error_quark ()</title>
 260 <indexterm><primary>gconf_error_quark</primary></indexterm><programlisting><link linkend="GQuark">GQuark</link>              gconf_error_quark                   (void);</programlisting>
 261 <para>
 262 Converts the string 'gconf-error-quark' to a <link linkend="GQuark"><type>GQuark</type></link> and returns the value.
 263 </para><variablelist role="params">
 264 <varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GQuark"><type>GQuark</type></link> representing the string.
 265
 266
 267 </simpara></listitem></varlistentry>
 268 </variablelist></refsect2>
 269 <refsect2>
 270 <title><anchor id="gconf-set-error" role="function"/>gconf_set_error ()</title>
 271 <indexterm><primary>gconf_set_error</primary></indexterm><programlisting><link linkend="void">void</link>                gconf_set_error                     (<link linkend="GError">GError</link> **err,
 272                                                          <link linkend="GConfError">GConfError</link> en,
 273                                                          const <link linkend="gchar">gchar</link> *format,
 274                                                          ...);</programlisting>
 275 <para>
 276 Internal function.
 277 </para><variablelist role="params">
 278 <varlistentry><term><parameter>err</parameter>&nbsp;:</term>
 279 <listitem><simpara>
 280 </simpara></listitem></varlistentry>
 281 <varlistentry><term><parameter>en</parameter>&nbsp;:</term>
 282 <listitem><simpara>
 283 </simpara></listitem></varlistentry>
 284 <varlistentry><term><parameter>format</parameter>&nbsp;:</term>
 285 <listitem><simpara>
 286 </simpara></listitem></varlistentry>
 287 <varlistentry><term><parameter>...</parameter>&nbsp;:</term>
 288 <listitem><simpara>
 289
 290
 291 </simpara></listitem></varlistentry>
 292 </variablelist></refsect2>
 293 <refsect2>
 294 <title><anchor id="gconf-compose-errors" role="function"/>gconf_compose_errors ()</title>
 295 <indexterm><primary>gconf_compose_errors</primary></indexterm><programlisting><link linkend="GError">GError</link>*             gconf_compose_errors                (<link linkend="GError">GError</link> *err1,
 296                                                          <link linkend="GError">GError</link> *err2);</programlisting>
 297 <para>
 298 Internal function.
 299 </para><variablelist role="params">
 300 <varlistentry><term><parameter>err1</parameter>&nbsp;:</term>
 301 <listitem><simpara>
 302 </simpara></listitem></varlistentry>
 303 <varlistentry><term><parameter>err2</parameter>&nbsp;:</term>
 304 <listitem><simpara>
 305 </simpara></listitem></varlistentry>
 306 <varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
 307
 308
 309 </simpara></listitem></varlistentry>
 310 </variablelist></refsect2>
 311
 312 </refsect1>
 313
 314
 315
 316
 317
 318 <refsect1><refsect2 /><refsect2 /></refsect1>
 319 </refentry>