iochannels.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<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>           (int 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);

void        <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);

void        <link linkend="g-io-channel-ref">g_io_channel_ref</link>                (<link linkend="GIOChannel">GIOChannel</link> *channel);
void        <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);
void        <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);
void        <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);
void        <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);
void        <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);
void        <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">GIOChannel</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">GIOChannel</link> on UNIX systems use <link linkend="g-io-channel-unix-new">g_io_channel_unix_new</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">g_io_channel_new_file</link>().
</para>
<para>
Once a <link linkend="GIOChannel">GIOChannel</link> has been created, it can be used in a generic manner
with the functions <link linkend="g-io-channel-read-chars">g_io_channel_read_chars</link>(), <link linkend="g-io-channel-write-chars">g_io_channel_write_chars</link>(),
<link linkend="g-io-channel-seek-position">g_io_channel_seek_position</link>(), and <link linkend="g-io-channel-close">g_io_channel_close</link>().
</para>
<para>
To add a <link linkend="GIOChannel">GIOChannel</link> to the 
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
use <link linkend="g-io-add-watch">g_io_add_watch</link>() or <link linkend="g-io-add-watch-full">g_io_add_watch_full</link>(). Here you specify which events
you are interested in on the <link linkend="GIOChannel">GIOChannel</link>, and provide a function to be
called whenever these events occur.
</para>
<para>
<link linkend="GIOChannel">GIOChannel</link> instances are created with an initial reference count of 1.
<link linkend="g-io-channel-ref">g_io_channel_ref</link>() and <link linkend="g-io-channel-unref">g_io_channel_unref</link>() can be used to increment or
decrement the reference count respectively. When the reference count falls
to 0, the <link linkend="GIOChannel">GIOChannel</link> is freed. (Though it isn't closed automatically,
unless it was created using <link linkend="g-io-channel-new-from-file">g_io_channel_new_from_file</link>().)
Using <link linkend="g-io-add-watch">g_io_add_watch</link>() or <link linkend="g-io-add-watch-full">g_io_add_watch_full</link>() increments a channel's
reference count.
</para>
<para>
GTK+ contains the convenience function <link linkend="gtk-input-add-full">gtk_input_add_full</link>()
which creates a <link linkend="GIOChannel">GIOChannel</link> from a file descriptor and adds it to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
The event source can later be removed with <link linkend="gtk-input-remove">gtk_input_remove</link>().
Similar functions can also be found in GDK.
</para>
<para>
The new functions <link linkend="g-io-channel-read-chars">g_io_channel_read_chars</link>(), <link linkend="g-io-channel-read-line">g_io_channel_read_line</link>(),
<link linkend="g-io-channel-read-line-string">g_io_channel_read_line_string</link>(), <link linkend="g-io-channel-read-to-end">g_io_channel_read_to_end</link>(),
<link linkend="g-io-channel-write-chars">g_io_channel_write_chars</link>(), <link linkend="g-io-channel-seek-position">g_io_channel_seek_position</link>(),
and <link linkend="g-io-channel-flush">g_io_channel_flush</link>() should not be mixed with the
deprecated functions <link linkend="g-io-channel-read">g_io_channel_read</link>(), <link linkend="g-io-channel-write">g_io_channel_write</link>(),
and <link linkend="g-io-channel-seek">g_io_channel_seek</link>() on the same channel.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GIOChannel">struct GIOChannel</title>
<programlisting>struct GIOChannel
{
  /*&lt; private &gt;*/
  guint ref_count;
  GIOFuncs *funcs;

  gchar *encoding;
  GIConv read_cd;
  GIConv write_cd;
  gchar *line_term;		/* String which indicates the end of a line of text */
  guint line_term_len;		/* So we can have null in the line term */

  gsize buf_size;
  GString *read_buf;		/* Raw data from the channel */
  GString *encoded_read_buf;    /* Channel data converted to UTF-8 */
  GString *write_buf;		/* Data ready to be written to the file */
  gchar partial_write_buf[6];	/* UTF-8 partial characters, null terminated */

  /* Group the flags together, immediately after partial_write_buf, to save memory */

  guint use_buffer     : 1;	/* The encoding uses the buffers */
  guint do_encode      : 1;	/* The encoding uses the GIConv coverters */
  guint close_on_unref : 1;	/* Close the channel on final unref */
  guint is_readable    : 1;	/* Cached GIOFlag */
  guint is_writeable   : 1;	/* ditto */
  guint is_seekable    : 1;	/* ditto */

  gpointer reserved1;	
  gpointer reserved2;	
};
</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>
<programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_unix_new           (int fd);</programlisting>
<para>
Creates a new <link linkend="GIOChannel">GIOChannel</link> given a file descriptor.
On UNIX systems this works for plain files, pipes, and sockets.
</para>
<para>
The returned <link linkend="GIOChannel">GIOChannel</link> has a reference count of 1.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>fd</parameter>&nbsp;:</entry>
<entry>a file descriptor.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GIOChannel">GIOChannel</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>