<refentry id="glib-IO-Channels">
<refmeta>
<refentrytitle>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><title>Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;


struct      <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="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="void">void</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);

struct      <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>;
G_CONST_RETURN <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);
G_CONST_RETURN <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>
<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-close"><function>g_io_channel_close()</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>
<title>Details</title>
<refsect2>
<title><anchor id="GIOChannel"/>struct GIOChannel</title>
<indexterm><primary>GIOChannel</primary></indexterm><programlisting>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>
<title><anchor id="g-io-channel-unix-new"/>g_io_channel_unix_new ()</title>
<indexterm><primary>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-charset-set-encoding"><function>g_io_charset_set_encoding()</function></link> function with <literal>NULL</literal> for the
encoding argument.
</para><variablelist role="params">
<varlistentry><term><parameter>fd</parameter>&nbsp;:</term>
<listitem><simpara>a file descriptor.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-unix-get-fd"/>g_io_channel_unix_get_fd ()</title>
<indexterm><primary>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 UNIX <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</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> :</term><listitem><simpara>the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-init"/>g_io_channel_init ()</title>
<indexterm><primary>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. 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><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-new-file"/>g_io_channel_new_file ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> A string containing the name of a file.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter>&nbsp;:</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>&nbsp;:</term>
<listitem><simpara> A location to return an error of type <literal>G_FILE_ERROR</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link> on success, <literal>NULL</literal> on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-chars"/>g_io_channel_read_chars ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&nbsp;:</term>
<listitem><simpara> a buffer to read data into
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter>&nbsp;:</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>&nbsp;:</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-<literal>NULL</literal>.
             This indicates that the next UTF-8 character is too wide for
             the buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-unichar"/>g_io_channel_read_unichar ()</title>
<indexterm><primary>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>
This function cannot be called on a channel with <literal>NULL</literal> encoding.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>thechar</parameter>&nbsp;:</term>
<listitem><simpara> a location to return a character
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-line"/>g_io_channel_read_line ()</title>
<indexterm><primary>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 <literal>G_IO_STATUS_NORMAL</literal>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_return</parameter>&nbsp;:</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 <literal>NULL</literal> instead.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara> location to store length of the read data, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>terminator_pos</parameter>&nbsp;:</term>
<listitem><simpara> location to store position of line terminator, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-line-string"/>g_io_channel_read_line_string ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</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>&nbsp;:</term>
<listitem><simpara> location to store position of line terminator, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-to-end"/>g_io_channel_read_to_end ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_return</parameter>&nbsp;:</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>&nbsp;:</term>
<listitem><simpara> Location to store length of the data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> <literal>G_IO_STATUS_NORMAL</literal> on success. 
This function never returns <literal>G_IO_STATUS_EOF</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-write-chars"/>g_io_channel_write_chars ()</title>
<indexterm><primary>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 <literal>NULL</literal> 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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&nbsp;:</term>
<listitem><simpara> a buffer to write data from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter>&nbsp;:</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>&nbsp;:</term>
<listitem><simpara> The number of bytes written. This can be nonzero
                even if the return value is not <literal>G_IO_STATUS_NORMAL</literal>.
                If the return value is <literal>G_IO_STATUS_NORMAL</literal> 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>&nbsp;:</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> :</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-write-unichar"/>g_io_channel_write_unichar ()</title>
<indexterm><primary>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>
This function cannot be called on a channel with <literal>NULL</literal> encoding.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>thechar</parameter>&nbsp;:</term>
<listitem><simpara> a character
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-flush"/>g_io_channel_flush ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> the status of the operation: One of
  <link linkend="G-IO-CHANNEL-NORMAL-CAPS"><type>G_IO_CHANNEL_NORMAL</type></link>, <link linkend="G-IO-CHANNEL-AGAIN-CAPS"><type>G_IO_CHANNEL_AGAIN</type></link>, or
  <link linkend="G-IO-CHANNEL-ERROR-CAPS"><type>G_IO_CHANNEL_ERROR</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-seek-position"/>g_io_channel_seek_position ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&nbsp;:</term>
<listitem><simpara> The offset in bytes from the position specified by <parameter>type</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GSeekType"><type>GSeekType</type></link>. The type <literal>G_SEEK_CUR</literal> 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>&nbsp;:</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> :</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GSeekType"/>enum GSeekType</title>
<indexterm><primary>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>
<term><literal>G_SEEK_CUR</literal></term>
<listitem><simpara>the current position in the file.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_SEEK_SET</literal></term>
<listitem><simpara>the start of the file.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_SEEK_END</literal></term>
<listitem><simpara>the end of the file.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-shutdown"/>g_io_channel_shutdown ()</title>
<indexterm><primary>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 <literal>TRUE</literal>. 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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flush</parameter>&nbsp;:</term>
<listitem><simpara> if <literal>TRUE</literal>, flush pending
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> location to store a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GIOStatus"/>enum GIOStatus</title>
<indexterm><primary>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>
<term><literal>G_IO_STATUS_ERROR</literal></term>
<listitem><simpara>An error occurred.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_STATUS_NORMAL</literal></term>
<listitem><simpara>Success.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_STATUS_EOF</literal></term>
<listitem><simpara>End of file.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_STATUS_AGAIN</literal></term>
<listitem><simpara>Resource temporarily unavailable.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GIOChannelError"/>enum GIOChannelError</title>
<indexterm><primary>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>
<term><literal>G_IO_CHANNEL_ERROR_FBIG</literal></term>
<listitem><simpara>File too large.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_INVAL</literal></term>
<listitem><simpara>Invalid argument.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_IO</literal></term>
<listitem><simpara>IO error.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_ISDIR</literal></term>
<listitem><simpara>File is a directory.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_NOSPC</literal></term>
<listitem><simpara>No space left on device.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_NXIO</literal></term>
<listitem><simpara>No such device or address.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_OVERFLOW</literal></term>
<listitem><simpara>Value too large for defined datatype.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_PIPE</literal></term>
<listitem><simpara>Broken pipe.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_CHANNEL_ERROR_FAILED</literal></term>
<listitem><simpara>Some other error.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="G-IO-CHANNEL-ERROR-CAPS"/>G_IO_CHANNEL_ERROR</title>
<indexterm><primary>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>
<title><anchor id="g-io-channel-error-from-errno"/>g_io_channel_error_from_errno ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOChannelError"><type>GIOChannelError</type></link> error number, e.g. <literal>G_IO_CHANNEL_ERROR_INVAL</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-ref"/>g_io_channel_ref ()</title>
<indexterm><primary>g_io_channel_ref</primary></indexterm><programlisting><link linkend="void">void</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><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-unref"/>g_io_channel_unref ()</title>
<indexterm><primary>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><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-create-watch"/>g_io_create_watch ()</title>
<indexterm><primary>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.  <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 at the default priority.
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link> to watch
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&nbsp;:</term>
<listitem><simpara>conditions to watch for
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GSource"><type>GSource</type></link>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-add-watch"/>g_io_add_watch ()</title>
<indexterm><primary>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
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
with the default priority.
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&nbsp;:</term>
<listitem><simpara>the condition to watch for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
<listitem><simpara>the function to call when the condition is satisfied.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>user data to pass to <parameter>func</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-add-watch-full"/>g_io_add_watch_full ()</title>
<indexterm><primary>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
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
with the given priority.
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter>&nbsp;:</term>
<listitem><simpara>the priority of the <link linkend="GIOChannel"><type>GIOChannel</type></link> source.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&nbsp;:</term>
<listitem><simpara>the condition to watch for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
<listitem><simpara>the function to call when the condition is satisfied.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>user data to pass to <parameter>func</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter>&nbsp;:</term>
<listitem><simpara>the function to call when the source is removed.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GIOCondition"/>enum GIOCondition</title>
<indexterm><primary>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>
<term><literal>G_IO_IN</literal></term>
<listitem><simpara>There is data to read.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_OUT</literal></term>
<listitem><simpara>Data can be written (without blocking).
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_PRI</literal></term>
<listitem><simpara>There is urgent data to read.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_ERR</literal></term>
<listitem><simpara>Error condition.
</simpara></listitem>
</varlistentry>
<varlistentry>
<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>
<term><literal>G_IO_NVAL</literal></term>
<listitem><simpara>Invalid request. The file descriptor is not open.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GIOFunc"/>GIOFunc ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara>the <link linkend="GIOChannel"><type>GIOChannel</type></link> event source.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter>&nbsp;:</term>
<listitem><simpara>the condition which has been satisfied.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</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> :</term><listitem><simpara>the function should return <literal>FALSE</literal> if the event source should be
removed.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GIOFuncs"/>struct GIOFuncs</title>
<indexterm><primary>GIOFuncs</primary></indexterm><programlisting>struct GIOFuncs {

  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);
};
</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>
<title><anchor id="g-io-channel-get-buffer-size"/>g_io_channel_get_buffer_size ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the size of the buffer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-buffer-size"/>g_io_channel_set_buffer_size ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> the size of the buffer. 0 == pick a good size
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-buffer-condition"/>g_io_channel_get_buffer_condition ()</title>
<indexterm><primary>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 <literal>G_IO_IN</literal> and
<literal>G_IO_OUT</literal> may be set.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOCondition"><type>GIOCondition</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-flags"/>g_io_channel_get_flags ()</title>
<indexterm><primary>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 <literal>G_IO_FLAG_IS_READABLE</literal>.
</para>
<para>
The values of the flags <literal>G_IO_FLAG_IS_READABLE</literal> and <literal>G_IO_FLAG_IS_WRITEABLE</literal>
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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the flags which are set on the channel
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-flags"/>g_io_channel_set_flags ()</title>
<indexterm><primary>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; <literal>G_IO_CHANNEL_SET_MASK</literal>).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> the flags to set on the IO channel.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> the status of the operation. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GIOFlags"/>enum GIOFlags</title>
<indexterm><primary>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>
<term><literal>G_IO_FLAG_APPEND</literal></term>
<listitem><simpara>turns on append mode, corresponds to <literal>O_APPEND</literal> (see the 
   documentation of the UNIX <function><link linkend="open"><function>open()</function></link></function> syscall).
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_FLAG_NONBLOCK</literal></term>
<listitem><simpara>turns on nonblocking mode, corresponds to 
   <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal> (see the documentation of the UNIX 
   <function><link linkend="open"><function>open()</function></link></function> syscall).
</simpara></listitem>
</varlistentry>
<varlistentry>
<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>
<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>
<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>
<term><literal>G_IO_FLAG_MASK</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_FLAG_GET_MASK</literal></term>
<listitem><simpara>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><literal>G_IO_FLAG_SET_MASK</literal></term>
<listitem><simpara>

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-line-term"/>g_io_channel_get_line_term ()</title>
<indexterm><primary>g_io_channel_get_line_term</primary></indexterm><programlisting>G_CONST_RETURN <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 <literal>NULL</literal>
indicates auto detection.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara> a location to return the length of the line terminator
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The line termination string. This value
  is owned by GLib and must not be freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-line-term"/>g_io_channel_set_line_term ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>line_term</parameter>&nbsp;:</term>
<listitem><simpara> The line termination string. Use <literal>NULL</literal> for auto detect.
            Auto detection breaks on "\n", "\r\n", "\r", "\0", and
            the Unicode paragraph separator. Auto detection should
            not be used for anything other than file-based channels.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</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 embeded nuls.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-buffered"/>g_io_channel_get_buffered ()</title>
<indexterm><primary>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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if the <parameter>channel</parameter> is buffered. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-buffered"/>g_io_channel_set_buffered ()</title>
<indexterm><primary>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 <literal>NULL</literal>. 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 <literal>G_IO_STATUS_EOF</literal>
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 <literal>G_SEEK_CUR</literal>
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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffered</parameter>&nbsp;:</term>
<listitem><simpara> whether to set the channel buffered or unbuffered
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-encoding"/>g_io_channel_get_encoding ()</title>
<indexterm><primary>g_io_channel_get_encoding</primary></indexterm><programlisting>G_CONST_RETURN <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 <literal>NULL</literal> makes the
channel safe for binary data.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</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>
<title><anchor id="g-io-channel-set-encoding"/>g_io_channel_set_encoding ()</title>
<indexterm><primary>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 <literal>NULL</literal> is safe to use with binary data.
</para>
<para>
The encoding can only be set if one of the following conditions
is true:
</para>
<para>
1. The channel was just created, and has not been written to
   or read from yet.
</para>
<para>
2. The channel is write-only.
</para>
<para>
3. 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>
<para>
4. The current encoding is <literal>NULL</literal> or UTF-8.
</para>
<para>
5. One of the (new API) read functions has just returned <literal>G_IO_STATUS_EOF</literal>
   (or, in the case of <link linkend="g-io-channel-read-to-end"><function>g_io_channel_read_to_end()</function></link>, <literal>G_IO_STATUS_NORMAL</literal>).
</para>
<para>
6. 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 <literal>G_IO_STATUS_AGAIN</literal> or <literal>G_IO_STATUS_ERROR</literal>. This may be
   useful in the case of <literal>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</literal>.
   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>
<para>
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 <literal>G_SEEK_CUR</literal>,
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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&nbsp;:</term>
<listitem><simpara> the encoding type
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</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> :</term><listitem><simpara> <literal>G_IO_STATUS_NORMAL</literal> if the encoding was successfully set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-close-on-unref"/>g_io_channel_get_close_on_unref ()</title>
<indexterm><primary>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 <literal>TRUE</literal> for channels created
by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>, and <literal>FALSE</literal> for all other channels.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the channel will be closed on the final unref of
              the GIOChannel data structure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-close-on-unref"/>g_io_channel_set_close_on_unref ()</title>
<indexterm><primary>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 <literal>TRUE</literal> for a channel you have already closed
can cause problems.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>do_close</parameter>&nbsp;:</term>
<listitem><simpara> Whether to close the channel on the final unref of
           the GIOChannel data structure. The default value of
           this is <literal>TRUE</literal> for channels created by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>,
           and <literal>FALSE</literal> for all other channels.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read"/>g_io_channel_read ()</title>
<indexterm role="deprecated"><primary>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> is deprecated 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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
<listitem><simpara> returns the number of bytes actually read. 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>G_IO_ERROR_NONE</literal> if the operation was successful. 

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="GIOError"/>enum GIOError</title>
<indexterm><primary>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></refsect2>
<refsect2>
<title><anchor id="g-io-channel-write"/>g_io_channel_write ()</title>
<indexterm role="deprecated"><primary>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> is deprecated 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>&nbsp;:</term>
<listitem><simpara>  a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter>&nbsp;:</term>
<listitem><simpara> the buffer containing the data to write. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter>&nbsp;:</term>
<listitem><simpara> the number of bytes to write.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_written</parameter>&nbsp;:</term>
<listitem><simpara>  the number of bytes actually written.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>  <literal>G_IO_ERROR_NONE</literal> if the operation was successful.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-seek"/>g_io_channel_seek ()</title>
<indexterm role="deprecated"><primary>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> is deprecated 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>&nbsp;:</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&nbsp;:</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>&nbsp;:</term>
<listitem><simpara> the position in the file, which can be <literal>G_SEEK_CUR</literal> (the current
       position), <literal>G_SEEK_SET</literal> (the start of the file), or <literal>G_SEEK_END</literal> (the end of the
       file).
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>G_IO_ERROR_NONE</literal> if the operation was successful.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-io-channel-close"/>g_io_channel_close ()</title>
<indexterm role="deprecated"><primary>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> is deprecated 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>&nbsp;:</term>
<listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1>
<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>
