glib2.0_2.20.1
[mer:glib2_0.git] / docs / reference / glib / xml / iochannels.xml
1 <refentry id="glib-IO-Channels">
2 <refmeta>
3 <refentrytitle role="top_of_page" id="glib-IO-Channels.top_of_page">IO Channels</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>GLIB Library</refmiscinfo>
6 </refmeta>
7
8 <refnamediv>
9 <refname>IO Channels</refname>
10 <refpurpose>portable support for using files, pipes and sockets</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv id="glib-IO-Channels.synopsis" role="synopsis">
14 <title role="synopsis.title">Synopsis</title>
15
16 <synopsis>
17
18 #include &lt;glib.h&gt;
19
20                     <link linkend="GIOChannel">GIOChannel</link>;
21
22 <link linkend="GIOChannel">GIOChannel</link>*         <link linkend="g-io-channel-unix-new">g_io_channel_unix_new</link>               (<link linkend="int">int</link> fd);
23 <link linkend="gint">gint</link>                <link linkend="g-io-channel-unix-get-fd">g_io_channel_unix_get_fd</link>            (<link linkend="GIOChannel">GIOChannel</link> *channel);
24 <link linkend="GIOChannel">GIOChannel</link>*         <link linkend="g-io-channel-win32-new-fd">g_io_channel_win32_new_fd</link>           (<link linkend="gint">gint</link> fd);
25 <link linkend="GIOChannel">GIOChannel</link> *        <link linkend="g-io-channel-win32-new-socket">g_io_channel_win32_new_socket</link>       (<link linkend="gint">gint</link> socket);
26 <link linkend="GIOChannel">GIOChannel</link> *        <link linkend="g-io-channel-win32-new-messages">g_io_channel_win32_new_messages</link>     (<link linkend="gsize">gsize</link> hwnd);
27
28 <link linkend="void">void</link>                <link linkend="g-io-channel-init">g_io_channel_init</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel);
29
30 <link linkend="GIOChannel">GIOChannel</link>*         <link linkend="g-io-channel-new-file">g_io_channel_new_file</link>               (const <link linkend="gchar">gchar</link> *filename,
31                                                          const <link linkend="gchar">gchar</link> *mode,
32                                                          <link linkend="GError">GError</link> **error);
33 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-chars">g_io_channel_read_chars</link>             (<link linkend="GIOChannel">GIOChannel</link> *channel,
34                                                          <link linkend="gchar">gchar</link> *buf,
35                                                          <link linkend="gsize">gsize</link> count,
36                                                          <link linkend="gsize">gsize</link> *bytes_read,
37                                                          <link linkend="GError">GError</link> **error);
38 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-unichar">g_io_channel_read_unichar</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel,
39                                                          <link linkend="gunichar">gunichar</link> *thechar,
40                                                          <link linkend="GError">GError</link> **error);
41 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-line">g_io_channel_read_line</link>              (<link linkend="GIOChannel">GIOChannel</link> *channel,
42                                                          <link linkend="gchar">gchar</link> **str_return,
43                                                          <link linkend="gsize">gsize</link> *length,
44                                                          <link linkend="gsize">gsize</link> *terminator_pos,
45                                                          <link linkend="GError">GError</link> **error);
46 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-line-string">g_io_channel_read_line_string</link>       (<link linkend="GIOChannel">GIOChannel</link> *channel,
47                                                          <link linkend="GString">GString</link> *buffer,
48                                                          <link linkend="gsize">gsize</link> *terminator_pos,
49                                                          <link linkend="GError">GError</link> **error);
50 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-to-end">g_io_channel_read_to_end</link>            (<link linkend="GIOChannel">GIOChannel</link> *channel,
51                                                          <link linkend="gchar">gchar</link> **str_return,
52                                                          <link linkend="gsize">gsize</link> *length,
53                                                          <link linkend="GError">GError</link> **error);
54 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-write-chars">g_io_channel_write_chars</link>            (<link linkend="GIOChannel">GIOChannel</link> *channel,
55                                                          const <link linkend="gchar">gchar</link> *buf,
56                                                          <link linkend="gssize">gssize</link> count,
57                                                          <link linkend="gsize">gsize</link> *bytes_written,
58                                                          <link linkend="GError">GError</link> **error);
59 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-write-unichar">g_io_channel_write_unichar</link>          (<link linkend="GIOChannel">GIOChannel</link> *channel,
60                                                          <link linkend="gunichar">gunichar</link> thechar,
61                                                          <link linkend="GError">GError</link> **error);
62 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-flush">g_io_channel_flush</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel,
63                                                          <link linkend="GError">GError</link> **error);
64 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-seek-position">g_io_channel_seek_position</link>          (<link linkend="GIOChannel">GIOChannel</link> *channel,
65                                                          <link linkend="gint64">gint64</link> offset,
66                                                          <link linkend="GSeekType">GSeekType</link> type,
67                                                          <link linkend="GError">GError</link> **error);
68 enum                <link linkend="GSeekType">GSeekType</link>;
69 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-shutdown">g_io_channel_shutdown</link>               (<link linkend="GIOChannel">GIOChannel</link> *channel,
70                                                          <link linkend="gboolean">gboolean</link> flush,
71                                                          <link linkend="GError">GError</link> **err);
72
73 enum                <link linkend="GIOStatus">GIOStatus</link>;
74 enum                <link linkend="GIOChannelError">GIOChannelError</link>;
75 #define             <link linkend="G-IO-CHANNEL-ERROR--CAPS">G_IO_CHANNEL_ERROR</link>
76 <link linkend="GIOChannelError">GIOChannelError</link>     <link linkend="g-io-channel-error-from-errno">g_io_channel_error_from_errno</link>       (<link linkend="gint">gint</link> en);
77
78 <link linkend="GIOChannel">GIOChannel</link> *        <link linkend="g-io-channel-ref">g_io_channel_ref</link>                    (<link linkend="GIOChannel">GIOChannel</link> *channel);
79 <link linkend="void">void</link>                <link linkend="g-io-channel-unref">g_io_channel_unref</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel);
80
81 <link linkend="GSource">GSource</link> *           <link linkend="g-io-create-watch">g_io_create_watch</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
82                                                          <link linkend="GIOCondition">GIOCondition</link> condition);
83 <link linkend="guint">guint</link>               <link linkend="g-io-add-watch">g_io_add_watch</link>                      (<link linkend="GIOChannel">GIOChannel</link> *channel,
84                                                          <link linkend="GIOCondition">GIOCondition</link> condition,
85                                                          <link linkend="GIOFunc">GIOFunc</link> func,
86                                                          <link linkend="gpointer">gpointer</link> user_data);
87 <link linkend="guint">guint</link>               <link linkend="g-io-add-watch-full">g_io_add_watch_full</link>                 (<link linkend="GIOChannel">GIOChannel</link> *channel,
88                                                          <link linkend="gint">gint</link> priority,
89                                                          <link linkend="GIOCondition">GIOCondition</link> condition,
90                                                          <link linkend="GIOFunc">GIOFunc</link> func,
91                                                          <link linkend="gpointer">gpointer</link> user_data,
92                                                          <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
93 enum                <link linkend="GIOCondition">GIOCondition</link>;
94 <link linkend="gboolean">gboolean</link>            (<link linkend="GIOFunc">*GIOFunc</link>)                          (<link linkend="GIOChannel">GIOChannel</link> *source,
95                                                          <link linkend="GIOCondition">GIOCondition</link> condition,
96                                                          <link linkend="gpointer">gpointer</link> data);
97
98                     <link linkend="GIOFuncs">GIOFuncs</link>;
99
100 <link linkend="gsize">gsize</link>               <link linkend="g-io-channel-get-buffer-size">g_io_channel_get_buffer_size</link>        (<link linkend="GIOChannel">GIOChannel</link> *channel);
101 <link linkend="void">void</link>                <link linkend="g-io-channel-set-buffer-size">g_io_channel_set_buffer_size</link>        (<link linkend="GIOChannel">GIOChannel</link> *channel,
102                                                          <link linkend="gsize">gsize</link> size);
103 <link linkend="GIOCondition">GIOCondition</link>        <link linkend="g-io-channel-get-buffer-condition">g_io_channel_get_buffer_condition</link>   (<link linkend="GIOChannel">GIOChannel</link> *channel);
104 <link linkend="GIOFlags">GIOFlags</link>            <link linkend="g-io-channel-get-flags">g_io_channel_get_flags</link>              (<link linkend="GIOChannel">GIOChannel</link> *channel);
105 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-set-flags">g_io_channel_set_flags</link>              (<link linkend="GIOChannel">GIOChannel</link> *channel,
106                                                          <link linkend="GIOFlags">GIOFlags</link> flags,
107                                                          <link linkend="GError">GError</link> **error);
108 enum                <link linkend="GIOFlags">GIOFlags</link>;
109 const <link linkend="gchar">gchar</link>*        <link linkend="g-io-channel-get-line-term">g_io_channel_get_line_term</link>          (<link linkend="GIOChannel">GIOChannel</link> *channel,
110                                                          <link linkend="gint">gint</link> *length);
111 <link linkend="void">void</link>                <link linkend="g-io-channel-set-line-term">g_io_channel_set_line_term</link>          (<link linkend="GIOChannel">GIOChannel</link> *channel,
112                                                          const <link linkend="gchar">gchar</link> *line_term,
113                                                          <link linkend="gint">gint</link> length);
114 <link linkend="gboolean">gboolean</link>            <link linkend="g-io-channel-get-buffered">g_io_channel_get_buffered</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel);
115 <link linkend="void">void</link>                <link linkend="g-io-channel-set-buffered">g_io_channel_set_buffered</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel,
116                                                          <link linkend="gboolean">gboolean</link> buffered);
117 const <link linkend="gchar">gchar</link>*        <link linkend="g-io-channel-get-encoding">g_io_channel_get_encoding</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel);
118 <link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-set-encoding">g_io_channel_set_encoding</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel,
119                                                          const <link linkend="gchar">gchar</link> *encoding,
120                                                          <link linkend="GError">GError</link> **error);
121 <link linkend="gboolean">gboolean</link>            <link linkend="g-io-channel-get-close-on-unref">g_io_channel_get_close_on_unref</link>     (<link linkend="GIOChannel">GIOChannel</link> *channel);
122 <link linkend="void">void</link>                <link linkend="g-io-channel-set-close-on-unref">g_io_channel_set_close_on_unref</link>     (<link linkend="GIOChannel">GIOChannel</link> *channel,
123                                                          <link linkend="gboolean">gboolean</link> do_close);
124
125
126 <link linkend="GIOError">GIOError</link>            <link linkend="g-io-channel-read">g_io_channel_read</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
127                                                          <link linkend="gchar">gchar</link> *buf,
128                                                          <link linkend="gsize">gsize</link> count,
129                                                          <link linkend="gsize">gsize</link> *bytes_read);
130 enum                <link linkend="GIOError">GIOError</link>;
131 <link linkend="GIOError">GIOError</link>            <link linkend="g-io-channel-write">g_io_channel_write</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel,
132                                                          const <link linkend="gchar">gchar</link> *buf,
133                                                          <link linkend="gsize">gsize</link> count,
134                                                          <link linkend="gsize">gsize</link> *bytes_written);
135 <link linkend="GIOError">GIOError</link>            <link linkend="g-io-channel-seek">g_io_channel_seek</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
136                                                          <link linkend="gint64">gint64</link> offset,
137                                                          <link linkend="GSeekType">GSeekType</link> type);
138 <link linkend="void">void</link>                <link linkend="g-io-channel-close">g_io_channel_close</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel);
139 </synopsis>
140 </refsynopsisdiv>
141
142
143
144
145
146
147
148
149
150 <refsect1 id="glib-IO-Channels.description" role="desc">
151 <title role="desc.title">Description</title>
152 <para>
153 The <link linkend="GIOChannel"><type>GIOChannel</type></link> data type aims to provide a portable method for using file
154 descriptors, pipes, and sockets, and integrating them into the
155 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
156 Currently full support is available on UNIX platforms, support for
157 Windows is only partially complete.
158 </para>
159 <para>
160 To create a new <link linkend="GIOChannel"><type>GIOChannel</type></link> on UNIX systems use <link linkend="g-io-channel-unix-new"><function>g_io_channel_unix_new()</function></link>.
161 This works for plain file descriptors, pipes and sockets.
162 Alternatively, a channel can be created for a file in a system independent
163 manner using <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>.
164 </para>
165 <para>
166 Once a <link linkend="GIOChannel"><type>GIOChannel</type></link> has been created, it can be used in a generic manner
167 with the functions <link linkend="g-io-channel-read-chars"><function>g_io_channel_read_chars()</function></link>, <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link>,
168 <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>, and <link linkend="g-io-channel-shutdown"><function>g_io_channel_shutdown()</function></link>.
169 </para>
170 <para>
171 To add a <link linkend="GIOChannel"><type>GIOChannel</type></link> to the
172 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
173 use <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>. Here you specify which events
174 you are interested in on the <link linkend="GIOChannel"><type>GIOChannel</type></link>, and provide a function to be
175 called whenever these events occur.
176 </para>
177 <para>
178 <link linkend="GIOChannel"><type>GIOChannel</type></link> instances are created with an initial reference count of 1.
179 <link linkend="g-io-channel-ref"><function>g_io_channel_ref()</function></link> and <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link> can be used to increment or
180 decrement the reference count respectively. When the reference count falls
181 to 0, the <link linkend="GIOChannel"><type>GIOChannel</type></link> is freed. (Though it isn't closed automatically,
182 unless it was created using <link linkend="g-io-channel-new-from-file"><function>g_io_channel_new_from_file()</function></link>.)
183 Using <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link> increments a channel's
184 reference count.
185 </para>
186 <para>
187 The new functions <link linkend="g-io-channel-read-chars"><function>g_io_channel_read_chars()</function></link>, <link linkend="g-io-channel-read-line"><function>g_io_channel_read_line()</function></link>,
188 <link linkend="g-io-channel-read-line-string"><function>g_io_channel_read_line_string()</function></link>, <link linkend="g-io-channel-read-to-end"><function>g_io_channel_read_to_end()</function></link>,
189 <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link>, <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>,
190 and <link linkend="g-io-channel-flush"><function>g_io_channel_flush()</function></link> should not be mixed with the
191 deprecated functions <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link>, <link linkend="g-io-channel-write"><function>g_io_channel_write()</function></link>,
192 and <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link> on the same channel.
193 </para>
194 </refsect1>
195
196 <refsect1 id="glib-IO-Channels.details" role="details">
197 <title role="details.title">Details</title>
198 <refsect2 id="GIOChannel" role="struct">
199 <title>GIOChannel</title>
200 <indexterm zone="GIOChannel"><primary sortas="IOChannel">GIOChannel</primary></indexterm><programlisting>typedef struct {
201 } GIOChannel;
202 </programlisting>
203 <para>
204 A data structure representing an IO Channel. The fields should be considered
205 private and should only be accessed with the following functions.
206 </para></refsect2>
207 <refsect2 id="g-io-channel-unix-new" role="function">
208 <title>g_io_channel_unix_new ()</title>
209 <indexterm zone="g-io-channel-unix-new"><primary sortas="io_channel_unix_new">g_io_channel_unix_new</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>*         g_io_channel_unix_new               (<link linkend="int">int</link> fd);</programlisting>
210 <para>
211 Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor.
212 On UNIX systems this works for plain files, pipes, and sockets.
213 </para>
214 <para>
215 The returned <link linkend="GIOChannel"><type>GIOChannel</type></link> has a reference count of 1.
216 </para>
217 <para>
218 The default encoding for <link linkend="GIOChannel"><type>GIOChannel</type></link> is UTF-8. If your application
219 is reading output from a command using via pipe, you may need to
220 set the encoding to the encoding of the current locale (see
221 <link linkend="g-get-charset"><function>g_get_charset()</function></link>) with the <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link> function.
222 </para>
223 <para>
224 If you want to read raw binary data without interpretation, then
225 call the <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link> function with <link linkend="NULL--CAPS"><literal>NULL</literal></link> for the
226 encoding argument.
227 </para>
228 <para>
229 This function is available in GLib on Windows, too, but you should
230 avoid using it on Windows. The domain of file descriptors and sockets
231 overlap. There is no way for GLib to know which one you mean in case
232 the argument you pass to this function happens to be both a valid file
233 descriptor and socket. If that happens a warning is issued, and GLib
234 assumes that it is the file descriptor you mean.
235 </para><variablelist role="params">
236 <varlistentry><term><parameter>fd</parameter>&#160;:</term>
237 <listitem><simpara>a file descriptor.
238 </simpara></listitem></varlistentry>
239 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
240 </simpara></listitem></varlistentry>
241 </variablelist></refsect2>
242 <refsect2 id="g-io-channel-unix-get-fd" role="function">
243 <title>g_io_channel_unix_get_fd ()</title>
244 <indexterm zone="g-io-channel-unix-get-fd"><primary sortas="io_channel_unix_get_fd">g_io_channel_unix_get_fd</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_io_channel_unix_get_fd            (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
245 <para>
246 Returns the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
247 </para>
248 <para>
249 On Windows this function returns the file descriptor or socket of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
250 </para><variablelist role="params">
251 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
252 <listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>, created with <link linkend="g-io-channel-unix-new"><function>g_io_channel_unix_new()</function></link>.
253 </simpara></listitem></varlistentry>
254 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
255 </simpara></listitem></varlistentry>
256 </variablelist></refsect2>
257 <refsect2 id="g-io-channel-win32-new-fd" role="function">
258 <title>g_io_channel_win32_new_fd ()</title>
259 <indexterm zone="g-io-channel-win32-new-fd"><primary sortas="io_channel_win32_new_fd">g_io_channel_win32_new_fd</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>*         g_io_channel_win32_new_fd           (<link linkend="gint">gint</link> fd);</programlisting>
260 <para>
261 Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor on Windows.
262 This works for file descriptors from the C runtime.
263 </para>
264 <para>
265 This function works for file descriptors as returned by the <link linkend="open"><function>open()</function></link>,
266 <link linkend="creat"><function>creat()</function></link>, <link linkend="pipe"><function>pipe()</function></link> and <link linkend="fileno"><function>fileno()</function></link> calls in the Microsoft C runtime. In
267 order to meaningfully use this function your code should use the same
268 C runtime as GLib uses, which is msvcrt.dll. Note that in current
269 Microsoft compilers it is near impossible to convince it to build code
270 that would use msvcrt.dll. The last Microsoft compiler version that
271 supported using msvcrt.dll as the C runtime was version 6. The GNU
272 compiler and toolchain for Windows, also known as Mingw, fully
273 supports msvcrt.dll.
274 </para>
275 <para>
276 If you have created a <link linkend="GIOChannel"><type>GIOChannel</type></link> for a file descriptor and started
277 watching (polling) it, you shouldn't call <link linkend="read"><function>read()</function></link> on the file
278 descriptor. This is because adding polling for a file descriptor is
279 implemented in GLib on Windows by starting a thread that sits blocked
280 in a <link linkend="read"><function>read()</function></link> from the file descriptor most of the time. All reads from
281 the file descriptor should be done by this internal GLib thread. Your
282 code should call only <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link>.
283 </para>
284 <para>
285 This function is available only in GLib on Windows.
286 </para><variablelist role="params">
287 <varlistentry><term><parameter>fd</parameter>&#160;:</term>
288 <listitem><simpara>a C library file descriptor.
289 </simpara></listitem></varlistentry>
290 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
291 </simpara></listitem></varlistentry>
292 </variablelist></refsect2>
293 <refsect2 id="g-io-channel-win32-new-socket" role="function">
294 <title>g_io_channel_win32_new_socket ()</title>
295 <indexterm zone="g-io-channel-win32-new-socket"><primary sortas="io_channel_win32_new_socket">g_io_channel_win32_new_socket</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> *        g_io_channel_win32_new_socket       (<link linkend="gint">gint</link> socket);</programlisting>
296 <para>
297 Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a socket on Windows.
298 </para>
299 <para>
300 This function works for sockets created by Winsock.
301 It's available only in GLib on Windows.
302 </para>
303 <para>
304 Polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket
305 puts the socket in non-blocking mode. This is a side-effect
306 of the implementation and unavoidable.
307 </para><variablelist role="params">
308 <varlistentry><term><parameter>socket</parameter>&#160;:</term>
309 <listitem><simpara>a Winsock socket
310 </simpara></listitem></varlistentry>
311 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>
312 </simpara></listitem></varlistentry>
313 </variablelist></refsect2>
314 <refsect2 id="g-io-channel-win32-new-messages" role="function">
315 <title>g_io_channel_win32_new_messages ()</title>
316 <indexterm zone="g-io-channel-win32-new-messages"><primary sortas="io_channel_win32_new_messages">g_io_channel_win32_new_messages</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> *        g_io_channel_win32_new_messages     (<link linkend="gsize">gsize</link> hwnd);</programlisting>
317 <para>
318 Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a window handle on Windows.
319 </para>
320 <para>
321 This function creates a <link linkend="GIOChannel"><type>GIOChannel</type></link> that can be used to poll for
322 Windows messages for the window in question.
323 </para><variablelist role="params">
324 <varlistentry><term><parameter>hwnd</parameter>&#160;:</term>
325 <listitem><simpara>a window handle.
326 </simpara></listitem></varlistentry>
327 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
328 </simpara></listitem></varlistentry>
329 </variablelist></refsect2>
330 <refsect2 id="g-io-channel-init" role="function">
331 <title>g_io_channel_init ()</title>
332 <indexterm zone="g-io-channel-init"><primary sortas="io_channel_init">g_io_channel_init</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_channel_init                   (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
333 <para>
334 Initializes a <link linkend="GIOChannel"><type>GIOChannel</type></link> struct. 
335 </para>
336 <para>
337 This is called by each of the above functions when creating a 
338 <link linkend="GIOChannel"><type>GIOChannel</type></link>, and so is not often needed by the application 
339 programmer (unless you are creating a new type of <link linkend="GIOChannel"><type>GIOChannel</type></link>).</para>
340 <para>
341 </para><variablelist role="params">
342 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
343 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
344 </simpara></listitem></varlistentry>
345 </variablelist></refsect2>
346 <refsect2 id="g-io-channel-new-file" role="function">
347 <title>g_io_channel_new_file ()</title>
348 <indexterm zone="g-io-channel-new-file"><primary sortas="io_channel_new_file">g_io_channel_new_file</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>*         g_io_channel_new_file               (const <link linkend="gchar">gchar</link> *filename,
349                                                          const <link linkend="gchar">gchar</link> *mode,
350                                                          <link linkend="GError">GError</link> **error);</programlisting>
351 <para>
352 Open a file <parameter>filename</parameter> as a <link linkend="GIOChannel"><type>GIOChannel</type></link> using mode <parameter>mode</parameter>. This
353 channel will be closed when the last reference to it is dropped,
354 so there is no need to call <link linkend="g-io-channel-close"><function>g_io_channel_close()</function></link> (though doing
355 so will not cause problems, as long as no attempt is made to
356 access the channel after it is closed).</para>
357 <para>
358 </para><variablelist role="params">
359 <varlistentry><term><parameter>filename</parameter>&#160;:</term>
360 <listitem><simpara> A string containing the name of a file
361 </simpara></listitem></varlistentry>
362 <varlistentry><term><parameter>mode</parameter>&#160;:</term>
363 <listitem><simpara> One of "r", "w", "a", "r+", "w+", "a+". These have
364        the same meaning as in <link linkend="fopen"><function>fopen()</function></link>
365 </simpara></listitem></varlistentry>
366 <varlistentry><term><parameter>error</parameter>&#160;:</term>
367 <listitem><simpara> A location to return an error of type <link linkend="G-FILE-ERROR--CAPS"><literal>G_FILE_ERROR</literal></link>
368 </simpara></listitem></varlistentry>
369 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link> on success, <link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure.
370 </simpara></listitem></varlistentry>
371 </variablelist></refsect2>
372 <refsect2 id="g-io-channel-read-chars" role="function">
373 <title>g_io_channel_read_chars ()</title>
374 <indexterm zone="g-io-channel-read-chars"><primary sortas="io_channel_read_chars">g_io_channel_read_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_read_chars             (<link linkend="GIOChannel">GIOChannel</link> *channel,
375                                                          <link linkend="gchar">gchar</link> *buf,
376                                                          <link linkend="gsize">gsize</link> count,
377                                                          <link linkend="gsize">gsize</link> *bytes_read,
378                                                          <link linkend="GError">GError</link> **error);</programlisting>
379 <para>
380 Replacement for <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link> with the new API.</para>
381 <para>
382 </para><variablelist role="params">
383 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
384 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
385 </simpara></listitem></varlistentry>
386 <varlistentry><term><parameter>buf</parameter>&#160;:</term>
387 <listitem><simpara> a buffer to read data into
388 </simpara></listitem></varlistentry>
389 <varlistentry><term><parameter>count</parameter>&#160;:</term>
390 <listitem><simpara> the size of the buffer. Note that the buffer may
391         not be complelely filled even if there is data
392         in the buffer if the remaining data is not a
393         complete character.
394 </simpara></listitem></varlistentry>
395 <varlistentry><term><parameter>bytes_read</parameter>&#160;:</term>
396 <listitem><simpara> The number of bytes read. This may be zero even on
397              success if count &lt; 6 and the channel's encoding is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>.
398              This indicates that the next UTF-8 character is too wide for
399              the buffer.
400 </simpara></listitem></varlistentry>
401 <varlistentry><term><parameter>error</parameter>&#160;:</term>
402 <listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
403         or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.
404 </simpara></listitem></varlistentry>
405 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
406 </simpara></listitem></varlistentry>
407 </variablelist></refsect2>
408 <refsect2 id="g-io-channel-read-unichar" role="function">
409 <title>g_io_channel_read_unichar ()</title>
410 <indexterm zone="g-io-channel-read-unichar"><primary sortas="io_channel_read_unichar">g_io_channel_read_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_read_unichar           (<link linkend="GIOChannel">GIOChannel</link> *channel,
411                                                          <link linkend="gunichar">gunichar</link> *thechar,
412                                                          <link linkend="GError">GError</link> **error);</programlisting>
413 <para>
414 Reads a Unicode character from <parameter>channel</parameter>.
415 This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>
416 <para>
417 </para><variablelist role="params">
418 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
419 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
420 </simpara></listitem></varlistentry>
421 <varlistentry><term><parameter>thechar</parameter>&#160;:</term>
422 <listitem><simpara> a location to return a character
423 </simpara></listitem></varlistentry>
424 <varlistentry><term><parameter>error</parameter>&#160;:</term>
425 <listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
426         or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
427 </simpara></listitem></varlistentry>
428 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
429 </simpara></listitem></varlistentry>
430 </variablelist></refsect2>
431 <refsect2 id="g-io-channel-read-line" role="function">
432 <title>g_io_channel_read_line ()</title>
433 <indexterm zone="g-io-channel-read-line"><primary sortas="io_channel_read_line">g_io_channel_read_line</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_read_line              (<link linkend="GIOChannel">GIOChannel</link> *channel,
434                                                          <link linkend="gchar">gchar</link> **str_return,
435                                                          <link linkend="gsize">gsize</link> *length,
436                                                          <link linkend="gsize">gsize</link> *terminator_pos,
437                                                          <link linkend="GError">GError</link> **error);</programlisting>
438 <para>
439 Reads a line, including the terminating character(s),
440 from a <link linkend="GIOChannel"><type>GIOChannel</type></link> into a newly-allocated string.
441 <parameter>str_return</parameter> will contain allocated memory if the return
442 is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.</para>
443 <para>
444 </para><variablelist role="params">
445 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
446 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
447 </simpara></listitem></varlistentry>
448 <varlistentry><term><parameter>str_return</parameter>&#160;:</term>
449 <listitem><simpara> The line read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>, including the
450              line terminator. This data should be freed with <link linkend="g-free"><function>g_free()</function></link>
451              when no longer needed. This is a nul-terminated string. 
452              If a <parameter>length</parameter> of zero is returned, this will be <link linkend="NULL--CAPS"><literal>NULL</literal></link> instead.
453 </simpara></listitem></varlistentry>
454 <varlistentry><term><parameter>length</parameter>&#160;:</term>
455 <listitem><simpara> location to store length of the read data, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
456 </simpara></listitem></varlistentry>
457 <varlistentry><term><parameter>terminator_pos</parameter>&#160;:</term>
458 <listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
459 </simpara></listitem></varlistentry>
460 <varlistentry><term><parameter>error</parameter>&#160;:</term>
461 <listitem><simpara> A location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
462         or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
463 </simpara></listitem></varlistentry>
464 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
465 </simpara></listitem></varlistentry>
466 </variablelist></refsect2>
467 <refsect2 id="g-io-channel-read-line-string" role="function">
468 <title>g_io_channel_read_line_string ()</title>
469 <indexterm zone="g-io-channel-read-line-string"><primary sortas="io_channel_read_line_string">g_io_channel_read_line_string</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_read_line_string       (<link linkend="GIOChannel">GIOChannel</link> *channel,
470                                                          <link linkend="GString">GString</link> *buffer,
471                                                          <link linkend="gsize">gsize</link> *terminator_pos,
472                                                          <link linkend="GError">GError</link> **error);</programlisting>
473 <para>
474 Reads a line from a <link linkend="GIOChannel"><type>GIOChannel</type></link>, using a <link linkend="GString"><type>GString</type></link> as a buffer.</para>
475 <para>
476 </para><variablelist role="params">
477 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
478 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
479 </simpara></listitem></varlistentry>
480 <varlistentry><term><parameter>buffer</parameter>&#160;:</term>
481 <listitem><simpara> a <link linkend="GString"><type>GString</type></link> into which the line will be written.
482          If <parameter>buffer</parameter> already contains data, the old data will
483          be overwritten.
484 </simpara></listitem></varlistentry>
485 <varlistentry><term><parameter>terminator_pos</parameter>&#160;:</term>
486 <listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
487 </simpara></listitem></varlistentry>
488 <varlistentry><term><parameter>error</parameter>&#160;:</term>
489 <listitem><simpara> a location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
490         or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
491 </simpara></listitem></varlistentry>
492 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
493 </simpara></listitem></varlistentry>
494 </variablelist></refsect2>
495 <refsect2 id="g-io-channel-read-to-end" role="function">
496 <title>g_io_channel_read_to_end ()</title>
497 <indexterm zone="g-io-channel-read-to-end"><primary sortas="io_channel_read_to_end">g_io_channel_read_to_end</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_read_to_end            (<link linkend="GIOChannel">GIOChannel</link> *channel,
498                                                          <link linkend="gchar">gchar</link> **str_return,
499                                                          <link linkend="gsize">gsize</link> *length,
500                                                          <link linkend="GError">GError</link> **error);</programlisting>
501 <para>
502 Reads all the remaining data from the file.</para>
503 <para>
504 </para><variablelist role="params">
505 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
506 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
507 </simpara></listitem></varlistentry>
508 <varlistentry><term><parameter>str_return</parameter>&#160;:</term>
509 <listitem><simpara> Location to store a pointer to a string holding
510              the remaining data in the <link linkend="GIOChannel"><type>GIOChannel</type></link>. This data should
511              be freed with <link linkend="g-free"><function>g_free()</function></link> when no longer needed. This
512              data is terminated by an extra nul character, but there 
513              may be other nuls in the intervening data.
514 </simpara></listitem></varlistentry>
515 <varlistentry><term><parameter>length</parameter>&#160;:</term>
516 <listitem><simpara> location to store length of the data
517 </simpara></listitem></varlistentry>
518 <varlistentry><term><parameter>error</parameter>&#160;:</term>
519 <listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
520         or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
521 </simpara></listitem></varlistentry>
522 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> on success. 
523     This function never returns <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>.
524 </simpara></listitem></varlistentry>
525 </variablelist></refsect2>
526 <refsect2 id="g-io-channel-write-chars" role="function">
527 <title>g_io_channel_write_chars ()</title>
528 <indexterm zone="g-io-channel-write-chars"><primary sortas="io_channel_write_chars">g_io_channel_write_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_write_chars            (<link linkend="GIOChannel">GIOChannel</link> *channel,
529                                                          const <link linkend="gchar">gchar</link> *buf,
530                                                          <link linkend="gssize">gssize</link> count,
531                                                          <link linkend="gsize">gsize</link> *bytes_written,
532                                                          <link linkend="GError">GError</link> **error);</programlisting>
533 <para>
534 Replacement for <link linkend="g-io-channel-write"><function>g_io_channel_write()</function></link> with the new API.
535 </para>
536 <para>
537 On seekable channels with encodings other than <link linkend="NULL--CAPS"><literal>NULL</literal></link> or UTF-8, generic
538 mixing of reading and writing is not allowed. A call to <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link>
539 may only be made on a channel from which data has been read in the
540 cases described in the documentation for <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>.</para>
541 <para>
542 </para><variablelist role="params">
543 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
544 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
545 </simpara></listitem></varlistentry>
546 <varlistentry><term><parameter>buf</parameter>&#160;:</term>
547 <listitem><simpara> a buffer to write data from
548 </simpara></listitem></varlistentry>
549 <varlistentry><term><parameter>count</parameter>&#160;:</term>
550 <listitem><simpara> the size of the buffer. If -1, the buffer
551         is taken to be a nul-terminated string.
552 </simpara></listitem></varlistentry>
553 <varlistentry><term><parameter>bytes_written</parameter>&#160;:</term>
554 <listitem><simpara> The number of bytes written. This can be nonzero
555                 even if the return value is not <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.
556                 If the return value is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> and the
557                 channel is blocking, this will always be equal
558                 to <parameter>count</parameter> if <parameter>count</parameter> &gt;= 0.
559 </simpara></listitem></varlistentry>
560 <varlistentry><term><parameter>error</parameter>&#160;:</term>
561 <listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
562         or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
563 </simpara></listitem></varlistentry>
564 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
565 </simpara></listitem></varlistentry>
566 </variablelist></refsect2>
567 <refsect2 id="g-io-channel-write-unichar" role="function">
568 <title>g_io_channel_write_unichar ()</title>
569 <indexterm zone="g-io-channel-write-unichar"><primary sortas="io_channel_write_unichar">g_io_channel_write_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_write_unichar          (<link linkend="GIOChannel">GIOChannel</link> *channel,
570                                                          <link linkend="gunichar">gunichar</link> thechar,
571                                                          <link linkend="GError">GError</link> **error);</programlisting>
572 <para>
573 Writes a Unicode character to <parameter>channel</parameter>.
574 This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>
575 <para>
576 </para><variablelist role="params">
577 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
578 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
579 </simpara></listitem></varlistentry>
580 <varlistentry><term><parameter>thechar</parameter>&#160;:</term>
581 <listitem><simpara> a character
582 </simpara></listitem></varlistentry>
583 <varlistentry><term><parameter>error</parameter>&#160;:</term>
584 <listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
585         or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
586 </simpara></listitem></varlistentry>
587 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
588 </simpara></listitem></varlistentry>
589 </variablelist></refsect2>
590 <refsect2 id="g-io-channel-flush" role="function">
591 <title>g_io_channel_flush ()</title>
592 <indexterm zone="g-io-channel-flush"><primary sortas="io_channel_flush">g_io_channel_flush</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_flush                  (<link linkend="GIOChannel">GIOChannel</link> *channel,
593                                                          <link linkend="GError">GError</link> **error);</programlisting>
594 <para>
595 Flushes the write buffer for the GIOChannel.</para>
596 <para>
597 </para><variablelist role="params">
598 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
599 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
600 </simpara></listitem></varlistentry>
601 <varlistentry><term><parameter>error</parameter>&#160;:</term>
602 <listitem><simpara> location to store an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
603 </simpara></listitem></varlistentry>
604 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation: One of
605   <link linkend="G-IO-STATUS-NORMAL--CAPS"><type>G_IO_STATUS_NORMAL</type></link>, <link linkend="G-IO-STATUS-AGAIN--CAPS"><type>G_IO_STATUS_AGAIN</type></link>, or
606   <link linkend="G-IO-STATUS-ERROR--CAPS"><type>G_IO_STATUS_ERROR</type></link>.
607 </simpara></listitem></varlistentry>
608 </variablelist></refsect2>
609 <refsect2 id="g-io-channel-seek-position" role="function">
610 <title>g_io_channel_seek_position ()</title>
611 <indexterm zone="g-io-channel-seek-position"><primary sortas="io_channel_seek_position">g_io_channel_seek_position</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_seek_position          (<link linkend="GIOChannel">GIOChannel</link> *channel,
612                                                          <link linkend="gint64">gint64</link> offset,
613                                                          <link linkend="GSeekType">GSeekType</link> type,
614                                                          <link linkend="GError">GError</link> **error);</programlisting>
615 <para>
616 Replacement for <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link> with the new API.</para>
617 <para>
618 </para><variablelist role="params">
619 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
620 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
621 </simpara></listitem></varlistentry>
622 <varlistentry><term><parameter>offset</parameter>&#160;:</term>
623 <listitem><simpara> The offset in bytes from the position specified by <parameter>type</parameter>
624 </simpara></listitem></varlistentry>
625 <varlistentry><term><parameter>type</parameter>&#160;:</term>
626 <listitem><simpara> a <link linkend="GSeekType"><type>GSeekType</type></link>. The type <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link> is only allowed in those
627                      cases where a call to <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>
628                      is allowed. See the documentation for
629                      <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link> for details.
630 </simpara></listitem></varlistentry>
631 <varlistentry><term><parameter>error</parameter>&#160;:</term>
632 <listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
633 </simpara></listitem></varlistentry>
634 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
635 </simpara></listitem></varlistentry>
636 </variablelist></refsect2>
637 <refsect2 id="GSeekType" role="enum">
638 <title>enum GSeekType</title>
639 <indexterm zone="GSeekType"><primary sortas="SeekType">GSeekType</primary></indexterm><programlisting>typedef enum
640 {
641   G_SEEK_CUR,
642   G_SEEK_SET,
643   G_SEEK_END
644 } GSeekType;
645 </programlisting>
646 <para>
647 An enumeration specifying the base position for a <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>
648 operation.
649 </para><variablelist role="enum">
650 <varlistentry id="G-SEEK-CUR--CAPS" role="constant">
651 <term><literal>G_SEEK_CUR</literal></term>
652 <listitem><simpara>the current position in the file.
653 </simpara></listitem>
654 </varlistentry>
655 <varlistentry id="G-SEEK-SET--CAPS" role="constant">
656 <term><literal>G_SEEK_SET</literal></term>
657 <listitem><simpara>the start of the file.
658 </simpara></listitem>
659 </varlistentry>
660 <varlistentry id="G-SEEK-END--CAPS" role="constant">
661 <term><literal>G_SEEK_END</literal></term>
662 <listitem><simpara>the end of the file.
663 </simpara></listitem>
664 </varlistentry>
665 </variablelist></refsect2>
666 <refsect2 id="g-io-channel-shutdown" role="function">
667 <title>g_io_channel_shutdown ()</title>
668 <indexterm zone="g-io-channel-shutdown"><primary sortas="io_channel_shutdown">g_io_channel_shutdown</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_shutdown               (<link linkend="GIOChannel">GIOChannel</link> *channel,
669                                                          <link linkend="gboolean">gboolean</link> flush,
670                                                          <link linkend="GError">GError</link> **err);</programlisting>
671 <para>
672 Close an IO channel. Any pending data to be written will be
673 flushed if <parameter>flush</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. The channel will not be freed until the
674 last reference is dropped using <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link>.</para>
675 <para>
676 </para><variablelist role="params">
677 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
678 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
679 </simpara></listitem></varlistentry>
680 <varlistentry><term><parameter>flush</parameter>&#160;:</term>
681 <listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, flush pending
682 </simpara></listitem></varlistentry>
683 <varlistentry><term><parameter>err</parameter>&#160;:</term>
684 <listitem><simpara> location to store a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
685 </simpara></listitem></varlistentry>
686 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
687 </simpara></listitem></varlistentry>
688 </variablelist></refsect2>
689 <refsect2 id="GIOStatus" role="enum">
690 <title>enum GIOStatus</title>
691 <indexterm zone="GIOStatus"><primary sortas="IOStatus">GIOStatus</primary></indexterm><programlisting>typedef enum
692 {
693   G_IO_STATUS_ERROR,
694   G_IO_STATUS_NORMAL,
695   G_IO_STATUS_EOF,
696   G_IO_STATUS_AGAIN
697 } GIOStatus;
698 </programlisting>
699 <para>
700 Stati returned by most of the <link linkend="GIOFuncs"><type>GIOFuncs</type></link> functions.
701 </para><variablelist role="enum">
702 <varlistentry id="G-IO-STATUS-ERROR--CAPS" role="constant">
703 <term><literal>G_IO_STATUS_ERROR</literal></term>
704 <listitem><simpara>An error occurred.
705 </simpara></listitem>
706 </varlistentry>
707 <varlistentry id="G-IO-STATUS-NORMAL--CAPS" role="constant">
708 <term><literal>G_IO_STATUS_NORMAL</literal></term>
709 <listitem><simpara>Success.
710 </simpara></listitem>
711 </varlistentry>
712 <varlistentry id="G-IO-STATUS-EOF--CAPS" role="constant">
713 <term><literal>G_IO_STATUS_EOF</literal></term>
714 <listitem><simpara>End of file.
715 </simpara></listitem>
716 </varlistentry>
717 <varlistentry id="G-IO-STATUS-AGAIN--CAPS" role="constant">
718 <term><literal>G_IO_STATUS_AGAIN</literal></term>
719 <listitem><simpara>Resource temporarily unavailable.
720 </simpara></listitem>
721 </varlistentry>
722 </variablelist></refsect2>
723 <refsect2 id="GIOChannelError" role="enum">
724 <title>enum GIOChannelError</title>
725 <indexterm zone="GIOChannelError"><primary sortas="IOChannelError">GIOChannelError</primary></indexterm><programlisting>typedef enum
726 {
727   /* Derived from errno */
728   G_IO_CHANNEL_ERROR_FBIG,
729   G_IO_CHANNEL_ERROR_INVAL,
730   G_IO_CHANNEL_ERROR_IO,
731   G_IO_CHANNEL_ERROR_ISDIR,
732   G_IO_CHANNEL_ERROR_NOSPC,
733   G_IO_CHANNEL_ERROR_NXIO,
734   G_IO_CHANNEL_ERROR_OVERFLOW,
735   G_IO_CHANNEL_ERROR_PIPE,
736   /* Other */
737   G_IO_CHANNEL_ERROR_FAILED
738 } GIOChannelError;
739 </programlisting>
740 <para>
741 Error codes returned by <link linkend="GIOChannel"><type>GIOChannel</type></link> operations.
742 </para><variablelist role="enum">
743 <varlistentry id="G-IO-CHANNEL-ERROR-FBIG--CAPS" role="constant">
744 <term><literal>G_IO_CHANNEL_ERROR_FBIG</literal></term>
745 <listitem><simpara>File too large.
746 </simpara></listitem>
747 </varlistentry>
748 <varlistentry id="G-IO-CHANNEL-ERROR-INVAL--CAPS" role="constant">
749 <term><literal>G_IO_CHANNEL_ERROR_INVAL</literal></term>
750 <listitem><simpara>Invalid argument.
751 </simpara></listitem>
752 </varlistentry>
753 <varlistentry id="G-IO-CHANNEL-ERROR-IO--CAPS" role="constant">
754 <term><literal>G_IO_CHANNEL_ERROR_IO</literal></term>
755 <listitem><simpara>IO error.
756 </simpara></listitem>
757 </varlistentry>
758 <varlistentry id="G-IO-CHANNEL-ERROR-ISDIR--CAPS" role="constant">
759 <term><literal>G_IO_CHANNEL_ERROR_ISDIR</literal></term>
760 <listitem><simpara>File is a directory.
761 </simpara></listitem>
762 </varlistentry>
763 <varlistentry id="G-IO-CHANNEL-ERROR-NOSPC--CAPS" role="constant">
764 <term><literal>G_IO_CHANNEL_ERROR_NOSPC</literal></term>
765 <listitem><simpara>No space left on device.
766 </simpara></listitem>
767 </varlistentry>
768 <varlistentry id="G-IO-CHANNEL-ERROR-NXIO--CAPS" role="constant">
769 <term><literal>G_IO_CHANNEL_ERROR_NXIO</literal></term>
770 <listitem><simpara>No such device or address.
771 </simpara></listitem>
772 </varlistentry>
773 <varlistentry id="G-IO-CHANNEL-ERROR-OVERFLOW--CAPS" role="constant">
774 <term><literal>G_IO_CHANNEL_ERROR_OVERFLOW</literal></term>
775 <listitem><simpara>Value too large for defined datatype.
776 </simpara></listitem>
777 </varlistentry>
778 <varlistentry id="G-IO-CHANNEL-ERROR-PIPE--CAPS" role="constant">
779 <term><literal>G_IO_CHANNEL_ERROR_PIPE</literal></term>
780 <listitem><simpara>Broken pipe.
781 </simpara></listitem>
782 </varlistentry>
783 <varlistentry id="G-IO-CHANNEL-ERROR-FAILED--CAPS" role="constant">
784 <term><literal>G_IO_CHANNEL_ERROR_FAILED</literal></term>
785 <listitem><simpara>Some other error.
786 </simpara></listitem>
787 </varlistentry>
788 </variablelist></refsect2>
789 <refsect2 id="G-IO-CHANNEL-ERROR--CAPS" role="macro">
790 <title>G_IO_CHANNEL_ERROR</title>
791 <indexterm zone="G-IO-CHANNEL-ERROR--CAPS"><primary sortas="IO_CHANNEL_ERROR">G_IO_CHANNEL_ERROR</primary></indexterm><programlisting>#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()
792 </programlisting>
793 <para>
794 Error domain for <link linkend="GIOChannel"><type>GIOChannel</type></link> operations. Errors in this domain will
795 be from the <link linkend="GIOChannelError"><type>GIOChannelError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
796 error domains.
797 </para></refsect2>
798 <refsect2 id="g-io-channel-error-from-errno" role="function">
799 <title>g_io_channel_error_from_errno ()</title>
800 <indexterm zone="g-io-channel-error-from-errno"><primary sortas="io_channel_error_from_errno">g_io_channel_error_from_errno</primary></indexterm><programlisting><link linkend="GIOChannelError">GIOChannelError</link>     g_io_channel_error_from_errno       (<link linkend="gint">gint</link> en);</programlisting>
801 <para>
802 Converts an <literal>errno</literal> error number to a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.</para>
803 <para>
804 </para><variablelist role="params">
805 <varlistentry><term><parameter>en</parameter>&#160;:</term>
806 <listitem><simpara> an <literal>errno</literal> error number, e.g. <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link>
807 </simpara></listitem></varlistentry>
808 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GIOChannelError"><type>GIOChannelError</type></link> error number, e.g. 
809      <link linkend="G-IO-CHANNEL-ERROR-INVAL--CAPS"><literal>G_IO_CHANNEL_ERROR_INVAL</literal></link>.
810 </simpara></listitem></varlistentry>
811 </variablelist></refsect2>
812 <refsect2 id="g-io-channel-ref" role="function">
813 <title>g_io_channel_ref ()</title>
814 <indexterm zone="g-io-channel-ref"><primary sortas="io_channel_ref">g_io_channel_ref</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> *        g_io_channel_ref                    (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
815 <para>
816 Increments the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
817 <para>
818 </para><variablelist role="params">
819 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
820 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
821 </simpara></listitem></varlistentry>
822 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <parameter>channel</parameter> that was passed in (since 2.6)
823 </simpara></listitem></varlistentry>
824 </variablelist></refsect2>
825 <refsect2 id="g-io-channel-unref" role="function">
826 <title>g_io_channel_unref ()</title>
827 <indexterm zone="g-io-channel-unref"><primary sortas="io_channel_unref">g_io_channel_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_channel_unref                  (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
828 <para>
829 Decrements the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
830 <para>
831 </para><variablelist role="params">
832 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
833 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
834 </simpara></listitem></varlistentry>
835 </variablelist></refsect2>
836 <refsect2 id="g-io-create-watch" role="function">
837 <title>g_io_create_watch ()</title>
838 <indexterm zone="g-io-create-watch"><primary sortas="io_create_watch">g_io_create_watch</primary></indexterm><programlisting><link linkend="GSource">GSource</link> *           g_io_create_watch                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
839                                                          <link linkend="GIOCondition">GIOCondition</link> condition);</programlisting>
840 <para>
841 Creates a <link linkend="GSource"><type>GSource</type></link> that's dispatched when <parameter>condition</parameter> is met for the 
842 given <parameter>channel</parameter>. For example, if condition is <link linkend="G-IO-IN--CAPS"><type>G_IO_IN</type></link>, the source will 
843 be dispatched when there's data available for reading.
844 </para>
845 <para>
846 <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> is a simpler interface to this same functionality, for 
847 the case where you want to add the source to the default main loop context 
848 at the default priority.
849 </para>
850 <para>
851 On Windows, polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket
852 puts the socket in non-blocking mode. This is a side-effect of the
853 implementation and unavoidable.</para>
854 <para>
855 </para><variablelist role="params">
856 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
857 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link> to watch
858 </simpara></listitem></varlistentry>
859 <varlistentry><term><parameter>condition</parameter>&#160;:</term>
860 <listitem><simpara> conditions to watch for
861 </simpara></listitem></varlistentry>
862 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GSource"><type>GSource</type></link>
863 </simpara></listitem></varlistentry>
864 </variablelist></refsect2>
865 <refsect2 id="g-io-add-watch" role="function">
866 <title>g_io_add_watch ()</title>
867 <indexterm zone="g-io-add-watch"><primary sortas="io_add_watch">g_io_add_watch</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_io_add_watch                      (<link linkend="GIOChannel">GIOChannel</link> *channel,
868                                                          <link linkend="GIOCondition">GIOCondition</link> condition,
869                                                          <link linkend="GIOFunc">GIOFunc</link> func,
870                                                          <link linkend="gpointer">gpointer</link> user_data);</programlisting>
871 <para>
872 Adds the <link linkend="GIOChannel"><type>GIOChannel</type></link> into the default main loop context
873 with the default priority.</para>
874 <para>
875 </para><variablelist role="params">
876 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
877 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
878 </simpara></listitem></varlistentry>
879 <varlistentry><term><parameter>condition</parameter>&#160;:</term>
880 <listitem><simpara> the condition to watch for
881 </simpara></listitem></varlistentry>
882 <varlistentry><term><parameter>func</parameter>&#160;:</term>
883 <listitem><simpara> the function to call when the condition is satisfied
884 </simpara></listitem></varlistentry>
885 <varlistentry><term><parameter>user_data</parameter>&#160;:</term>
886 <listitem><simpara> user data to pass to <parameter>func</parameter>
887 </simpara></listitem></varlistentry>
888 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the event source id
889 </simpara></listitem></varlistentry>
890 </variablelist></refsect2>
891 <refsect2 id="g-io-add-watch-full" role="function">
892 <title>g_io_add_watch_full ()</title>
893 <indexterm zone="g-io-add-watch-full"><primary sortas="io_add_watch_full">g_io_add_watch_full</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_io_add_watch_full                 (<link linkend="GIOChannel">GIOChannel</link> *channel,
894                                                          <link linkend="gint">gint</link> priority,
895                                                          <link linkend="GIOCondition">GIOCondition</link> condition,
896                                                          <link linkend="GIOFunc">GIOFunc</link> func,
897                                                          <link linkend="gpointer">gpointer</link> user_data,
898                                                          <link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
899 <para>
900 Adds the <link linkend="GIOChannel"><type>GIOChannel</type></link> into the default main loop context
901 with the given priority.
902 </para>
903 <para>
904 This internally creates a main loop source using <link linkend="g-io-create-watch"><function>g_io_create_watch()</function></link>
905 and attaches it to the main loop context with <link linkend="g-source-attach"><function>g_source_attach()</function></link>.
906 You can do these steps manuallt if you need greater control.</para>
907 <para>
908 </para><variablelist role="params">
909 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
910 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
911 </simpara></listitem></varlistentry>
912 <varlistentry><term><parameter>priority</parameter>&#160;:</term>
913 <listitem><simpara> the priority of the <link linkend="GIOChannel"><type>GIOChannel</type></link> source
914 </simpara></listitem></varlistentry>
915 <varlistentry><term><parameter>condition</parameter>&#160;:</term>
916 <listitem><simpara> the condition to watch for
917 </simpara></listitem></varlistentry>
918 <varlistentry><term><parameter>func</parameter>&#160;:</term>
919 <listitem><simpara> the function to call when the condition is satisfied
920 </simpara></listitem></varlistentry>
921 <varlistentry><term><parameter>user_data</parameter>&#160;:</term>
922 <listitem><simpara> user data to pass to <parameter>func</parameter>
923 </simpara></listitem></varlistentry>
924 <varlistentry><term><parameter>notify</parameter>&#160;:</term>
925 <listitem><simpara> the function to call when the source is removed
926 </simpara></listitem></varlistentry>
927 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the event source id
928 </simpara></listitem></varlistentry>
929 </variablelist></refsect2>
930 <refsect2 id="GIOCondition" role="enum">
931 <title>enum GIOCondition</title>
932 <indexterm zone="GIOCondition"><primary sortas="IOCondition">GIOCondition</primary></indexterm><programlisting>typedef enum
933 {
934   G_IO_IN       GLIB_SYSDEF_POLLIN,
935   G_IO_OUT      GLIB_SYSDEF_POLLOUT,
936   G_IO_PRI      GLIB_SYSDEF_POLLPRI,
937   G_IO_ERR      GLIB_SYSDEF_POLLERR,
938   G_IO_HUP      GLIB_SYSDEF_POLLHUP,
939   G_IO_NVAL     GLIB_SYSDEF_POLLNVAL
940 } GIOCondition;
941 </programlisting>
942 <para>
943 A bitwise combination representing a condition to watch for on
944 an event source.
945 </para><variablelist role="enum">
946 <varlistentry id="G-IO-IN--CAPS" role="constant">
947 <term><literal>G_IO_IN</literal></term>
948 <listitem><simpara>There is data to read.
949 </simpara></listitem>
950 </varlistentry>
951 <varlistentry id="G-IO-OUT--CAPS" role="constant">
952 <term><literal>G_IO_OUT</literal></term>
953 <listitem><simpara>Data can be written (without blocking).
954 </simpara></listitem>
955 </varlistentry>
956 <varlistentry id="G-IO-PRI--CAPS" role="constant">
957 <term><literal>G_IO_PRI</literal></term>
958 <listitem><simpara>There is urgent data to read.
959 </simpara></listitem>
960 </varlistentry>
961 <varlistentry id="G-IO-ERR--CAPS" role="constant">
962 <term><literal>G_IO_ERR</literal></term>
963 <listitem><simpara>Error condition.
964 </simpara></listitem>
965 </varlistentry>
966 <varlistentry id="G-IO-HUP--CAPS" role="constant">
967 <term><literal>G_IO_HUP</literal></term>
968 <listitem><simpara>Hung up (the connection has been broken, usually for pipes 
969            and sockets).
970 </simpara></listitem>
971 </varlistentry>
972 <varlistentry id="G-IO-NVAL--CAPS" role="constant">
973 <term><literal>G_IO_NVAL</literal></term>
974 <listitem><simpara>Invalid request. The file descriptor is not open.
975 </simpara></listitem>
976 </varlistentry>
977 </variablelist></refsect2>
978 <refsect2 id="GIOFunc" role="function">
979 <title>GIOFunc ()</title>
980 <indexterm zone="GIOFunc"><primary sortas="IOFunc">GIOFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GIOFunc)                          (<link linkend="GIOChannel">GIOChannel</link> *source,
981                                                          <link linkend="GIOCondition">GIOCondition</link> condition,
982                                                          <link linkend="gpointer">gpointer</link> data);</programlisting>
983 <para>
984 Specifies the type of function passed to <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or
985 <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>, which is called when the requested
986 condition on a <link linkend="GIOChannel"><type>GIOChannel</type></link> is satisfied.
987 </para><variablelist role="params">
988 <varlistentry><term><parameter>source</parameter>&#160;:</term>
989 <listitem><simpara>the <link linkend="GIOChannel"><type>GIOChannel</type></link> event source
990 </simpara></listitem></varlistentry>
991 <varlistentry><term><parameter>condition</parameter>&#160;:</term>
992 <listitem><simpara>the condition which has been satisfied
993 </simpara></listitem></varlistentry>
994 <varlistentry><term><parameter>data</parameter>&#160;:</term>
995 <listitem><simpara>user data set in <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>
996 </simpara></listitem></varlistentry>
997 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the function should return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the event source 
998   should be removed
999 </simpara></listitem></varlistentry>
1000 </variablelist></refsect2>
1001 <refsect2 id="GIOFuncs" role="struct">
1002 <title>GIOFuncs</title>
1003 <indexterm zone="GIOFuncs"><primary sortas="IOFuncs">GIOFuncs</primary></indexterm><programlisting>typedef struct {
1004   GIOStatus (*io_read)           (GIOChannel   *channel, 
1005                                   gchar        *buf, 
1006                                   gsize         count,
1007                                   gsize        *bytes_read,
1008                                   GError      **err);
1009   GIOStatus (*io_write)          (GIOChannel   *channel, 
1010                                   const gchar  *buf, 
1011                                   gsize         count,
1012                                   gsize        *bytes_written,
1013                                   GError      **err);
1014   GIOStatus (*io_seek)           (GIOChannel   *channel, 
1015                                   gint64        offset, 
1016                                   GSeekType     type,
1017                                   GError      **err);
1018   GIOStatus  (*io_close)         (GIOChannel   *channel,
1019                                   GError      **err);
1020   GSource*   (*io_create_watch)  (GIOChannel   *channel,
1021                                   GIOCondition  condition);
1022   void       (*io_free)          (GIOChannel   *channel);
1023   GIOStatus  (*io_set_flags)     (GIOChannel   *channel,
1024                                   GIOFlags      flags,
1025                                   GError      **err);
1026   GIOFlags   (*io_get_flags)     (GIOChannel   *channel);
1027 } GIOFuncs;
1028 </programlisting>
1029 <para>
1030 A table of functions used to handle different types of <link linkend="GIOChannel"><type>GIOChannel</type></link>
1031 in a generic way.
1032 </para></refsect2>
1033 <refsect2 id="g-io-channel-get-buffer-size" role="function">
1034 <title>g_io_channel_get_buffer_size ()</title>
1035 <indexterm zone="g-io-channel-get-buffer-size"><primary sortas="io_channel_get_buffer_size">g_io_channel_get_buffer_size</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_io_channel_get_buffer_size        (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1036 <para>
1037 Gets the buffer size.</para>
1038 <para>
1039 </para><variablelist role="params">
1040 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1041 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1042 </simpara></listitem></varlistentry>
1043 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the size of the buffer.
1044 </simpara></listitem></varlistentry>
1045 </variablelist></refsect2>
1046 <refsect2 id="g-io-channel-set-buffer-size" role="function">
1047 <title>g_io_channel_set_buffer_size ()</title>
1048 <indexterm zone="g-io-channel-set-buffer-size"><primary sortas="io_channel_set_buffer_size">g_io_channel_set_buffer_size</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_channel_set_buffer_size        (<link linkend="GIOChannel">GIOChannel</link> *channel,
1049                                                          <link linkend="gsize">gsize</link> size);</programlisting>
1050 <para>
1051 Sets the buffer size.</para>
1052 <para>
1053 </para><variablelist role="params">
1054 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1055 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1056 </simpara></listitem></varlistentry>
1057 <varlistentry><term><parameter>size</parameter>&#160;:</term>
1058 <listitem><simpara> the size of the buffer, or 0 to let GLib pick a good size
1059 </simpara></listitem></varlistentry>
1060 </variablelist></refsect2>
1061 <refsect2 id="g-io-channel-get-buffer-condition" role="function">
1062 <title>g_io_channel_get_buffer_condition ()</title>
1063 <indexterm zone="g-io-channel-get-buffer-condition"><primary sortas="io_channel_get_buffer_condition">g_io_channel_get_buffer_condition</primary></indexterm><programlisting><link linkend="GIOCondition">GIOCondition</link>        g_io_channel_get_buffer_condition   (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1064 <para>
1065 This function returns a <link linkend="GIOCondition"><type>GIOCondition</type></link> depending on whether there
1066 is data to be read/space to write data in the internal buffers in 
1067 the <link linkend="GIOChannel"><type>GIOChannel</type></link>. Only the flags <link linkend="G-IO-IN--CAPS"><literal>G_IO_IN</literal></link> and <link linkend="G-IO-OUT--CAPS"><literal>G_IO_OUT</literal></link> may be set.</para>
1068 <para>
1069 </para><variablelist role="params">
1070 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1071 <listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>
1072 </simpara></listitem></varlistentry>
1073 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A <link linkend="GIOCondition"><type>GIOCondition</type></link>
1074 </simpara></listitem></varlistentry>
1075 </variablelist></refsect2>
1076 <refsect2 id="g-io-channel-get-flags" role="function">
1077 <title>g_io_channel_get_flags ()</title>
1078 <indexterm zone="g-io-channel-get-flags"><primary sortas="io_channel_get_flags">g_io_channel_get_flags</primary></indexterm><programlisting><link linkend="GIOFlags">GIOFlags</link>            g_io_channel_get_flags              (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1079 <para>
1080 Gets the current flags for a <link linkend="GIOChannel"><type>GIOChannel</type></link>, including read-only
1081 flags such as <link linkend="G-IO-FLAG-IS-READABLE--CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link>.
1082 </para>
1083 <para>
1084 The values of the flags <link linkend="G-IO-FLAG-IS-READABLE--CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link> and <link linkend="G-IO-FLAG-IS-WRITEABLE--CAPS"><literal>G_IO_FLAG_IS_WRITEABLE</literal></link>
1085 are cached for internal use by the channel when it is created.
1086 If they should change at some later point (e.g. partial shutdown
1087 of a socket with the UNIX <link linkend="shutdown"><function>shutdown()</function></link> function), the user
1088 should immediately call <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link> to update
1089 the internal values of these flags.</para>
1090 <para>
1091 </para><variablelist role="params">
1092 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1093 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1094 </simpara></listitem></varlistentry>
1095 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the flags which are set on the channel
1096 </simpara></listitem></varlistentry>
1097 </variablelist></refsect2>
1098 <refsect2 id="g-io-channel-set-flags" role="function">
1099 <title>g_io_channel_set_flags ()</title>
1100 <indexterm zone="g-io-channel-set-flags"><primary sortas="io_channel_set_flags">g_io_channel_set_flags</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_set_flags              (<link linkend="GIOChannel">GIOChannel</link> *channel,
1101                                                          <link linkend="GIOFlags">GIOFlags</link> flags,
1102                                                          <link linkend="GError">GError</link> **error);</programlisting>
1103 <para>
1104 Sets the (writeable) flags in <parameter>channel</parameter> to (<parameter>flags</parameter> &amp; <link linkend="G-IO-CHANNEL-SET-MASK--CAPS"><literal>G_IO_CHANNEL_SET_MASK</literal></link>).</para>
1105 <para>
1106 </para><variablelist role="params">
1107 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1108 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1109 </simpara></listitem></varlistentry>
1110 <varlistentry><term><parameter>flags</parameter>&#160;:</term>
1111 <listitem><simpara> the flags to set on the IO channel
1112 </simpara></listitem></varlistentry>
1113 <varlistentry><term><parameter>error</parameter>&#160;:</term>
1114 <listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
1115 </simpara></listitem></varlistentry>
1116 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation. 
1117 </simpara></listitem></varlistentry>
1118 </variablelist></refsect2>
1119 <refsect2 id="GIOFlags" role="enum">
1120 <title>enum GIOFlags</title>
1121 <indexterm zone="GIOFlags"><primary sortas="IOFlags">GIOFlags</primary></indexterm><programlisting>typedef enum
1122 {
1123   G_IO_FLAG_APPEND = 1 &lt;&lt; 0,
1124   G_IO_FLAG_NONBLOCK = 1 &lt;&lt; 1,
1125   G_IO_FLAG_IS_READABLE = 1 &lt;&lt; 2, /* Read only flag */
1126   G_IO_FLAG_IS_WRITEABLE = 1 &lt;&lt; 3,        /* Read only flag */
1127   G_IO_FLAG_IS_SEEKABLE = 1 &lt;&lt; 4, /* Read only flag */
1128   G_IO_FLAG_MASK = (1 &lt;&lt; 5) - 1,
1129   G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK,
1130   G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK
1131 } GIOFlags;
1132 </programlisting>
1133 <para>
1134 Specifies properties of a <link linkend="GIOChannel"><type>GIOChannel</type></link>. Some of the flags can only
1135 be read with <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link>, but not changed with
1136 <link linkend="g-io-channel-set-flags"><function>g_io_channel_set_flags()</function></link>.
1137 </para><variablelist role="enum">
1138 <varlistentry id="G-IO-FLAG-APPEND--CAPS" role="constant">
1139 <term><literal>G_IO_FLAG_APPEND</literal></term>
1140 <listitem><simpara>turns on append mode, corresponds to <link linkend="O-APPEND--CAPS"><literal>O_APPEND</literal></link> 
1141   (see the documentation of the UNIX <link linkend="open"><function>open()</function></link> syscall).
1142 </simpara></listitem>
1143 </varlistentry>
1144 <varlistentry id="G-IO-FLAG-NONBLOCK--CAPS" role="constant">
1145 <term><literal>G_IO_FLAG_NONBLOCK</literal></term>
1146 <listitem><simpara>turns on nonblocking mode, corresponds to 
1147   <link linkend="O-NONBLOCK--CAPS"><literal>O_NONBLOCK</literal></link>/<link linkend="O-NDELAY--CAPS"><literal>O_NDELAY</literal></link> (see the documentation of the UNIX <link linkend="open"><function>open()</function></link>
1148   syscall).
1149 </simpara></listitem>
1150 </varlistentry>
1151 <varlistentry id="G-IO-FLAG-IS-READABLE--CAPS" role="constant">
1152 <term><literal>G_IO_FLAG_IS_READABLE</literal></term>
1153 <listitem><simpara>indicates that the io channel is readable. 
1154   This flag can not be changed.
1155 </simpara></listitem>
1156 </varlistentry>
1157 <varlistentry id="G-IO-FLAG-IS-WRITEABLE--CAPS" role="constant">
1158 <term><literal>G_IO_FLAG_IS_WRITEABLE</literal></term>
1159 <listitem><simpara>indicates that the io channel is writable. 
1160   This flag can not be changed.
1161 </simpara></listitem>
1162 </varlistentry>
1163 <varlistentry id="G-IO-FLAG-IS-SEEKABLE--CAPS" role="constant">
1164 <term><literal>G_IO_FLAG_IS_SEEKABLE</literal></term>
1165 <listitem><simpara>indicates that the io channel is seekable, 
1166   i.e. that <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> can be used on it.
1167   This flag can not be changed.
1168 </simpara></listitem>
1169 </varlistentry>
1170 <varlistentry id="G-IO-FLAG-MASK--CAPS" role="constant">
1171 <term><literal>G_IO_FLAG_MASK</literal></term>
1172 <listitem><simpara>
1173 </simpara></listitem>
1174 </varlistentry>
1175 <varlistentry id="G-IO-FLAG-GET-MASK--CAPS" role="constant">
1176 <term><literal>G_IO_FLAG_GET_MASK</literal></term>
1177 <listitem><simpara>
1178 </simpara></listitem>
1179 </varlistentry>
1180 <varlistentry id="G-IO-FLAG-SET-MASK--CAPS" role="constant">
1181 <term><literal>G_IO_FLAG_SET_MASK</literal></term>
1182 <listitem><simpara>
1183 </simpara></listitem>
1184 </varlistentry>
1185 </variablelist></refsect2>
1186 <refsect2 id="g-io-channel-get-line-term" role="function">
1187 <title>g_io_channel_get_line_term ()</title>
1188 <indexterm zone="g-io-channel-get-line-term"><primary sortas="io_channel_get_line_term">g_io_channel_get_line_term</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_io_channel_get_line_term          (<link linkend="GIOChannel">GIOChannel</link> *channel,
1189                                                          <link linkend="gint">gint</link> *length);</programlisting>
1190 <para>
1191 This returns the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine
1192 where in the file a line break occurs. A value of <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1193 indicates autodetection.</para>
1194 <para>
1195 </para><variablelist role="params">
1196 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1197 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1198 </simpara></listitem></varlistentry>
1199 <varlistentry><term><parameter>length</parameter>&#160;:</term>
1200 <listitem><simpara> a location to return the length of the line terminator
1201 </simpara></listitem></varlistentry>
1202 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The line termination string. This value
1203   is owned by GLib and must not be freed.
1204 </simpara></listitem></varlistentry>
1205 </variablelist></refsect2>
1206 <refsect2 id="g-io-channel-set-line-term" role="function">
1207 <title>g_io_channel_set_line_term ()</title>
1208 <indexterm zone="g-io-channel-set-line-term"><primary sortas="io_channel_set_line_term">g_io_channel_set_line_term</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_channel_set_line_term          (<link linkend="GIOChannel">GIOChannel</link> *channel,
1209                                                          const <link linkend="gchar">gchar</link> *line_term,
1210                                                          <link linkend="gint">gint</link> length);</programlisting>
1211 <para>
1212 This sets the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine
1213 where in the file a line break occurs.</para>
1214 <para>
1215 </para><variablelist role="params">
1216 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1217 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1218 </simpara></listitem></varlistentry>
1219 <varlistentry><term><parameter>line_term</parameter>&#160;:</term>
1220 <listitem><simpara> The line termination string. Use <link linkend="NULL--CAPS"><literal>NULL</literal></link> for autodetect.
1221             Autodetection breaks on "\n", "\r\n", "\r", "\0", and
1222             the Unicode paragraph separator. Autodetection should
1223             not be used for anything other than file-based channels.
1224 </simpara></listitem></varlistentry>
1225 <varlistentry><term><parameter>length</parameter>&#160;:</term>
1226 <listitem><simpara> The length of the termination string. If -1 is passed, the
1227          string is assumed to be nul-terminated. This option allows
1228          termination strings with embedded nuls.
1229 </simpara></listitem></varlistentry>
1230 </variablelist></refsect2>
1231 <refsect2 id="g-io-channel-get-buffered" role="function">
1232 <title>g_io_channel_get_buffered ()</title>
1233 <indexterm zone="g-io-channel-get-buffered"><primary sortas="io_channel_get_buffered">g_io_channel_get_buffered</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_io_channel_get_buffered           (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1234 <para>
1235 Returns whether <parameter>channel</parameter> is buffered.</para>
1236 <para>
1237 </para><variablelist role="params">
1238 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1239 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1240 </simpara></listitem></varlistentry>
1241 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <parameter>channel</parameter> is buffered. 
1242 </simpara></listitem></varlistentry>
1243 </variablelist></refsect2>
1244 <refsect2 id="g-io-channel-set-buffered" role="function">
1245 <title>g_io_channel_set_buffered ()</title>
1246 <indexterm zone="g-io-channel-set-buffered"><primary sortas="io_channel_set_buffered">g_io_channel_set_buffered</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_channel_set_buffered           (<link linkend="GIOChannel">GIOChannel</link> *channel,
1247                                                          <link linkend="gboolean">gboolean</link> buffered);</programlisting>
1248 <para>
1249 The buffering state can only be set if the channel's encoding
1250 is <link linkend="NULL--CAPS"><literal>NULL</literal></link>. For any other encoding, the channel must be buffered.
1251 </para>
1252 <para>
1253 A buffered channel can only be set unbuffered if the channel's
1254 internal buffers have been flushed. Newly created channels or
1255 channels which have returned <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>
1256 not require such a flush. For write-only channels, a call to
1257 <link linkend="g-io-channel-flush"><function>g_io_channel_flush()</function></link> is sufficient. For all other channels,
1258 the buffers may be flushed by a call to <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>.
1259 This includes the possibility of seeking with seek type <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link>
1260 and an offset of zero. Note that this means that socket-based
1261 channels cannot be set unbuffered once they have had data
1262 read from them.
1263 </para>
1264 <para>
1265 On unbuffered channels, it is safe to mix read and write
1266 calls from the new and old APIs, if this is necessary for
1267 maintaining old code.
1268 </para>
1269 <para>
1270 The default state of the channel is buffered.</para>
1271 <para>
1272 </para><variablelist role="params">
1273 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1274 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1275 </simpara></listitem></varlistentry>
1276 <varlistentry><term><parameter>buffered</parameter>&#160;:</term>
1277 <listitem><simpara> whether to set the channel buffered or unbuffered
1278 </simpara></listitem></varlistentry>
1279 </variablelist></refsect2>
1280 <refsect2 id="g-io-channel-get-encoding" role="function">
1281 <title>g_io_channel_get_encoding ()</title>
1282 <indexterm zone="g-io-channel-get-encoding"><primary sortas="io_channel_get_encoding">g_io_channel_get_encoding</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_io_channel_get_encoding           (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1283 <para>
1284 Gets the encoding for the input/output of the channel. 
1285 The internal encoding is always UTF-8. The encoding <link linkend="NULL--CAPS"><literal>NULL</literal></link> 
1286 makes the channel safe for binary data.</para>
1287 <para>
1288 </para><variablelist role="params">
1289 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1290 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1291 </simpara></listitem></varlistentry>
1292 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A string containing the encoding, this string is
1293   owned by GLib and must not be freed.
1294 </simpara></listitem></varlistentry>
1295 </variablelist></refsect2>
1296 <refsect2 id="g-io-channel-set-encoding" role="function">
1297 <title>g_io_channel_set_encoding ()</title>
1298 <indexterm zone="g-io-channel-set-encoding"><primary sortas="io_channel_set_encoding">g_io_channel_set_encoding</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link>           g_io_channel_set_encoding           (<link linkend="GIOChannel">GIOChannel</link> *channel,
1299                                                          const <link linkend="gchar">gchar</link> *encoding,
1300                                                          <link linkend="GError">GError</link> **error);</programlisting>
1301 <para>
1302 Sets the encoding for the input/output of the channel. 
1303 The internal encoding is always UTF-8. The default encoding 
1304 for the external file is UTF-8.
1305 </para>
1306 <para>
1307 The encoding <link linkend="NULL--CAPS"><literal>NULL</literal></link> is safe to use with binary data.
1308 </para>
1309 <para>
1310 The encoding can only be set if one of the following conditions
1311 is true:
1312 <itemizedlist>
1313 <listitem><para>
1314    The channel was just created, and has not been written to or read 
1315    from yet.
1316 </para></listitem>
1317 <listitem><para>
1318    The channel is write-only.
1319 </para></listitem>
1320 <listitem><para>
1321    The channel is a file, and the file pointer was just
1322    repositioned by a call to <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>.
1323    (This flushes all the internal buffers.)
1324 </para></listitem>
1325 <listitem><para>
1326    The current encoding is <link linkend="NULL--CAPS"><literal>NULL</literal></link> or UTF-8.
1327 </para></listitem>
1328 <listitem><para>
1329    One of the (new API) read functions has just returned <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>
1330    (or, in the case of <link linkend="g-io-channel-read-to-end"><function>g_io_channel_read_to_end()</function></link>, <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>).
1331 </para></listitem>
1332 <listitem><para>
1333    One of the functions <link linkend="g-io-channel-read-chars"><function>g_io_channel_read_chars()</function></link> or 
1334    <link linkend="g-io-channel-read-unichar"><function>g_io_channel_read_unichar()</function></link> has returned <link linkend="G-IO-STATUS-AGAIN--CAPS"><literal>G_IO_STATUS_AGAIN</literal></link> or 
1335    <link linkend="G-IO-STATUS-ERROR--CAPS"><literal>G_IO_STATUS_ERROR</literal></link>. This may be useful in the case of 
1336    <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE--CAPS"><literal>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</literal></link>.
1337    Returning one of these statuses from <link linkend="g-io-channel-read-line"><function>g_io_channel_read_line()</function></link>,
1338    <link linkend="g-io-channel-read-line-string"><function>g_io_channel_read_line_string()</function></link>, or <link linkend="g-io-channel-read-to-end"><function>g_io_channel_read_to_end()</function></link>
1339    does <emphasis>not</emphasis> guarantee that the encoding can 
1340    be changed.
1341 </para></listitem>
1342 </itemizedlist>
1343 Channels which do not meet one of the above conditions cannot call
1344 <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> with an offset of <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link>, and, if 
1345 they are "seekable", cannot call <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link> after 
1346 calling one of the API "read" functions.</para>
1347 <para>
1348 </para><variablelist role="params">
1349 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1350 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1351 </simpara></listitem></varlistentry>
1352 <varlistentry><term><parameter>encoding</parameter>&#160;:</term>
1353 <listitem><simpara> the encoding type
1354 </simpara></listitem></varlistentry>
1355 <varlistentry><term><parameter>error</parameter>&#160;:</term>
1356 <listitem><simpara> location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
1357 </simpara></listitem></varlistentry>
1358 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> if the encoding was successfully set.
1359 </simpara></listitem></varlistentry>
1360 </variablelist></refsect2>
1361 <refsect2 id="g-io-channel-get-close-on-unref" role="function">
1362 <title>g_io_channel_get_close_on_unref ()</title>
1363 <indexterm zone="g-io-channel-get-close-on-unref"><primary sortas="io_channel_get_close_on_unref">g_io_channel_get_close_on_unref</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_io_channel_get_close_on_unref     (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1364 <para>
1365 Returns whether the file/socket/whatever associated with <parameter>channel</parameter>
1366 will be closed when <parameter>channel</parameter> receives its final unref and is
1367 destroyed. The default value of this is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for channels created
1368 by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>, and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.</para>
1369 <para>
1370 </para><variablelist role="params">
1371 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1372 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
1373 </simpara></listitem></varlistentry>
1374 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Whether the channel will be closed on the final unref of
1375               the GIOChannel data structure.
1376 </simpara></listitem></varlistentry>
1377 </variablelist></refsect2>
1378 <refsect2 id="g-io-channel-set-close-on-unref" role="function">
1379 <title>g_io_channel_set_close_on_unref ()</title>
1380 <indexterm zone="g-io-channel-set-close-on-unref"><primary sortas="io_channel_set_close_on_unref">g_io_channel_set_close_on_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_channel_set_close_on_unref     (<link linkend="GIOChannel">GIOChannel</link> *channel,
1381                                                          <link linkend="gboolean">gboolean</link> do_close);</programlisting>
1382 <para>
1383 Setting this flag to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for a channel you have already closed
1384 can cause problems.</para>
1385 <para>
1386 </para><variablelist role="params">
1387 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1388 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1389 </simpara></listitem></varlistentry>
1390 <varlistentry><term><parameter>do_close</parameter>&#160;:</term>
1391 <listitem><simpara> Whether to close the channel on the final unref of
1392            the GIOChannel data structure. The default value of
1393            this is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for channels created by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>,
1394            and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.
1395 </simpara></listitem></varlistentry>
1396 </variablelist></refsect2>
1397 <refsect2 id="g-io-channel-read" role="function" condition="deprecated:2.2: Use g_io_channel_read_chars() instead.">
1398 <title>g_io_channel_read ()</title>
1399 <indexterm zone="g-io-channel-read" role="deprecated"><primary sortas="io_channel_read">g_io_channel_read</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link>            g_io_channel_read                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
1400                                                          <link linkend="gchar">gchar</link> *buf,
1401                                                          <link linkend="gsize">gsize</link> count,
1402                                                          <link linkend="gsize">gsize</link> *bytes_read);</programlisting>
1403 <warning><para><literal>g_io_channel_read</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-read-chars"><function>g_io_channel_read_chars()</function></link> instead.</para></warning>
1404 <para>
1405 Reads data from a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
1406 <para>
1407 </para><variablelist role="params">
1408 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1409 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1410 </simpara></listitem></varlistentry>
1411 <varlistentry><term><parameter>buf</parameter>&#160;:</term>
1412 <listitem><simpara> a buffer to read the data into (which should be at least 
1413       count bytes long)
1414 </simpara></listitem></varlistentry>
1415 <varlistentry><term><parameter>count</parameter>&#160;:</term>
1416 <listitem><simpara> the number of bytes to read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>
1417 </simpara></listitem></varlistentry>
1418 <varlistentry><term><parameter>bytes_read</parameter>&#160;:</term>
1419 <listitem><simpara> returns the number of bytes actually read
1420 </simpara></listitem></varlistentry>
1421 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful. 
1422
1423 </simpara></listitem></varlistentry>
1424 </variablelist></refsect2>
1425 <refsect2 id="GIOError" role="enum">
1426 <title>enum GIOError</title>
1427 <indexterm zone="GIOError"><primary sortas="IOError">GIOError</primary></indexterm><programlisting>typedef enum
1428 {
1429   G_IO_ERROR_NONE,
1430   G_IO_ERROR_AGAIN,
1431   G_IO_ERROR_INVAL,
1432   G_IO_ERROR_UNKNOWN
1433 } GIOError;
1434 </programlisting>
1435 <para>
1436 <link linkend="GIOError"><type>GIOError</type></link> is only used by the deprecated functions <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link>,
1437 <link linkend="g-io-channel-write"><function>g_io_channel_write()</function></link>, and <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link>.
1438 </para><variablelist role="enum">
1439 <varlistentry id="G-IO-ERROR-NONE--CAPS" role="constant">
1440 <term><literal>G_IO_ERROR_NONE</literal></term>
1441 <listitem><simpara>no error
1442 </simpara></listitem>
1443 </varlistentry>
1444 <varlistentry id="G-IO-ERROR-AGAIN--CAPS" role="constant">
1445 <term><literal>G_IO_ERROR_AGAIN</literal></term>
1446 <listitem><simpara>an EAGAIN error occurred
1447 </simpara></listitem>
1448 </varlistentry>
1449 <varlistentry id="G-IO-ERROR-INVAL--CAPS" role="constant">
1450 <term><literal>G_IO_ERROR_INVAL</literal></term>
1451 <listitem><simpara>an EINVAL error occurred
1452 </simpara></listitem>
1453 </varlistentry>
1454 <varlistentry id="G-IO-ERROR-UNKNOWN--CAPS" role="constant">
1455 <term><literal>G_IO_ERROR_UNKNOWN</literal></term>
1456 <listitem><simpara>another error occurred
1457 </simpara></listitem>
1458 </varlistentry>
1459 </variablelist></refsect2>
1460 <refsect2 id="g-io-channel-write" role="function" condition="deprecated:2.2: Use g_io_channel_write_chars() instead.">
1461 <title>g_io_channel_write ()</title>
1462 <indexterm zone="g-io-channel-write" role="deprecated"><primary sortas="io_channel_write">g_io_channel_write</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link>            g_io_channel_write                  (<link linkend="GIOChannel">GIOChannel</link> *channel,
1463                                                          const <link linkend="gchar">gchar</link> *buf,
1464                                                          <link linkend="gsize">gsize</link> count,
1465                                                          <link linkend="gsize">gsize</link> *bytes_written);</programlisting>
1466 <warning><para><literal>g_io_channel_write</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link> instead.</para></warning>
1467 <para>
1468 Writes data to a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
1469 <para>
1470 </para><variablelist role="params">
1471 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1472 <listitem><simpara>  a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1473 </simpara></listitem></varlistentry>
1474 <varlistentry><term><parameter>buf</parameter>&#160;:</term>
1475 <listitem><simpara> the buffer containing the data to write
1476 </simpara></listitem></varlistentry>
1477 <varlistentry><term><parameter>count</parameter>&#160;:</term>
1478 <listitem><simpara> the number of bytes to write
1479 </simpara></listitem></varlistentry>
1480 <varlistentry><term><parameter>bytes_written</parameter>&#160;:</term>
1481 <listitem><simpara> the number of bytes actually written
1482 </simpara></listitem></varlistentry>
1483 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>  <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1484
1485 </simpara></listitem></varlistentry>
1486 </variablelist></refsect2>
1487 <refsect2 id="g-io-channel-seek" role="function" condition="deprecated:2.2: Use g_io_channel_seek_position() instead.">
1488 <title>g_io_channel_seek ()</title>
1489 <indexterm zone="g-io-channel-seek" role="deprecated"><primary sortas="io_channel_seek">g_io_channel_seek</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link>            g_io_channel_seek                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
1490                                                          <link linkend="gint64">gint64</link> offset,
1491                                                          <link linkend="GSeekType">GSeekType</link> type);</programlisting>
1492 <warning><para><literal>g_io_channel_seek</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> instead.</para></warning>
1493 <para>
1494 Sets the current position in the <link linkend="GIOChannel"><type>GIOChannel</type></link>, similar to the standard 
1495 library function <link linkend="fseek"><function>fseek()</function></link>.</para>
1496 <para>
1497 </para><variablelist role="params">
1498 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1499 <listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1500 </simpara></listitem></varlistentry>
1501 <varlistentry><term><parameter>offset</parameter>&#160;:</term>
1502 <listitem><simpara> an offset, in bytes, which is added to the position specified 
1503          by <parameter>type</parameter>
1504 </simpara></listitem></varlistentry>
1505 <varlistentry><term><parameter>type</parameter>&#160;:</term>
1506 <listitem><simpara> the position in the file, which can be <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link> (the current
1507        position), <link linkend="G-SEEK-SET--CAPS"><literal>G_SEEK_SET</literal></link> (the start of the file), or <link linkend="G-SEEK-END--CAPS"><literal>G_SEEK_END</literal></link> 
1508        (the end of the file)
1509 </simpara></listitem></varlistentry>
1510 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1511
1512 </simpara></listitem></varlistentry>
1513 </variablelist></refsect2>
1514 <refsect2 id="g-io-channel-close" role="function" condition="deprecated:2.2: Use g_io_channel_shutdown() instead.">
1515 <title>g_io_channel_close ()</title>
1516 <indexterm zone="g-io-channel-close" role="deprecated"><primary sortas="io_channel_close">g_io_channel_close</primary></indexterm><programlisting><link linkend="void">void</link>                g_io_channel_close                  (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1517 <warning><para><literal>g_io_channel_close</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-shutdown"><function>g_io_channel_shutdown()</function></link> instead.</para></warning>
1518 <para>
1519 Close an IO channel. Any pending data to be written will be
1520 flushed, ignoring errors. The channel will not be freed until the
1521 last reference is dropped using <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link>.</para>
1522 <para>
1523 </para><variablelist role="params">
1524 <varlistentry><term><parameter>channel</parameter>&#160;:</term>
1525 <listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>
1526 </simpara></listitem></varlistentry>
1527 </variablelist></refsect2>
1528
1529 </refsect1>
1530
1531
1532
1533 <refsect1 id="glib-IO-Channels.see-also">
1534 <title>See Also</title>
1535 <para>
1536 <variablelist>
1537 <varlistentry>
1538 <term><link linkend="gtk-input-add-full"><function>gtk_input_add_full()</function></link>, <link linkend="gtk-input-remove"><function>gtk_input_remove()</function></link>, <link linkend="gdk-input-add"><function>gdk_input_add()</function></link>,
1539 <link linkend="gdk-input-add-full"><function>gdk_input_add_full()</function></link>, <link linkend="gdk-input-remove"><function>gdk_input_remove()</function></link></term>
1540 <listitem><para>
1541 Convenience functions for creating <link linkend="GIOChannel"><type>GIOChannel</type></link> instances and adding them to the
1542 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
1543 </para></listitem>
1544 </varlistentry>
1545 </variablelist>
1546 </para>
1547 </refsect1>
1548
1549 </refentry>