iochannels.sgml

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

<title><anchor id="g-io-channel-unix-get-fd">g_io_channel_unix_get_fd ()</title>
<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">GIOChannel</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry>a <link linkend="GIOChannel">GIOChannel</link>, created with <link linkend="g-io-channel-unix-new">g_io_channel_unix_new</link>().
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the file descriptor of the <link linkend="GIOChannel">GIOChannel</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-init">g_io_channel_init ()</title>
<programlisting>void        g_io_channel_init               (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
<para>
Initializes a <link linkend="GIOChannel">GIOChannel</link> struct. This is called by each of the above functions
when creating a <link linkend="GIOChannel">GIOChannel</link>, and so is not often needed by the application
programmer (unless you are creating a new type of <link linkend="GIOChannel">GIOChannel</link>).
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry>a <link linkend="GIOChannel">GIOChannel</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-new-file">g_io_channel_new_file ()</title>
<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">GIOChannel</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">g_io_channel_close</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> A string containing the name of a file.
</entry></row>
<row><entry align="right"><parameter>mode</parameter>&nbsp;:</entry>
<entry> One of "r", "w", "a", "r+", "w+", "a+". These have
       the same meaning as in <function><link linkend="fopen">fopen</link>()</function>.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> A location to return an error of type <literal>G_FILE_ERROR</literal>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="GIOChannel">GIOChannel</link> on success, <literal>NULL</literal> on failure.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-chars">g_io_channel_read_chars ()</title>
<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">g_io_channel_read</link>() with the new API.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><parameter>buf</parameter>&nbsp;:</entry>
<entry> a buffer to read data into
</entry></row>
<row><entry align="right"><parameter>count</parameter>&nbsp;:</entry>
<entry> 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.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry> 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.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> A location to return an error of type <link linkend="GConvertError">GConvertError</link>
        or <link linkend="GIOChannelError">GIOChannelError</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the status of the operation.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-unichar">g_io_channel_read_unichar ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><parameter>thechar</parameter>&nbsp;:</entry>
<entry> a location to return a character
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> A location to return an error of type <link linkend="GConvertError">GConvertError</link>
        or <link linkend="GIOChannelError">GIOChannelError</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a <link linkend="GIOStatus">GIOStatus</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-line">g_io_channel_read_line ()</title>
<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">GIOChannel</link> into a newly-allocated string.
<parameter>length</parameter> will contain allocated memory if the return
is <literal>G_IO_STATUS_NORMAL</literal>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><parameter>str_return</parameter>&nbsp;:</entry>
<entry> The line read from the <link linkend="GIOChannel">GIOChannel</link>, not including the
             line terminator. This data should be freed with <link linkend="g-free">g_free</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.
</entry></row>
<row><entry align="right"><parameter>length</parameter>&nbsp;:</entry>
<entry> location to store length of the read data, or <literal>NULL</literal>
</entry></row>
<row><entry align="right"><parameter>terminator_pos</parameter>&nbsp;:</entry>
<entry> location to store position of line terminator, or <literal>NULL</literal>
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> A location to return an error of type <link linkend="GConvertError">GConvertError</link>
        or <link linkend="GIOChannelError">GIOChannelError</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated string. Free this string
  with <link linkend="g-free">g_free</link>() when you are done with it.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-line-string">g_io_channel_read_line_string ()</title>
<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">GIOChannel</link>, using a <link linkend="GString">GString</link> as a buffer.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><parameter>buffer</parameter>&nbsp;:</entry>
<entry> a <link linkend="GString">GString</link> into which the line will be written.
         If <parameter>buffer</parameter> already contains data, the old data will
         be overwritten.
</entry></row>
<row><entry align="right"><parameter>terminator_pos</parameter>&nbsp;:</entry>
<entry> location to store position of line terminator, or <literal>NULL</literal>
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> a location to store an error of type <link linkend="GConvertError">GConvertError</link>
        or <link linkend="GIOChannelError">GIOChannelError</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the status of the operation.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-read-to-end">g_io_channel_read_to_end ()</title>
<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>
Return value: <literal>G_IO_STATUS_NORMAL</literal> on success. This function never</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><parameter>str_return</parameter>&nbsp;:</entry>
<entry> Location to store a pointer to a string holding
             the remaining data in the <link linkend="GIOChannel">GIOChannel</link>. This data should
             be freed with <link linkend="g-free">g_free</link>() when no longer needed. This
             data is terminated by an extra nul character, but there 
             may be other nuls in the intervening data.
</entry></row>
<row><entry align="right"><parameter>length</parameter>&nbsp;:</entry>
<entry> Location to store length of the data
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> A location to return an error of type <link linkend="GConvertError">GConvertError</link>
        or <link linkend="GIOChannelError">GIOChannelError</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>G_IO_STATUS_EOF</literal>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-write-chars">g_io_channel_write_chars ()</title>
<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">g_io_channel_write</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">g_io_channel_write_chars</link>()
may only be made on a channel from which data has been read in the