<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 <glib.h>
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> :</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> :</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> :</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> :</term>
<listitem><simpara> A string containing the name of a file.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter> :</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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter> :</term>
<listitem><simpara> a buffer to read data into
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter> :</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> :</term>
<listitem><simpara> The number of bytes read. This may be zero even on
success if count < 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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>thechar</parameter> :</term>
<listitem><simpara> a location to return a character
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_return</parameter> :</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> :</term>
<listitem><simpara> location to store length of the read data, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>terminator_pos</parameter> :</term>
<listitem><simpara> location to store position of line terminator, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter> :</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> :</term>
<listitem><simpara> location to store position of line terminator, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_return</parameter> :</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> :</term>
<listitem><simpara> Location to store length of the data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter> :</term>
<listitem><simpara> a buffer to write data from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter> :</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> :</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> >= 0.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>thechar</parameter> :</term>
<listitem><simpara> a character
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter> :</term>
<listitem><simpara> The offset in bytes from the position specified by <parameter>type</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter> :</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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flush</parameter> :</term>
<listitem><simpara> if <literal>TRUE</literal>, flush pending
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>err</parameter> :</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> :</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> :</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> :</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> :</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link> to watch
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter> :</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> :</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter> :</term>
<listitem><simpara>the condition to watch for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter> :</term>
<listitem><simpara>the function to call when the condition is satisfied.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</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> :</term>
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>priority</parameter> :</term>
<listitem><simpara>the priority of the <link linkend="GIOChannel"><type>GIOChannel</type></link> source.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter> :</term>
<listitem><simpara>the condition to watch for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter> :</term>
<listitem><simpara>the function to call when the condition is satisfied.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara>user data to pass to <parameter>func</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>notify</parameter> :</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> :</term>
<listitem><simpara>the <link linkend="GIOChannel"><type>GIOChannel</type></link> event source.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>condition</parameter> :</term>
<listitem><simpara>the condition which has been satisfied.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter> :</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> :</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> :</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> & <literal>G_IO_CHANNEL_SET_MASK</literal>).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>channel</parameter> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter> :</term>
<listitem><simpara> the flags to set on the IO channel.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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 << 0,
G_IO_FLAG_NONBLOCK = 1 << 1,
G_IO_FLAG_IS_READABLE = 1 << 2, /* Read only flag */
G_IO_FLAG_IS_WRITEABLE = 1 << 3, /* Read only flag */
G_IO_FLAG_IS_SEEKABLE = 1 << 4, /* Read only flag */
G_IO_FLAG_MASK = (1 << 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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>line_term</parameter> :</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> :</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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffered</parameter> :</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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter> :</term>
<listitem><simpara> the encoding type
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>do_close</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter> :</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> :</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> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter> :</term>
<listitem><simpara> the buffer containing the data to write.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>count</parameter> :</term>
<listitem><simpara> the number of bytes to write.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes_written</parameter> :</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> :</term>
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter> :</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> :</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> :</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>