1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 portable support for using files, pipes and sockets.
7 <!-- ##### SECTION Long_Description ##### -->
9 The #GIOChannel data type aims to provide a portable method for using file
10 descriptors, pipes, and sockets, and integrating them into the
11 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
12 Currently full support is available on Unix platforms, support for
13 Windows is only partially complete.
16 To create a new #GIOChannel on Unix systems use g_io_channel_unix_new().
17 This works for plain file descriptors, pipes and sockets.
18 Alternatively, a channel can be created for a file in a system independent
19 manner using g_io_channel_new_file().
22 Once a #GIOChannel has been created, it can be used in a generic manner
23 with the functions g_io_channel_read_chars(), g_io_channel_write_chars(),
24 g_io_channel_seek_position(), and g_io_channel_close().
27 To add a #GIOChannel to the
28 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
29 use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events
30 you are interested in on the #GIOChannel, and provide a function to be
31 called whenever these events occur.
34 #GIOChannel instances are created with an initial reference count of 1.
35 g_io_channel_ref() and g_io_channel_unref() can be used to increment or
36 decrement the reference count respectively. When the reference count falls
37 to 0, the #GIOChannel is freed. (Though it isn't closed automatically,
38 unless it was created using g_io_channel_new_from_file().)
39 Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
43 GTK+ contains the convenience function gtk_input_add_full()
44 which creates a #GIOChannel from a file descriptor and adds it to the
45 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
46 The event source can later be removed with gtk_input_remove().
47 Similar functions can also be found in GDK.
50 The new functions g_io_channel_read_chars(), g_io_channel_read_line(),
51 g_io_channel_read_line_string(), g_io_channel_read_to_end(),
52 g_io_channel_write_chars(), g_io_channel_seek_position(),
53 and g_io_channel_flush() should not be mixed with the
54 deprecated functions g_io_channel_read(), g_io_channel_write(),
55 and g_io_channel_seek() on the same channel.
58 <!-- ##### SECTION See_Also ##### -->
63 <term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
64 gdk_input_add_full(), gdk_input_remove()</term>
66 Convenience functions for creating #GIOChannel instances and adding them to the
67 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
74 <!-- ##### STRUCT GIOChannel ##### -->
76 A data structure representing an IO Channel. The fields should be considered
77 private and should only be accessed with the following functions.
81 <!-- ##### FUNCTION g_io_channel_unix_new ##### -->
83 Creates a new #GIOChannel given a file descriptor.
84 On Unix systems this works for plain files, pipes, and sockets.
87 The returned #GIOChannel has a reference count of 1.
90 @fd: a file descriptor.
91 @Returns: a new #GIOChannel.
94 <!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
96 Returns the file descriptor of the Unix #GIOChannel.
99 @channel: a #GIOChannel, created with g_io_channel_unix_new().
100 @Returns: the file descriptor of the #GIOChannel.
103 <!-- ##### FUNCTION g_io_channel_init ##### -->
105 Initializes a #GIOChannel struct. This is called by each of the above functions
106 when creating a #GIOChannel, and so is not often needed by the application
107 programmer (unless you are creating a new type of #GIOChannel).
110 @channel: a #GIOChannel.
113 <!-- ##### FUNCTION g_io_channel_new_file ##### -->
123 <!-- ##### FUNCTION g_io_channel_read_chars ##### -->
136 <!-- ##### FUNCTION g_io_channel_read_unichar ##### -->
147 <!-- ##### FUNCTION g_io_channel_read_line ##### -->
160 <!-- ##### FUNCTION g_io_channel_read_line_string ##### -->
172 <!-- ##### FUNCTION g_io_channel_read_to_end ##### -->
184 <!-- ##### FUNCTION g_io_channel_write_chars ##### -->
197 <!-- ##### FUNCTION g_io_channel_write_unichar ##### -->
208 <!-- ##### FUNCTION g_io_channel_flush ##### -->
218 <!-- ##### FUNCTION g_io_channel_seek_position ##### -->
230 <!-- ##### ENUM GSeekType ##### -->
232 An enumeration specifying the base position for a g_io_channel_seek_position()
236 @G_SEEK_CUR: the current position in the file.
237 @G_SEEK_SET: the start of the file.
238 @G_SEEK_END: the end of the file.
240 <!-- ##### FUNCTION g_io_channel_shutdown ##### -->
251 <!-- ##### ENUM GIOStatus ##### -->
253 Stati returned by most of the #GIOFuncs functions.
256 @G_IO_STATUS_ERROR: An error occurred.
257 @G_IO_STATUS_NORMAL: Success.
258 @G_IO_STATUS_EOF: End of file.
259 @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
261 <!-- ##### ENUM GIOChannelError ##### -->
263 Error codes returned by #GIOChannel operations.
266 @G_IO_CHANNEL_ERROR_FBIG: File too large.
267 @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
268 @G_IO_CHANNEL_ERROR_IO: IO error.
269 @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
270 @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
271 @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
272 @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
273 @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
274 @G_IO_CHANNEL_ERROR_FAILED: Some other error.
276 <!-- ##### MACRO G_IO_CHANNEL_ERROR ##### -->
278 Error domain for #GIOChannel operations. Errors in this domain will
279 be from the #IOChannelError enumeration. See #GError for information on
285 <!-- ##### FUNCTION g_io_channel_error_from_errno ##### -->
294 <!-- ##### FUNCTION g_io_channel_ref ##### -->
296 Increments the reference count of a #GIOChannel.
299 @channel: a #GIOChannel.
302 <!-- ##### FUNCTION g_io_channel_unref ##### -->
304 Decrements the reference count of a #GIOChannel.
307 @channel: a #GIOChannel.
310 <!-- ##### FUNCTION g_io_create_watch ##### -->
312 Creates a #GSource that's dispatched when @condition is met for the given
313 @channel. For example, if condition is #G_IO_IN, the source will be dispatched
314 when there's data available for reading. g_io_add_watch() is a simpler
315 interface to this same functionality, for the case where you want to add the
316 source to the default main loop at the default priority.
319 @channel: a #GIOChannel to watch
320 @condition: conditions to watch for
321 @Returns: a new #GSource
324 <!-- ##### FUNCTION g_io_add_watch ##### -->
326 Adds the #GIOChannel into the
327 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
328 with the default priority.
331 @channel: a #GIOChannel.
332 @condition: the condition to watch for.
333 @func: the function to call when the condition is satisfied.
334 @user_data: user data to pass to @func.
335 @Returns: the event source id.
338 <!-- ##### FUNCTION g_io_add_watch_full ##### -->
340 Adds the #GIOChannel into the
341 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
342 with the given priority.
345 @channel: a #GIOChannel.
346 @priority: the priority of the #GIOChannel source.
347 @condition: the condition to watch for.
348 @func: the function to call when the condition is satisfied.
349 @user_data: user data to pass to @func.
350 @notify: the function to call when the source is removed.
351 @Returns: the event source id.
354 <!-- ##### ENUM GIOCondition ##### -->
356 A bitwise combination representing a condition to watch for on an event
360 @G_IO_IN: There is data to read.
361 @G_IO_OUT: Data can be written (without blocking).
362 @G_IO_PRI: There is urgent data to read.
363 @G_IO_ERR: Error condition.
364 @G_IO_HUP: Hung up (the connection has been broken, usually for pipes
366 @G_IO_NVAL: Invalid request. The file descriptor is not open.
368 <!-- ##### USER_FUNCTION GIOFunc ##### -->
370 Specifies the type of function passed to g_io_add_watch() or
371 g_io_add_watch_full(), which is called when the requested condition on a
372 #GIOChannel is satisfied.
375 @source: the #GIOChannel event source.
376 @condition: the condition which has been satisfied.
377 @data: user data set in g_io_add_watch() or g_io_add_watch_full().
378 @Returns: the function should return %FALSE if the event source should be
382 <!-- ##### STRUCT GIOFuncs ##### -->
384 A table of functions used to handle different types of #GIOChannel in a
397 <!-- ##### FUNCTION g_io_channel_get_buffer_size ##### -->
406 <!-- ##### FUNCTION g_io_channel_set_buffer_size ##### -->
415 <!-- ##### FUNCTION g_io_channel_get_buffer_condition ##### -->
424 <!-- ##### FUNCTION g_io_channel_get_flags ##### -->
433 <!-- ##### FUNCTION g_io_channel_set_flags ##### -->
444 <!-- ##### ENUM GIOFlags ##### -->
446 Specifies properties of a #GIOChannel. Some of the flags can only
447 be read with g_io_channel_get_flags(), but not changed with
448 g_io_channel_set_flags().
451 @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the
452 documentation of the Unix <function>open()</function> syscall).
453 @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
454 %O_NONBLOCK/%O_NDELAY (see the documentation of the Unix
455 <function>open()</function> syscall).
456 @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag
458 @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable. This flag
460 @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that
461 g_io_channel_seek_position() can be used on it. This flag can not be changed.
466 <!-- ##### FUNCTION g_io_channel_get_line_term ##### -->
476 <!-- ##### FUNCTION g_io_channel_set_line_term ##### -->
486 <!-- ##### FUNCTION g_io_channel_get_buffered ##### -->
495 <!-- ##### FUNCTION g_io_channel_set_buffered ##### -->
504 <!-- ##### FUNCTION g_io_channel_get_encoding ##### -->
513 <!-- ##### FUNCTION g_io_channel_set_encoding ##### -->
524 <!-- ##### FUNCTION g_io_channel_get_close_on_unref ##### -->
533 <!-- ##### FUNCTION g_io_channel_set_close_on_unref ##### -->
542 <!-- ##### FUNCTION g_io_channel_read ##### -->
553 <!-- ##### ENUM GIOError ##### -->
555 #GIOError is only used by the deprecated functions g_io_channel_read(),
556 g_io_channel_write(), and g_io_channel_seek().
564 <!-- ##### FUNCTION g_io_channel_write ##### -->
575 <!-- ##### FUNCTION g_io_channel_seek ##### -->
586 <!-- ##### FUNCTION g_io_channel_close ##### -->