← Back to branch summary

~ubuntu-branches/ubuntu/utopic/glib2.0/utopic

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/keyfile.xml

Tags: upstream-2.12.12
Import upstream version 2.12.12

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/xml/keyfile.xml
 
1
<refentry id="glib-Key-value-file-parser">
 
2
<refmeta>
 
3
<refentrytitle role="top_of_page">Key-value file parser</refentrytitle>
 
4
<manvolnum>3</manvolnum>
 
5
<refmiscinfo>GLIB Library</refmiscinfo>
 
6
</refmeta>
 
7
 
 
8
<refnamediv>
 
9
<refname>Key-value file parser</refname>
 
10
<refpurpose>parses <filename>.ini</filename>-like config files</refpurpose>
 
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 
12
</refnamediv>
 
13
 
 
14
<refsynopsisdiv role="synopsis">
 
15
<title role="synopsis.title">Synopsis</title>
 
16
 
 
17
<synopsis>
 
18
 
 
19
#include &lt;glib.h&gt;
 
20
 
 
21
 
 
22
                    <link linkend="GKeyFile">GKeyFile</link>;
 
23
#define             <link linkend="G-KEY-FILE-ERROR:CAPS">G_KEY_FILE_ERROR</link>
 
24
enum                <link linkend="GKeyFileError">GKeyFileError</link>;
 
25
enum                <link linkend="GKeyFileFlags">GKeyFileFlags</link>;
 
26
<link linkend="GKeyFile">GKeyFile</link>*           <link linkend="g-key-file-new">g_key_file_new</link>                      (void);
 
27
<link linkend="void">void</link>                <link linkend="g-key-file-free">g_key_file_free</link>                     (<link linkend="GKeyFile">GKeyFile</link> *key_file);
 
28
<link linkend="void">void</link>                <link linkend="g-key-file-set-list-separator">g_key_file_set_list_separator</link>       (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
29
                                                         <link linkend="gchar">gchar</link> separator);
 
30
<link linkend="gboolean">gboolean</link>            <link linkend="g-key-file-load-from-file">g_key_file_load_from_file</link>           (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
31
                                                         const <link linkend="gchar">gchar</link> *file,
 
32
                                                         <link linkend="GKeyFileFlags">GKeyFileFlags</link> flags,
 
33
                                                         <link linkend="GError">GError</link> **error);
 
34
<link linkend="gboolean">gboolean</link>            <link linkend="g-key-file-load-from-data">g_key_file_load_from_data</link>           (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
35
                                                         const <link linkend="gchar">gchar</link> *data,
 
36
                                                         <link linkend="gsize">gsize</link> length,
 
37
                                                         <link linkend="GKeyFileFlags">GKeyFileFlags</link> flags,
 
38
                                                         <link linkend="GError">GError</link> **error);
 
39
<link linkend="gboolean">gboolean</link>            <link linkend="g-key-file-load-from-data-dirs">g_key_file_load_from_data_dirs</link>      (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
40
                                                         const <link linkend="gchar">gchar</link> *file,
 
41
                                                         <link linkend="gchar">gchar</link> **full_path,
 
42
                                                         <link linkend="GKeyFileFlags">GKeyFileFlags</link> flags,
 
43
                                                         <link linkend="GError">GError</link> **error);
 
44
<link linkend="gchar">gchar</link>*              <link linkend="g-key-file-to-data">g_key_file_to_data</link>                  (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
45
                                                         <link linkend="gsize">gsize</link> *length,
 
46
                                                         <link linkend="GError">GError</link> **error);
 
47
<link linkend="gchar">gchar</link>*              <link linkend="g-key-file-get-start-group">g_key_file_get_start_group</link>          (<link linkend="GKeyFile">GKeyFile</link> *key_file);
 
48
<link linkend="gchar">gchar</link>**             <link linkend="g-key-file-get-groups">g_key_file_get_groups</link>               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
49
                                                         <link linkend="gsize">gsize</link> *length);
 
50
<link linkend="gchar">gchar</link>**             <link linkend="g-key-file-get-keys">g_key_file_get_keys</link>                 (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
51
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
52
                                                         <link linkend="gsize">gsize</link> *length,
 
53
                                                         <link linkend="GError">GError</link> **error);
 
54
<link linkend="gboolean">gboolean</link>            <link linkend="g-key-file-has-group">g_key_file_has_group</link>                (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
55
                                                         const <link linkend="gchar">gchar</link> *group_name);
 
56
<link linkend="gboolean">gboolean</link>            <link linkend="g-key-file-has-key">g_key_file_has_key</link>                  (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
57
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
58
                                                         const <link linkend="gchar">gchar</link> *key,
 
59
                                                         <link linkend="GError">GError</link> **error);
 
60
 
 
61
<link linkend="gchar">gchar</link>*              <link linkend="g-key-file-get-value">g_key_file_get_value</link>                (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
62
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
63
                                                         const <link linkend="gchar">gchar</link> *key,
 
64
                                                         <link linkend="GError">GError</link> **error);
 
65
<link linkend="gchar">gchar</link>*              <link linkend="g-key-file-get-string">g_key_file_get_string</link>               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
66
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
67
                                                         const <link linkend="gchar">gchar</link> *key,
 
68
                                                         <link linkend="GError">GError</link> **error);
 
69
<link linkend="gchar">gchar</link>*              <link linkend="g-key-file-get-locale-string">g_key_file_get_locale_string</link>        (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
70
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
71
                                                         const <link linkend="gchar">gchar</link> *key,
 
72
                                                         const <link linkend="gchar">gchar</link> *locale,
 
73
                                                         <link linkend="GError">GError</link> **error);
 
74
<link linkend="gboolean">gboolean</link>            <link linkend="g-key-file-get-boolean">g_key_file_get_boolean</link>              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
75
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
76
                                                         const <link linkend="gchar">gchar</link> *key,
 
77
                                                         <link linkend="GError">GError</link> **error);
 
78
<link linkend="gint">gint</link>                <link linkend="g-key-file-get-integer">g_key_file_get_integer</link>              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
79
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
80
                                                         const <link linkend="gchar">gchar</link> *key,
 
81
                                                         <link linkend="GError">GError</link> **error);
 
82
<link linkend="gdouble">gdouble</link>             <link linkend="g-key-file-get-double">g_key_file_get_double</link>               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
83
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
84
                                                         const <link linkend="gchar">gchar</link> *key,
 
85
                                                         <link linkend="GError">GError</link> **error);
 
86
<link linkend="gchar">gchar</link>**             <link linkend="g-key-file-get-string-list">g_key_file_get_string_list</link>          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
87
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
88
                                                         const <link linkend="gchar">gchar</link> *key,
 
89
                                                         <link linkend="gsize">gsize</link> *length,
 
90
                                                         <link linkend="GError">GError</link> **error);
 
91
<link linkend="gchar">gchar</link>**             <link linkend="g-key-file-get-locale-string-list">g_key_file_get_locale_string_list</link>   (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
92
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
93
                                                         const <link linkend="gchar">gchar</link> *key,
 
94
                                                         const <link linkend="gchar">gchar</link> *locale,
 
95
                                                         <link linkend="gsize">gsize</link> *length,
 
96
                                                         <link linkend="GError">GError</link> **error);
 
97
<link linkend="gboolean">gboolean</link>*           <link linkend="g-key-file-get-boolean-list">g_key_file_get_boolean_list</link>         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
98
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
99
                                                         const <link linkend="gchar">gchar</link> *key,
 
100
                                                         <link linkend="gsize">gsize</link> *length,
 
101
                                                         <link linkend="GError">GError</link> **error);
 
102
<link linkend="gint">gint</link>*               <link linkend="g-key-file-get-integer-list">g_key_file_get_integer_list</link>         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
103
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
104
                                                         const <link linkend="gchar">gchar</link> *key,
 
105
                                                         <link linkend="gsize">gsize</link> *length,
 
106
                                                         <link linkend="GError">GError</link> **error);
 
107
<link linkend="gdouble">gdouble</link>*            <link linkend="g-key-file-get-double-list">g_key_file_get_double_list</link>          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
108
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
109
                                                         const <link linkend="gchar">gchar</link> *key,
 
110
                                                         <link linkend="gsize">gsize</link> *length,
 
111
                                                         <link linkend="GError">GError</link> **error);
 
112
<link linkend="gchar">gchar</link>*              <link linkend="g-key-file-get-comment">g_key_file_get_comment</link>              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
113
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
114
                                                         const <link linkend="gchar">gchar</link> *key,
 
115
                                                         <link linkend="GError">GError</link> **error);
 
116
 
 
117
<link linkend="void">void</link>                <link linkend="g-key-file-set-value">g_key_file_set_value</link>                (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
118
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
119
                                                         const <link linkend="gchar">gchar</link> *key,
 
120
                                                         const <link linkend="gchar">gchar</link> *value);
 
121
<link linkend="void">void</link>                <link linkend="g-key-file-set-string">g_key_file_set_string</link>               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
122
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
123
                                                         const <link linkend="gchar">gchar</link> *key,
 
124
                                                         const <link linkend="gchar">gchar</link> *string);
 
125
<link linkend="void">void</link>                <link linkend="g-key-file-set-locale-string">g_key_file_set_locale_string</link>        (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
126
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
127
                                                         const <link linkend="gchar">gchar</link> *key,
 
128
                                                         const <link linkend="gchar">gchar</link> *locale,
 
129
                                                         const <link linkend="gchar">gchar</link> *string);
 
130
<link linkend="void">void</link>                <link linkend="g-key-file-set-boolean">g_key_file_set_boolean</link>              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
131
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
132
                                                         const <link linkend="gchar">gchar</link> *key,
 
133
                                                         <link linkend="gboolean">gboolean</link> value);
 
134
<link linkend="void">void</link>                <link linkend="g-key-file-set-integer">g_key_file_set_integer</link>              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
135
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
136
                                                         const <link linkend="gchar">gchar</link> *key,
 
137
                                                         <link linkend="gint">gint</link> value);
 
138
<link linkend="void">void</link>                <link linkend="g-key-file-set-double">g_key_file_set_double</link>               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
139
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
140
                                                         const <link linkend="gchar">gchar</link> *key,
 
141
                                                         <link linkend="gdouble">gdouble</link> value);
 
142
<link linkend="void">void</link>                <link linkend="g-key-file-set-string-list">g_key_file_set_string_list</link>          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
143
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
144
                                                         const <link linkend="gchar">gchar</link> *key,
 
145
                                                         const <link linkend="gchar">gchar</link> * const list[],
 
146
                                                         <link linkend="gsize">gsize</link> length);
 
147
<link linkend="void">void</link>                <link linkend="g-key-file-set-locale-string-list">g_key_file_set_locale_string_list</link>   (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
148
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
149
                                                         const <link linkend="gchar">gchar</link> *key,
 
150
                                                         const <link linkend="gchar">gchar</link> *locale,
 
151
                                                         const <link linkend="gchar">gchar</link> * const list[],
 
152
                                                         <link linkend="gsize">gsize</link> length);
 
153
<link linkend="void">void</link>                <link linkend="g-key-file-set-boolean-list">g_key_file_set_boolean_list</link>         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
154
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
155
                                                         const <link linkend="gchar">gchar</link> *key,
 
156
                                                         <link linkend="gboolean">gboolean</link> list[],
 
157
                                                         <link linkend="gsize">gsize</link> length);
 
158
<link linkend="void">void</link>                <link linkend="g-key-file-set-integer-list">g_key_file_set_integer_list</link>         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
159
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
160
                                                         const <link linkend="gchar">gchar</link> *key,
 
161
                                                         <link linkend="gint">gint</link> list[],
 
162
                                                         <link linkend="gsize">gsize</link> length);
 
163
<link linkend="void">void</link>                <link linkend="g-key-file-set-double-list">g_key_file_set_double_list</link>          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
164
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
165
                                                         const <link linkend="gchar">gchar</link> *key,
 
166
                                                         <link linkend="gdouble">gdouble</link> list[],
 
167
                                                         <link linkend="gsize">gsize</link> length);
 
168
<link linkend="void">void</link>                <link linkend="g-key-file-set-comment">g_key_file_set_comment</link>              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
169
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
170
                                                         const <link linkend="gchar">gchar</link> *key,
 
171
                                                         const <link linkend="gchar">gchar</link> *comment,
 
172
                                                         <link linkend="GError">GError</link> **error);
 
173
<link linkend="void">void</link>                <link linkend="g-key-file-remove-group">g_key_file_remove_group</link>             (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
174
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
175
                                                         <link linkend="GError">GError</link> **error);
 
176
<link linkend="void">void</link>                <link linkend="g-key-file-remove-key">g_key_file_remove_key</link>               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
177
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
178
                                                         const <link linkend="gchar">gchar</link> *key,
 
179
                                                         <link linkend="GError">GError</link> **error);
 
180
<link linkend="void">void</link>                <link linkend="g-key-file-remove-comment">g_key_file_remove_comment</link>           (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
181
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
182
                                                         const <link linkend="gchar">gchar</link> *key,
 
183
                                                         <link linkend="GError">GError</link> **error);
 
184
 
 
185
</synopsis>
 
186
</refsynopsisdiv>
 
187
 
 
188
 
 
189
 
 
190
 
 
191
 
 
192
 
 
193
 
 
194
 
 
195
 
 
196
<refsect1 role="desc">
 
197
<title role="desc.title">Description</title>
 
198
<para>
 
199
<link linkend="GKeyFile"><type>GKeyFile</type></link> lets you parse, edit or create files containing groups of
 
200
key-value pairs, which we call <firstterm>key files</firstterm> for 
 
201
lack of a better name. Several freedesktop.org specifications use
 
202
key files now, e.g the 
 
203
<ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
 
204
Entry Specification</ulink> and the
 
205
<ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon
 
206
Theme Specification</ulink>. 
 
207
</para>
 
208
 
 
209
<para>
 
210
The syntax of key files is described in detail in the 
 
211
<ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
 
212
Entry Specification</ulink>, here is a quick summary: Key files
 
213
consists of groups of key-value pairs, interspersed with comments.
 
214
</para>
 
215
 
 
216
<informalexample><programlisting>
 
217
# this is just an example
 
218
# there can be comments before the first group
 
219
 
 
220
[First Group]
 
221
 
 
222
Name=Key File Example\tthis value shows\nescaping
 
223
 
 
224
# localized strings are stored in multiple key-value pairs
 
225
Welcome=Hello
 
226
Welcome[de]=Hallo
 
227
Welcome[fr]=Bonjour
 
228
Welcome[it]=Ciao
 
229
 
 
230
[Another Group]
 
231
 
 
232
Numbers=2;20;-200;0
 
233
 
 
234
Booleans=true;false;true;true
 
235
 
 
236
</programlisting></informalexample>
 
237
 
 
238
<para>
 
239
Lines beginning with a '#' and blank lines are considered comments.
 
240
</para>
 
241
 
 
242
<para>
 
243
Groups are started by a header line containing the group name enclosed
 
244
in '[' and ']', and ended implicitly by the start of the next group or
 
245
the end of the file. Each key-value pair must be contained in a group.
 
246
</para>
 
247
 
 
248
<para>
 
249
Key-value pairs generally have the form <literal>key=value</literal>, 
 
250
with the exception of localized strings, which have the form 
 
251
<literal>key[locale]=value</literal>. Space before and after the 
 
252
'=' character are ignored. Newline, tab, carriage return and backslash 
 
253
characters are escaped as \n, \t, \r, and \\, respectively. To preserve
 
254
leading spaces in values, these can also be escaped as \s.
 
255
</para>
 
256
 
 
257
<para>
 
258
Key files can store strings (possibly with localized variants), integers,
 
259
booleans and lists of these. Lists are separated by a separator character,
 
260
typically ';' or ','. To use the list separator character in a value in
 
261
a list, it has to be escaped by prefixing it with a backslash.
 
262
</para>
 
263
 
 
264
<para>
 
265
This syntax is obviously inspired by the <filename>.ini</filename> 
 
266
files commonly met on Windows, but there are some important differences:
 
267
<itemizedlist>
 
268
<listitem><para>
 
269
<filename>.ini</filename> files use the ';' character to begin comments,
 
270
 key files use the '#' character.
 
271
</para></listitem>
 
272
<listitem><para>
 
273
Key files allow only comments before the first group.
 
274
</para></listitem>
 
275
<listitem><para>
 
276
Key files are always encoded in UTF-8.
 
277
</para></listitem>
 
278
<listitem><para>
 
279
Key and Group names are case-sensitive, for example a group called
 
280
<literal>[GROUP]</literal> is a different group from <literal>[group]</literal>.
 
281
</para></listitem>
 
282
</itemizedlist>
 
283
</para>
 
284
 
 
285
<para>
 
286
Note that in contrast to the
 
287
<ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
 
288
Entry Specification</ulink>, groups in key files may contain the same
 
289
key multiple times; the last entry wins. Key files may also contain
 
290
multiple groups with the same name; they are merged together.
 
291
Another difference is that keys and group names in key files are not
 
292
restricted to ASCII characters.
 
293
</para>
 
294
</refsect1>
 
295
 
 
296
<refsect1 role="details">
 
297
<title role="details.title">Details</title>
 
298
<refsect2>
 
299
<title><anchor id="GKeyFile" role="struct"/>GKeyFile</title>
 
300
<indexterm><primary>GKeyFile</primary></indexterm><programlisting>typedef struct _GKeyFile GKeyFile;</programlisting>
 
301
<para>
 
302
The <structname>GKeyFile</structname> struct contains only private fields
 
303
and should not be used directly.
 
304
</para></refsect2>
 
305
<refsect2>
 
306
<title><anchor id="G-KEY-FILE-ERROR:CAPS" role="macro"/>G_KEY_FILE_ERROR</title>
 
307
<indexterm><primary>G_KEY_FILE_ERROR</primary></indexterm><programlisting>#define G_KEY_FILE_ERROR g_key_file_error_quark()
 
308
</programlisting>
 
309
<para>
 
310
Error domain for key file parsing. Errors in this domain will
 
311
be from the <link linkend="GKeyFileError"><type>GKeyFileError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on 
 
312
error domains.
 
313
</para></refsect2>
 
314
<refsect2>
 
315
<title><anchor id="GKeyFileError" role="enum"/>enum GKeyFileError</title>
 
316
<indexterm><primary>GKeyFileError</primary></indexterm><programlisting>typedef enum
 
317
{
 
318
  G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
 
319
  G_KEY_FILE_ERROR_PARSE,
 
320
  G_KEY_FILE_ERROR_NOT_FOUND,
 
321
  G_KEY_FILE_ERROR_KEY_NOT_FOUND,
 
322
  G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
 
323
  G_KEY_FILE_ERROR_INVALID_VALUE
 
324
} GKeyFileError;
 
325
</programlisting>
 
326
<para>
 
327
Error codes returned by key file parsing.
 
328
</para><variablelist role="enum">
 
329
<varlistentry>
 
330
<term><anchor id="G-KEY-FILE-ERROR-UNKNOWN-ENCODING:CAPS" role="constant"/><literal>G_KEY_FILE_ERROR_UNKNOWN_ENCODING</literal></term>
 
331
<listitem><simpara>the text being parsed was in an unknown encoding
 
332
</simpara></listitem>
 
333
</varlistentry>
 
334
<varlistentry>
 
335
<term><anchor id="G-KEY-FILE-ERROR-PARSE:CAPS" role="constant"/><literal>G_KEY_FILE_ERROR_PARSE</literal></term>
 
336
<listitem><simpara>document was ill-formed
 
337
</simpara></listitem>
 
338
</varlistentry>
 
339
<varlistentry>
 
340
<term><anchor id="G-KEY-FILE-ERROR-NOT-FOUND:CAPS" role="constant"/><literal>G_KEY_FILE_ERROR_NOT_FOUND</literal></term>
 
341
<listitem><simpara>the file was not found
 
342
</simpara></listitem>
 
343
</varlistentry>
 
344
<varlistentry>
 
345
<term><anchor id="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS" role="constant"/><literal>G_KEY_FILE_ERROR_KEY_NOT_FOUND</literal></term>
 
346
<listitem><simpara>a requested key was not found
 
347
</simpara></listitem>
 
348
</varlistentry>
 
349
<varlistentry>
 
350
<term><anchor id="G-KEY-FILE-ERROR-GROUP-NOT-FOUND:CAPS" role="constant"/><literal>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</literal></term>
 
351
<listitem><simpara>a requested group was not found
 
352
</simpara></listitem>
 
353
</varlistentry>
 
354
<varlistentry>
 
355
<term><anchor id="G-KEY-FILE-ERROR-INVALID-VALUE:CAPS" role="constant"/><literal>G_KEY_FILE_ERROR_INVALID_VALUE</literal></term>
 
356
<listitem><simpara>a value could not be parsed
 
357
 
 
358
</simpara></listitem>
 
359
</varlistentry>
 
360
</variablelist></refsect2>
 
361
<refsect2>
 
362
<title><anchor id="GKeyFileFlags" role="enum"/>enum GKeyFileFlags</title>
 
363
<indexterm><primary>GKeyFileFlags</primary></indexterm><programlisting>typedef enum
 
364
{
 
365
  G_KEY_FILE_NONE              = 0,
 
366
  G_KEY_FILE_KEEP_COMMENTS     = 1 &lt;&lt; 0,
 
367
  G_KEY_FILE_KEEP_TRANSLATIONS = 1 &lt;&lt; 1
 
368
} GKeyFileFlags;
 
369
</programlisting>
 
370
<para>
 
371
Flags which influence the parsing.
 
372
</para><variablelist role="enum">
 
373
<varlistentry>
 
374
<term><anchor id="G-KEY-FILE-NONE:CAPS" role="constant"/><literal>G_KEY_FILE_NONE</literal></term>
 
375
<listitem><simpara>No flags, default behaviour
 
376
</simpara></listitem>
 
377
</varlistentry>
 
378
<varlistentry>
 
379
<term><anchor id="G-KEY-FILE-KEEP-COMMENTS:CAPS" role="constant"/><literal>G_KEY_FILE_KEEP_COMMENTS</literal></term>
 
380
<listitem><simpara>Use this flag if you plan to write the (possibly modified)
 
381
  contents of the key file back to a file; otherwise all comments will be lost when
 
382
  the key file is written back.
 
383
</simpara></listitem>
 
384
</varlistentry>
 
385
<varlistentry>
 
386
<term><anchor id="G-KEY-FILE-KEEP-TRANSLATIONS:CAPS" role="constant"/><literal>G_KEY_FILE_KEEP_TRANSLATIONS</literal></term>
 
387
<listitem><simpara>Use this flag if you plan to write the (possibly modified)
 
388
  contents of the key file back to a file; otherwise only the translations for the current
 
389
  language will be written back.
 
390
 
 
391
</simpara></listitem>
 
392
</varlistentry>
 
393
</variablelist></refsect2>
 
394
<refsect2>
 
395
<title><anchor id="g-key-file-new" role="function" condition="since:2.6"/>g_key_file_new ()</title>
 
396
<indexterm role="2.6"><primary>g_key_file_new</primary></indexterm><programlisting><link linkend="GKeyFile">GKeyFile</link>*           g_key_file_new                      (void);</programlisting>
 
397
<para>
 
398
Creates a new empty <link linkend="GKeyFile"><type>GKeyFile</type></link> object. Use <link linkend="g-key-file-load-from-file"><function>g_key_file_load_from_file()</function></link>,
 
399
<link linkend="g-key-file-load-from-data"><function>g_key_file_load_from_data()</function></link> or <link linkend="g-key-file-load-from-data-dirs"><function>g_key_file_load_from_data_dirs()</function></link> to
 
400
read an existing key file.</para>
 
401
<para>
 
402
 
 
403
</para><variablelist role="params">
 
404
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> an empty <link linkend="GKeyFile"><type>GKeyFile</type></link>.
 
405
 
 
406
</simpara></listitem></varlistentry>
 
407
</variablelist><para role="since">Since  2.6
 
408
</para></refsect2>
 
409
<refsect2>
 
410
<title><anchor id="g-key-file-free" role="function" condition="since:2.6"/>g_key_file_free ()</title>
 
411
<indexterm role="2.6"><primary>g_key_file_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_free                     (<link linkend="GKeyFile">GKeyFile</link> *key_file);</programlisting>
 
412
<para>
 
413
Frees a <link linkend="GKeyFile"><type>GKeyFile</type></link>.</para>
 
414
<para>
 
415
 
 
416
</para><variablelist role="params">
 
417
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
418
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
419
</simpara></listitem></varlistentry>
 
420
</variablelist><para role="since">Since  2.6
 
421
</para></refsect2>
 
422
<refsect2>
 
423
<title><anchor id="g-key-file-set-list-separator" role="function" condition="since:2.6"/>g_key_file_set_list_separator ()</title>
 
424
<indexterm role="2.6"><primary>g_key_file_set_list_separator</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_list_separator       (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
425
                                                         <link linkend="gchar">gchar</link> separator);</programlisting>
 
426
<para>
 
427
Sets the character which is used to separate
 
428
values in lists. Typically ';' or ',' are used
 
429
as separators. The default list separator is ';'.</para>
 
430
<para>
 
431
 
 
432
</para><variablelist role="params">
 
433
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
434
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link> 
 
435
</simpara></listitem></varlistentry>
 
436
<varlistentry><term><parameter>separator</parameter>&nbsp;:</term>
 
437
<listitem><simpara> the separator
 
438
</simpara></listitem></varlistentry>
 
439
</variablelist><para role="since">Since  2.6
 
440
</para></refsect2>
 
441
<refsect2>
 
442
<title><anchor id="g-key-file-load-from-file" role="function" condition="since:2.6"/>g_key_file_load_from_file ()</title>
 
443
<indexterm role="2.6"><primary>g_key_file_load_from_file</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_key_file_load_from_file           (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
444
                                                         const <link linkend="gchar">gchar</link> *file,
 
445
                                                         <link linkend="GKeyFileFlags">GKeyFileFlags</link> flags,
 
446
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
447
<para>
 
448
Loads a key file into an empty <link linkend="GKeyFile"><type>GKeyFile</type></link> structure.
 
449
If the file could not be loaded then <link linkend="error"><literal>error</literal></link> is set to 
 
450
either a <link linkend="GFileError"><type>GFileError</type></link> or <link linkend="GKeyFileError"><type>GKeyFileError</type></link>.</para>
 
451
<para>
 
452
 
 
453
</para><variablelist role="params">
 
454
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
455
<listitem><simpara> an empty <link linkend="GKeyFile"><type>GKeyFile</type></link> struct
 
456
</simpara></listitem></varlistentry>
 
457
<varlistentry><term><parameter>file</parameter>&nbsp;:</term>
 
458
<listitem><simpara> the path of a filename to load, in the GLib file name encoding
 
459
</simpara></listitem></varlistentry>
 
460
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
 
461
<listitem><simpara> flags from <link linkend="GKeyFileFlags"><type>GKeyFileFlags</type></link>
 
462
</simpara></listitem></varlistentry>
 
463
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
464
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
465
</simpara></listitem></varlistentry>
 
466
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if a key file could be loaded, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> othewise
 
467
</simpara></listitem></varlistentry>
 
468
</variablelist><para role="since">Since  2.6
 
469
</para></refsect2>
 
470
<refsect2>
 
471
<title><anchor id="g-key-file-load-from-data" role="function" condition="since:2.6"/>g_key_file_load_from_data ()</title>
 
472
<indexterm role="2.6"><primary>g_key_file_load_from_data</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_key_file_load_from_data           (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
473
                                                         const <link linkend="gchar">gchar</link> *data,
 
474
                                                         <link linkend="gsize">gsize</link> length,
 
475
                                                         <link linkend="GKeyFileFlags">GKeyFileFlags</link> flags,
 
476
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
477
<para>
 
478
Loads a key file from memory into an empty <link linkend="GKeyFile"><type>GKeyFile</type></link> structure.  If
 
479
the object cannot be created then <link linkend="error"><literal>error</literal></link> is set to a
 
480
<link linkend="GKeyFileError"><type>GKeyFileError</type></link>.</para>
 
481
<para>
 
482
 
 
483
</para><variablelist role="params">
 
484
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
485
<listitem><simpara> an empty <link linkend="GKeyFile"><type>GKeyFile</type></link> struct
 
486
</simpara></listitem></varlistentry>
 
487
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
488
<listitem><simpara> key file loaded in memory.
 
489
</simpara></listitem></varlistentry>
 
490
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
491
<listitem><simpara> the length of <parameter>data</parameter> in bytes
 
492
</simpara></listitem></varlistentry>
 
493
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
 
494
<listitem><simpara> flags from <link linkend="GKeyFileFlags"><type>GKeyFileFlags</type></link>
 
495
</simpara></listitem></varlistentry>
 
496
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
497
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
498
</simpara></listitem></varlistentry>
 
499
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if a key file could be loaded, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> othewise
 
500
</simpara></listitem></varlistentry>
 
501
</variablelist><para role="since">Since  2.6
 
502
</para></refsect2>
 
503
<refsect2>
 
504
<title><anchor id="g-key-file-load-from-data-dirs" role="function" condition="since:2.6"/>g_key_file_load_from_data_dirs ()</title>
 
505
<indexterm role="2.6"><primary>g_key_file_load_from_data_dirs</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_key_file_load_from_data_dirs      (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
506
                                                         const <link linkend="gchar">gchar</link> *file,
 
507
                                                         <link linkend="gchar">gchar</link> **full_path,
 
508
                                                         <link linkend="GKeyFileFlags">GKeyFileFlags</link> flags,
 
509
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
510
<para>
 
511
This function looks for a key file named <parameter>file</parameter> in the paths 
 
512
returned from <link linkend="g-get-user-data-dir"><function>g_get_user_data_dir()</function></link> and <link linkend="g-get-system-data-dirs"><function>g_get_system_data_dirs()</function></link>, 
 
513
loads the file into <parameter>key_file</parameter> and returns the file's full path in 
 
514
<parameter>full_path</parameter>.  If the file could not be loaded then an <link linkend="error"><literal>error</literal></link> is
 
515
set to either a <link linkend="GFileError"><type>GFileError</type></link> or <link linkend="GKeyFileError"><type>GKeyFileError</type></link>.</para>
 
516
<para>
 
517
 
 
518
</para><variablelist role="params">
 
519
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
520
<listitem><simpara> an empty <link linkend="GKeyFile"><type>GKeyFile</type></link> struct
 
521
</simpara></listitem></varlistentry>
 
522
<varlistentry><term><parameter>file</parameter>&nbsp;:</term>
 
523
<listitem><simpara> a relative path to a filename to open and parse
 
524
</simpara></listitem></varlistentry>
 
525
<varlistentry><term><parameter>full_path</parameter>&nbsp;:</term>
 
526
<listitem><simpara> return location for a string containing the full path
 
527
  of the file, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
528
</simpara></listitem></varlistentry>
 
529
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
 
530
<listitem><simpara> flags from <link linkend="GKeyFileFlags"><type>GKeyFileFlags</type></link> 
 
531
</simpara></listitem></varlistentry>
 
532
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
533
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
534
</simpara></listitem></varlistentry>
 
535
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if a key file could be loaded, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> othewise
 
536
</simpara></listitem></varlistentry>
 
537
</variablelist><para role="since">Since  2.6
 
538
</para></refsect2>
 
539
<refsect2>
 
540
<title><anchor id="g-key-file-to-data" role="function" condition="since:2.6"/>g_key_file_to_data ()</title>
 
541
<indexterm role="2.6"><primary>g_key_file_to_data</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_key_file_to_data                  (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
542
                                                         <link linkend="gsize">gsize</link> *length,
 
543
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
544
<para>
 
545
This function outputs <parameter>key_file</parameter> as a string.</para>
 
546
<para>
 
547
 
 
548
</para><variablelist role="params">
 
549
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
550
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
551
</simpara></listitem></varlistentry>
 
552
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
553
<listitem><simpara> return location for the length of the 
 
554
  returned string, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
555
</simpara></listitem></varlistentry>
 
556
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
557
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
558
</simpara></listitem></varlistentry>
 
559
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string holding
 
560
  the contents of the <link linkend="GKeyFile"><type>GKeyFile</type></link> 
 
561
 
 
562
</simpara></listitem></varlistentry>
 
563
</variablelist><para role="since">Since  2.6
 
564
</para></refsect2>
 
565
<refsect2>
 
566
<title><anchor id="g-key-file-get-start-group" role="function" condition="since:2.6"/>g_key_file_get_start_group ()</title>
 
567
<indexterm role="2.6"><primary>g_key_file_get_start_group</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_key_file_get_start_group          (<link linkend="GKeyFile">GKeyFile</link> *key_file);</programlisting>
 
568
<para>
 
569
Returns the name of the start group of the file.</para>
 
570
<para>
 
571
 
 
572
</para><variablelist role="params">
 
573
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
574
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
575
</simpara></listitem></varlistentry>
 
576
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The start group of the key file.
 
577
 
 
578
</simpara></listitem></varlistentry>
 
579
</variablelist><para role="since">Since  2.6
 
580
</para></refsect2>
 
581
<refsect2>
 
582
<title><anchor id="g-key-file-get-groups" role="function" condition="since:2.6"/>g_key_file_get_groups ()</title>
 
583
<indexterm role="2.6"><primary>g_key_file_get_groups</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_key_file_get_groups               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
584
                                                         <link linkend="gsize">gsize</link> *length);</programlisting>
 
585
<para>
 
586
Returns all groups in the key file loaded with <parameter>key_file</parameter>.  The
 
587
array of returned groups will be <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated, so <parameter>length</parameter> may
 
588
optionally be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
 
589
<para>
 
590
 
 
591
</para><variablelist role="params">
 
592
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
593
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
594
</simpara></listitem></varlistentry>
 
595
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
596
<listitem><simpara> return location for the number of returned groups, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
597
</simpara></listitem></varlistentry>
 
598
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly-allocated <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings. 
 
599
  Use <link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.
 
600
</simpara></listitem></varlistentry>
 
601
</variablelist><para role="since">Since  2.6
 
602
</para></refsect2>
 
603
<refsect2>
 
604
<title><anchor id="g-key-file-get-keys" role="function" condition="since:2.6"/>g_key_file_get_keys ()</title>
 
605
<indexterm role="2.6"><primary>g_key_file_get_keys</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_key_file_get_keys                 (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
606
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
607
                                                         <link linkend="gsize">gsize</link> *length,
 
608
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
609
<para>
 
610
Returns all keys for the group name <parameter>group_name</parameter>.  The array of
 
611
returned keys will be <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated, so <parameter>length</parameter> may
 
612
optionally be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. In the event that the <parameter>group_name</parameter> cannot
 
613
be found, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned and <parameter>error</parameter> is set to
 
614
<link linkend="G-KEY-FILE-ERROR-GROUP-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type></link>.</para>
 
615
<para>
 
616
 
 
617
</para><variablelist role="params">
 
618
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
619
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
620
</simpara></listitem></varlistentry>
 
621
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
622
<listitem><simpara> a group name
 
623
</simpara></listitem></varlistentry>
 
624
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
625
<listitem><simpara> return location for the number of keys returned, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
626
</simpara></listitem></varlistentry>
 
627
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
628
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
629
</simpara></listitem></varlistentry>
 
630
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly-allocated <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of
 
631
strings. Use <link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.
 
632
 
 
633
</simpara></listitem></varlistentry>
 
634
</variablelist><para role="since">Since  2.6
 
635
</para></refsect2>
 
636
<refsect2>
 
637
<title><anchor id="g-key-file-has-group" role="function" condition="since:2.6"/>g_key_file_has_group ()</title>
 
638
<indexterm role="2.6"><primary>g_key_file_has_group</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_key_file_has_group                (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
639
                                                         const <link linkend="gchar">gchar</link> *group_name);</programlisting>
 
640
<para>
 
641
Looks whether the key file has the group <parameter>group_name</parameter>.</para>
 
642
<para>
 
643
 
 
644
</para><variablelist role="params">
 
645
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
646
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
647
</simpara></listitem></varlistentry>
 
648
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
649
<listitem><simpara> a group name
 
650
</simpara></listitem></varlistentry>
 
651
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>group_name</parameter> is a part of <parameter>key_file</parameter>, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
 
652
otherwise.
 
653
</simpara></listitem></varlistentry>
 
654
</variablelist><para role="since">Since  2.6
 
655
</para></refsect2>
 
656
<refsect2>
 
657
<title><anchor id="g-key-file-has-key" role="function" condition="since:2.6"/>g_key_file_has_key ()</title>
 
658
<indexterm role="2.6"><primary>g_key_file_has_key</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_key_file_has_key                  (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
659
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
660
                                                         const <link linkend="gchar">gchar</link> *key,
 
661
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
662
<para>
 
663
Looks whether the key file has the key <parameter>key</parameter> in the group
 
664
<parameter>group_name</parameter>.</para>
 
665
<para>
 
666
 
 
667
</para><variablelist role="params">
 
668
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
669
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
670
</simpara></listitem></varlistentry>
 
671
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
672
<listitem><simpara> a group name
 
673
</simpara></listitem></varlistentry>
 
674
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
675
<listitem><simpara> a key name
 
676
</simpara></listitem></varlistentry>
 
677
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
678
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
679
</simpara></listitem></varlistentry>
 
680
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>key</parameter> is a part of <parameter>group_name</parameter>, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
 
681
otherwise.
 
682
 
 
683
</simpara></listitem></varlistentry>
 
684
</variablelist><para role="since">Since  2.6
 
685
</para></refsect2>
 
686
<refsect2>
 
687
<title><anchor id="g-key-file-get-value" role="function" condition="since:2.6"/>g_key_file_get_value ()</title>
 
688
<indexterm role="2.6"><primary>g_key_file_get_value</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_key_file_get_value                (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
689
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
690
                                                         const <link linkend="gchar">gchar</link> *key,
 
691
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
692
<para>
 
693
Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter>.  
 
694
</para>
 
695
<para>
 
696
In the event the key cannot be found, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned and 
 
697
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>.  In the 
 
698
event that the <parameter>group_name</parameter> cannot be found, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned 
 
699
and <parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-GROUP-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type></link>.</para>
 
700
<para>
 
701
 
 
702
</para><variablelist role="params">
 
703
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
704
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
705
</simpara></listitem></varlistentry>
 
706
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
707
<listitem><simpara> a group name
 
708
</simpara></listitem></varlistentry>
 
709
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
710
<listitem><simpara> a key
 
711
</simpara></listitem></varlistentry>
 
712
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
713
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
714
</simpara></listitem></varlistentry>
 
715
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the specified 
 
716
 key cannot be found.
 
717
 
 
718
</simpara></listitem></varlistentry>
 
719
</variablelist><para role="since">Since  2.6
 
720
</para></refsect2>
 
721
<refsect2>
 
722
<title><anchor id="g-key-file-get-string" role="function" condition="since:2.6"/>g_key_file_get_string ()</title>
 
723
<indexterm role="2.6"><primary>g_key_file_get_string</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_key_file_get_string               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
724
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
725
                                                         const <link linkend="gchar">gchar</link> *key,
 
726
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
727
<para>
 
728
Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter>.  
 
729
</para>
 
730
<para>
 
731
In the event the key cannot be found, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned and 
 
732
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>.  In the 
 
733
event that the <parameter>group_name</parameter> cannot be found, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned 
 
734
and <parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-GROUP-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type></link>.</para>
 
735
<para>
 
736
 
 
737
</para><variablelist role="params">
 
738
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
739
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
740
</simpara></listitem></varlistentry>
 
741
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
742
<listitem><simpara> a group name
 
743
</simpara></listitem></varlistentry>
 
744
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
745
<listitem><simpara> a key
 
746
</simpara></listitem></varlistentry>
 
747
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
748
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
749
</simpara></listitem></varlistentry>
 
750
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the specified 
 
751
  key cannot be found.
 
752
 
 
753
</simpara></listitem></varlistentry>
 
754
</variablelist><para role="since">Since  2.6
 
755
</para></refsect2>
 
756
<refsect2>
 
757
<title><anchor id="g-key-file-get-locale-string" role="function" condition="since:2.6"/>g_key_file_get_locale_string ()</title>
 
758
<indexterm role="2.6"><primary>g_key_file_get_locale_string</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_key_file_get_locale_string        (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
759
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
760
                                                         const <link linkend="gchar">gchar</link> *key,
 
761
                                                         const <link linkend="gchar">gchar</link> *locale,
 
762
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
763
<para>
 
764
Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter>
 
765
translated in the given <parameter>locale</parameter> if available.  If <parameter>locale</parameter> is
 
766
<link linkend="NULL:CAPS"><literal>NULL</literal></link> then the current locale is assumed. 
 
767
</para>
 
768
<para>
 
769
If <parameter>key</parameter> cannot be found then <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned and <parameter>error</parameter> is set to
 
770
<link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. If the value associated
 
771
with <parameter>key</parameter> cannot be interpreted or no suitable translation can
 
772
be found then the untranslated value is returned.</para>
 
773
<para>
 
774
 
 
775
</para><variablelist role="params">
 
776
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
777
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
778
</simpara></listitem></varlistentry>
 
779
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
780
<listitem><simpara> a group name
 
781
</simpara></listitem></varlistentry>
 
782
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
783
<listitem><simpara> a key
 
784
</simpara></listitem></varlistentry>
 
785
<varlistentry><term><parameter>locale</parameter>&nbsp;:</term>
 
786
<listitem><simpara> a locale or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
787
</simpara></listitem></varlistentry>
 
788
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
789
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
790
</simpara></listitem></varlistentry>
 
791
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the specified 
 
792
  key cannot be found.
 
793
 
 
794
</simpara></listitem></varlistentry>
 
795
</variablelist><para role="since">Since  2.6
 
796
</para></refsect2>
 
797
<refsect2>
 
798
<title><anchor id="g-key-file-get-boolean" role="function" condition="since:2.6"/>g_key_file_get_boolean ()</title>
 
799
<indexterm role="2.6"><primary>g_key_file_get_boolean</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_key_file_get_boolean              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
800
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
801
                                                         const <link linkend="gchar">gchar</link> *key,
 
802
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
803
<para>
 
804
Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as a
 
805
boolean. 
 
806
</para>
 
807
<para>
 
808
If <parameter>key</parameter> cannot be found then the return value is undefined and
 
809
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. Likewise, if
 
810
the value associated with <parameter>key</parameter> cannot be interpreted as a boolean
 
811
then the return value is also undefined and <parameter>error</parameter> is set to
 
812
<link linkend="G-KEY-FILE-ERROR-INVALID-VALUE:CAPS"><type>G_KEY_FILE_ERROR_INVALID_VALUE</type></link>.</para>
 
813
<para>
 
814
 
 
815
</para><variablelist role="params">
 
816
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
817
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
818
</simpara></listitem></varlistentry>
 
819
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
820
<listitem><simpara> a group name
 
821
</simpara></listitem></varlistentry>
 
822
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
823
<listitem><simpara> a key
 
824
</simpara></listitem></varlistentry>
 
825
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
826
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
827
</simpara></listitem></varlistentry>
 
828
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the value associated with the key as a boolean
 
829
</simpara></listitem></varlistentry>
 
830
</variablelist><para role="since">Since  2.6
 
831
</para></refsect2>
 
832
<refsect2>
 
833
<title><anchor id="g-key-file-get-integer" role="function" condition="since:2.6"/>g_key_file_get_integer ()</title>
 
834
<indexterm role="2.6"><primary>g_key_file_get_integer</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_key_file_get_integer              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
835
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
836
                                                         const <link linkend="gchar">gchar</link> *key,
 
837
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
838
<para>
 
839
Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as an
 
840
integer. If <parameter>group_name</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the start_group is used.
 
841
</para>
 
842
<para>
 
843
If <parameter>key</parameter> cannot be found then the return value is undefined and
 
844
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. Likewise, if
 
845
the value associated with <parameter>key</parameter> cannot be interpreted as an integer
 
846
then the return value is also undefined and <parameter>error</parameter> is set to
 
847
<link linkend="G-KEY-FILE-ERROR-INVALID-VALUE:CAPS"><type>G_KEY_FILE_ERROR_INVALID_VALUE</type></link>.</para>
 
848
<para>
 
849
 
 
850
</para><variablelist role="params">
 
851
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
852
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
853
</simpara></listitem></varlistentry>
 
854
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
855
<listitem><simpara> a group name
 
856
</simpara></listitem></varlistentry>
 
857
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
858
<listitem><simpara> a key
 
859
</simpara></listitem></varlistentry>
 
860
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
861
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
862
</simpara></listitem></varlistentry>
 
863
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the value associated with the key as an integer.
 
864
 
 
865
</simpara></listitem></varlistentry>
 
866
</variablelist><para role="since">Since  2.6
 
867
</para></refsect2>
 
868
<refsect2>
 
869
<title><anchor id="g-key-file-get-double" role="function" condition="since:2.12"/>g_key_file_get_double ()</title>
 
870
<indexterm role="2.12"><primary>g_key_file_get_double</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link>             g_key_file_get_double               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
871
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
872
                                                         const <link linkend="gchar">gchar</link> *key,
 
873
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
874
<para>
 
875
Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as an
 
876
integer. If <parameter>group_name</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the start_group is used.
 
877
</para>
 
878
<para>
 
879
If <parameter>key</parameter> cannot be found then the return value is undefined and
 
880
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. Likewise, if
 
881
the value associated with <parameter>key</parameter> cannot be interpreted as a double
 
882
then the return value is also undefined and <parameter>error</parameter> is set to
 
883
<link linkend="G-KEY-FILE-ERROR-INVALID-VALUE:CAPS"><type>G_KEY_FILE_ERROR_INVALID_VALUE</type></link>.</para>
 
884
<para>
 
885
 
 
886
</para><variablelist role="params">
 
887
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
888
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
889
</simpara></listitem></varlistentry>
 
890
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
891
<listitem><simpara> a group name
 
892
</simpara></listitem></varlistentry>
 
893
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
894
<listitem><simpara> a key
 
895
</simpara></listitem></varlistentry>
 
896
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
897
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
898
</simpara></listitem></varlistentry>
 
899
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the value associated with the key as a double.
 
900
 
 
901
</simpara></listitem></varlistentry>
 
902
</variablelist><para role="since">Since  2.12
 
903
</para></refsect2>
 
904
<refsect2>
 
905
<title><anchor id="g-key-file-get-string-list" role="function" condition="since:2.6"/>g_key_file_get_string_list ()</title>
 
906
<indexterm role="2.6"><primary>g_key_file_get_string_list</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_key_file_get_string_list          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
907
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
908
                                                         const <link linkend="gchar">gchar</link> *key,
 
909
                                                         <link linkend="gsize">gsize</link> *length,
 
910
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
911
<para>
 
912
Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter>.
 
913
</para>
 
914
<para>
 
915
In the event the key cannot be found, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned and
 
916
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>.  In the
 
917
event that the <parameter>group_name</parameter> cannot be found, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned
 
918
and <parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-GROUP-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type></link>.</para>
 
919
<para>
 
920
 
 
921
</para><variablelist role="params">
 
922
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
923
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
924
</simpara></listitem></varlistentry>
 
925
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
926
<listitem><simpara> a group name
 
927
</simpara></listitem></varlistentry>
 
928
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
929
<listitem><simpara> a key
 
930
</simpara></listitem></varlistentry>
 
931
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
932
<listitem><simpara> return location for the number of returned strings, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
933
</simpara></listitem></varlistentry>
 
934
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
935
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
936
</simpara></listitem></varlistentry>
 
937
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated string array or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the specified 
 
938
  key cannot be found. The array should be freed with <link linkend="g-strfreev"><function>g_strfreev()</function></link>.
 
939
 
 
940
</simpara></listitem></varlistentry>
 
941
</variablelist><para role="since">Since  2.6
 
942
</para></refsect2>
 
943
<refsect2>
 
944
<title><anchor id="g-key-file-get-locale-string-list" role="function" condition="since:2.6"/>g_key_file_get_locale_string_list ()</title>
 
945
<indexterm role="2.6"><primary>g_key_file_get_locale_string_list</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_key_file_get_locale_string_list   (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
946
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
947
                                                         const <link linkend="gchar">gchar</link> *key,
 
948
                                                         const <link linkend="gchar">gchar</link> *locale,
 
949
                                                         <link linkend="gsize">gsize</link> *length,
 
950
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
951
<para>
 
952
Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter>
 
953
translated in the given <parameter>locale</parameter> if available.  If <parameter>locale</parameter> is
 
954
<link linkend="NULL:CAPS"><literal>NULL</literal></link> then the current locale is assumed.
 
955
</para>
 
956
<para>
 
957
If <parameter>key</parameter> cannot be found then <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned and <parameter>error</parameter> is set to
 
958
<link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. If the values associated
 
959
with <parameter>key</parameter> cannot be interpreted or no suitable translations
 
960
can be found then the untranslated values are returned.
 
961
The returned array is <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated, so <parameter>length</parameter> may optionally be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
 
962
<para>
 
963
 
 
964
</para><variablelist role="params">
 
965
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
966
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
967
</simpara></listitem></varlistentry>
 
968
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
969
<listitem><simpara> a group name
 
970
</simpara></listitem></varlistentry>
 
971
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
972
<listitem><simpara> a key
 
973
</simpara></listitem></varlistentry>
 
974
<varlistentry><term><parameter>locale</parameter>&nbsp;:</term>
 
975
<listitem><simpara> a locale
 
976
</simpara></listitem></varlistentry>
 
977
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
978
<listitem><simpara> return location for the number of returned strings or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
979
</simpara></listitem></varlistentry>
 
980
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
981
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
982
</simpara></listitem></varlistentry>
 
983
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated string array
 
984
  or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the key isn't found. The string array should be freed
 
985
  with <link linkend="g-strfreev"><function>g_strfreev()</function></link>.
 
986
 
 
987
</simpara></listitem></varlistentry>
 
988
</variablelist><para role="since">Since  2.6
 
989
</para></refsect2>
 
990
<refsect2>
 
991
<title><anchor id="g-key-file-get-boolean-list" role="function" condition="since:2.6"/>g_key_file_get_boolean_list ()</title>
 
992
<indexterm role="2.6"><primary>g_key_file_get_boolean_list</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>*           g_key_file_get_boolean_list         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
993
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
994
                                                         const <link linkend="gchar">gchar</link> *key,
 
995
                                                         <link linkend="gsize">gsize</link> *length,
 
996
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
997
<para>
 
998
Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter> as
 
999
booleans. If <parameter>group_name</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the start_group is used.
 
1000
</para>
 
1001
<para>
 
1002
If <parameter>key</parameter> cannot be found then the return value is undefined and
 
1003
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. Likewise, if
 
1004
the values associated with <parameter>key</parameter> cannot be interpreted as booleans
 
1005
then the return value is also undefined and <parameter>error</parameter> is set to
 
1006
<link linkend="G-KEY-FILE-ERROR-INVALID-VALUE:CAPS"><type>G_KEY_FILE_ERROR_INVALID_VALUE</type></link>.</para>
 
1007
<para>
 
1008
 
 
1009
</para><variablelist role="params">
 
1010
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1011
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1012
</simpara></listitem></varlistentry>
 
1013
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1014
<listitem><simpara> a group name
 
1015
</simpara></listitem></varlistentry>
 
1016
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1017
<listitem><simpara> a key
 
1018
</simpara></listitem></varlistentry>
 
1019
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1020
<listitem><simpara> the number of booleans returned
 
1021
</simpara></listitem></varlistentry>
 
1022
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1023
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
1024
</simpara></listitem></varlistentry>
 
1025
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the values associated with the key as a boolean
 
1026
 
 
1027
</simpara></listitem></varlistentry>
 
1028
</variablelist><para role="since">Since  2.6
 
1029
</para></refsect2>
 
1030
<refsect2>
 
1031
<title><anchor id="g-key-file-get-integer-list" role="function" condition="since:2.6"/>g_key_file_get_integer_list ()</title>
 
1032
<indexterm role="2.6"><primary>g_key_file_get_integer_list</primary></indexterm><programlisting><link linkend="gint">gint</link>*               g_key_file_get_integer_list         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1033
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1034
                                                         const <link linkend="gchar">gchar</link> *key,
 
1035
                                                         <link linkend="gsize">gsize</link> *length,
 
1036
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
1037
<para>
 
1038
Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter> as
 
1039
integers. 
 
1040
</para>
 
1041
<para>
 
1042
If <parameter>key</parameter> cannot be found then the return value is undefined and
 
1043
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. Likewise, if
 
1044
the values associated with <parameter>key</parameter> cannot be interpreted as integers
 
1045
then the return value is also undefined and <parameter>error</parameter> is set to
 
1046
<link linkend="G-KEY-FILE-ERROR-INVALID-VALUE:CAPS"><type>G_KEY_FILE_ERROR_INVALID_VALUE</type></link>.</para>
 
1047
<para>
 
1048
 
 
1049
</para><variablelist role="params">
 
1050
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1051
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1052
</simpara></listitem></varlistentry>
 
1053
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1054
<listitem><simpara> a group name
 
1055
</simpara></listitem></varlistentry>
 
1056
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1057
<listitem><simpara> a key
 
1058
</simpara></listitem></varlistentry>
 
1059
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1060
<listitem><simpara> the number of integers returned
 
1061
</simpara></listitem></varlistentry>
 
1062
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1063
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
1064
</simpara></listitem></varlistentry>
 
1065
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the values associated with the key as a integer
 
1066
 
 
1067
</simpara></listitem></varlistentry>
 
1068
</variablelist><para role="since">Since  2.6
 
1069
</para></refsect2>
 
1070
<refsect2>
 
1071
<title><anchor id="g-key-file-get-double-list" role="function" condition="since:2.12"/>g_key_file_get_double_list ()</title>
 
1072
<indexterm role="2.12"><primary>g_key_file_get_double_list</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link>*            g_key_file_get_double_list          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1073
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1074
                                                         const <link linkend="gchar">gchar</link> *key,
 
1075
                                                         <link linkend="gsize">gsize</link> *length,
 
1076
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
1077
<para>
 
1078
Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter> as
 
1079
doubles. If <parameter>group_name</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the start group is used.
 
1080
</para>
 
1081
<para>
 
1082
If <parameter>key</parameter> cannot be found then the return value is undefined and
 
1083
<parameter>error</parameter> is set to <link linkend="G-KEY-FILE-ERROR-KEY-NOT-FOUND:CAPS"><type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type></link>. Likewise, if
 
1084
the values associated with <parameter>key</parameter> cannot be interpreted as doubles
 
1085
then the return value is also undefined and <parameter>error</parameter> is set to
 
1086
<link linkend="G-KEY-FILE-ERROR-INVALID-VALUE:CAPS"><type>G_KEY_FILE_ERROR_INVALID_VALUE</type></link>.</para>
 
1087
<para>
 
1088
 
 
1089
</para><variablelist role="params">
 
1090
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1091
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1092
</simpara></listitem></varlistentry>
 
1093
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1094
<listitem><simpara> a group name
 
1095
</simpara></listitem></varlistentry>
 
1096
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1097
<listitem><simpara> a key
 
1098
</simpara></listitem></varlistentry>
 
1099
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1100
<listitem><simpara> the number of doubles returned
 
1101
</simpara></listitem></varlistentry>
 
1102
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1103
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
1104
</simpara></listitem></varlistentry>
 
1105
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the values associated with the key as a double
 
1106
 
 
1107
</simpara></listitem></varlistentry>
 
1108
</variablelist><para role="since">Since  2.12
 
1109
</para></refsect2>
 
1110
<refsect2>
 
1111
<title><anchor id="g-key-file-get-comment" role="function" condition="since:2.6"/>g_key_file_get_comment ()</title>
 
1112
<indexterm role="2.6"><primary>g_key_file_get_comment</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_key_file_get_comment              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1113
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1114
                                                         const <link linkend="gchar">gchar</link> *key,
 
1115
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
1116
<para>
 
1117
Retrieves a comment above <parameter>key</parameter> from <parameter>group_name</parameter>.
 
1118
<parameter>group_name</parameter>. If <parameter>key</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> then <parameter>comment</parameter> will
 
1119
be read from above <parameter>group_name</parameter>.  If both <parameter>key</parameter>
 
1120
and <parameter>group_name</parameter> are NULL, then <parameter>comment</parameter> will
 
1121
be read from above the first group in the file.</para>
 
1122
<para>
 
1123
 
 
1124
</para><variablelist role="params">
 
1125
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1126
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1127
</simpara></listitem></varlistentry>
 
1128
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1129
<listitem><simpara> a group name, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
1130
</simpara></listitem></varlistentry>
 
1131
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1132
<listitem><simpara> a key
 
1133
</simpara></listitem></varlistentry>
 
1134
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1135
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
1136
</simpara></listitem></varlistentry>
 
1137
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a comment that should be freed with <link linkend="g-free"><function>g_free()</function></link>
 
1138
 
 
1139
</simpara></listitem></varlistentry>
 
1140
</variablelist><para role="since">Since  2.6
 
1141
</para></refsect2>
 
1142
<refsect2>
 
1143
<title><anchor id="g-key-file-set-value" role="function" condition="since:2.6"/>g_key_file_set_value ()</title>
 
1144
<indexterm role="2.6"><primary>g_key_file_set_value</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_value                (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1145
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1146
                                                         const <link linkend="gchar">gchar</link> *key,
 
1147
                                                         const <link linkend="gchar">gchar</link> *value);</programlisting>
 
1148
<para>
 
1149
Associates a new value with <parameter>key</parameter> under <parameter>group_name</parameter>.  If <parameter>key</parameter>
 
1150
cannot be found then it is created. If <parameter>group_name</parameter> cannot be
 
1151
found then it is created.</para>
 
1152
<para>
 
1153
 
 
1154
</para><variablelist role="params">
 
1155
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1156
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1157
</simpara></listitem></varlistentry>
 
1158
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1159
<listitem><simpara> a group name
 
1160
</simpara></listitem></varlistentry>
 
1161
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1162
<listitem><simpara> a key
 
1163
</simpara></listitem></varlistentry>
 
1164
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
1165
<listitem><simpara> a string
 
1166
</simpara></listitem></varlistentry>
 
1167
</variablelist><para role="since">Since  2.6
 
1168
</para></refsect2>
 
1169
<refsect2>
 
1170
<title><anchor id="g-key-file-set-string" role="function" condition="since:2.6"/>g_key_file_set_string ()</title>
 
1171
<indexterm role="2.6"><primary>g_key_file_set_string</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_string               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1172
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1173
                                                         const <link linkend="gchar">gchar</link> *key,
 
1174
                                                         const <link linkend="gchar">gchar</link> *string);</programlisting>
 
1175
<para>
 
1176
Associates a new string value with <parameter>key</parameter> under <parameter>group_name</parameter>.  If
 
1177
<parameter>key</parameter> cannot be found then it is created.  If <parameter>group_name</parameter>
 
1178
cannot be found then it is created.</para>
 
1179
<para>
 
1180
 
 
1181
</para><variablelist role="params">
 
1182
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1183
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1184
</simpara></listitem></varlistentry>
 
1185
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1186
<listitem><simpara> a group name
 
1187
</simpara></listitem></varlistentry>
 
1188
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1189
<listitem><simpara> a key
 
1190
</simpara></listitem></varlistentry>
 
1191
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
 
1192
<listitem><simpara> a string
 
1193
</simpara></listitem></varlistentry>
 
1194
</variablelist><para role="since">Since  2.6
 
1195
</para></refsect2>
 
1196
<refsect2>
 
1197
<title><anchor id="g-key-file-set-locale-string" role="function" condition="since:2.6"/>g_key_file_set_locale_string ()</title>
 
1198
<indexterm role="2.6"><primary>g_key_file_set_locale_string</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_locale_string        (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1199
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1200
                                                         const <link linkend="gchar">gchar</link> *key,
 
1201
                                                         const <link linkend="gchar">gchar</link> *locale,
 
1202
                                                         const <link linkend="gchar">gchar</link> *string);</programlisting>
 
1203
<para>
 
1204
Associates a string value for <parameter>key</parameter> and <parameter>locale</parameter> under
 
1205
<parameter>group_name</parameter>.  If the translation for <parameter>key</parameter> cannot be found 
 
1206
then it is created.</para>
 
1207
<para>
 
1208
 
 
1209
</para><variablelist role="params">
 
1210
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1211
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1212
</simpara></listitem></varlistentry>
 
1213
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1214
<listitem><simpara> a group name
 
1215
</simpara></listitem></varlistentry>
 
1216
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1217
<listitem><simpara> a key
 
1218
</simpara></listitem></varlistentry>
 
1219
<varlistentry><term><parameter>locale</parameter>&nbsp;:</term>
 
1220
<listitem><simpara> a locale
 
1221
</simpara></listitem></varlistentry>
 
1222
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
 
1223
<listitem><simpara> a string
 
1224
</simpara></listitem></varlistentry>
 
1225
</variablelist><para role="since">Since  2.6
 
1226
</para></refsect2>
 
1227
<refsect2>
 
1228
<title><anchor id="g-key-file-set-boolean" role="function" condition="since:2.6"/>g_key_file_set_boolean ()</title>
 
1229
<indexterm role="2.6"><primary>g_key_file_set_boolean</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_boolean              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1230
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1231
                                                         const <link linkend="gchar">gchar</link> *key,
 
1232
                                                         <link linkend="gboolean">gboolean</link> value);</programlisting>
 
1233
<para>
 
1234
Associates a new boolean value with <parameter>key</parameter> under <parameter>group_name</parameter>.
 
1235
If <parameter>key</parameter> cannot be found then it is created.</para>
 
1236
<para>
 
1237
 
 
1238
</para><variablelist role="params">
 
1239
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1240
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1241
</simpara></listitem></varlistentry>
 
1242
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1243
<listitem><simpara> a group name
 
1244
</simpara></listitem></varlistentry>
 
1245
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1246
<listitem><simpara> a key
 
1247
</simpara></listitem></varlistentry>
 
1248
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
1249
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
 
1250
</simpara></listitem></varlistentry>
 
1251
</variablelist><para role="since">Since  2.6
 
1252
</para></refsect2>
 
1253
<refsect2>
 
1254
<title><anchor id="g-key-file-set-integer" role="function" condition="since:2.6"/>g_key_file_set_integer ()</title>
 
1255
<indexterm role="2.6"><primary>g_key_file_set_integer</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_integer              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1256
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1257
                                                         const <link linkend="gchar">gchar</link> *key,
 
1258
                                                         <link linkend="gint">gint</link> value);</programlisting>
 
1259
<para>
 
1260
Associates a new integer value with <parameter>key</parameter> under <parameter>group_name</parameter>.
 
1261
If <parameter>key</parameter> cannot be found then it is created.</para>
 
1262
<para>
 
1263
 
 
1264
</para><variablelist role="params">
 
1265
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1266
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1267
</simpara></listitem></varlistentry>
 
1268
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1269
<listitem><simpara> a group name
 
1270
</simpara></listitem></varlistentry>
 
1271
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1272
<listitem><simpara> a key
 
1273
</simpara></listitem></varlistentry>
 
1274
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
1275
<listitem><simpara> an integer value
 
1276
</simpara></listitem></varlistentry>
 
1277
</variablelist><para role="since">Since  2.6
 
1278
</para></refsect2>
 
1279
<refsect2>
 
1280
<title><anchor id="g-key-file-set-double" role="function" condition="since:2.12"/>g_key_file_set_double ()</title>
 
1281
<indexterm role="2.12"><primary>g_key_file_set_double</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_double               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1282
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1283
                                                         const <link linkend="gchar">gchar</link> *key,
 
1284
                                                         <link linkend="gdouble">gdouble</link> value);</programlisting>
 
1285
<para>
 
1286
Associates a new double value with <parameter>key</parameter> under <parameter>group_name</parameter>.
 
1287
If <parameter>key</parameter> cannot be found then it is created. If <parameter>group_name</parameter>
 
1288
is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the start group is used.</para>
 
1289
<para>
 
1290
 
 
1291
</para><variablelist role="params">
 
1292
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1293
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1294
</simpara></listitem></varlistentry>
 
1295
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1296
<listitem><simpara> a group name
 
1297
</simpara></listitem></varlistentry>
 
1298
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1299
<listitem><simpara> a key
 
1300
</simpara></listitem></varlistentry>
 
1301
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
1302
<listitem><simpara> an double value
 
1303
</simpara></listitem></varlistentry>
 
1304
</variablelist><para role="since">Since  2.12
 
1305
</para></refsect2>
 
1306
<refsect2>
 
1307
<title><anchor id="g-key-file-set-string-list" role="function" condition="since:2.6"/>g_key_file_set_string_list ()</title>
 
1308
<indexterm role="2.6"><primary>g_key_file_set_string_list</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_string_list          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1309
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1310
                                                         const <link linkend="gchar">gchar</link> *key,
 
1311
                                                         const <link linkend="gchar">gchar</link> * const list[],
 
1312
                                                         <link linkend="gsize">gsize</link> length);</programlisting>
 
1313
<para>
 
1314
Associates a list of string values for <parameter>key</parameter> under <parameter>group_name</parameter>.
 
1315
If <parameter>key</parameter> cannot be found then it is created.  If <parameter>group_name</parameter> 
 
1316
cannot be found then it is created.</para>
 
1317
<para>
 
1318
 
 
1319
</para><variablelist role="params">
 
1320
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1321
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1322
</simpara></listitem></varlistentry>
 
1323
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1324
<listitem><simpara> a group name
 
1325
</simpara></listitem></varlistentry>
 
1326
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1327
<listitem><simpara> a key
 
1328
</simpara></listitem></varlistentry>
 
1329
<varlistentry><term><parameter>list</parameter>&nbsp;:</term>
 
1330
<listitem><simpara> an array of locale string values
 
1331
</simpara></listitem></varlistentry>
 
1332
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1333
<listitem><simpara> number of locale string values in <parameter>list</parameter>
 
1334
</simpara></listitem></varlistentry>
 
1335
</variablelist><para role="since">Since  2.6
 
1336
</para></refsect2>
 
1337
<refsect2>
 
1338
<title><anchor id="g-key-file-set-locale-string-list" role="function" condition="since:2.6"/>g_key_file_set_locale_string_list ()</title>
 
1339
<indexterm role="2.6"><primary>g_key_file_set_locale_string_list</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_locale_string_list   (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1340
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1341
                                                         const <link linkend="gchar">gchar</link> *key,
 
1342
                                                         const <link linkend="gchar">gchar</link> *locale,
 
1343
                                                         const <link linkend="gchar">gchar</link> * const list[],
 
1344
                                                         <link linkend="gsize">gsize</link> length);</programlisting>
 
1345
<para>
 
1346
Associates a list of string values for <parameter>key</parameter> and <parameter>locale</parameter> under
 
1347
<parameter>group_name</parameter>.  If the translation for <parameter>key</parameter> cannot be found then
 
1348
it is created.</para>
 
1349
<para>
 
1350
 
 
1351
</para><variablelist role="params">
 
1352
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1353
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1354
</simpara></listitem></varlistentry>
 
1355
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1356
<listitem><simpara> a group name
 
1357
</simpara></listitem></varlistentry>
 
1358
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1359
<listitem><simpara> a key
 
1360
</simpara></listitem></varlistentry>
 
1361
<varlistentry><term><parameter>locale</parameter>&nbsp;:</term>
 
1362
<listitem><simpara> a locale
 
1363
</simpara></listitem></varlistentry>
 
1364
<varlistentry><term><parameter>list</parameter>&nbsp;:</term>
 
1365
<listitem><simpara> a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of locale string values
 
1366
</simpara></listitem></varlistentry>
 
1367
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1368
<listitem><simpara> the length of <parameter>list</parameter>
 
1369
</simpara></listitem></varlistentry>
 
1370
</variablelist><para role="since">Since  2.6
 
1371
</para></refsect2>
 
1372
<refsect2>
 
1373
<title><anchor id="g-key-file-set-boolean-list" role="function" condition="since:2.6"/>g_key_file_set_boolean_list ()</title>
 
1374
<indexterm role="2.6"><primary>g_key_file_set_boolean_list</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_boolean_list         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1375
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1376
                                                         const <link linkend="gchar">gchar</link> *key,
 
1377
                                                         <link linkend="gboolean">gboolean</link> list[],
 
1378
                                                         <link linkend="gsize">gsize</link> length);</programlisting>
 
1379
<para>
 
1380
Associates a list of boolean values with <parameter>key</parameter> under
 
1381
<parameter>group_name</parameter>.  If <parameter>key</parameter> cannot be found then it is created.
 
1382
If <parameter>group_name</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the start_group is used.</para>
 
1383
<para>
 
1384
 
 
1385
</para><variablelist role="params">
 
1386
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1387
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1388
</simpara></listitem></varlistentry>
 
1389
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1390
<listitem><simpara> a group name
 
1391
</simpara></listitem></varlistentry>
 
1392
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1393
<listitem><simpara> a key
 
1394
</simpara></listitem></varlistentry>
 
1395
<varlistentry><term><parameter>list</parameter>&nbsp;:</term>
 
1396
<listitem><simpara> an array of boolean values
 
1397
</simpara></listitem></varlistentry>
 
1398
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1399
<listitem><simpara> length of <parameter>list</parameter>
 
1400
</simpara></listitem></varlistentry>
 
1401
</variablelist><para role="since">Since  2.6
 
1402
</para></refsect2>
 
1403
<refsect2>
 
1404
<title><anchor id="g-key-file-set-integer-list" role="function" condition="since:2.6"/>g_key_file_set_integer_list ()</title>
 
1405
<indexterm role="2.6"><primary>g_key_file_set_integer_list</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_integer_list         (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1406
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1407
                                                         const <link linkend="gchar">gchar</link> *key,
 
1408
                                                         <link linkend="gint">gint</link> list[],
 
1409
                                                         <link linkend="gsize">gsize</link> length);</programlisting>
 
1410
<para>
 
1411
Associates a list of integer values with <parameter>key</parameter> under
 
1412
<parameter>group_name</parameter>.  If <parameter>key</parameter> cannot be found then it is created.</para>
 
1413
<para>
 
1414
 
 
1415
</para><variablelist role="params">
 
1416
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1417
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1418
</simpara></listitem></varlistentry>
 
1419
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1420
<listitem><simpara> a group name
 
1421
</simpara></listitem></varlistentry>
 
1422
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1423
<listitem><simpara> a key
 
1424
</simpara></listitem></varlistentry>
 
1425
<varlistentry><term><parameter>list</parameter>&nbsp;:</term>
 
1426
<listitem><simpara> an array of integer values
 
1427
</simpara></listitem></varlistentry>
 
1428
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1429
<listitem><simpara> number of integer values in <parameter>list</parameter>
 
1430
</simpara></listitem></varlistentry>
 
1431
</variablelist><para role="since">Since  2.6
 
1432
</para></refsect2>
 
1433
<refsect2>
 
1434
<title><anchor id="g-key-file-set-double-list" role="function" condition="since:2.12"/>g_key_file_set_double_list ()</title>
 
1435
<indexterm role="2.12"><primary>g_key_file_set_double_list</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_double_list          (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1436
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1437
                                                         const <link linkend="gchar">gchar</link> *key,
 
1438
                                                         <link linkend="gdouble">gdouble</link> list[],
 
1439
                                                         <link linkend="gsize">gsize</link> length);</programlisting>
 
1440
<para>
 
1441
Associates a list of double values with <parameter>key</parameter> under
 
1442
<parameter>group_name</parameter>.  If <parameter>key</parameter> cannot be found then it is created.
 
1443
If <parameter>group_name</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> the start group is used.</para>
 
1444
<para>
 
1445
 
 
1446
</para><variablelist role="params">
 
1447
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1448
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1449
</simpara></listitem></varlistentry>
 
1450
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1451
<listitem><simpara> a group name
 
1452
</simpara></listitem></varlistentry>
 
1453
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1454
<listitem><simpara> a key
 
1455
</simpara></listitem></varlistentry>
 
1456
<varlistentry><term><parameter>list</parameter>&nbsp;:</term>
 
1457
<listitem><simpara> an array of double values
 
1458
</simpara></listitem></varlistentry>
 
1459
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
1460
<listitem><simpara> number of double values in <parameter>list</parameter>
 
1461
</simpara></listitem></varlistentry>
 
1462
</variablelist><para role="since">Since  2.12
 
1463
</para></refsect2>
 
1464
<refsect2>
 
1465
<title><anchor id="g-key-file-set-comment" role="function" condition="since:2.6"/>g_key_file_set_comment ()</title>
 
1466
<indexterm role="2.6"><primary>g_key_file_set_comment</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_set_comment              (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1467
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1468
                                                         const <link linkend="gchar">gchar</link> *key,
 
1469
                                                         const <link linkend="gchar">gchar</link> *comment,
 
1470
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
1471
<para>
 
1472
Places a comment above <parameter>key</parameter> from <parameter>group_name</parameter>.
 
1473
<parameter>group_name</parameter>. If <parameter>key</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> then <parameter>comment</parameter> will
 
1474
be written above <parameter>group_name</parameter>.  If both <parameter>key</parameter>
 
1475
and <parameter>group_name</parameter> are NULL, then <parameter>comment</parameter> will
 
1476
be written above the first group in the file.</para>
 
1477
<para>
 
1478
 
 
1479
</para><variablelist role="params">
 
1480
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1481
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1482
</simpara></listitem></varlistentry>
 
1483
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1484
<listitem><simpara> a group name, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
1485
</simpara></listitem></varlistentry>
 
1486
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1487
<listitem><simpara> a key
 
1488
</simpara></listitem></varlistentry>
 
1489
<varlistentry><term><parameter>comment</parameter>&nbsp;:</term>
 
1490
<listitem><simpara> a comment
 
1491
</simpara></listitem></varlistentry>
 
1492
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1493
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
1494
</simpara></listitem></varlistentry>
 
1495
</variablelist><para role="since">Since  2.6
 
1496
</para></refsect2>
 
1497
<refsect2>
 
1498
<title><anchor id="g-key-file-remove-group" role="function" condition="since:2.6"/>g_key_file_remove_group ()</title>
 
1499
<indexterm role="2.6"><primary>g_key_file_remove_group</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_remove_group             (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1500
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1501
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
1502
<para>
 
1503
Removes the specified group, <parameter>group_name</parameter>, 
 
1504
from the key file.</para>
 
1505
<para>
 
1506
 
 
1507
</para><variablelist role="params">
 
1508
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1509
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1510
</simpara></listitem></varlistentry>
 
1511
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1512
<listitem><simpara> a group name
 
1513
</simpara></listitem></varlistentry>
 
1514
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1515
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
1516
</simpara></listitem></varlistentry>
 
1517
</variablelist><para role="since">Since  2.6
 
1518
</para></refsect2>
 
1519
<refsect2>
 
1520
<title><anchor id="g-key-file-remove-key" role="function" condition="since:2.6"/>g_key_file_remove_key ()</title>
 
1521
<indexterm role="2.6"><primary>g_key_file_remove_key</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_remove_key               (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1522
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1523
                                                         const <link linkend="gchar">gchar</link> *key,
 
1524
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
1525
<para>
 
1526
Removes <parameter>key</parameter> in <parameter>group_name</parameter> from the key file.</para>
 
1527
<para>
 
1528
 
 
1529
</para><variablelist role="params">
 
1530
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1531
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1532
</simpara></listitem></varlistentry>
 
1533
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1534
<listitem><simpara> a group name
 
1535
</simpara></listitem></varlistentry>
 
1536
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1537
<listitem><simpara> a key name to remove
 
1538
</simpara></listitem></varlistentry>
 
1539
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1540
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
1541
</simpara></listitem></varlistentry>
 
1542
</variablelist><para role="since">Since  2.6
 
1543
</para></refsect2>
 
1544
<refsect2>
 
1545
<title><anchor id="g-key-file-remove-comment" role="function" condition="since:2.6"/>g_key_file_remove_comment ()</title>
 
1546
<indexterm role="2.6"><primary>g_key_file_remove_comment</primary></indexterm><programlisting><link linkend="void">void</link>                g_key_file_remove_comment           (<link linkend="GKeyFile">GKeyFile</link> *key_file,
 
1547
                                                         const <link linkend="gchar">gchar</link> *group_name,
 
1548
                                                         const <link linkend="gchar">gchar</link> *key,
 
1549
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
1550
<para>
 
1551
Removes a comment above <parameter>key</parameter> from <parameter>group_name</parameter>.
 
1552
<parameter>group_name</parameter>. If <parameter>key</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> then <parameter>comment</parameter> will
 
1553
be written above <parameter>group_name</parameter>.  If both <parameter>key</parameter>
 
1554
and <parameter>group_name</parameter> are NULL, then <parameter>comment</parameter> will
 
1555
be written above the first group in the file.</para>
 
1556
<para>
 
1557
 
 
1558
</para><variablelist role="params">
 
1559
<varlistentry><term><parameter>key_file</parameter>&nbsp;:</term>
 
1560
<listitem><simpara> a <link linkend="GKeyFile"><type>GKeyFile</type></link>
 
1561
</simpara></listitem></varlistentry>
 
1562
<varlistentry><term><parameter>group_name</parameter>&nbsp;:</term>
 
1563
<listitem><simpara> a group name, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
1564
</simpara></listitem></varlistentry>
 
1565
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
1566
<listitem><simpara> a key
 
1567
</simpara></listitem></varlistentry>
 
1568
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1569
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
 
1570
</simpara></listitem></varlistentry>
 
1571
</variablelist><para role="since">Since  2.6
 
1572
</para></refsect2>
 
1573
 
 
1574
</refsect1>
 
1575
 
 
1576
 
 
1577
 
 
1578
 
 
1579
</refentry>