docs/reference/glib/tmpl/iochannels.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 IO Channels
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 portable support for using files, pipes and sockets.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   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, though support for
  13 Windows is only partially complete.
  14 </para>
  15 <para>
  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 </para>
  19 <para>
  20 Once a #GIOChannel has been created, it can be used in a generic manner
  21 with the functions g_io_channel_read(), g_io_channel_write(),
  22 g_io_channel_seek(), and g_io_channel_close().
  23 </para>
  24 <para>
  25 To add a #GIOChannel to the
  26 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
  27 use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events
  28 you are interested in on the #GIOChannel, and provide a function to be
  29 called whenever these events occur.
  30 </para>
  31 <para>
  32 #GIOChannel instances are created with an initial reference count of 1.
  33 g_io_channel_ref() and g_io_channel_unref() can be used to increment or
  34 decrement the reference count respectively. When the reference count falls
  35 to 0, the #GIOChannel is freed. (Though it isn't closed automatically.)
  36 Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
  37 reference count.
  38 </para>
  39 <para>
  40 GTK+ contains the convenience function gtk_input_add_full()
  41 which creates a #GIOChannel from a file descriptor and adds it to the
  42 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
  43 The event source can later be removed with gtk_input_remove().
  44 Similar functions can also be found in GDK.
  45 </para>
  46
  47 <!-- ##### SECTION See_Also ##### -->
  48 <para>
  49 <variablelist>
  50
  51 <varlistentry>
  52 <term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
  53 gdk_input_add_full(), gdk_input_remove()</term>
  54 <listitem><para>
  55 Convenience functions for creating #GIOChannel instances and adding them to the
  56 <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
  57 </para></listitem>
  58 </varlistentry>
  59
  60 </variablelist>
  61 </para>
  62
  63 <!-- ##### STRUCT GIOChannel ##### -->
  64 <para>
  65 A data structure representing an IO Channel. The fields should be considered
  66 private and should only be accessed with the following functions.
  67 </para>
  68
  69 @channel_flags:
  70 @ref_count:
  71 @funcs:
  72
  73 <!-- ##### FUNCTION g_io_channel_unix_new ##### -->
  74 <para>
  75 Creates a new #GIOChannel given a file descriptor.
  76 On Unix systems this works for plain files, pipes, and sockets.
  77 </para>
  78 <para>
  79 The returned #GIOChannel has a reference count of 1.
  80 </para>
  81
  82 @fd: a file descriptor.
  83 @Returns: a new #GIOChannel.
  84
  85
  86 <!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
  87 <para>
  88 Returns the file descriptor of the Unix #GIOChannel.
  89 </para>
  90
  91 @channel: a #GIOChannel, created with g_io_channel_unix_new().
  92 @Returns: the file descriptor of the #GIOChannel.
  93
  94
  95 <!-- ##### FUNCTION g_io_channel_init ##### -->
  96 <para>
  97 Initializes a #GIOChannel struct. This is called by each of the above functions
  98 when creating a #GIOChannel, and so is not often needed by the application
  99 programmer (unless you are creating a new type of #GIOChannel).
 100 </para>
 101
 102 @channel: a #GIOChannel.
 103
 104
 105 <!-- ##### FUNCTION g_io_channel_read ##### -->
 106 <para>
 107 Reads data from a #GIOChannel.
 108 </para>
 109
 110 @channel: a #GIOChannel.
 111 @buf: a buffer to read the data into (which should be at least count bytes
 112 long).
 113 @count: the number of bytes to read from the #GIOChannel.
 114 @bytes_read: returns the number of bytes actually read.
 115 @Returns: %G_IO_ERROR_NONE if the operation was successful.
 116
 117
 118 <!-- ##### ENUM GIOError ##### -->
 119 <para>
 120
 121 </para>
 122
 123 @G_IO_ERROR_NONE:
 124 @G_IO_ERROR_AGAIN:
 125 @G_IO_ERROR_INVAL:
 126 @G_IO_ERROR_UNKNOWN:
 127
 128 <!-- ##### FUNCTION g_io_channel_write ##### -->
 129 <para>
 130 Writes data to a #GIOChannel.
 131 </para>
 132
 133 @channel: a #GIOChannel.
 134 @buf: the buffer containing the data to write.
 135 @count: the number of bytes to write.
 136 @bytes_written: the number of bytes actually written.
 137 @Returns: %G_IO_ERROR_NONE if the operation was successful.
 138
 139
 140 <!-- ##### FUNCTION g_io_channel_seek ##### -->
 141 <para>
 142 Sets the current position in the #GIOChannel, similar to the standard system
 143 call <function>fseek()</function>.
 144 </para>
 145
 146 @channel: a #GIOChannel.
 147 @offset: an offset, in bytes, which is added to the position specified by
 148 @type.
 149 @type: the position in the file, which can be %G_SEEK_CUR (the current
 150 position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the
 151 file).
 152 @Returns: %G_IO_ERROR_NONE if the operation was successful.
 153
 154
 155 <!-- ##### ENUM GSeekType ##### -->
 156 <para>
 157 An enumeration specifying the base position for a g_io_channel_seek()
 158 operation.
 159
 160 <informaltable pgwide=1 frame="none" role="enum">
 161 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
 162 <tbody>
 163
 164 <row>
 165 <entry>G_SEEK_CUR</entry>
 166 <entry>the current position in the file.</entry>
 167 </row>
 168
 169 <row>
 170 <entry>G_SEEK_SET</entry>
 171 <entry>the start of the file.</entry>
 172 </row>
 173
 174 <row>
 175 <entry>G_SEEK_END</entry>
 176 <entry>the end of the file.</entry>
 177 </row>
 178
 179 </tbody></tgroup></informaltable>
 180
 181 </para>
 182
 183 @G_SEEK_CUR:
 184 @G_SEEK_SET:
 185 @G_SEEK_END:
 186
 187 <!-- ##### FUNCTION g_io_channel_close ##### -->
 188 <para>
 189 Closes a #GIOChannel.
 190 The #GIOChannel will be freed when its reference count drops to 0.
 191 </para>
 192
 193 @channel: a #GIOChannel.
 194
 195
 196 <!-- ##### FUNCTION g_io_channel_ref ##### -->
 197 <para>
 198 Increments the reference count of a #GIOChannel.
 199 </para>
 200
 201 @channel: a #GIOChannel.
 202
 203
 204 <!-- ##### FUNCTION g_io_channel_unref ##### -->
 205 <para>
 206 Decrements the reference count of a #GIOChannel.
 207 </para>
 208
 209 @channel: a #GIOChannel.
 210
 211
 212 <!-- ##### FUNCTION g_io_create_watch ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @channel:
 218 @condition:
 219 @Returns:
 220
 221
 222 <!-- ##### FUNCTION g_io_add_watch ##### -->
 223 <para>
 224 Adds the #GIOChannel into the
 225 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
 226 with the default priority.
 227 </para>
 228
 229 @channel: a #GIOChannel.
 230 @condition: the condition to watch for.
 231 @func: the function to call when the condition is satisfied.
 232 @user_data: user data to pass to @func.
 233 @Returns: the event source id.
 234
 235
 236 <!-- ##### FUNCTION g_io_add_watch_full ##### -->
 237 <para>
 238 Adds the #GIOChannel into the
 239 <link linkend="glib-The-Main-Event-Loop">main event loop</link>
 240 with the given priority.
 241 </para>
 242
 243 @channel: a #GIOChannel.
 244 @priority: the priority of the #GIOChannel source.
 245 @condition: the condition to watch for.
 246 @func: the function to call when the condition is satisfied.
 247 @user_data: user data to pass to @func.
 248 @notify: the function to call when the source is removed.
 249 @Returns: the event source id.
 250
 251
 252 <!-- ##### ENUM GIOCondition ##### -->
 253 <para>
 254 A bitwise combination representing a condition to watch for on an event
 255 source.
 256
 257 <informaltable pgwide=1 frame="none" role="enum">
 258 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
 259 <tbody>
 260
 261 <row>
 262 <entry>G_IO_IN</entry>
 263 <entry>There is data to read.</entry>
 264 </row>
 265
 266 <row>
 267 <entry>G_IO_OUT</entry>
 268 <entry>Data can be written (without blocking).</entry>
 269 </row>
 270
 271 <row>
 272 <entry>G_IO_PRI</entry>
 273 <entry>There is urgent data to read.</entry>
 274 </row>
 275
 276 <row>
 277 <entry>G_IO_ERR</entry>
 278 <entry>Error condition.</entry>
 279 </row>
 280
 281 <row>
 282 <entry>G_IO_HUP</entry>
 283 <entry>Hung up (the connection has been broken, usually for pipes and
 284 sockets).</entry>
 285 </row>
 286
 287 <row>
 288 <entry>G_IO_NVAL</entry>
 289 <entry>Invalid request. The file descriptor is not open.</entry>
 290 </row>
 291
 292 </tbody></tgroup></informaltable>
 293
 294 </para>
 295
 296 @G_IO_IN:
 297 @G_IO_OUT:
 298 @G_IO_PRI:
 299 @G_IO_ERR:
 300 @G_IO_HUP:
 301 @G_IO_NVAL:
 302
 303 <!-- ##### USER_FUNCTION GIOFunc ##### -->
 304 <para>
 305 Specifies the type of function passed to g_io_add_watch() or
 306 g_io_add_watch_full(), which is called when the requested condition on a
 307 #GIOChannel is satisfied.
 308 </para>
 309
 310 @source: the #GIOChannel event source.
 311 @condition: the condition which has been satisfied.
 312 @data: user data set in g_io_add_watch() or g_io_add_watch_full().
 313 @Returns: the function should return FALSE if the event source should be
 314 removed.
 315
 316
 317 <!-- ##### STRUCT GIOFuncs ##### -->
 318 <para>
 319 A table of functions used to handle different types of #GIOChannel in a
 320 generic way.
 321 </para>
 322
 323 @io_read:
 324 @io_write:
 325 @io_seek:
 326 @io_close:
 327 @io_create_watch:
 328 @io_free:
 329