<!-- ##### 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_close(). </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> <!-- ##### 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_charset_set_encoding() function with %NULL for the encoding argument. </para> @fd: a file descriptor. @Returns: a new #GIOChannel. <!-- ##### FUNCTION g_io_channel_unix_get_fd ##### --> <para> Returns the file descriptor of the UNIX #GIOChannel. </para> @channel: a #GIOChannel, created with g_io_channel_unix_new(). @Returns: the file descriptor of the #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. <!-- ##### ENUM GIOChannelError ##### --> <para> Error codes returned by #GIOChannel operations. </para> @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. <!-- ##### MACRO G_IO_CHANNEL_ERROR ##### --> <para> Error domain for #GIOChannel operations. Errors in this domain will be from the #GIOChannelError enumeration. See #GError for information on error domains. </para> <!-- ##### FUNCTION g_io_channel_error_from_errno ##### --> <para> </para> @en: @Returns: <!-- ##### FUNCTION g_io_channel_ref ##### --> <para> Increments the reference count of a #GIOChannel. </para> @channel: a #GIOChannel. <!-- ##### FUNCTION g_io_channel_unref ##### --> <para> Decrements the reference count of a #GIOChannel. </para> @channel: a #GIOChannel. <!-- ##### FUNCTION g_io_create_watch ##### --> <para> 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. </para> @channel: a #GIOChannel to watch @condition: conditions to watch for @Returns: a new #GSource <!-- ##### FUNCTION g_io_add_watch ##### --> <para> Adds the #GIOChannel into the <link linkend="glib-The-Main-Event-Loop">main event loop</link> with the default priority. </para> @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. <!-- ##### FUNCTION g_io_add_watch_full ##### --> <para> Adds the #GIOChannel into the <link linkend="glib-The-Main-Event-Loop">main event loop</link> with the given priority. </para> @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. <!-- ##### ENUM GIOCondition ##### --> <para> A bitwise combination representing a condition to watch for on an event source. </para> @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. <!-- ##### USER_FUNCTION GIOFunc ##### --> <para> 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. </para> @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. <!-- ##### STRUCT GIOFuncs ##### --> <para> A table of functions used to handle different types of #GIOChannel in a generic way. </para> @io_read: @io_write: @io_seek: @io_close: @io_create_watch: @io_free: @io_set_flags: @io_get_flags: <!-- ##### FUNCTION g_io_channel_get_buffer_size ##### --> <para> </para> @channel: @Returns: <!-- ##### FUNCTION g_io_channel_set_buffer_size ##### --> <para> </para> @channel: @size: <!-- ##### FUNCTION g_io_channel_get_buffer_condition ##### --> <para> </para> @channel: @Returns: <!-- ##### FUNCTION g_io_channel_get_flags ##### --> <para> </para> @channel: @Returns: <!-- ##### FUNCTION g_io_channel_set_flags ##### --> <para> </para> @channel: @flags: @error: @Returns: <!-- ##### ENUM GIOFlags ##### --> <para> 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(). </para> @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the documentation of the UNIX <function>open()</function> syscall). @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX <function>open()</function> 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: <!-- ##### FUNCTION g_io_channel_get_line_term ##### --> <para> </para> @channel: @length: @Returns: <!-- ##### FUNCTION g_io_channel_set_line_term ##### --> <para> </para> @channel: @line_term: @length: <!-- ##### FUNCTION g_io_channel_get_buffered ##### --> <para> </para> @channel: @Returns: <!-- ##### FUNCTION g_io_channel_set_buffered ##### --> <para> </para> @channel: @buffered: <!-- ##### FUNCTION g_io_channel_get_encoding ##### --> <para> </para> @channel: @Returns: <!-- ##### FUNCTION g_io_channel_set_encoding ##### --> <para> </para> @channel: @encoding: @error: @Returns: <!-- ##### FUNCTION g_io_channel_get_close_on_unref ##### --> <para> </para> @channel: @Returns: <!-- ##### FUNCTION g_io_channel_set_close_on_unref ##### --> <para> </para> @channel: @do_close: <!-- ##### FUNCTION g_io_channel_read ##### --> <para> </para> @channel: @buf: @count: @bytes_read: @Returns: <!-- ##### ENUM GIOError ##### --> <para> #GIOError is only used by the deprecated functions g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). </para> @G_IO_ERROR_NONE: @G_IO_ERROR_AGAIN: @G_IO_ERROR_INVAL: @G_IO_ERROR_UNKNOWN: <!-- ##### FUNCTION g_io_channel_write ##### --> <para> </para> @channel: @buf: @count: @bytes_written: @Returns: <!-- ##### FUNCTION g_io_channel_seek ##### --> <para> </para> @channel: @offset: @type. @type: @Returns: <!-- ##### FUNCTION g_io_channel_close ##### --> <para> </para> @channel: