IO Channels
portable support for using files, pipes and sockets.
The #GIOChannel data type aims to provide a portable method for using file
descriptors, pipes, and sockets, and integrating them into the
main event loop.
Currently full support is available on UNIX platforms, support for
Windows is only partially complete.
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().
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_close().
To add a #GIOChannel to the
main event loop
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.
#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.
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.
gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
gdk_input_add_full(), gdk_input_remove()
Convenience functions for creating #GIOChannel instances and adding them to the
main event loop.
A data structure representing an IO Channel. The fields should be considered
private and should only be accessed with the following functions.
Creates a new #GIOChannel given a file descriptor.
On UNIX systems this works for plain files, pipes, and sockets.
The returned #GIOChannel has a reference count of 1.
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.
If you want to read raw binary data without interpretation, then
call the g_io_charset_set_encoding() function with %NULL for the
encoding argument.
@fd: a file descriptor.
@Returns: a new #GIOChannel.
Returns the file descriptor of the UNIX #GIOChannel.
@channel: a #GIOChannel, created with g_io_channel_unix_new().
@Returns: the file descriptor of the #GIOChannel.
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).
@channel: a #GIOChannel.
@filename:
@mode:
@error:
@Returns:
@channel:
@buf:
@count:
@bytes_read:
@error:
@Returns:
@channel:
@thechar:
@error:
@Returns:
@channel:
@str_return:
@length:
@terminator_pos:
@error:
@Returns:
@channel:
@buffer:
@terminator_pos:
@error:
@Returns:
@channel:
@str_return:
@length:
@error:
@Returns:
@channel:
@buf:
@count:
@bytes_written:
@error:
@Returns:
@channel:
@thechar:
@error:
@Returns:
@channel:
@error:
@Returns:
@channel:
@offset:
@type:
@error:
@Returns:
An enumeration specifying the base position for a g_io_channel_seek_position()
operation.
@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.
@channel:
@flush:
@err:
@Returns:
Stati returned by most of the #GIOFuncs functions.
@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.
Error codes returned by #GIOChannel operations.
@G_IO_CHANNEL_ERROR_FBIG: File too large.
@G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
@G_IO_CHANNEL_ERROR_IO: IO error.
@G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
@G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
@G_IO_CHANNEL_ERROR_NXIO: No such device or address.
@G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
@G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
@G_IO_CHANNEL_ERROR_FAILED: Some other error.
Error domain for #GIOChannel operations. Errors in this domain will
be from the #GIOChannelError enumeration. See #GError for information on
error domains.
@en:
@Returns:
Increments the reference count of a #GIOChannel.
@channel: a #GIOChannel.
Decrements the reference count of a #GIOChannel.
@channel: a #GIOChannel.
Creates a #GSource that's dispatched when @condition is met for the given
@channel. For example, if condition is #G_IO_IN, the source will be dispatched
when there's data available for reading. g_io_add_watch() 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.
@channel: a #GIOChannel to watch
@condition: conditions to watch for
@Returns: a new #GSource
Adds the #GIOChannel into the
main event loop
with the default priority.
@channel: a #GIOChannel.
@condition: the condition to watch for.
@func: the function to call when the condition is satisfied.
@user_data: user data to pass to @func.
@Returns: the event source id.
Adds the #GIOChannel into the
main event loop
with the given priority.
@channel: a #GIOChannel.
@priority: the priority of the #GIOChannel source.
@condition: the condition to watch for.
@func: the function to call when the condition is satisfied.
@user_data: user data to pass to @func.
@notify: the function to call when the source is removed.
@Returns: the event source id.
A bitwise combination representing a condition to watch for on an event
source.
@G_IO_IN: There is data to read.
@G_IO_OUT: Data can be written (without blocking).
@G_IO_PRI: There is urgent data to read.
@G_IO_ERR: Error condition.
@G_IO_HUP: Hung up (the connection has been broken, usually for pipes
and sockets).
@G_IO_NVAL: Invalid request. The file descriptor is not open.
Specifies the type of function passed to g_io_add_watch() or
g_io_add_watch_full(), which is called when the requested condition on a
#GIOChannel is satisfied.
@source: the #GIOChannel event source.
@condition: the condition which has been satisfied.
@data: user data set in g_io_add_watch() or g_io_add_watch_full().
@Returns: the function should return %FALSE if the event source should be
removed.
A table of functions used to handle different types of #GIOChannel in a
generic way.
@io_read:
@io_write:
@io_seek:
@io_close:
@io_create_watch:
@io_free:
@io_set_flags:
@io_get_flags:
@channel:
@Returns:
@channel:
@size:
@channel:
@Returns:
@channel:
@Returns:
@channel:
@flags:
@error:
@Returns:
Specifies properties of a #GIOChannel. Some of the flags can only
be read with g_io_channel_get_flags(), but not changed with
g_io_channel_set_flags().
@G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the
documentation of the UNIX open() syscall).
@G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
%O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX
open() syscall).
@G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag
can not be changed.
@G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable. This flag
can not be changed.
@G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that
g_io_channel_seek_position() can be used on it. This flag can not be changed.
@G_IO_FLAG_MASK:
@G_IO_FLAG_GET_MASK:
@G_IO_FLAG_SET_MASK:
@channel:
@length:
@Returns:
@channel:
@line_term:
@length:
@channel:
@Returns:
@channel:
@buffered:
@channel:
@Returns:
@channel:
@encoding:
@error:
@Returns:
@channel:
@Returns:
@channel:
@do_close:
@channel:
@buf:
@count:
@bytes_read:
@Returns:
#GIOError is only used by the deprecated functions g_io_channel_read(),
g_io_channel_write(), and g_io_channel_seek().
@G_IO_ERROR_NONE:
@G_IO_ERROR_AGAIN:
@G_IO_ERROR_INVAL:
@G_IO_ERROR_UNKNOWN:
@channel:
@buf:
@count:
@bytes_written:
@Returns:
@channel:
@offset:
@type.
@type:
@Returns:
@channel: