← Back to branch summary

~ubuntu-branches/ubuntu/quantal/gconf/quantal

« back to all changes in this revision

Viewing changes to doc/gconf/xml/gconf-error.xml

  • Committer: Bazaar Package Importer
  • Author(s): Josselin Mouette
  • Date: 2007-11-01 18:47:26 UTC
  • mto: (7.1.1 lenny) (1.2.1) (76.1.1 oneiric-proposed)
  • mto: This revision was merged to the branch mainline in revision 7.
  • Revision ID: james.westby@ubuntu.com-20071101184726-e3e4cxfcp41tz6ui
Tags: upstream-2.20.1
Import upstream version 2.20.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
</refentry>