GLib Reference Manual
<<< Previous PageHomeUpNext Page >>>

IO Channels

Name

IO Channels -- portable support for using files, pipes and sockets.

Synopsis


#include <glib.h>


struct      GIOChannel;

GIOChannel* g_io_channel_unix_new           (int fd);
gint        g_io_channel_unix_get_fd        (GIOChannel *channel);

void        g_io_channel_init               (GIOChannel *channel);

GIOError    g_io_channel_read               (GIOChannel *channel,
                                             gchar *buf,
                                             guint count,
                                             guint *bytes_read);
enum        GIOError;
GIOError    g_io_channel_write              (GIOChannel *channel,
                                             gchar *buf,
                                             guint count,
                                             guint *bytes_written);
GIOError    g_io_channel_seek               (GIOChannel *channel,
                                             gint offset,
                                             GSeekType type);
enum        GSeekType;
void        g_io_channel_close              (GIOChannel *channel);

void        g_io_channel_ref                (GIOChannel *channel);
void        g_io_channel_unref              (GIOChannel *channel);

guint       g_io_add_watch                  (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data);
guint       g_io_add_watch_full             (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data,
                                             GDestroyNotify notify);
enum        GIOCondition;
gboolean    (*GIOFunc)                      (GIOChannel *source,
                                             GIOCondition condition,
                                             gpointer data);

struct      GIOFuncs;

Description

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, though 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.

Once a GIOChannel has been created, it can be used in a generic manner with the functions g_io_channel_read(), g_io_channel_write(), g_io_channel_seek(), 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.) Using g_io_add_watch() or g_io_add_watch_full() increments a channel's reference count.

GTK+ contains the convenience function gtk_input_add_full() which creates a GIOChannel from a file descriptor and adds it to the main event loop. The event source can later be removed with gtk_input_remove(). Similar functions can also be found in GDK.

Details

struct GIOChannel

struct GIOChannel
{
  guint channel_flags;
  guint ref_count;
  GIOFuncs *funcs;
};

A data structure representing an IO Channel. The fields should be considered private and should only be accessed with the following functions.

g_io_channel_unix_new ()

GIOChannel* g_io_channel_unix_new           (int fd);

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.

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

g_io_channel_unix_get_fd ()

gint        g_io_channel_unix_get_fd        (GIOChannel *channel);

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.

g_io_channel_init ()

void        g_io_channel_init               (GIOChannel *channel);

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.

g_io_channel_read ()

GIOError    g_io_channel_read               (GIOChannel *channel,
                                             gchar *buf,
                                             guint count,
                                             guint *bytes_read);

Reads data from a GIOChannel.

channel :a GIOChannel.
buf :a buffer to read the data into (which should be at least count bytes long).
count :the number of bytes to read from the GIOChannel.
bytes_read :returns the number of bytes actually read.
Returns :G_IO_ERROR_NONE if the operation was successful.

enum GIOError

typedef enum
{
  G_IO_ERROR_NONE,
  G_IO_ERROR_AGAIN,
  G_IO_ERROR_INVAL,
  G_IO_ERROR_UNKNOWN
} GIOError;

g_io_channel_write ()

GIOError    g_io_channel_write              (GIOChannel *channel,
                                             gchar *buf,
                                             guint count,
                                             guint *bytes_written);

Writes data to a GIOChannel.

channel :a GIOChannel.
buf :the buffer containing the data to write.
count :the number of bytes to write.
bytes_written :the number of bytes actually written.
Returns :G_IO_ERROR_NONE if the operation was successful.

g_io_channel_seek ()

GIOError    g_io_channel_seek               (GIOChannel *channel,
                                             gint offset,
                                             GSeekType type);

Sets the current position in the GIOChannel, similar to the standard system call fseek().

channel :a GIOChannel.
offset :an offset, in bytes, which is added to the position specified by type.
type :the position in the file, which can be G_SEEK_CUR (the current position), G_SEEK_SET (the start of the file), or G_SEEK_END (the end of the file).
Returns :G_IO_ERROR_NONE if the operation was successful.

enum GSeekType

typedef enum
{
  G_SEEK_CUR,
  G_SEEK_SET,
  G_SEEK_END
} GSeekType;

An enumeration specifying the base position for a g_io_channel_seek() operation.

G_SEEK_CURthe current position in the file.
G_SEEK_SETthe start of the file.
G_SEEK_ENDthe end of the file.

g_io_channel_close ()

void        g_io_channel_close              (GIOChannel *channel);

Closes a GIOChannel. The GIOChannel will be freed when its reference count drops to 0.

channel :a GIOChannel.

g_io_channel_ref ()

void        g_io_channel_ref                (GIOChannel *channel);

Increments the reference count of a GIOChannel.

channel :a GIOChannel.

g_io_channel_unref ()

void        g_io_channel_unref              (GIOChannel *channel);

Decrements the reference count of a GIOChannel.

channel :a GIOChannel.

g_io_add_watch ()

guint       g_io_add_watch                  (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data);

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.

g_io_add_watch_full ()

guint       g_io_add_watch_full             (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data,
                                             GDestroyNotify notify);

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.

enum GIOCondition

typedef enum
{
  G_IO_IN	GLIB_SYSDEF_POLLIN,
  G_IO_OUT	GLIB_SYSDEF_POLLOUT,
  G_IO_PRI	GLIB_SYSDEF_POLLPRI,
  G_IO_ERR	GLIB_SYSDEF_POLLERR,
  G_IO_HUP	GLIB_SYSDEF_POLLHUP,
  G_IO_NVAL	GLIB_SYSDEF_POLLNVAL
} GIOCondition;

A bitwise combination representing a condition to watch for on an event source.

G_IO_INThere is data to read.
G_IO_OUTData can be written (without blocking).
G_IO_PRIThere is urgent data to read.
G_IO_ERRError condition.
G_IO_HUPHung up (the connection has been broken, usually for pipes and sockets).
G_IO_NVALInvalid request. The file descriptor is not open.

GIOFunc ()

gboolean    (*GIOFunc)                      (GIOChannel *source,
                                             GIOCondition condition,
                                             gpointer data);

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.

struct GIOFuncs

struct GIOFuncs
{
  GIOError (*io_read)   (GIOChannel 	*channel, 
		         gchar      	*buf, 
		         guint      	 count,
			 guint      	*bytes_read);
  GIOError (*io_write)  (GIOChannel 	*channel, 
		 	 gchar      	*buf, 
			 guint      	 count,
			 guint      	*bytes_written);
  GIOError (*io_seek)   (GIOChannel   	*channel, 
		 	 gint       	 offset, 
		  	 GSeekType  	 type);
  void (*io_close)      (GIOChannel	*channel);
  guint (*io_add_watch) (GIOChannel     *channel,
			 gint            priority,
			 GIOCondition    condition,
			 GIOFunc         func,
			 gpointer        user_data,
			 GDestroyNotify  notify);
  void (*io_free)       (GIOChannel	*channel);
};

A table of functions used to handle different types of GIOChannel in a generic way.

See Also

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.



<<< Previous PageHomeUpNext Page >>>
Memory AllocationMessage Output and Debugging Functions