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 The new functions g_io_channel_read_chars(), g_io_channel_read_line(),
44 g_io_channel_read_line_string(), g_io_channel_read_to_end(),
45 g_io_channel_write_chars(), g_io_channel_seek_position(),
46 and g_io_channel_flush() should not be mixed with the
47 deprecated functions g_io_channel_read(), g_io_channel_write(),
48 and g_io_channel_seek() on the same channel.
51 <!-- ##### SECTION See_Also ##### -->
56 <term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
57 gdk_input_add_full(), gdk_input_remove()</term>
59 Convenience functions for creating #GIOChannel instances and adding them to the
60 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
67 <!-- ##### SECTION Stability_Level ##### -->
70 <!-- ##### STRUCT GIOChannel ##### -->
72 A data structure representing an IO Channel. The fields should be considered
73 private and should only be accessed with the following functions.
77 <!-- ##### FUNCTION g_io_channel_unix_new ##### -->
79 Creates a new #GIOChannel given a file descriptor.
80 On UNIX systems this works for plain files, pipes, and sockets.
83 The returned #GIOChannel has a reference count of 1.
86 The default encoding for #GIOChannel is UTF-8. If your application
87 is reading output from a command using via pipe, you may need to
88 set the encoding to the encoding of the current locale (see
89 g_get_charset()) with the g_io_channel_set_encoding() function.
92 If you want to read raw binary data without interpretation, then
93 call the g_io_channel_set_encoding() function with %NULL for the
97 @fd: a file descriptor.
98 @Returns: a new #GIOChannel.
101 <!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
103 Returns the file descriptor of the UNIX #GIOChannel.
106 @channel: a #GIOChannel, created with g_io_channel_unix_new().
107 @Returns: the file descriptor of the #GIOChannel.
110 <!-- ##### FUNCTION g_io_channel_init ##### -->
112 Initializes a #GIOChannel struct. This is called by each of the above functions
113 when creating a #GIOChannel, and so is not often needed by the application
114 programmer (unless you are creating a new type of #GIOChannel).
117 @channel: a #GIOChannel.
120 <!-- ##### FUNCTION g_io_channel_new_file ##### -->
130 <!-- ##### FUNCTION g_io_channel_read_chars ##### -->
143 <!-- ##### FUNCTION g_io_channel_read_unichar ##### -->
154 <!-- ##### FUNCTION g_io_channel_read_line ##### -->
167 <!-- ##### FUNCTION g_io_channel_read_line_string ##### -->
179 <!-- ##### FUNCTION g_io_channel_read_to_end ##### -->
191 <!-- ##### FUNCTION g_io_channel_write_chars ##### -->
204 <!-- ##### FUNCTION g_io_channel_write_unichar ##### -->
215 <!-- ##### FUNCTION g_io_channel_flush ##### -->
225 <!-- ##### FUNCTION g_io_channel_seek_position ##### -->
237 <!-- ##### ENUM GSeekType ##### -->
239 An enumeration specifying the base position for a g_io_channel_seek_position()
243 @G_SEEK_CUR: the current position in the file.
244 @G_SEEK_SET: the start of the file.
245 @G_SEEK_END: the end of the file.
247 <!-- ##### FUNCTION g_io_channel_shutdown ##### -->
258 <!-- ##### ENUM GIOStatus ##### -->
260 Stati returned by most of the #GIOFuncs functions.
263 @G_IO_STATUS_ERROR: An error occurred.
264 @G_IO_STATUS_NORMAL: Success.
265 @G_IO_STATUS_EOF: End of file.
266 @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
268 <!-- ##### ENUM GIOChannelError ##### -->
270 Error codes returned by #GIOChannel operations.
273 @G_IO_CHANNEL_ERROR_FBIG: File too large.
274 @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
275 @G_IO_CHANNEL_ERROR_IO: IO error.
276 @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
277 @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
278 @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
279 @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
280 @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
281 @G_IO_CHANNEL_ERROR_FAILED: Some other error.
283 <!-- ##### MACRO G_IO_CHANNEL_ERROR ##### -->
285 Error domain for #GIOChannel operations. Errors in this domain will
286 be from the #GIOChannelError enumeration. See #GError for information on
292 <!-- ##### FUNCTION g_io_channel_error_from_errno ##### -->
301 <!-- ##### FUNCTION g_io_channel_ref ##### -->
303 Increments the reference count of a #GIOChannel.
306 @channel: a #GIOChannel.
307 @Returns: the @channel that was passed in (since 2.6)
310 <!-- ##### FUNCTION g_io_channel_unref ##### -->
312 Decrements the reference count of a #GIOChannel.
315 @channel: a #GIOChannel.
318 <!-- ##### FUNCTION g_io_create_watch ##### -->
320 Creates a #GSource that's dispatched when @condition is met for the given
321 @channel. For example, if condition is #G_IO_IN, the source will be dispatched
322 when there's data available for reading. g_io_add_watch() is a simpler
323 interface to this same functionality, for the case where you want to add the
324 source to the default main loop at the default priority.
327 @channel: a #GIOChannel to watch
328 @condition: conditions to watch for
329 @Returns: a new #GSource
332 <!-- ##### FUNCTION g_io_add_watch ##### -->
334 Adds the #GIOChannel into the
335 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
336 with the default priority.
339 @channel: a #GIOChannel.
340 @condition: the condition to watch for.
341 @func: the function to call when the condition is satisfied.
342 @user_data: user data to pass to @func.
343 @Returns: the event source id.
346 <!-- ##### FUNCTION g_io_add_watch_full ##### -->
348 Adds the #GIOChannel into the
349 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
350 with the given priority.
353 @channel: a #GIOChannel.
354 @priority: the priority of the #GIOChannel source.
355 @condition: the condition to watch for.
356 @func: the function to call when the condition is satisfied.
357 @user_data: user data to pass to @func.
358 @notify: the function to call when the source is removed.
359 @Returns: the event source id.
362 <!-- ##### ENUM GIOCondition ##### -->
364 A bitwise combination representing a condition to watch for on an event
368 @G_IO_IN: There is data to read.
369 @G_IO_OUT: Data can be written (without blocking).
370 @G_IO_PRI: There is urgent data to read.
371 @G_IO_ERR: Error condition.
372 @G_IO_HUP: Hung up (the connection has been broken, usually for pipes
374 @G_IO_NVAL: Invalid request. The file descriptor is not open.
376 <!-- ##### USER_FUNCTION GIOFunc ##### -->
378 Specifies the type of function passed to g_io_add_watch() or
379 g_io_add_watch_full(), which is called when the requested condition on a
380 #GIOChannel is satisfied.
383 @source: the #GIOChannel event source.
384 @condition: the condition which has been satisfied.
385 @data: user data set in g_io_add_watch() or g_io_add_watch_full().
386 @Returns: the function should return %FALSE if the event source should be
390 <!-- ##### STRUCT GIOFuncs ##### -->
392 A table of functions used to handle different types of #GIOChannel in a
405 <!-- ##### FUNCTION g_io_channel_get_buffer_size ##### -->
414 <!-- ##### FUNCTION g_io_channel_set_buffer_size ##### -->
423 <!-- ##### FUNCTION g_io_channel_get_buffer_condition ##### -->
432 <!-- ##### FUNCTION g_io_channel_get_flags ##### -->
441 <!-- ##### FUNCTION g_io_channel_set_flags ##### -->
452 <!-- ##### ENUM GIOFlags ##### -->
454 Specifies properties of a #GIOChannel. Some of the flags can only
455 be read with g_io_channel_get_flags(), but not changed with
456 g_io_channel_set_flags().
459 @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the
460 documentation of the UNIX <function>open()</function> syscall).
461 @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
462 %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX
463 <function>open()</function> syscall).
464 @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag
466 @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable. This flag
468 @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that
469 g_io_channel_seek_position() can be used on it. This flag can not be changed.
474 <!-- ##### FUNCTION g_io_channel_get_line_term ##### -->
484 <!-- ##### FUNCTION g_io_channel_set_line_term ##### -->
494 <!-- ##### FUNCTION g_io_channel_get_buffered ##### -->
503 <!-- ##### FUNCTION g_io_channel_set_buffered ##### -->
512 <!-- ##### FUNCTION g_io_channel_get_encoding ##### -->
521 <!-- ##### FUNCTION g_io_channel_set_encoding ##### -->
532 <!-- ##### FUNCTION g_io_channel_get_close_on_unref ##### -->
541 <!-- ##### FUNCTION g_io_channel_set_close_on_unref ##### -->
550 <!-- ##### FUNCTION g_io_channel_read ##### -->
561 <!-- ##### ENUM GIOError ##### -->
563 #GIOError is only used by the deprecated functions g_io_channel_read(),
564 g_io_channel_write(), and g_io_channel_seek().
567 @G_IO_ERROR_NONE: no error
568 @G_IO_ERROR_AGAIN: an EAGAIN error occurred
569 @G_IO_ERROR_INVAL: an EINVAL error occurred
570 @G_IO_ERROR_UNKNOWN: another error occurred
572 <!-- ##### FUNCTION g_io_channel_write ##### -->
583 <!-- ##### FUNCTION g_io_channel_seek ##### -->
594 <!-- ##### FUNCTION g_io_channel_close ##### -->