<refentry id="glib-IO-Channels">
<refmeta>
<refentrytitle role="top_of_page" id="glib-IO-Channels.top_of_page">IO Channels</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>IO Channels</refname>
<refpurpose>portable support for using files, pipes and sockets</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-IO-Channels.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <link linkend="GIOChannel">GIOChannel</link>;

<link linkend="GIOChannel">GIOChannel</link>*         <link linkend="g-io-channel-unix-new">g_io_channel_unix_new</link>               (<link linkend="int">int</link> fd);
<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);
<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);
<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);
<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);

<link linkend="void">void</link>                <link linkend="g-io-channel-init">g_io_channel_init</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel);

<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,
                                                         const <link linkend="gchar">gchar</link> *mode,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-chars">g_io_channel_read_chars</link>             (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gsize">gsize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_read,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-unichar">g_io_channel_read_unichar</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gunichar">gunichar</link> *thechar,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-read-line">g_io_channel_read_line</link>              (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gchar">gchar</link> **str_return,
                                                         <link linkend="gsize">gsize</link> *length,
                                                         <link linkend="gsize">gsize</link> *terminator_pos,
                                                         <link linkend="GError">GError</link> **error);
<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,
                                                         <link linkend="GString">GString</link> *buffer,
                                                         <link linkend="gsize">gsize</link> *terminator_pos,
                                                         <link linkend="GError">GError</link> **error);
<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,
                                                         <link linkend="gchar">gchar</link> **str_return,
                                                         <link linkend="gsize">gsize</link> *length,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-write-chars">g_io_channel_write_chars</link>            (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gssize">gssize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_written,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-write-unichar">g_io_channel_write_unichar</link>          (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gunichar">gunichar</link> thechar,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-flush">g_io_channel_flush</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-seek-position">g_io_channel_seek_position</link>          (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gint64">gint64</link> offset,
                                                         <link linkend="GSeekType">GSeekType</link> type,
                                                         <link linkend="GError">GError</link> **error);
enum                <link linkend="GSeekType">GSeekType</link>;
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-shutdown">g_io_channel_shutdown</link>               (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gboolean">gboolean</link> flush,
                                                         <link linkend="GError">GError</link> **err);

enum                <link linkend="GIOStatus">GIOStatus</link>;
enum                <link linkend="GIOChannelError">GIOChannelError</link>;
#define             <link linkend="G-IO-CHANNEL-ERROR--CAPS">G_IO_CHANNEL_ERROR</link>
<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);

<link linkend="GIOChannel">GIOChannel</link> *        <link linkend="g-io-channel-ref">g_io_channel_ref</link>                    (<link linkend="GIOChannel">GIOChannel</link> *channel);
<link linkend="void">void</link>                <link linkend="g-io-channel-unref">g_io_channel_unref</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel);

<link linkend="GSource">GSource</link> *           <link linkend="g-io-create-watch">g_io_create_watch</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition);
<link linkend="guint">guint</link>               <link linkend="g-io-add-watch">g_io_add_watch</link>                      (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition,
                                                         <link linkend="GIOFunc">GIOFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="guint">guint</link>               <link linkend="g-io-add-watch-full">g_io_add_watch_full</link>                 (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gint">gint</link> priority,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition,
                                                         <link linkend="GIOFunc">GIOFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
enum                <link linkend="GIOCondition">GIOCondition</link>;
<link linkend="gboolean">gboolean</link>            (<link linkend="GIOFunc">*GIOFunc</link>)                          (<link linkend="GIOChannel">GIOChannel</link> *source,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition,
                                                         <link linkend="gpointer">gpointer</link> data);

                    <link linkend="GIOFuncs">GIOFuncs</link>;

<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);
<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,
                                                         <link linkend="gsize">gsize</link> size);
<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);
<link linkend="GIOFlags">GIOFlags</link>            <link linkend="g-io-channel-get-flags">g_io_channel_get_flags</link>              (<link linkend="GIOChannel">GIOChannel</link> *channel);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-set-flags">g_io_channel_set_flags</link>              (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="GIOFlags">GIOFlags</link> flags,
                                                         <link linkend="GError">GError</link> **error);
enum                <link linkend="GIOFlags">GIOFlags</link>;
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,
                                                         <link linkend="gint">gint</link> *length);
<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,
                                                         const <link linkend="gchar">gchar</link> *line_term,
                                                         <link linkend="gint">gint</link> length);
<link linkend="gboolean">gboolean</link>            <link linkend="g-io-channel-get-buffered">g_io_channel_get_buffered</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel);
<link linkend="void">void</link>                <link linkend="g-io-channel-set-buffered">g_io_channel_set_buffered</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gboolean">gboolean</link> buffered);
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);
<link linkend="GIOStatus">GIOStatus</link>           <link linkend="g-io-channel-set-encoding">g_io_channel_set_encoding</link>           (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *encoding,
                                                         <link linkend="GError">GError</link> **error);
<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);
<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,
                                                         <link linkend="gboolean">gboolean</link> do_close);


<link linkend="GIOError">GIOError</link>            <link linkend="g-io-channel-read">g_io_channel_read</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gsize">gsize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_read);
enum                <link linkend="GIOError">GIOError</link>;
<link linkend="GIOError">GIOError</link>            <link linkend="g-io-channel-write">g_io_channel_write</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         const <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gsize">gsize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_written);
<link linkend="GIOError">GIOError</link>            <link linkend="g-io-channel-seek">g_io_channel_seek</link>                   (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                                         <link linkend="gint64">gint64</link> offset,
                                                         <link linkend="GSeekType">GSeekType</link> type);
<link linkend="void">void</link>                <link linkend="g-io-channel-close">g_io_channel_close</link>                  (<link linkend="GIOChannel">GIOChannel</link> *channel);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-IO-Channels.description" role="desc">
<title role="desc.title">Description</title>
<para>
The <link linkend="GIOChannel"><type>GIOChannel</type></link> data type aims to provide a portable method for using file
descriptors, pipes, and sockets, and integrating them into the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
Currently full support is available on UNIX platforms, support for
Windows is only partially complete.
</para>
<para>
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>.
This works for plain file descriptors, pipes and sockets.
Alternatively, a channel can be created for a file in a system independent
manner using <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>.
</para>
<para>
Once a <link linkend="GIOChannel"><type>GIOChannel</type></link> has been created, it can be used in a generic manner
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>,
<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>.
</para>
<para>
To add a <link linkend="GIOChannel"><type>GIOChannel</type></link> to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
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
you are interested in on the <link linkend="GIOChannel"><type>GIOChannel</type></link>, and provide a function to be
called whenever these events occur.
</para>
<para>
<link linkend="GIOChannel"><type>GIOChannel</type></link> instances are created with an initial reference count of 1.
<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
decrement the reference count respectively. When the reference count falls
to 0, the <link linkend="GIOChannel"><type>GIOChannel</type></link> is freed. (Though it isn't closed automatically,
unless it was created using <link linkend="g-io-channel-new-from-file"><function>g_io_channel_new_from_file()</function></link>.)
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
reference count.
</para>
<para>
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>,
<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>,
<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>,
and <link linkend="g-io-channel-flush"><function>g_io_channel_flush()</function></link> should not be mixed with the
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>,
and <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link> on the same channel.
</para>
</refsect1>

<refsect1 id="glib-IO-Channels.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GIOChannel" role="struct">
<title>GIOChannel</title>
<indexterm zone="GIOChannel"><primary sortas="IOChannel">GIOChannel</primary></indexterm><programlisting>typedef struct {
} GIOChannel;
</programlisting>
<para>
A data structure representing an IO Channel. The fields should be considered
private and should only be accessed with the following functions.
</para></refsect2>
<refsect2 id="g-io-channel-unix-new" role="function">
<title>g_io_channel_unix_new ()</title>
<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>
<para>
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor.
On UNIX systems this works for plain files, pipes, and sockets.
</para>
<para>
The returned <link linkend="GIOChannel"><type>GIOChannel</type></link> has a reference count of 1.
</para>
<para>
The default encoding for <link linkend="GIOChannel"><type>GIOChannel</type></link> is UTF-8. If your application
is reading output from a command using via pipe, you may need to
set the encoding to the encoding of the current locale (see
<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.
</para>
<para>
If you want to read raw binary data without interpretation, then
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
encoding argument.
</para>
<para>
This function is available in GLib on Windows, too, but you should
avoid using it on Windows. The domain of file descriptors and sockets
overlap. There is no way for GLib to know which one you mean in case
the argument you pass to this function happens to be both a valid file
descriptor and socket. If that happens a warning is issued, and GLib
assumes that it is the file descriptor you mean.
</para><variablelist role="params">
<varlistentry><term><parameter>fd</parameter>&#160;:</term>
<listitem><simpara>a file descriptor.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-unix-get-fd" role="function">
<title>g_io_channel_unix_get_fd ()</title>
<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>
<para>
Returns the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</para>
<para>
On Windows this function returns the file descriptor or socket of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<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>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-win32-new-fd" role="function">
<title>g_io_channel_win32_new_fd ()</title>
<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>
<para>
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor on Windows.
This works for file descriptors from the C runtime.
</para>
<para>
This function works for file descriptors as returned by the <link linkend="open"><function>open()</function></link>,
<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
order to meaningfully use this function your code should use the same
C runtime as GLib uses, which is msvcrt.dll. Note that in current
Microsoft compilers it is near impossible to convince it to build code
that would use msvcrt.dll. The last Microsoft compiler version that
supported using msvcrt.dll as the C runtime was version 6. The GNU
compiler and toolchain for Windows, also known as Mingw, fully
supports msvcrt.dll.
</para>
<para>
If you have created a <link linkend="GIOChannel"><type>GIOChannel</type></link> for a file descriptor and started
watching (polling) it, you shouldn't call <link linkend="read"><function>read()</function></link> on the file
descriptor. This is because adding polling for a file descriptor is
implemented in GLib on Windows by starting a thread that sits blocked
in a <link linkend="read"><function>read()</function></link> from the file descriptor most of the time. All reads from
the file descriptor should be done by this internal GLib thread. Your
code should call only <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link>.
</para>
<para>
This function is available only in GLib on Windows.
</para><variablelist role="params">
<varlistentry><term><parameter>fd</parameter>&#160;:</term>
<listitem><simpara>a C library file descriptor.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-win32-new-socket" role="function">
<title>g_io_channel_win32_new_socket ()</title>
<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>
<para>
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a socket on Windows.
</para>
<para>
This function works for sockets created by Winsock.
It's available only in GLib on Windows.
</para>
<para>
Polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket
puts the socket in non-blocking mode. This is a side-effect
of the implementation and unavoidable.
</para><variablelist role="params">
<varlistentry><term><parameter>socket</parameter>&#160;:</term>
<listitem><simpara>a Winsock socket
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-win32-new-messages" role="function">
<title>g_io_channel_win32_new_messages ()</title>
<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>
<para>
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a window handle on Windows.
</para>
<para>
This function creates a <link linkend="GIOChannel"><type>GIOChannel</type></link> that can be used to poll for
Windows messages for the window in question.
</para><variablelist role="params">
<varlistentry><term><parameter>hwnd</parameter>&#160;:</term>
<listitem><simpara>a window handle.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-init" role="function">
<title>g_io_channel_init ()</title>
<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>
<para>
Initializes a <link linkend="GIOChannel"><type>GIOChannel</type></link> struct. 
</para>
<para>
This is called by each of the above functions when creating a 
<link linkend="GIOChannel"><type>GIOChannel</type></link>, and so is not often needed by the application 
programmer (unless you are creating a new type of <link linkend="GIOChannel"><type>GIOChannel</type></link>).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-new-file" role="function">
<title>g_io_channel_new_file ()</title>
<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,
                                                         const <link linkend="gchar">gchar</link> *mode,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Open a file <parameter>filename</parameter> as a <link linkend="GIOChannel"><type>GIOChannel</type></link> using mode <parameter>mode</parameter>. This
channel will be closed when the last reference to it is dropped,
so there is no need to call <link linkend="g-io-channel-close"><function>g_io_channel_close()</function></link> (though doing
so will not cause problems, as long as no attempt is made to
access the channel after it is closed).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&#160;:</term>
<listitem><simpara> A string containing the name of a file
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter>&#160;:</term>
<listitem><simpara> One of "r", "w", "a", "r+", "w+", "a+". These have
       the same meaning as in <link linkend="fopen"><function>fopen()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> A location to return an error of type <link linkend="G-FILE-ERROR--CAPS"><literal>G_FILE_ERROR</literal></link>
</simpara></listitem></varlistentry>
<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.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-read-chars" role="function">
<title>g_io_channel_read_chars ()</title>
<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,
                                                         <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gsize">gsize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_read,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Replacement for <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link> with the new API.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&#160;:</term>
<listitem><simpara> a buffer to read data into
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter>&#160;:</term>
<listitem><simpara> the size of the buffer. Note that the buffer may
        not be complelely filled even if there is data
        in the buffer if the remaining data is not a
        complete character.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_read</parameter>&#160;:</term>
<listitem><simpara> The number of bytes read. This may be zero even on
             success if count &lt; 6 and the channel's encoding is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>.
             This indicates that the next UTF-8 character is too wide for
             the buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
        or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-read-unichar" role="function">
<title>g_io_channel_read_unichar ()</title>
<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,
                                                         <link linkend="gunichar">gunichar</link> *thechar,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Reads a Unicode character from <parameter>channel</parameter>.
This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>thechar</parameter>&#160;:</term>
<listitem><simpara> a location to return a character
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
        or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-read-line" role="function">
<title>g_io_channel_read_line ()</title>
<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,
                                                         <link linkend="gchar">gchar</link> **str_return,
                                                         <link linkend="gsize">gsize</link> *length,
                                                         <link linkend="gsize">gsize</link> *terminator_pos,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Reads a line, including the terminating character(s),
from a <link linkend="GIOChannel"><type>GIOChannel</type></link> into a newly-allocated string.
<parameter>str_return</parameter> will contain allocated memory if the return
is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_return</parameter>&#160;:</term>
<listitem><simpara> The line read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>, including the
             line terminator. This data should be freed with <link linkend="g-free"><function>g_free()</function></link>
             when no longer needed. This is a nul-terminated string. 
             If a <parameter>length</parameter> of zero is returned, this will be <link linkend="NULL--CAPS"><literal>NULL</literal></link> instead.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara> location to store length of the read data, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>terminator_pos</parameter>&#160;:</term>
<listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> A location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
        or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-read-line-string" role="function">
<title>g_io_channel_read_line_string ()</title>
<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,
                                                         <link linkend="GString">GString</link> *buffer,
                                                         <link linkend="gsize">gsize</link> *terminator_pos,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GString"><type>GString</type></link> into which the line will be written.
         If <parameter>buffer</parameter> already contains data, the old data will
         be overwritten.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>terminator_pos</parameter>&#160;:</term>
<listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
        or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-read-to-end" role="function">
<title>g_io_channel_read_to_end ()</title>
<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,
                                                         <link linkend="gchar">gchar</link> **str_return,
                                                         <link linkend="gsize">gsize</link> *length,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Reads all the remaining data from the file.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_return</parameter>&#160;:</term>
<listitem><simpara> Location to store a pointer to a string holding
             the remaining data in the <link linkend="GIOChannel"><type>GIOChannel</type></link>. This data should
             be freed with <link linkend="g-free"><function>g_free()</function></link> when no longer needed. This
             data is terminated by an extra nul character, but there 
             may be other nuls in the intervening data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara> location to store length of the data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
        or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<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. 
    This function never returns <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-write-chars" role="function">
<title>g_io_channel_write_chars ()</title>
<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,
                                                         const <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gssize">gssize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_written,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Replacement for <link linkend="g-io-channel-write"><function>g_io_channel_write()</function></link> with the new API.
</para>
<para>
On seekable channels with encodings other than <link linkend="NULL--CAPS"><literal>NULL</literal></link> or UTF-8, generic
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>
may only be made on a channel from which data has been read in the
cases described in the documentation for <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&#160;:</term>
<listitem><simpara> a buffer to write data from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter>&#160;:</term>
<listitem><simpara> the size of the buffer. If -1, the buffer
        is taken to be a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_written</parameter>&#160;:</term>
<listitem><simpara> The number of bytes written. This can be nonzero
                even if the return value is not <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.
                If the return value is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> and the
                channel is blocking, this will always be equal
                to <parameter>count</parameter> if <parameter>count</parameter> &gt;= 0.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
        or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-write-unichar" role="function">
<title>g_io_channel_write_unichar ()</title>
<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,
                                                         <link linkend="gunichar">gunichar</link> thechar,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Writes a Unicode character to <parameter>channel</parameter>.
This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>thechar</parameter>&#160;:</term>
<listitem><simpara> a character
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
        or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-flush" role="function">
<title>g_io_channel_flush ()</title>
<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,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Flushes the write buffer for the GIOChannel.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> location to store an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation: One of
  <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
  <link linkend="G-IO-STATUS-ERROR--CAPS"><type>G_IO_STATUS_ERROR</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-seek-position" role="function">
<title>g_io_channel_seek_position ()</title>
<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,
                                                         <link linkend="gint64">gint64</link> offset,
                                                         <link linkend="GSeekType">GSeekType</link> type,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Replacement for <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link> with the new API.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&#160;:</term>
<listitem><simpara> The offset in bytes from the position specified by <parameter>type</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<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
                     cases where a call to <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>
                     is allowed. See the documentation for
                     <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link> for details.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GSeekType" role="enum">
<title>enum GSeekType</title>
<indexterm zone="GSeekType"><primary sortas="SeekType">GSeekType</primary></indexterm><programlisting>typedef enum
{
  G_SEEK_CUR,
  G_SEEK_SET,
  G_SEEK_END
} GSeekType;
</programlisting>
<para>
An enumeration specifying the base position for a <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>
operation.
</para><variablelist role="enum">
<varlistentry id="G-SEEK-CUR--CAPS" role="constant">
<term><literal>G_SEEK_CUR</literal></term>
<listitem><simpara>the current position in the file.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-SEEK-SET--CAPS" role="constant">
<term><literal>G_SEEK_SET</literal></term>
<listitem><simpara>the start of the file.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-SEEK-END--CAPS" role="constant">
<term><literal>G_SEEK_END</literal></term>
<listitem><simpara>the end of the file.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-shutdown" role="function">
<title>g_io_channel_shutdown ()</title>
<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,
                                                         <link linkend="gboolean">gboolean</link> flush,
                                                         <link linkend="GError">GError</link> **err);</programlisting>
<para>
Close an IO channel. Any pending data to be written will be
flushed if <parameter>flush</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. The channel will not be freed until the
last reference is dropped using <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flush</parameter>&#160;:</term>
<listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, flush pending
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&#160;:</term>
<listitem><simpara> location to store a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GIOStatus" role="enum">
<title>enum GIOStatus</title>
<indexterm zone="GIOStatus"><primary sortas="IOStatus">GIOStatus</primary></indexterm><programlisting>typedef enum
{
  G_IO_STATUS_ERROR,
  G_IO_STATUS_NORMAL,
  G_IO_STATUS_EOF,
  G_IO_STATUS_AGAIN
} GIOStatus;
</programlisting>
<para>
Stati returned by most of the <link linkend="GIOFuncs"><type>GIOFuncs</type></link> functions.
</para><variablelist role="enum">
<varlistentry id="G-IO-STATUS-ERROR--CAPS" role="constant">
<term><literal>G_IO_STATUS_ERROR</literal></term>
<listitem><simpara>An error occurred.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-STATUS-NORMAL--CAPS" role="constant">
<term><literal>G_IO_STATUS_NORMAL</literal></term>
<listitem><simpara>Success.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-STATUS-EOF--CAPS" role="constant">
<term><literal>G_IO_STATUS_EOF</literal></term>
<listitem><simpara>End of file.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-STATUS-AGAIN--CAPS" role="constant">
<term><literal>G_IO_STATUS_AGAIN</literal></term>
<listitem><simpara>Resource temporarily unavailable.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="GIOChannelError" role="enum">
<title>enum GIOChannelError</title>
<indexterm zone="GIOChannelError"><primary sortas="IOChannelError">GIOChannelError</primary></indexterm><programlisting>typedef enum
{
  /* Derived from errno */
  G_IO_CHANNEL_ERROR_FBIG,
  G_IO_CHANNEL_ERROR_INVAL,
  G_IO_CHANNEL_ERROR_IO,
  G_IO_CHANNEL_ERROR_ISDIR,
  G_IO_CHANNEL_ERROR_NOSPC,
  G_IO_CHANNEL_ERROR_NXIO,
  G_IO_CHANNEL_ERROR_OVERFLOW,
  G_IO_CHANNEL_ERROR_PIPE,
  /* Other */
  G_IO_CHANNEL_ERROR_FAILED
} GIOChannelError;
</programlisting>
<para>
Error codes returned by <link linkend="GIOChannel"><type>GIOChannel</type></link> operations.
</para><variablelist role="enum">
<varlistentry id="G-IO-CHANNEL-ERROR-FBIG--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_FBIG</literal></term>
<listitem><simpara>File too large.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-INVAL--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_INVAL</literal></term>
<listitem><simpara>Invalid argument.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-IO--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_IO</literal></term>
<listitem><simpara>IO error.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-ISDIR--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_ISDIR</literal></term>
<listitem><simpara>File is a directory.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-NOSPC--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_NOSPC</literal></term>
<listitem><simpara>No space left on device.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-NXIO--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_NXIO</literal></term>
<listitem><simpara>No such device or address.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-OVERFLOW--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_OVERFLOW</literal></term>
<listitem><simpara>Value too large for defined datatype.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-PIPE--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_PIPE</literal></term>
<listitem><simpara>Broken pipe.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-CHANNEL-ERROR-FAILED--CAPS" role="constant">
<term><literal>G_IO_CHANNEL_ERROR_FAILED</literal></term>
<listitem><simpara>Some other error.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="G-IO-CHANNEL-ERROR--CAPS" role="macro">
<title>G_IO_CHANNEL_ERROR</title>
<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()
</programlisting>
<para>
Error domain for <link linkend="GIOChannel"><type>GIOChannel</type></link> operations. Errors in this domain will
be from the <link linkend="GIOChannelError"><type>GIOChannelError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
error domains.
</para></refsect2>
<refsect2 id="g-io-channel-error-from-errno" role="function">
<title>g_io_channel_error_from_errno ()</title>
<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>
<para>
Converts an <literal>errno</literal> error number to a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>en</parameter>&#160;:</term>
<listitem><simpara> an <literal>errno</literal> error number, e.g. <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GIOChannelError"><type>GIOChannelError</type></link> error number, e.g. 
     <link linkend="G-IO-CHANNEL-ERROR-INVAL--CAPS"><literal>G_IO_CHANNEL_ERROR_INVAL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-ref" role="function">
<title>g_io_channel_ref ()</title>
<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>
<para>
Increments the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <parameter>channel</parameter> that was passed in (since 2.6)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-unref" role="function">
<title>g_io_channel_unref ()</title>
<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>
<para>
Decrements the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-create-watch" role="function">
<title>g_io_create_watch ()</title>
<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,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition);</programlisting>
<para>
Creates a <link linkend="GSource"><type>GSource</type></link> that's dispatched when <parameter>condition</parameter> is met for the 
given <parameter>channel</parameter>. For example, if condition is <link linkend="G-IO-IN--CAPS"><type>G_IO_IN</type></link>, the source will 
be dispatched when there's data available for reading.
</para>
<para>
<link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> is a simpler interface to this same functionality, for 
the case where you want to add the source to the default main loop context 
at the default priority.
</para>
<para>
On Windows, polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket
puts the socket in non-blocking mode. This is a side-effect of the
implementation and unavoidable.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link> to watch
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&#160;:</term>
<listitem><simpara> conditions to watch for
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GSource"><type>GSource</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-add-watch" role="function">
<title>g_io_add_watch ()</title>
<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,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition,
                                                         <link linkend="GIOFunc">GIOFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Adds the <link linkend="GIOChannel"><type>GIOChannel</type></link> into the default main loop context
with the default priority.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&#160;:</term>
<listitem><simpara> the condition to watch for
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call when the condition is satisfied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data to pass to <parameter>func</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the event source id
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-add-watch-full" role="function">
<title>g_io_add_watch_full ()</title>
<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,
                                                         <link linkend="gint">gint</link> priority,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition,
                                                         <link linkend="GIOFunc">GIOFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
<para>
Adds the <link linkend="GIOChannel"><type>GIOChannel</type></link> into the default main loop context
with the given priority.
</para>
<para>
This internally creates a main loop source using <link linkend="g-io-create-watch"><function>g_io_create_watch()</function></link>
and attaches it to the main loop context with <link linkend="g-source-attach"><function>g_source_attach()</function></link>.
You can do these steps manuallt if you need greater control.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter>&#160;:</term>
<listitem><simpara> the priority of the <link linkend="GIOChannel"><type>GIOChannel</type></link> source
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&#160;:</term>
<listitem><simpara> the condition to watch for
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call when the condition is satisfied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data to pass to <parameter>func</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
<listitem><simpara> the function to call when the source is removed
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the event source id
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GIOCondition" role="enum">
<title>enum GIOCondition</title>
<indexterm zone="GIOCondition"><primary sortas="IOCondition">GIOCondition</primary></indexterm><programlisting>typedef enum
{
  G_IO_IN	GLIB_SYSDEF_POLLIN,
  G_IO_OUT	GLIB_SYSDEF_POLLOUT,
  G_IO_PRI	GLIB_SYSDEF_POLLPRI,
  G_IO_ERR	GLIB_SYSDEF_POLLERR,
  G_IO_HUP	GLIB_SYSDEF_POLLHUP,
  G_IO_NVAL	GLIB_SYSDEF_POLLNVAL
} GIOCondition;
</programlisting>
<para>
A bitwise combination representing a condition to watch for on
an event source.
</para><variablelist role="enum">
<varlistentry id="G-IO-IN--CAPS" role="constant">
<term><literal>G_IO_IN</literal></term>
<listitem><simpara>There is data to read.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-OUT--CAPS" role="constant">
<term><literal>G_IO_OUT</literal></term>
<listitem><simpara>Data can be written (without blocking).
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-PRI--CAPS" role="constant">
<term><literal>G_IO_PRI</literal></term>
<listitem><simpara>There is urgent data to read.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-ERR--CAPS" role="constant">
<term><literal>G_IO_ERR</literal></term>
<listitem><simpara>Error condition.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-HUP--CAPS" role="constant">
<term><literal>G_IO_HUP</literal></term>
<listitem><simpara>Hung up (the connection has been broken, usually for pipes 
           and sockets).
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-NVAL--CAPS" role="constant">
<term><literal>G_IO_NVAL</literal></term>
<listitem><simpara>Invalid request. The file descriptor is not open.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="GIOFunc" role="function">
<title>GIOFunc ()</title>
<indexterm zone="GIOFunc"><primary sortas="IOFunc">GIOFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GIOFunc)                          (<link linkend="GIOChannel">GIOChannel</link> *source,
                                                         <link linkend="GIOCondition">GIOCondition</link> condition,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <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>, which is called when the requested
condition on a <link linkend="GIOChannel"><type>GIOChannel</type></link> is satisfied.
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="GIOChannel"><type>GIOChannel</type></link> event source
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&#160;:</term>
<listitem><simpara>the condition which has been satisfied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<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>
</simpara></listitem></varlistentry>
<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 
  should be removed
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GIOFuncs" role="struct">
<title>GIOFuncs</title>
<indexterm zone="GIOFuncs"><primary sortas="IOFuncs">GIOFuncs</primary></indexterm><programlisting>typedef struct {
  GIOStatus (*io_read)           (GIOChannel   *channel, 
			          gchar        *buf, 
				  gsize         count,
				  gsize        *bytes_read,
				  GError      **err);
  GIOStatus (*io_write)          (GIOChannel   *channel, 
				  const gchar  *buf, 
				  gsize         count,
				  gsize        *bytes_written,
				  GError      **err);
  GIOStatus (*io_seek)           (GIOChannel   *channel, 
				  gint64        offset, 
				  GSeekType     type,
				  GError      **err);
  GIOStatus  (*io_close)         (GIOChannel   *channel,
				  GError      **err);
  GSource*   (*io_create_watch)  (GIOChannel   *channel,
				  GIOCondition  condition);
  void       (*io_free)          (GIOChannel   *channel);
  GIOStatus  (*io_set_flags)     (GIOChannel   *channel,
                                  GIOFlags      flags,
				  GError      **err);
  GIOFlags   (*io_get_flags)     (GIOChannel   *channel);
} GIOFuncs;
</programlisting>
<para>
A table of functions used to handle different types of <link linkend="GIOChannel"><type>GIOChannel</type></link>
in a generic way.
</para></refsect2>
<refsect2 id="g-io-channel-get-buffer-size" role="function">
<title>g_io_channel_get_buffer_size ()</title>
<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>
<para>
Gets the buffer size.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the size of the buffer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-set-buffer-size" role="function">
<title>g_io_channel_set_buffer_size ()</title>
<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,
                                                         <link linkend="gsize">gsize</link> size);</programlisting>
<para>
Sets the buffer size.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara> the size of the buffer, or 0 to let GLib pick a good size
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-get-buffer-condition" role="function">
<title>g_io_channel_get_buffer_condition ()</title>
<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>
<para>
This function returns a <link linkend="GIOCondition"><type>GIOCondition</type></link> depending on whether there
is data to be read/space to write data in the internal buffers in 
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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A <link linkend="GIOCondition"><type>GIOCondition</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-get-flags" role="function">
<title>g_io_channel_get_flags ()</title>
<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>
<para>
Gets the current flags for a <link linkend="GIOChannel"><type>GIOChannel</type></link>, including read-only
flags such as <link linkend="G-IO-FLAG-IS-READABLE--CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link>.
</para>
<para>
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>
are cached for internal use by the channel when it is created.
If they should change at some later point (e.g. partial shutdown
of a socket with the UNIX <link linkend="shutdown"><function>shutdown()</function></link> function), the user
should immediately call <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link> to update
the internal values of these flags.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the flags which are set on the channel
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-set-flags" role="function">
<title>g_io_channel_set_flags ()</title>
<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,
                                                         <link linkend="GIOFlags">GIOFlags</link> flags,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&#160;:</term>
<listitem><simpara> the flags to set on the IO channel
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the status of the operation. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GIOFlags" role="enum">
<title>enum GIOFlags</title>
<indexterm zone="GIOFlags"><primary sortas="IOFlags">GIOFlags</primary></indexterm><programlisting>typedef enum
{
  G_IO_FLAG_APPEND = 1 &lt;&lt; 0,
  G_IO_FLAG_NONBLOCK = 1 &lt;&lt; 1,
  G_IO_FLAG_IS_READABLE = 1 &lt;&lt; 2,	/* Read only flag */
  G_IO_FLAG_IS_WRITEABLE = 1 &lt;&lt; 3,	/* Read only flag */
  G_IO_FLAG_IS_SEEKABLE = 1 &lt;&lt; 4,	/* Read only flag */
  G_IO_FLAG_MASK = (1 &lt;&lt; 5) - 1,
  G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK,
  G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK
} GIOFlags;
</programlisting>
<para>
Specifies properties of a <link linkend="GIOChannel"><type>GIOChannel</type></link>. Some of the flags can only
be read with <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link>, but not changed with
<link linkend="g-io-channel-set-flags"><function>g_io_channel_set_flags()</function></link>.
</para><variablelist role="enum">
<varlistentry id="G-IO-FLAG-APPEND--CAPS" role="constant">
<term><literal>G_IO_FLAG_APPEND</literal></term>
<listitem><simpara>turns on append mode, corresponds to <link linkend="O-APPEND--CAPS"><literal>O_APPEND</literal></link> 
  (see the documentation of the UNIX <link linkend="open"><function>open()</function></link> syscall).
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-FLAG-NONBLOCK--CAPS" role="constant">
<term><literal>G_IO_FLAG_NONBLOCK</literal></term>
<listitem><simpara>turns on nonblocking mode, corresponds to 
  <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>
  syscall).
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-FLAG-IS-READABLE--CAPS" role="constant">
<term><literal>G_IO_FLAG_IS_READABLE</literal></term>
<listitem><simpara>indicates that the io channel is readable. 
  This flag can not be changed.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-FLAG-IS-WRITEABLE--CAPS" role="constant">
<term><literal>G_IO_FLAG_IS_WRITEABLE</literal></term>
<listitem><simpara>indicates that the io channel is writable. 
  This flag can not be changed.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-FLAG-IS-SEEKABLE--CAPS" role="constant">
<term><literal>G_IO_FLAG_IS_SEEKABLE</literal></term>
<listitem><simpara>indicates that the io channel is seekable, 
  i.e. that <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> can be used on it.
  This flag can not be changed.
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-FLAG-MASK--CAPS" role="constant">
<term><literal>G_IO_FLAG_MASK</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-FLAG-GET-MASK--CAPS" role="constant">
<term><literal>G_IO_FLAG_GET_MASK</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-FLAG-SET-MASK--CAPS" role="constant">
<term><literal>G_IO_FLAG_SET_MASK</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-get-line-term" role="function">
<title>g_io_channel_get_line_term ()</title>
<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,
                                                         <link linkend="gint">gint</link> *length);</programlisting>
<para>
This returns the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine
where in the file a line break occurs. A value of <link linkend="NULL--CAPS"><literal>NULL</literal></link>
indicates autodetection.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara> a location to return the length of the line terminator
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The line termination string. This value
  is owned by GLib and must not be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-set-line-term" role="function">
<title>g_io_channel_set_line_term ()</title>
<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,
                                                         const <link linkend="gchar">gchar</link> *line_term,
                                                         <link linkend="gint">gint</link> length);</programlisting>
<para>
This sets the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine
where in the file a line break occurs.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>line_term</parameter>&#160;:</term>
<listitem><simpara> The line termination string. Use <link linkend="NULL--CAPS"><literal>NULL</literal></link> for autodetect.
            Autodetection breaks on "\n", "\r\n", "\r", "\0", and
            the Unicode paragraph separator. Autodetection should
            not be used for anything other than file-based channels.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara> The length of the termination string. If -1 is passed, the
         string is assumed to be nul-terminated. This option allows
         termination strings with embedded nuls.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-get-buffered" role="function">
<title>g_io_channel_get_buffered ()</title>
<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>
<para>
Returns whether <parameter>channel</parameter> is buffered.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <parameter>channel</parameter> is buffered. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-set-buffered" role="function">
<title>g_io_channel_set_buffered ()</title>
<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,
                                                         <link linkend="gboolean">gboolean</link> buffered);</programlisting>
<para>
The buffering state can only be set if the channel's encoding
is <link linkend="NULL--CAPS"><literal>NULL</literal></link>. For any other encoding, the channel must be buffered.
</para>
<para>
A buffered channel can only be set unbuffered if the channel's
internal buffers have been flushed. Newly created channels or
channels which have returned <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>
not require such a flush. For write-only channels, a call to
<link linkend="g-io-channel-flush"><function>g_io_channel_flush()</function></link> is sufficient. For all other channels,
the buffers may be flushed by a call to <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>.
This includes the possibility of seeking with seek type <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link>
and an offset of zero. Note that this means that socket-based
channels cannot be set unbuffered once they have had data
read from them.
</para>
<para>
On unbuffered channels, it is safe to mix read and write
calls from the new and old APIs, if this is necessary for
maintaining old code.
</para>
<para>
The default state of the channel is buffered.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffered</parameter>&#160;:</term>
<listitem><simpara> whether to set the channel buffered or unbuffered
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-get-encoding" role="function">
<title>g_io_channel_get_encoding ()</title>
<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>
<para>
Gets the encoding for the input/output of the channel. 
The internal encoding is always UTF-8. The encoding <link linkend="NULL--CAPS"><literal>NULL</literal></link> 
makes the channel safe for binary data.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A string containing the encoding, this string is
  owned by GLib and must not be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-set-encoding" role="function">
<title>g_io_channel_set_encoding ()</title>
<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,
                                                         const <link linkend="gchar">gchar</link> *encoding,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Sets the encoding for the input/output of the channel. 
The internal encoding is always UTF-8. The default encoding 
for the external file is UTF-8.
</para>
<para>
The encoding <link linkend="NULL--CAPS"><literal>NULL</literal></link> is safe to use with binary data.
</para>
<para>
The encoding can only be set if one of the following conditions
is true:
<itemizedlist>
<listitem><para>
   The channel was just created, and has not been written to or read 
   from yet.
</para></listitem>
<listitem><para>
   The channel is write-only.
</para></listitem>
<listitem><para>
   The channel is a file, and the file pointer was just
   repositioned by a call to <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>.
   (This flushes all the internal buffers.)
</para></listitem>
<listitem><para>
   The current encoding is <link linkend="NULL--CAPS"><literal>NULL</literal></link> or UTF-8.
</para></listitem>
<listitem><para>
   One of the (new API) read functions has just returned <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>
   (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>).
</para></listitem>
<listitem><para>
   One of the functions <link linkend="g-io-channel-read-chars"><function>g_io_channel_read_chars()</function></link> or 
   <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 
   <link linkend="G-IO-STATUS-ERROR--CAPS"><literal>G_IO_STATUS_ERROR</literal></link>. This may be useful in the case of 
   <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE--CAPS"><literal>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</literal></link>.
   Returning one of these statuses from <link linkend="g-io-channel-read-line"><function>g_io_channel_read_line()</function></link>,
   <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>
   does <emphasis>not</emphasis> guarantee that the encoding can 
   be changed.
</para></listitem>
</itemizedlist>
Channels which do not meet one of the above conditions cannot call
<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 
they are "seekable", cannot call <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link> after 
calling one of the API "read" functions.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara> the encoding type
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
</simpara></listitem></varlistentry>
<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.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-get-close-on-unref" role="function">
<title>g_io_channel_get_close_on_unref ()</title>
<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>
<para>
Returns whether the file/socket/whatever associated with <parameter>channel</parameter>
will be closed when <parameter>channel</parameter> receives its final unref and is
destroyed. The default value of 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>, and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Whether the channel will be closed on the final unref of
              the GIOChannel data structure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-set-close-on-unref" role="function">
<title>g_io_channel_set_close_on_unref ()</title>
<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,
                                                         <link linkend="gboolean">gboolean</link> do_close);</programlisting>
<para>
Setting this flag to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for a channel you have already closed
can cause problems.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>do_close</parameter>&#160;:</term>
<listitem><simpara> Whether to close the channel on the final unref of
           the GIOChannel data structure. The default value of
           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>,
           and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-read" role="function" condition="deprecated:2.2: Use g_io_channel_read_chars() instead.">
<title>g_io_channel_read ()</title>
<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,
                                                         <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gsize">gsize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_read);</programlisting>
<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>
<para>
Reads data from a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&#160;:</term>
<listitem><simpara> a buffer to read the data into (which should be at least 
      count bytes long)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter>&#160;:</term>
<listitem><simpara> the number of bytes to read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_read</parameter>&#160;:</term>
<listitem><simpara> returns the number of bytes actually read
</simpara></listitem></varlistentry>
<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. 

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GIOError" role="enum">
<title>enum GIOError</title>
<indexterm zone="GIOError"><primary sortas="IOError">GIOError</primary></indexterm><programlisting>typedef enum
{
  G_IO_ERROR_NONE,
  G_IO_ERROR_AGAIN,
  G_IO_ERROR_INVAL,
  G_IO_ERROR_UNKNOWN
} GIOError;
</programlisting>
<para>
<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>,
<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>.
</para><variablelist role="enum">
<varlistentry id="G-IO-ERROR-NONE--CAPS" role="constant">
<term><literal>G_IO_ERROR_NONE</literal></term>
<listitem><simpara>no error
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-ERROR-AGAIN--CAPS" role="constant">
<term><literal>G_IO_ERROR_AGAIN</literal></term>
<listitem><simpara>an EAGAIN error occurred
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-ERROR-INVAL--CAPS" role="constant">
<term><literal>G_IO_ERROR_INVAL</literal></term>
<listitem><simpara>an EINVAL error occurred
</simpara></listitem>
</varlistentry>
<varlistentry id="G-IO-ERROR-UNKNOWN--CAPS" role="constant">
<term><literal>G_IO_ERROR_UNKNOWN</literal></term>
<listitem><simpara>another error occurred
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-write" role="function" condition="deprecated:2.2: Use g_io_channel_write_chars() instead.">
<title>g_io_channel_write ()</title>
<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,
                                                         const <link linkend="gchar">gchar</link> *buf,
                                                         <link linkend="gsize">gsize</link> count,
                                                         <link linkend="gsize">gsize</link> *bytes_written);</programlisting>
<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>
<para>
Writes data to a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara>  a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&#160;:</term>
<listitem><simpara> the buffer containing the data to write
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter>&#160;:</term>
<listitem><simpara> the number of bytes to write
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_written</parameter>&#160;:</term>
<listitem><simpara> the number of bytes actually written
</simpara></listitem></varlistentry>
<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.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-seek" role="function" condition="deprecated:2.2: Use g_io_channel_seek_position() instead.">
<title>g_io_channel_seek ()</title>
<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,
                                                         <link linkend="gint64">gint64</link> offset,
                                                         <link linkend="GSeekType">GSeekType</link> type);</programlisting>
<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>
<para>
Sets the current position in the <link linkend="GIOChannel"><type>GIOChannel</type></link>, similar to the standard 
library function <link linkend="fseek"><function>fseek()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&#160;:</term>
<listitem><simpara> an offset, in bytes, which is added to the position specified 
         by <parameter>type</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara> the position in the file, which can be <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link> (the current
       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> 
       (the end of the file)
</simpara></listitem></varlistentry>
<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.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-io-channel-close" role="function" condition="deprecated:2.2: Use g_io_channel_shutdown() instead.">
<title>g_io_channel_close ()</title>
<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>
<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>
<para>
Close an IO channel. Any pending data to be written will be
flushed, ignoring errors. The channel will not be freed until the
last reference is dropped using <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1 id="glib-IO-Channels.see-also">
<title>See Also</title>
<para>
<variablelist>
<varlistentry>
<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>,
<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>
<listitem><para>
Convenience functions for creating <link linkend="GIOChannel"><type>GIOChannel</type></link> instances and adding them to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

</refentry>
