iochannels.sgml

This GLib version 2.16.1. GLib is the low-level core library that forms the basis for projects such

<!-- ##### SECTION Title ##### -->
IO Channels

<!-- ##### SECTION Short_Description ##### -->
portable support for using files, pipes and sockets

<!-- ##### SECTION Long_Description ##### -->
<para>
The #GIOChannel 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 #GIOChannel on UNIX systems use g_io_channel_unix_new().
This works for plain file descriptors, pipes and sockets.
Alternatively, a channel can be created for a file in a system independent
manner using g_io_channel_new_file().
</para>
<para>
Once a #GIOChannel has been created, it can be used in a generic manner
with the functions g_io_channel_read_chars(), g_io_channel_write_chars(),
g_io_channel_seek_position(), and g_io_channel_shutdown().
</para>
<para>
To add a #GIOChannel to the 
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events
you are interested in on the #GIOChannel, and provide a function to be
called whenever these events occur.
</para>
<para>
#GIOChannel instances are created with an initial reference count of 1.
g_io_channel_ref() and g_io_channel_unref() can be used to increment or
decrement the reference count respectively. When the reference count falls
to 0, the #GIOChannel is freed. (Though it isn't closed automatically,
unless it was created using g_io_channel_new_from_file().)
Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
reference count.
</para>
<para>
The new functions g_io_channel_read_chars(), g_io_channel_read_line(),
g_io_channel_read_line_string(), g_io_channel_read_to_end(),
g_io_channel_write_chars(), g_io_channel_seek_position(),
and g_io_channel_flush() should not be mixed with the
deprecated functions g_io_channel_read(), g_io_channel_write(),
and g_io_channel_seek() on the same channel.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>

<varlistentry>
<term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
gdk_input_add_full(), gdk_input_remove()</term>
<listitem><para>
Convenience functions for creating #GIOChannel instances and adding them to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
</para></listitem>
</varlistentry>

</variablelist>
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GIOChannel ##### -->
<para>
A data structure representing an IO Channel. The fields should be considered
private and should only be accessed with the following functions.
</para>


<!-- ##### FUNCTION g_io_channel_unix_new ##### -->
<para>
Creates a new #GIOChannel given a file descriptor.
On UNIX systems this works for plain files, pipes, and sockets.
</para>
<para>
The returned #GIOChannel has a reference count of 1.
</para>
<para>
The default encoding for #GIOChannel 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
g_get_charset()) with the g_io_channel_set_encoding() function.
</para>
<para>
If you want to read raw binary data without interpretation, then
call the g_io_channel_set_encoding() function with %NULL for the
encoding argument.
</para>
<para>
This function is available in GLib on Windows, too, but you should
avoid using it on Windows. The domain of file descriptors and sockets
overlap. There is no way for GLib to know which one you mean in case
the argument you pass to this function happens to be both a valid file
descriptor and socket. If that happens a warning is issued, and GLib
assumes that it is the file descriptor you mean.
</para>

@fd: a file descriptor.
@Returns: a new #GIOChannel.


<!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
<para>
Returns the file descriptor of the #GIOChannel.
</para>
<para>
On Windows this function returns the file descriptor or socket of the #GIOChannel.
</para>

@channel: a #GIOChannel, created with g_io_channel_unix_new().
@Returns: the file descriptor of the #GIOChannel.


<!-- ##### FUNCTION g_io_channel_win32_new_fd ##### -->
<para>
Creates a new #GIOChannel given a file descriptor on Windows. 
This works for file descriptors from the C runtime.
</para>
<para>
This function works for file descriptors as returned by the open(),
creat(), pipe() and fileno() calls in the Microsoft C runtime. In
order to meaningfully use this function your code should use the same
C runtime as GLib uses, which is msvcrt.dll. Note that in current
Microsoft compilers it is near impossible to convince it to build code
that would use msvcrt.dll. The last Microsoft compiler version that
supported using msvcrt.dll as the C runtime was version 6. The GNU
compiler and toolchain for Windows, also known as Mingw, fully
supports msvcrt.dll.
</para>
<para>
If you have created a #GIOChannel for a file descriptor and started
watching (polling) it, you shouldn't call read() on the file
descriptor. This is because adding polling for a file descriptor is
implemented in GLib on Windows by starting a thread that sits blocked
in a read() from the file descriptor most of the time. All reads from
the file descriptor should be done by this internal GLib thread. Your
code should call only g_io_channel_read().
</para>
<para>
This function is available only in GLib on Windows.
</para>

@fd: a C library file descriptor.
@Returns: a new #GIOChannel.


<!-- ##### FUNCTION g_io_channel_win32_new_socket ##### -->
<para>
Creates a new #GIOChannel given a socket on Windows.
</para>
<para>
This function works for sockets created by Winsock. 
It's available only in GLib on Windows.
</para>
<para>
Polling a #GSource created to watch a channel for a socket 
puts the socket in non-blocking mode. This is a side-effect 
of the implementation and unavoidable.
</para>

@socket: a Winsock socket
@Returns: a new #GIOChannel


<!-- ##### FUNCTION g_io_channel_win32_new_messages ##### -->
<para>
Creates a new #GIOChannel given a window handle on Windows.
</para>
<para>
This function creates a #GIOChannel that can be used to poll for
Windows messages for the window in question.
</para>

@hwnd: a window handle.
@Returns: a new #GIOChannel.


<!-- ##### FUNCTION g_io_channel_init ##### -->
<para>
Initializes a #GIOChannel struct. This is called by each of the 
above functions when creating a #GIOChannel, and so is not often 
needed by the application programmer (unless you are creating a 
new type of #GIOChannel).
</para>

@channel: a #GIOChannel


<!-- ##### FUNCTION g_io_channel_new_file ##### -->
<para>
</para>

@filename: 
@mode: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_read_chars ##### -->
<para>

</para>

@channel: 
@buf: 
@count: 
@bytes_read: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_read_unichar ##### -->
<para>

</para>

@channel: 
@thechar: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_read_line ##### -->
<para>

</para>

@channel: 
@str_return: 
@length: 
@terminator_pos: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_read_line_string ##### -->
<para>

</para>

@channel: 
@buffer: 
@terminator_pos: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_read_to_end ##### -->
<para>

</para>

@channel: 
@str_return: 
@length: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_write_chars ##### -->
<para>

</para>

@channel: 
@buf: 
@count: 
@bytes_written: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_write_unichar ##### -->
<para>

</para>

@channel: 
@thechar: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_flush ##### -->
<para>

</para>

@channel: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_io_channel_seek_position ##### -->
<para>

</para>

@channel: 
@offset: 
@type: 
@error: 
@Returns: 


<!-- ##### ENUM GSeekType ##### -->
<para>
An enumeration specifying the base position for a g_io_channel_seek_position()
operation.
</para>

@G_SEEK_CUR: the current position in the file.
@G_SEEK_SET: the start of the file.
@G_SEEK_END: the end of the file.

<!-- ##### FUNCTION g_io_channel_shutdown ##### -->
<para>

</para>

@channel: 
@flush: 
@err: 
@Returns: 


<!-- ##### ENUM GIOStatus ##### -->
<para>
Stati returned by most of the #GIOFuncs functions. 
</para>

@G_IO_STATUS_ERROR: An error occurred.
@G_IO_STATUS_NORMAL: Success.
@G_IO_STATUS_EOF: End of file.
@G_IO_STATUS_AGAIN: Resource temporarily unavailable.