236
233
descriptor and socket. If that happens a warning is issued, and GLib
237
234
assumes that it is the file descriptor you mean.
238
235
</para><variablelist role="params">
239
<varlistentry><term><parameter>fd</parameter> :</term>
236
<varlistentry><term><parameter>fd</parameter> :</term>
240
237
<listitem><simpara>a file descriptor.
241
238
</simpara></listitem></varlistentry>
242
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
239
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
245
240
</simpara></listitem></varlistentry>
246
241
</variablelist></refsect2>
248
<title><anchor id="g-io-channel-unix-get-fd" role="function"/>g_io_channel_unix_get_fd ()</title>
249
<indexterm><primary>g_io_channel_unix_get_fd</primary></indexterm><programlisting><link linkend="gint">gint</link> g_io_channel_unix_get_fd (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
242
<refsect2 id="g-io-channel-unix-get-fd" role="function">
243
<title>g_io_channel_unix_get_fd ()</title>
244
<indexterm zone="g-io-channel-unix-get-fd"><primary sortas="g_io_channel_unix_get_fd">g_io_channel_unix_get_fd</primary></indexterm><programlisting><link linkend="gint">gint</link> g_io_channel_unix_get_fd (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
251
246
Returns the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
254
249
On Windows this function returns the file descriptor or socket of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
255
250
</para><variablelist role="params">
256
<varlistentry><term><parameter>channel</parameter> :</term>
251
<varlistentry><term><parameter>channel</parameter> :</term>
257
252
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>, created with <link linkend="g-io-channel-unix-new"><function>g_io_channel_unix_new()</function></link>.
258
253
</simpara></listitem></varlistentry>
259
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
254
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the file descriptor of the <link linkend="GIOChannel"><type>GIOChannel</type></link>.
262
255
</simpara></listitem></varlistentry>
263
256
</variablelist></refsect2>
265
<title><anchor id="g-io-channel-win32-new-fd" role="function"/>g_io_channel_win32_new_fd ()</title>
266
<indexterm><primary>g_io_channel_win32_new_fd</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_fd (<link linkend="gint">gint</link> fd);</programlisting>
257
<refsect2 id="g-io-channel-win32-new-fd" role="function">
258
<title>g_io_channel_win32_new_fd ()</title>
259
<indexterm zone="g-io-channel-win32-new-fd"><primary sortas="g_io_channel_win32_new_fd">g_io_channel_win32_new_fd</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_fd (<link linkend="gint">gint</link> fd);</programlisting>
268
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor on Windows.
261
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a file descriptor on Windows.
269
262
This works for file descriptors from the C runtime.
292
285
This function is available only in GLib on Windows.
293
286
</para><variablelist role="params">
294
<varlistentry><term><parameter>fd</parameter> :</term>
287
<varlistentry><term><parameter>fd</parameter> :</term>
295
288
<listitem><simpara>a C library file descriptor.
296
289
</simpara></listitem></varlistentry>
297
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
290
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
300
291
</simpara></listitem></varlistentry>
301
292
</variablelist></refsect2>
303
<title><anchor id="g-io-channel-win32-new-socket" role="function"/>g_io_channel_win32_new_socket ()</title>
304
<indexterm><primary>g_io_channel_win32_new_socket</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_socket (<link linkend="gint">gint</link> socket);</programlisting>
293
<refsect2 id="g-io-channel-win32-new-socket" role="function">
294
<title>g_io_channel_win32_new_socket ()</title>
295
<indexterm zone="g-io-channel-win32-new-socket"><primary sortas="g_io_channel_win32_new_socket">g_io_channel_win32_new_socket</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> * g_io_channel_win32_new_socket (<link linkend="gint">gint</link> socket);</programlisting>
306
297
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a socket on Windows.
309
This function works for sockets created by Winsock.
300
This function works for sockets created by Winsock.
310
301
It's available only in GLib on Windows.
313
Polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket
314
puts the socket in non-blocking mode. This is a side-effect
304
Polling a <link linkend="GSource"><type>GSource</type></link> created to watch a channel for a socket
305
puts the socket in non-blocking mode. This is a side-effect
315
306
of the implementation and unavoidable.
316
307
</para><variablelist role="params">
317
<varlistentry><term><parameter>socket</parameter> :</term>
308
<varlistentry><term><parameter>socket</parameter> :</term>
318
309
<listitem><simpara>a Winsock socket
319
310
</simpara></listitem></varlistentry>
320
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>
311
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>
323
312
</simpara></listitem></varlistentry>
324
313
</variablelist></refsect2>
326
<title><anchor id="g-io-channel-win32-new-messages" role="function"/>g_io_channel_win32_new_messages ()</title>
327
<indexterm><primary>g_io_channel_win32_new_messages</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_win32_new_messages (<link linkend="guint">guint</link> hwnd);</programlisting>
314
<refsect2 id="g-io-channel-win32-new-messages" role="function">
315
<title>g_io_channel_win32_new_messages ()</title>
316
<indexterm zone="g-io-channel-win32-new-messages"><primary sortas="g_io_channel_win32_new_messages">g_io_channel_win32_new_messages</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> * g_io_channel_win32_new_messages (<link linkend="gsize">gsize</link> hwnd);</programlisting>
329
318
Creates a new <link linkend="GIOChannel"><type>GIOChannel</type></link> given a window handle on Windows.
332
321
This function creates a <link linkend="GIOChannel"><type>GIOChannel</type></link> that can be used to poll for
333
322
Windows messages for the window in question.
334
323
</para><variablelist role="params">
335
<varlistentry><term><parameter>hwnd</parameter> :</term>
324
<varlistentry><term><parameter>hwnd</parameter> :</term>
336
325
<listitem><simpara>a window handle.
337
326
</simpara></listitem></varlistentry>
338
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
327
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GIOChannel"><type>GIOChannel</type></link>.
341
328
</simpara></listitem></varlistentry>
342
329
</variablelist></refsect2>
344
<title><anchor id="g-io-channel-init" role="function"/>g_io_channel_init ()</title>
345
<indexterm><primary>g_io_channel_init</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_init (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
330
<refsect2 id="g-io-channel-init" role="function">
331
<title>g_io_channel_init ()</title>
332
<indexterm zone="g-io-channel-init"><primary sortas="g_io_channel_init">g_io_channel_init</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_init (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
347
Initializes a <link linkend="GIOChannel"><type>GIOChannel</type></link> struct. This is called by each of the
348
above functions when creating a <link linkend="GIOChannel"><type>GIOChannel</type></link>, and so is not often
349
needed by the application programmer (unless you are creating a
334
Initializes a <link linkend="GIOChannel"><type>GIOChannel</type></link> struct. This is called by each of the
335
above functions when creating a <link linkend="GIOChannel"><type>GIOChannel</type></link>, and so is not often
336
needed by the application programmer (unless you are creating a
350
337
new type of <link linkend="GIOChannel"><type>GIOChannel</type></link>).
351
338
</para><variablelist role="params">
352
<varlistentry><term><parameter>channel</parameter> :</term>
339
<varlistentry><term><parameter>channel</parameter> :</term>
353
340
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>
356
341
</simpara></listitem></varlistentry>
357
342
</variablelist></refsect2>
359
<title><anchor id="g-io-channel-new-file" role="function"/>g_io_channel_new_file ()</title>
360
<indexterm><primary>g_io_channel_new_file</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_new_file (const <link linkend="gchar">gchar</link> *filename,
343
<refsect2 id="g-io-channel-new-file" role="function">
344
<title>g_io_channel_new_file ()</title>
345
<indexterm zone="g-io-channel-new-file"><primary sortas="g_io_channel_new_file">g_io_channel_new_file</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_new_file (const <link linkend="gchar">gchar</link> *filename,
361
346
const <link linkend="gchar">gchar</link> *mode,
362
347
<link linkend="GError">GError</link> **error);</programlisting>
368
353
access the channel after it is closed).</para>
370
355
</para><variablelist role="params">
371
<varlistentry><term><parameter>filename</parameter> :</term>
356
<varlistentry><term><parameter>filename</parameter> :</term>
372
357
<listitem><simpara> A string containing the name of a file
373
358
</simpara></listitem></varlistentry>
374
<varlistentry><term><parameter>mode</parameter> :</term>
359
<varlistentry><term><parameter>mode</parameter> :</term>
375
360
<listitem><simpara> One of "r", "w", "a", "r+", "w+", "a+". These have
376
361
the same meaning as in <link linkend="fopen"><function>fopen()</function></link>
377
362
</simpara></listitem></varlistentry>
378
<varlistentry><term><parameter>error</parameter> :</term>
379
<listitem><simpara> A location to return an error of type <link linkend="G-FILE-ERROR:CAPS"><literal>G_FILE_ERROR</literal></link>
363
<varlistentry><term><parameter>error</parameter> :</term>
364
<listitem><simpara> A location to return an error of type <link linkend="G-FILE-ERROR--CAPS"><literal>G_FILE_ERROR</literal></link>
380
365
</simpara></listitem></varlistentry>
381
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link> on success, <link linkend="NULL:CAPS"><literal>NULL</literal></link> on failure.
366
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link> on success, <link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure.
382
367
</simpara></listitem></varlistentry>
383
368
</variablelist></refsect2>
385
<title><anchor id="g-io-channel-read-chars" role="function"/>g_io_channel_read_chars ()</title>
386
<indexterm><primary>g_io_channel_read_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,
369
<refsect2 id="g-io-channel-read-chars" role="function">
370
<title>g_io_channel_read_chars ()</title>
371
<indexterm zone="g-io-channel-read-chars"><primary sortas="g_io_channel_read_chars">g_io_channel_read_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,
387
372
<link linkend="gchar">gchar</link> *buf,
388
373
<link linkend="gsize">gsize</link> count,
389
374
<link linkend="gsize">gsize</link> *bytes_read,
392
377
Replacement for <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link> with the new API.</para>
395
379
</para><variablelist role="params">
396
<varlistentry><term><parameter>channel</parameter> :</term>
380
<varlistentry><term><parameter>channel</parameter> :</term>
397
381
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
398
382
</simpara></listitem></varlistentry>
399
<varlistentry><term><parameter>buf</parameter> :</term>
383
<varlistentry><term><parameter>buf</parameter> :</term>
400
384
<listitem><simpara> a buffer to read data into
401
385
</simpara></listitem></varlistentry>
402
<varlistentry><term><parameter>count</parameter> :</term>
386
<varlistentry><term><parameter>count</parameter> :</term>
403
387
<listitem><simpara> the size of the buffer. Note that the buffer may
404
388
not be complelely filled even if there is data
405
389
in the buffer if the remaining data is not a
406
390
complete character.
407
391
</simpara></listitem></varlistentry>
408
<varlistentry><term><parameter>bytes_read</parameter> :</term>
392
<varlistentry><term><parameter>bytes_read</parameter> :</term>
409
393
<listitem><simpara> The number of bytes read. This may be zero even on
410
success if count < 6 and the channel's encoding is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>.
394
success if count < 6 and the channel's encoding is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>.
411
395
This indicates that the next UTF-8 character is too wide for
413
397
</simpara></listitem></varlistentry>
414
<varlistentry><term><parameter>error</parameter> :</term>
398
<varlistentry><term><parameter>error</parameter> :</term>
415
399
<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
416
400
or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.
417
401
</simpara></listitem></varlistentry>
418
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
402
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
419
403
</simpara></listitem></varlistentry>
420
404
</variablelist></refsect2>
422
<title><anchor id="g-io-channel-read-unichar" role="function"/>g_io_channel_read_unichar ()</title>
423
<indexterm><primary>g_io_channel_read_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,
405
<refsect2 id="g-io-channel-read-unichar" role="function">
406
<title>g_io_channel_read_unichar ()</title>
407
<indexterm zone="g-io-channel-read-unichar"><primary sortas="g_io_channel_read_unichar">g_io_channel_read_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,
424
408
<link linkend="gunichar">gunichar</link> *thechar,
425
409
<link linkend="GError">GError</link> **error);</programlisting>
427
411
Reads a Unicode character from <parameter>channel</parameter>.
428
This function cannot be called on a channel with <link linkend="NULL:CAPS"><literal>NULL</literal></link> encoding.</para>
412
This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>
431
414
</para><variablelist role="params">
432
<varlistentry><term><parameter>channel</parameter> :</term>
415
<varlistentry><term><parameter>channel</parameter> :</term>
433
416
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
434
417
</simpara></listitem></varlistentry>
435
<varlistentry><term><parameter>thechar</parameter> :</term>
418
<varlistentry><term><parameter>thechar</parameter> :</term>
436
419
<listitem><simpara> a location to return a character
437
420
</simpara></listitem></varlistentry>
438
<varlistentry><term><parameter>error</parameter> :</term>
421
<varlistentry><term><parameter>error</parameter> :</term>
439
422
<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
440
423
or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
441
424
</simpara></listitem></varlistentry>
442
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
425
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
443
426
</simpara></listitem></varlistentry>
444
427
</variablelist></refsect2>
446
<title><anchor id="g-io-channel-read-line" role="function"/>g_io_channel_read_line ()</title>
447
<indexterm><primary>g_io_channel_read_line</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line (<link linkend="GIOChannel">GIOChannel</link> *channel,
428
<refsect2 id="g-io-channel-read-line" role="function">
429
<title>g_io_channel_read_line ()</title>
430
<indexterm zone="g-io-channel-read-line"><primary sortas="g_io_channel_read_line">g_io_channel_read_line</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line (<link linkend="GIOChannel">GIOChannel</link> *channel,
448
431
<link linkend="gchar">gchar</link> **str_return,
449
432
<link linkend="gsize">gsize</link> *length,
450
433
<link linkend="gsize">gsize</link> *terminator_pos,
453
436
Reads a line, including the terminating character(s),
454
437
from a <link linkend="GIOChannel"><type>GIOChannel</type></link> into a newly-allocated string.
455
438
<parameter>str_return</parameter> will contain allocated memory if the return
456
is <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.</para>
439
is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.</para>
459
441
</para><variablelist role="params">
460
<varlistentry><term><parameter>channel</parameter> :</term>
442
<varlistentry><term><parameter>channel</parameter> :</term>
461
443
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
462
444
</simpara></listitem></varlistentry>
463
<varlistentry><term><parameter>str_return</parameter> :</term>
445
<varlistentry><term><parameter>str_return</parameter> :</term>
464
446
<listitem><simpara> The line read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>, including the
465
447
line terminator. This data should be freed with <link linkend="g-free"><function>g_free()</function></link>
466
448
when no longer needed. This is a nul-terminated string.
467
If a <parameter>length</parameter> of zero is returned, this will be <link linkend="NULL:CAPS"><literal>NULL</literal></link> instead.
468
</simpara></listitem></varlistentry>
469
<varlistentry><term><parameter>length</parameter> :</term>
470
<listitem><simpara> location to store length of the read data, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
471
</simpara></listitem></varlistentry>
472
<varlistentry><term><parameter>terminator_pos</parameter> :</term>
473
<listitem><simpara> location to store position of line terminator, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
474
</simpara></listitem></varlistentry>
475
<varlistentry><term><parameter>error</parameter> :</term>
449
If a <parameter>length</parameter> of zero is returned, this will be <link linkend="NULL--CAPS"><literal>NULL</literal></link> instead.
450
</simpara></listitem></varlistentry>
451
<varlistentry><term><parameter>length</parameter> :</term>
452
<listitem><simpara> location to store length of the read data, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
453
</simpara></listitem></varlistentry>
454
<varlistentry><term><parameter>terminator_pos</parameter> :</term>
455
<listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
456
</simpara></listitem></varlistentry>
457
<varlistentry><term><parameter>error</parameter> :</term>
476
458
<listitem><simpara> A location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
477
459
or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
478
460
</simpara></listitem></varlistentry>
479
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
461
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
480
462
</simpara></listitem></varlistentry>
481
463
</variablelist></refsect2>
483
<title><anchor id="g-io-channel-read-line-string" role="function"/>g_io_channel_read_line_string ()</title>
484
<indexterm><primary>g_io_channel_read_line_string</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line_string (<link linkend="GIOChannel">GIOChannel</link> *channel,
464
<refsect2 id="g-io-channel-read-line-string" role="function">
465
<title>g_io_channel_read_line_string ()</title>
466
<indexterm zone="g-io-channel-read-line-string"><primary sortas="g_io_channel_read_line_string">g_io_channel_read_line_string</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_line_string (<link linkend="GIOChannel">GIOChannel</link> *channel,
485
467
<link linkend="GString">GString</link> *buffer,
486
468
<link linkend="gsize">gsize</link> *terminator_pos,
487
469
<link linkend="GError">GError</link> **error);</programlisting>
489
471
Reads a line from a <link linkend="GIOChannel"><type>GIOChannel</type></link>, using a <link linkend="GString"><type>GString</type></link> as a buffer.</para>
492
473
</para><variablelist role="params">
493
<varlistentry><term><parameter>channel</parameter> :</term>
474
<varlistentry><term><parameter>channel</parameter> :</term>
494
475
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
495
476
</simpara></listitem></varlistentry>
496
<varlistentry><term><parameter>buffer</parameter> :</term>
477
<varlistentry><term><parameter>buffer</parameter> :</term>
497
478
<listitem><simpara> a <link linkend="GString"><type>GString</type></link> into which the line will be written.
498
479
If <parameter>buffer</parameter> already contains data, the old data will
500
481
</simpara></listitem></varlistentry>
501
<varlistentry><term><parameter>terminator_pos</parameter> :</term>
502
<listitem><simpara> location to store position of line terminator, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
482
<varlistentry><term><parameter>terminator_pos</parameter> :</term>
483
<listitem><simpara> location to store position of line terminator, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
503
484
</simpara></listitem></varlistentry>
504
<varlistentry><term><parameter>error</parameter> :</term>
485
<varlistentry><term><parameter>error</parameter> :</term>
505
486
<listitem><simpara> a location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
506
487
or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
507
488
</simpara></listitem></varlistentry>
508
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
489
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
509
490
</simpara></listitem></varlistentry>
510
491
</variablelist></refsect2>
512
<title><anchor id="g-io-channel-read-to-end" role="function"/>g_io_channel_read_to_end ()</title>
513
<indexterm><primary>g_io_channel_read_to_end</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_to_end (<link linkend="GIOChannel">GIOChannel</link> *channel,
492
<refsect2 id="g-io-channel-read-to-end" role="function">
493
<title>g_io_channel_read_to_end ()</title>
494
<indexterm zone="g-io-channel-read-to-end"><primary sortas="g_io_channel_read_to_end">g_io_channel_read_to_end</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_read_to_end (<link linkend="GIOChannel">GIOChannel</link> *channel,
514
495
<link linkend="gchar">gchar</link> **str_return,
515
496
<link linkend="gsize">gsize</link> *length,
516
497
<link linkend="GError">GError</link> **error);</programlisting>
518
499
Reads all the remaining data from the file.</para>
521
501
</para><variablelist role="params">
522
<varlistentry><term><parameter>channel</parameter> :</term>
502
<varlistentry><term><parameter>channel</parameter> :</term>
523
503
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
524
504
</simpara></listitem></varlistentry>
525
<varlistentry><term><parameter>str_return</parameter> :</term>
505
<varlistentry><term><parameter>str_return</parameter> :</term>
526
506
<listitem><simpara> Location to store a pointer to a string holding
527
507
the remaining data in the <link linkend="GIOChannel"><type>GIOChannel</type></link>. This data should
528
508
be freed with <link linkend="g-free"><function>g_free()</function></link> when no longer needed. This
529
509
data is terminated by an extra nul character, but there
530
510
may be other nuls in the intervening data.
531
511
</simpara></listitem></varlistentry>
532
<varlistentry><term><parameter>length</parameter> :</term>
512
<varlistentry><term><parameter>length</parameter> :</term>
533
513
<listitem><simpara> location to store length of the data
534
514
</simpara></listitem></varlistentry>
535
<varlistentry><term><parameter>error</parameter> :</term>
515
<varlistentry><term><parameter>error</parameter> :</term>
536
516
<listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
537
517
or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
538
518
</simpara></listitem></varlistentry>
539
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> on success.
540
This function never returns <link linkend="G-IO-STATUS-EOF:CAPS"><literal>G_IO_STATUS_EOF</literal></link>.
519
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> on success.
520
This function never returns <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>.
541
521
</simpara></listitem></varlistentry>
542
522
</variablelist></refsect2>
544
<title><anchor id="g-io-channel-write-chars" role="function"/>g_io_channel_write_chars ()</title>
545
<indexterm><primary>g_io_channel_write_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,
523
<refsect2 id="g-io-channel-write-chars" role="function">
524
<title>g_io_channel_write_chars ()</title>
525
<indexterm zone="g-io-channel-write-chars"><primary sortas="g_io_channel_write_chars">g_io_channel_write_chars</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_chars (<link linkend="GIOChannel">GIOChannel</link> *channel,
546
526
const <link linkend="gchar">gchar</link> *buf,
547
527
<link linkend="gssize">gssize</link> count,
548
528
<link linkend="gsize">gsize</link> *bytes_written,
551
531
Replacement for <link linkend="g-io-channel-write"><function>g_io_channel_write()</function></link> with the new API.
554
On seekable channels with encodings other than <link linkend="NULL:CAPS"><literal>NULL</literal></link> or UTF-8, generic
534
On seekable channels with encodings other than <link linkend="NULL--CAPS"><literal>NULL</literal></link> or UTF-8, generic
555
535
mixing of reading and writing is not allowed. A call to <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link>
556
536
may only be made on a channel from which data has been read in the
557
537
cases described in the documentation for <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>.</para>
560
539
</para><variablelist role="params">
561
<varlistentry><term><parameter>channel</parameter> :</term>
540
<varlistentry><term><parameter>channel</parameter> :</term>
562
541
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
563
542
</simpara></listitem></varlistentry>
564
<varlistentry><term><parameter>buf</parameter> :</term>
543
<varlistentry><term><parameter>buf</parameter> :</term>
565
544
<listitem><simpara> a buffer to write data from
566
545
</simpara></listitem></varlistentry>
567
<varlistentry><term><parameter>count</parameter> :</term>
546
<varlistentry><term><parameter>count</parameter> :</term>
568
547
<listitem><simpara> the size of the buffer. If -1, the buffer
569
548
is taken to be a nul-terminated string.
570
549
</simpara></listitem></varlistentry>
571
<varlistentry><term><parameter>bytes_written</parameter> :</term>
550
<varlistentry><term><parameter>bytes_written</parameter> :</term>
572
551
<listitem><simpara> The number of bytes written. This can be nonzero
573
even if the return value is not <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.
574
If the return value is <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> and the
552
even if the return value is not <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link>.
553
If the return value is <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> and the
575
554
channel is blocking, this will always be equal
576
555
to <parameter>count</parameter> if <parameter>count</parameter> >= 0.
577
556
</simpara></listitem></varlistentry>
578
<varlistentry><term><parameter>error</parameter> :</term>
557
<varlistentry><term><parameter>error</parameter> :</term>
579
558
<listitem><simpara> a location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
580
559
or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
581
560
</simpara></listitem></varlistentry>
582
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
561
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
583
562
</simpara></listitem></varlistentry>
584
563
</variablelist></refsect2>
586
<title><anchor id="g-io-channel-write-unichar" role="function"/>g_io_channel_write_unichar ()</title>
587
<indexterm><primary>g_io_channel_write_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,
564
<refsect2 id="g-io-channel-write-unichar" role="function">
565
<title>g_io_channel_write_unichar ()</title>
566
<indexterm zone="g-io-channel-write-unichar"><primary sortas="g_io_channel_write_unichar">g_io_channel_write_unichar</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_write_unichar (<link linkend="GIOChannel">GIOChannel</link> *channel,
588
567
<link linkend="gunichar">gunichar</link> thechar,
589
568
<link linkend="GError">GError</link> **error);</programlisting>
591
570
Writes a Unicode character to <parameter>channel</parameter>.
592
This function cannot be called on a channel with <link linkend="NULL:CAPS"><literal>NULL</literal></link> encoding.</para>
571
This function cannot be called on a channel with <link linkend="NULL--CAPS"><literal>NULL</literal></link> encoding.</para>
595
573
</para><variablelist role="params">
596
<varlistentry><term><parameter>channel</parameter> :</term>
574
<varlistentry><term><parameter>channel</parameter> :</term>
597
575
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
598
576
</simpara></listitem></varlistentry>
599
<varlistentry><term><parameter>thechar</parameter> :</term>
577
<varlistentry><term><parameter>thechar</parameter> :</term>
600
578
<listitem><simpara> a character
601
579
</simpara></listitem></varlistentry>
602
<varlistentry><term><parameter>error</parameter> :</term>
580
<varlistentry><term><parameter>error</parameter> :</term>
603
581
<listitem><simpara> location to return an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
604
582
or <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
605
583
</simpara></listitem></varlistentry>
606
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
584
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOStatus"><type>GIOStatus</type></link>
607
585
</simpara></listitem></varlistentry>
608
586
</variablelist></refsect2>
610
<title><anchor id="g-io-channel-flush" role="function"/>g_io_channel_flush ()</title>
611
<indexterm><primary>g_io_channel_flush</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_flush (<link linkend="GIOChannel">GIOChannel</link> *channel,
587
<refsect2 id="g-io-channel-flush" role="function">
588
<title>g_io_channel_flush ()</title>
589
<indexterm zone="g-io-channel-flush"><primary sortas="g_io_channel_flush">g_io_channel_flush</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_flush (<link linkend="GIOChannel">GIOChannel</link> *channel,
612
590
<link linkend="GError">GError</link> **error);</programlisting>
614
592
Flushes the write buffer for the GIOChannel.</para>
617
594
</para><variablelist role="params">
618
<varlistentry><term><parameter>channel</parameter> :</term>
595
<varlistentry><term><parameter>channel</parameter> :</term>
619
596
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
620
597
</simpara></listitem></varlistentry>
621
<varlistentry><term><parameter>error</parameter> :</term>
598
<varlistentry><term><parameter>error</parameter> :</term>
622
599
<listitem><simpara> location to store an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
623
600
</simpara></listitem></varlistentry>
624
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation: One of
625
<link linkend="G-IO-CHANNEL-NORMAL:CAPS"><type>G_IO_CHANNEL_NORMAL</type></link>, <link linkend="G-IO-CHANNEL-AGAIN:CAPS"><type>G_IO_CHANNEL_AGAIN</type></link>, or
626
<link linkend="G-IO-CHANNEL-ERROR:CAPS"><type>G_IO_CHANNEL_ERROR</type></link>.
601
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation: One of
602
<link linkend="G-IO-CHANNEL-NORMAL--CAPS"><type>G_IO_CHANNEL_NORMAL</type></link>, <link linkend="G-IO-CHANNEL-AGAIN--CAPS"><type>G_IO_CHANNEL_AGAIN</type></link>, or
603
<link linkend="G-IO-CHANNEL-ERROR--CAPS"><type>G_IO_CHANNEL_ERROR</type></link>.
627
604
</simpara></listitem></varlistentry>
628
605
</variablelist></refsect2>
630
<title><anchor id="g-io-channel-seek-position" role="function"/>g_io_channel_seek_position ()</title>
631
<indexterm><primary>g_io_channel_seek_position</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_seek_position (<link linkend="GIOChannel">GIOChannel</link> *channel,
606
<refsect2 id="g-io-channel-seek-position" role="function">
607
<title>g_io_channel_seek_position ()</title>
608
<indexterm zone="g-io-channel-seek-position"><primary sortas="g_io_channel_seek_position">g_io_channel_seek_position</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_seek_position (<link linkend="GIOChannel">GIOChannel</link> *channel,
632
609
<link linkend="gint64">gint64</link> offset,
633
610
<link linkend="GSeekType">GSeekType</link> type,
634
611
<link linkend="GError">GError</link> **error);</programlisting>
636
613
Replacement for <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link> with the new API.</para>
639
615
</para><variablelist role="params">
640
<varlistentry><term><parameter>channel</parameter> :</term>
616
<varlistentry><term><parameter>channel</parameter> :</term>
641
617
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
642
618
</simpara></listitem></varlistentry>
643
<varlistentry><term><parameter>offset</parameter> :</term>
619
<varlistentry><term><parameter>offset</parameter> :</term>
644
620
<listitem><simpara> The offset in bytes from the position specified by <parameter>type</parameter>
645
621
</simpara></listitem></varlistentry>
646
<varlistentry><term><parameter>type</parameter> :</term>
647
<listitem><simpara> a <link linkend="GSeekType"><type>GSeekType</type></link>. The type <link linkend="G-SEEK-CUR:CAPS"><literal>G_SEEK_CUR</literal></link> is only allowed in those
622
<varlistentry><term><parameter>type</parameter> :</term>
623
<listitem><simpara> a <link linkend="GSeekType"><type>GSeekType</type></link>. The type <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link> is only allowed in those
648
624
cases where a call to <link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link>
649
625
is allowed. See the documentation for
650
626
<link linkend="g-io-channel-set-encoding"><function>g_io_channel_set_encoding()</function></link> for details.
651
627
</simpara></listitem></varlistentry>
652
<varlistentry><term><parameter>error</parameter> :</term>
628
<varlistentry><term><parameter>error</parameter> :</term>
653
629
<listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
654
630
</simpara></listitem></varlistentry>
655
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
631
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
656
632
</simpara></listitem></varlistentry>
657
633
</variablelist></refsect2>
659
<title><anchor id="GSeekType" role="enum"/>enum GSeekType</title>
660
<indexterm><primary>GSeekType</primary></indexterm><programlisting>typedef enum
634
<refsect2 id="GSeekType" role="enum">
635
<title>enum GSeekType</title>
636
<indexterm zone="GSeekType"><primary sortas="GSeekType">GSeekType</primary></indexterm><programlisting>typedef enum
668
644
An enumeration specifying the base position for a <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>
670
646
</para><variablelist role="enum">
672
<term><anchor id="G-SEEK-CUR:CAPS" role="constant"/><literal>G_SEEK_CUR</literal></term>
647
<varlistentry id="G-SEEK-CUR--CAPS" role="constant">
648
<term><literal>G_SEEK_CUR</literal></term>
673
649
<listitem><simpara>the current position in the file.
674
650
</simpara></listitem>
677
<term><anchor id="G-SEEK-SET:CAPS" role="constant"/><literal>G_SEEK_SET</literal></term>
652
<varlistentry id="G-SEEK-SET--CAPS" role="constant">
653
<term><literal>G_SEEK_SET</literal></term>
678
654
<listitem><simpara>the start of the file.
679
655
</simpara></listitem>
682
<term><anchor id="G-SEEK-END:CAPS" role="constant"/><literal>G_SEEK_END</literal></term>
657
<varlistentry id="G-SEEK-END--CAPS" role="constant">
658
<term><literal>G_SEEK_END</literal></term>
683
659
<listitem><simpara>the end of the file.
685
660
</simpara></listitem>
687
662
</variablelist></refsect2>
689
<title><anchor id="g-io-channel-shutdown" role="function"/>g_io_channel_shutdown ()</title>
690
<indexterm><primary>g_io_channel_shutdown</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_shutdown (<link linkend="GIOChannel">GIOChannel</link> *channel,
663
<refsect2 id="g-io-channel-shutdown" role="function">
664
<title>g_io_channel_shutdown ()</title>
665
<indexterm zone="g-io-channel-shutdown"><primary sortas="g_io_channel_shutdown">g_io_channel_shutdown</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_shutdown (<link linkend="GIOChannel">GIOChannel</link> *channel,
691
666
<link linkend="gboolean">gboolean</link> flush,
692
667
<link linkend="GError">GError</link> **err);</programlisting>
694
669
Close an IO channel. Any pending data to be written will be
695
flushed if <parameter>flush</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>. The channel will not be freed until the
670
flushed if <parameter>flush</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. The channel will not be freed until the
696
671
last reference is dropped using <link linkend="g-io-channel-unref"><function>g_io_channel_unref()</function></link>.</para>
699
673
</para><variablelist role="params">
700
<varlistentry><term><parameter>channel</parameter> :</term>
674
<varlistentry><term><parameter>channel</parameter> :</term>
701
675
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
702
676
</simpara></listitem></varlistentry>
703
<varlistentry><term><parameter>flush</parameter> :</term>
704
<listitem><simpara> if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, flush pending
677
<varlistentry><term><parameter>flush</parameter> :</term>
678
<listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, flush pending
705
679
</simpara></listitem></varlistentry>
706
<varlistentry><term><parameter>err</parameter> :</term>
680
<varlistentry><term><parameter>err</parameter> :</term>
707
681
<listitem><simpara> location to store a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
708
682
</simpara></listitem></varlistentry>
709
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
683
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
710
684
</simpara></listitem></varlistentry>
711
685
</variablelist></refsect2>
713
<title><anchor id="GIOStatus" role="enum"/>enum GIOStatus</title>
714
<indexterm><primary>GIOStatus</primary></indexterm><programlisting>typedef enum
686
<refsect2 id="GIOStatus" role="enum">
687
<title>enum GIOStatus</title>
688
<indexterm zone="GIOStatus"><primary sortas="GIOStatus">GIOStatus</primary></indexterm><programlisting>typedef enum
716
690
G_IO_STATUS_ERROR,
717
691
G_IO_STATUS_NORMAL,
765
738
Error codes returned by <link linkend="GIOChannel"><type>GIOChannel</type></link> operations.
766
739
</para><variablelist role="enum">
768
<term><anchor id="G-IO-CHANNEL-ERROR-FBIG:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_FBIG</literal></term>
740
<varlistentry id="G-IO-CHANNEL-ERROR-FBIG--CAPS" role="constant">
741
<term><literal>G_IO_CHANNEL_ERROR_FBIG</literal></term>
769
742
<listitem><simpara>File too large.
770
743
</simpara></listitem>
773
<term><anchor id="G-IO-CHANNEL-ERROR-INVAL:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_INVAL</literal></term>
745
<varlistentry id="G-IO-CHANNEL-ERROR-INVAL--CAPS" role="constant">
746
<term><literal>G_IO_CHANNEL_ERROR_INVAL</literal></term>
774
747
<listitem><simpara>Invalid argument.
775
748
</simpara></listitem>
778
<term><anchor id="G-IO-CHANNEL-ERROR-IO:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_IO</literal></term>
750
<varlistentry id="G-IO-CHANNEL-ERROR-IO--CAPS" role="constant">
751
<term><literal>G_IO_CHANNEL_ERROR_IO</literal></term>
779
752
<listitem><simpara>IO error.
780
753
</simpara></listitem>
783
<term><anchor id="G-IO-CHANNEL-ERROR-ISDIR:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_ISDIR</literal></term>
755
<varlistentry id="G-IO-CHANNEL-ERROR-ISDIR--CAPS" role="constant">
756
<term><literal>G_IO_CHANNEL_ERROR_ISDIR</literal></term>
784
757
<listitem><simpara>File is a directory.
785
758
</simpara></listitem>
788
<term><anchor id="G-IO-CHANNEL-ERROR-NOSPC:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_NOSPC</literal></term>
760
<varlistentry id="G-IO-CHANNEL-ERROR-NOSPC--CAPS" role="constant">
761
<term><literal>G_IO_CHANNEL_ERROR_NOSPC</literal></term>
789
762
<listitem><simpara>No space left on device.
790
763
</simpara></listitem>
793
<term><anchor id="G-IO-CHANNEL-ERROR-NXIO:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_NXIO</literal></term>
765
<varlistentry id="G-IO-CHANNEL-ERROR-NXIO--CAPS" role="constant">
766
<term><literal>G_IO_CHANNEL_ERROR_NXIO</literal></term>
794
767
<listitem><simpara>No such device or address.
795
768
</simpara></listitem>
798
<term><anchor id="G-IO-CHANNEL-ERROR-OVERFLOW:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_OVERFLOW</literal></term>
770
<varlistentry id="G-IO-CHANNEL-ERROR-OVERFLOW--CAPS" role="constant">
771
<term><literal>G_IO_CHANNEL_ERROR_OVERFLOW</literal></term>
799
772
<listitem><simpara>Value too large for defined datatype.
800
773
</simpara></listitem>
803
<term><anchor id="G-IO-CHANNEL-ERROR-PIPE:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_PIPE</literal></term>
775
<varlistentry id="G-IO-CHANNEL-ERROR-PIPE--CAPS" role="constant">
776
<term><literal>G_IO_CHANNEL_ERROR_PIPE</literal></term>
804
777
<listitem><simpara>Broken pipe.
805
778
</simpara></listitem>
808
<term><anchor id="G-IO-CHANNEL-ERROR-FAILED:CAPS" role="constant"/><literal>G_IO_CHANNEL_ERROR_FAILED</literal></term>
780
<varlistentry id="G-IO-CHANNEL-ERROR-FAILED--CAPS" role="constant">
781
<term><literal>G_IO_CHANNEL_ERROR_FAILED</literal></term>
809
782
<listitem><simpara>Some other error.
811
783
</simpara></listitem>
813
785
</variablelist></refsect2>
815
<title><anchor id="G-IO-CHANNEL-ERROR:CAPS" role="macro"/>G_IO_CHANNEL_ERROR</title>
816
<indexterm><primary>G_IO_CHANNEL_ERROR</primary></indexterm><programlisting>#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()
786
<refsect2 id="G-IO-CHANNEL-ERROR--CAPS" role="macro">
787
<title>G_IO_CHANNEL_ERROR</title>
788
<indexterm zone="G-IO-CHANNEL-ERROR--CAPS"><primary sortas="G_IO_CHANNEL_ERROR">G_IO_CHANNEL_ERROR</primary></indexterm><programlisting>#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()
817
789
</programlisting>
819
791
Error domain for <link linkend="GIOChannel"><type>GIOChannel</type></link> operations. Errors in this domain will
820
792
be from the <link linkend="GIOChannelError"><type>GIOChannelError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
822
794
</para></refsect2>
824
<title><anchor id="g-io-channel-error-from-errno" role="function"/>g_io_channel_error_from_errno ()</title>
825
<indexterm><primary>g_io_channel_error_from_errno</primary></indexterm><programlisting><link linkend="GIOChannelError">GIOChannelError</link> g_io_channel_error_from_errno (<link linkend="gint">gint</link> en);</programlisting>
795
<refsect2 id="g-io-channel-error-from-errno" role="function">
796
<title>g_io_channel_error_from_errno ()</title>
797
<indexterm zone="g-io-channel-error-from-errno"><primary sortas="g_io_channel_error_from_errno">g_io_channel_error_from_errno</primary></indexterm><programlisting><link linkend="GIOChannelError">GIOChannelError</link> g_io_channel_error_from_errno (<link linkend="gint">gint</link> en);</programlisting>
827
799
Converts an <literal>errno</literal> error number to a <link linkend="GIOChannelError"><type>GIOChannelError</type></link>.</para>
830
801
</para><variablelist role="params">
831
<varlistentry><term><parameter>en</parameter> :</term>
832
<listitem><simpara> an <literal>errno</literal> error number, e.g. <link linkend="EINVAL:CAPS"><literal>EINVAL</literal></link>
802
<varlistentry><term><parameter>en</parameter> :</term>
803
<listitem><simpara> an <literal>errno</literal> error number, e.g. <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link>
833
804
</simpara></listitem></varlistentry>
834
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOChannelError"><type>GIOChannelError</type></link> error number, e.g.
835
<link linkend="G-IO-CHANNEL-ERROR-INVAL:CAPS"><literal>G_IO_CHANNEL_ERROR_INVAL</literal></link>.
805
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GIOChannelError"><type>GIOChannelError</type></link> error number, e.g.
806
<link linkend="G-IO-CHANNEL-ERROR-INVAL--CAPS"><literal>G_IO_CHANNEL_ERROR_INVAL</literal></link>.
836
807
</simpara></listitem></varlistentry>
837
808
</variablelist></refsect2>
839
<title><anchor id="g-io-channel-ref" role="function"/>g_io_channel_ref ()</title>
840
<indexterm><primary>g_io_channel_ref</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link>* g_io_channel_ref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
809
<refsect2 id="g-io-channel-ref" role="function">
810
<title>g_io_channel_ref ()</title>
811
<indexterm zone="g-io-channel-ref"><primary sortas="g_io_channel_ref">g_io_channel_ref</primary></indexterm><programlisting><link linkend="GIOChannel">GIOChannel</link> * g_io_channel_ref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
842
813
Increments the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
843
814
</para><variablelist role="params">
844
<varlistentry><term><parameter>channel</parameter> :</term>
815
<varlistentry><term><parameter>channel</parameter> :</term>
845
816
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
846
817
</simpara></listitem></varlistentry>
847
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <parameter>channel</parameter> that was passed in (since 2.6)
818
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <parameter>channel</parameter> that was passed in (since 2.6)
850
819
</simpara></listitem></varlistentry>
851
820
</variablelist></refsect2>
853
<title><anchor id="g-io-channel-unref" role="function"/>g_io_channel_unref ()</title>
854
<indexterm><primary>g_io_channel_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
821
<refsect2 id="g-io-channel-unref" role="function">
822
<title>g_io_channel_unref ()</title>
823
<indexterm zone="g-io-channel-unref"><primary sortas="g_io_channel_unref">g_io_channel_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
856
825
Decrements the reference count of a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
857
826
</para><variablelist role="params">
858
<varlistentry><term><parameter>channel</parameter> :</term>
827
<varlistentry><term><parameter>channel</parameter> :</term>
859
828
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
862
829
</simpara></listitem></varlistentry>
863
830
</variablelist></refsect2>
865
<title><anchor id="g-io-create-watch" role="function"/>g_io_create_watch ()</title>
866
<indexterm><primary>g_io_create_watch</primary></indexterm><programlisting><link linkend="GSource">GSource</link>* g_io_create_watch (<link linkend="GIOChannel">GIOChannel</link> *channel,
831
<refsect2 id="g-io-create-watch" role="function">
832
<title>g_io_create_watch ()</title>
833
<indexterm zone="g-io-create-watch"><primary sortas="g_io_create_watch">g_io_create_watch</primary></indexterm><programlisting><link linkend="GSource">GSource</link> * g_io_create_watch (<link linkend="GIOChannel">GIOChannel</link> *channel,
867
834
<link linkend="GIOCondition">GIOCondition</link> condition);</programlisting>
869
836
Creates a <link linkend="GSource"><type>GSource</type></link> that's dispatched when <parameter>condition</parameter> is met for the given
870
<parameter>channel</parameter>. For example, if condition is <link linkend="G-IO-IN:CAPS"><type>G_IO_IN</type></link>, the source will be dispatched
837
<parameter>channel</parameter>. For example, if condition is <link linkend="G-IO-IN--CAPS"><type>G_IO_IN</type></link>, the source will be dispatched
871
838
when there's data available for reading. <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> is a simpler
872
839
interface to this same functionality, for the case where you want to add the
873
840
source to the default main loop at the default priority.
899
864
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
900
865
with the default priority.
901
866
</para><variablelist role="params">
902
<varlistentry><term><parameter>channel</parameter> :</term>
867
<varlistentry><term><parameter>channel</parameter> :</term>
903
868
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>
904
869
</simpara></listitem></varlistentry>
905
<varlistentry><term><parameter>condition</parameter> :</term>
870
<varlistentry><term><parameter>condition</parameter> :</term>
906
871
<listitem><simpara>the condition to watch for
907
872
</simpara></listitem></varlistentry>
908
<varlistentry><term><parameter>func</parameter> :</term>
873
<varlistentry><term><parameter>func</parameter> :</term>
909
874
<listitem><simpara>the function to call when the condition is satisfied
910
875
</simpara></listitem></varlistentry>
911
<varlistentry><term><parameter>user_data</parameter> :</term>
876
<varlistentry><term><parameter>user_data</parameter> :</term>
912
877
<listitem><simpara>user data to pass to <parameter>func</parameter>
913
878
</simpara></listitem></varlistentry>
914
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id
879
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id
917
880
</simpara></listitem></varlistentry>
918
881
</variablelist></refsect2>
920
<title><anchor id="g-io-add-watch-full" role="function"/>g_io_add_watch_full ()</title>
921
<indexterm><primary>g_io_add_watch_full</primary></indexterm><programlisting><link linkend="guint">guint</link> g_io_add_watch_full (<link linkend="GIOChannel">GIOChannel</link> *channel,
882
<refsect2 id="g-io-add-watch-full" role="function">
883
<title>g_io_add_watch_full ()</title>
884
<indexterm zone="g-io-add-watch-full"><primary sortas="g_io_add_watch_full">g_io_add_watch_full</primary></indexterm><programlisting><link linkend="guint">guint</link> g_io_add_watch_full (<link linkend="GIOChannel">GIOChannel</link> *channel,
922
885
<link linkend="gint">gint</link> priority,
923
886
<link linkend="GIOCondition">GIOCondition</link> condition,
924
887
<link linkend="GIOFunc">GIOFunc</link> func,
929
892
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
930
893
with the given priority.
931
894
</para><variablelist role="params">
932
<varlistentry><term><parameter>channel</parameter> :</term>
895
<varlistentry><term><parameter>channel</parameter> :</term>
933
896
<listitem><simpara>a <link linkend="GIOChannel"><type>GIOChannel</type></link>
934
897
</simpara></listitem></varlistentry>
935
<varlistentry><term><parameter>priority</parameter> :</term>
898
<varlistentry><term><parameter>priority</parameter> :</term>
936
899
<listitem><simpara>the priority of the <link linkend="GIOChannel"><type>GIOChannel</type></link> source
937
900
</simpara></listitem></varlistentry>
938
<varlistentry><term><parameter>condition</parameter> :</term>
901
<varlistentry><term><parameter>condition</parameter> :</term>
939
902
<listitem><simpara>the condition to watch for
940
903
</simpara></listitem></varlistentry>
941
<varlistentry><term><parameter>func</parameter> :</term>
904
<varlistentry><term><parameter>func</parameter> :</term>
942
905
<listitem><simpara>the function to call when the condition is satisfied
943
906
</simpara></listitem></varlistentry>
944
<varlistentry><term><parameter>user_data</parameter> :</term>
907
<varlistentry><term><parameter>user_data</parameter> :</term>
945
908
<listitem><simpara>user data to pass to <parameter>func</parameter>
946
909
</simpara></listitem></varlistentry>
947
<varlistentry><term><parameter>notify</parameter> :</term>
910
<varlistentry><term><parameter>notify</parameter> :</term>
948
911
<listitem><simpara>the function to call when the source is removed
949
912
</simpara></listitem></varlistentry>
950
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id
913
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the event source id
953
914
</simpara></listitem></varlistentry>
954
915
</variablelist></refsect2>
956
<title><anchor id="GIOCondition" role="enum"/>enum GIOCondition</title>
957
<indexterm><primary>GIOCondition</primary></indexterm><programlisting>typedef enum
916
<refsect2 id="GIOCondition" role="enum">
917
<title>enum GIOCondition</title>
918
<indexterm zone="GIOCondition"><primary sortas="GIOCondition">GIOCondition</primary></indexterm><programlisting>typedef enum
959
920
G_IO_IN GLIB_SYSDEF_POLLIN,
960
921
G_IO_OUT GLIB_SYSDEF_POLLOUT,
966
927
</programlisting>
968
A bitwise combination representing a condition to watch for on
929
A bitwise combination representing a condition to watch for on
970
931
</para><variablelist role="enum">
972
<term><anchor id="G-IO-IN:CAPS" role="constant"/><literal>G_IO_IN</literal></term>
932
<varlistentry id="G-IO-IN--CAPS" role="constant">
933
<term><literal>G_IO_IN</literal></term>
973
934
<listitem><simpara>There is data to read.
974
935
</simpara></listitem>
977
<term><anchor id="G-IO-OUT:CAPS" role="constant"/><literal>G_IO_OUT</literal></term>
937
<varlistentry id="G-IO-OUT--CAPS" role="constant">
938
<term><literal>G_IO_OUT</literal></term>
978
939
<listitem><simpara>Data can be written (without blocking).
979
940
</simpara></listitem>
982
<term><anchor id="G-IO-PRI:CAPS" role="constant"/><literal>G_IO_PRI</literal></term>
942
<varlistentry id="G-IO-PRI--CAPS" role="constant">
943
<term><literal>G_IO_PRI</literal></term>
983
944
<listitem><simpara>There is urgent data to read.
984
945
</simpara></listitem>
987
<term><anchor id="G-IO-ERR:CAPS" role="constant"/><literal>G_IO_ERR</literal></term>
947
<varlistentry id="G-IO-ERR--CAPS" role="constant">
948
<term><literal>G_IO_ERR</literal></term>
988
949
<listitem><simpara>Error condition.
989
950
</simpara></listitem>
992
<term><anchor id="G-IO-HUP:CAPS" role="constant"/><literal>G_IO_HUP</literal></term>
952
<varlistentry id="G-IO-HUP--CAPS" role="constant">
953
<term><literal>G_IO_HUP</literal></term>
993
954
<listitem><simpara>Hung up (the connection has been broken, usually for pipes
995
956
</simpara></listitem>
998
<term><anchor id="G-IO-NVAL:CAPS" role="constant"/><literal>G_IO_NVAL</literal></term>
958
<varlistentry id="G-IO-NVAL--CAPS" role="constant">
959
<term><literal>G_IO_NVAL</literal></term>
999
960
<listitem><simpara>Invalid request. The file descriptor is not open.
1001
961
</simpara></listitem>
1003
963
</variablelist></refsect2>
1005
<title><anchor id="GIOFunc" role="function"/>GIOFunc ()</title>
1006
<indexterm><primary>GIOFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*GIOFunc) (<link linkend="GIOChannel">GIOChannel</link> *source,
964
<refsect2 id="GIOFunc" role="function">
965
<title>GIOFunc ()</title>
966
<indexterm zone="GIOFunc"><primary sortas="GIOFunc">GIOFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*GIOFunc) (<link linkend="GIOChannel">GIOChannel</link> *source,
1007
967
<link linkend="GIOCondition">GIOCondition</link> condition,
1008
968
<link linkend="gpointer">gpointer</link> data);</programlisting>
1010
970
Specifies the type of function passed to <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or
1011
<link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>, which is called when the requested
971
<link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>, which is called when the requested
1012
972
condition on a <link linkend="GIOChannel"><type>GIOChannel</type></link> is satisfied.
1013
973
</para><variablelist role="params">
1014
<varlistentry><term><parameter>source</parameter> :</term>
974
<varlistentry><term><parameter>source</parameter> :</term>
1015
975
<listitem><simpara>the <link linkend="GIOChannel"><type>GIOChannel</type></link> event source
1016
976
</simpara></listitem></varlistentry>
1017
<varlistentry><term><parameter>condition</parameter> :</term>
977
<varlistentry><term><parameter>condition</parameter> :</term>
1018
978
<listitem><simpara>the condition which has been satisfied
1019
979
</simpara></listitem></varlistentry>
1020
<varlistentry><term><parameter>data</parameter> :</term>
980
<varlistentry><term><parameter>data</parameter> :</term>
1021
981
<listitem><simpara>user data set in <link linkend="g-io-add-watch"><function>g_io_add_watch()</function></link> or <link linkend="g-io-add-watch-full"><function>g_io_add_watch_full()</function></link>
1022
982
</simpara></listitem></varlistentry>
1023
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the function should return <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the event source
983
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the function should return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the event source
1024
984
should be removed
1027
985
</simpara></listitem></varlistentry>
1028
986
</variablelist></refsect2>
1030
<title><anchor id="GIOFuncs" role="struct"/>GIOFuncs</title>
1031
<indexterm><primary>GIOFuncs</primary></indexterm><programlisting>typedef struct {
987
<refsect2 id="GIOFuncs" role="struct">
988
<title>GIOFuncs</title>
989
<indexterm zone="GIOFuncs"><primary sortas="GIOFuncs">GIOFuncs</primary></indexterm><programlisting>typedef struct {
1032
990
GIOStatus (*io_read) (GIOChannel *channel,
1056
1014
</programlisting>
1058
A table of functions used to handle different types of <link linkend="GIOChannel"><type>GIOChannel</type></link>
1016
A table of functions used to handle different types of <link linkend="GIOChannel"><type>GIOChannel</type></link>
1059
1017
in a generic way.
1060
1018
</para></refsect2>
1062
<title><anchor id="g-io-channel-get-buffer-size" role="function"/>g_io_channel_get_buffer_size ()</title>
1063
<indexterm><primary>g_io_channel_get_buffer_size</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_io_channel_get_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1019
<refsect2 id="g-io-channel-get-buffer-size" role="function">
1020
<title>g_io_channel_get_buffer_size ()</title>
1021
<indexterm zone="g-io-channel-get-buffer-size"><primary sortas="g_io_channel_get_buffer_size">g_io_channel_get_buffer_size</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_io_channel_get_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1065
1023
Gets the buffer size.</para>
1068
1025
</para><variablelist role="params">
1069
<varlistentry><term><parameter>channel</parameter> :</term>
1026
<varlistentry><term><parameter>channel</parameter> :</term>
1070
1027
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1071
1028
</simpara></listitem></varlistentry>
1072
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the size of the buffer.
1029
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the size of the buffer.
1073
1030
</simpara></listitem></varlistentry>
1074
1031
</variablelist></refsect2>
1076
<title><anchor id="g-io-channel-set-buffer-size" role="function"/>g_io_channel_set_buffer_size ()</title>
1077
<indexterm><primary>g_io_channel_set_buffer_size</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel,
1032
<refsect2 id="g-io-channel-set-buffer-size" role="function">
1033
<title>g_io_channel_set_buffer_size ()</title>
1034
<indexterm zone="g-io-channel-set-buffer-size"><primary sortas="g_io_channel_set_buffer_size">g_io_channel_set_buffer_size</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffer_size (<link linkend="GIOChannel">GIOChannel</link> *channel,
1078
1035
<link linkend="gsize">gsize</link> size);</programlisting>
1080
1037
Sets the buffer size.</para>
1083
1039
</para><variablelist role="params">
1084
<varlistentry><term><parameter>channel</parameter> :</term>
1040
<varlistentry><term><parameter>channel</parameter> :</term>
1085
1041
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1086
1042
</simpara></listitem></varlistentry>
1087
<varlistentry><term><parameter>size</parameter> :</term>
1043
<varlistentry><term><parameter>size</parameter> :</term>
1088
1044
<listitem><simpara> the size of the buffer, or 0 to let GLib pick a good size
1089
1045
</simpara></listitem></varlistentry>
1090
1046
</variablelist></refsect2>
1092
<title><anchor id="g-io-channel-get-buffer-condition" role="function"/>g_io_channel_get_buffer_condition ()</title>
1093
<indexterm><primary>g_io_channel_get_buffer_condition</primary></indexterm><programlisting><link linkend="GIOCondition">GIOCondition</link> g_io_channel_get_buffer_condition (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1047
<refsect2 id="g-io-channel-get-buffer-condition" role="function">
1048
<title>g_io_channel_get_buffer_condition ()</title>
1049
<indexterm zone="g-io-channel-get-buffer-condition"><primary sortas="g_io_channel_get_buffer_condition">g_io_channel_get_buffer_condition</primary></indexterm><programlisting><link linkend="GIOCondition">GIOCondition</link> g_io_channel_get_buffer_condition (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1095
1051
This function returns a <link linkend="GIOCondition"><type>GIOCondition</type></link> depending on whether there
1096
1052
is data to be read/space to write data in the internal buffers in
1097
the <link linkend="GIOChannel"><type>GIOChannel</type></link>. Only the flags <link linkend="G-IO-IN:CAPS"><literal>G_IO_IN</literal></link> and <link linkend="G-IO-OUT:CAPS"><literal>G_IO_OUT</literal></link> may be set.</para>
1053
the <link linkend="GIOChannel"><type>GIOChannel</type></link>. Only the flags <link linkend="G-IO-IN--CAPS"><literal>G_IO_IN</literal></link> and <link linkend="G-IO-OUT--CAPS"><literal>G_IO_OUT</literal></link> may be set.</para>
1100
1055
</para><variablelist role="params">
1101
<varlistentry><term><parameter>channel</parameter> :</term>
1056
<varlistentry><term><parameter>channel</parameter> :</term>
1102
1057
<listitem><simpara> A <link linkend="GIOChannel"><type>GIOChannel</type></link>
1103
1058
</simpara></listitem></varlistentry>
1104
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOCondition"><type>GIOCondition</type></link>
1059
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GIOCondition"><type>GIOCondition</type></link>
1105
1060
</simpara></listitem></varlistentry>
1106
1061
</variablelist></refsect2>
1108
<title><anchor id="g-io-channel-get-flags" role="function"/>g_io_channel_get_flags ()</title>
1109
<indexterm><primary>g_io_channel_get_flags</primary></indexterm><programlisting><link linkend="GIOFlags">GIOFlags</link> g_io_channel_get_flags (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1062
<refsect2 id="g-io-channel-get-flags" role="function">
1063
<title>g_io_channel_get_flags ()</title>
1064
<indexterm zone="g-io-channel-get-flags"><primary sortas="g_io_channel_get_flags">g_io_channel_get_flags</primary></indexterm><programlisting><link linkend="GIOFlags">GIOFlags</link> g_io_channel_get_flags (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1111
1066
Gets the current flags for a <link linkend="GIOChannel"><type>GIOChannel</type></link>, including read-only
1112
flags such as <link linkend="G-IO-FLAG-IS-READABLE:CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link>.
1067
flags such as <link linkend="G-IO-FLAG-IS-READABLE--CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link>.
1115
The values of the flags <link linkend="G-IO-FLAG-IS-READABLE:CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link> and <link linkend="G-IO-FLAG-IS-WRITEABLE:CAPS"><literal>G_IO_FLAG_IS_WRITEABLE</literal></link>
1070
The values of the flags <link linkend="G-IO-FLAG-IS-READABLE--CAPS"><literal>G_IO_FLAG_IS_READABLE</literal></link> and <link linkend="G-IO-FLAG-IS-WRITEABLE--CAPS"><literal>G_IO_FLAG_IS_WRITEABLE</literal></link>
1116
1071
are cached for internal use by the channel when it is created.
1117
1072
If they should change at some later point (e.g. partial shutdown
1118
1073
of a socket with the UNIX <link linkend="shutdown"><function>shutdown()</function></link> function), the user
1119
1074
should immediately call <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link> to update
1120
1075
the internal values of these flags.</para>
1123
1077
</para><variablelist role="params">
1124
<varlistentry><term><parameter>channel</parameter> :</term>
1078
<varlistentry><term><parameter>channel</parameter> :</term>
1125
1079
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1126
1080
</simpara></listitem></varlistentry>
1127
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the flags which are set on the channel
1081
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the flags which are set on the channel
1128
1082
</simpara></listitem></varlistentry>
1129
1083
</variablelist></refsect2>
1131
<title><anchor id="g-io-channel-set-flags" role="function"/>g_io_channel_set_flags ()</title>
1132
<indexterm><primary>g_io_channel_set_flags</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_flags (<link linkend="GIOChannel">GIOChannel</link> *channel,
1084
<refsect2 id="g-io-channel-set-flags" role="function">
1085
<title>g_io_channel_set_flags ()</title>
1086
<indexterm zone="g-io-channel-set-flags"><primary sortas="g_io_channel_set_flags">g_io_channel_set_flags</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_flags (<link linkend="GIOChannel">GIOChannel</link> *channel,
1133
1087
<link linkend="GIOFlags">GIOFlags</link> flags,
1134
1088
<link linkend="GError">GError</link> **error);</programlisting>
1136
Sets the (writeable) flags in <parameter>channel</parameter> to (<parameter>flags</parameter> & <link linkend="G-IO-CHANNEL-SET-MASK:CAPS"><literal>G_IO_CHANNEL_SET_MASK</literal></link>).</para>
1090
Sets the (writeable) flags in <parameter>channel</parameter> to (<parameter>flags</parameter> & <link linkend="G-IO-CHANNEL-SET-MASK--CAPS"><literal>G_IO_CHANNEL_SET_MASK</literal></link>).</para>
1139
1092
</para><variablelist role="params">
1140
<varlistentry><term><parameter>channel</parameter> :</term>
1093
<varlistentry><term><parameter>channel</parameter> :</term>
1141
1094
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1142
1095
</simpara></listitem></varlistentry>
1143
<varlistentry><term><parameter>flags</parameter> :</term>
1096
<varlistentry><term><parameter>flags</parameter> :</term>
1144
1097
<listitem><simpara> the flags to set on the IO channel
1145
1098
</simpara></listitem></varlistentry>
1146
<varlistentry><term><parameter>error</parameter> :</term>
1099
<varlistentry><term><parameter>error</parameter> :</term>
1147
1100
<listitem><simpara> A location to return an error of type <link linkend="GIOChannelError"><type>GIOChannelError</type></link>
1148
1101
</simpara></listitem></varlistentry>
1149
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
1102
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the status of the operation.
1150
1103
</simpara></listitem></varlistentry>
1151
1104
</variablelist></refsect2>
1153
<title><anchor id="GIOFlags" role="enum"/>enum GIOFlags</title>
1154
<indexterm><primary>GIOFlags</primary></indexterm><programlisting>typedef enum
1105
<refsect2 id="GIOFlags" role="enum">
1106
<title>enum GIOFlags</title>
1107
<indexterm zone="GIOFlags"><primary sortas="GIOFlags">GIOFlags</primary></indexterm><programlisting>typedef enum
1156
1109
G_IO_FLAG_APPEND = 1 << 0,
1157
1110
G_IO_FLAG_NONBLOCK = 1 << 1,
1167
1120
Specifies properties of a <link linkend="GIOChannel"><type>GIOChannel</type></link>. Some of the flags can only
1168
1121
be read with <link linkend="g-io-channel-get-flags"><function>g_io_channel_get_flags()</function></link>, but not changed with
1169
<link linkend="g-io-channel-set-flags"><function>g_io_channel_set_flags()</function></link>.
1122
<link linkend="g-io-channel-set-flags"><function>g_io_channel_set_flags()</function></link>.
1170
1123
</para><variablelist role="enum">
1172
<term><anchor id="G-IO-FLAG-APPEND:CAPS" role="constant"/><literal>G_IO_FLAG_APPEND</literal></term>
1173
<listitem><simpara>turns on append mode, corresponds to <link linkend="O-APPEND:CAPS"><literal>O_APPEND</literal></link>
1124
<varlistentry id="G-IO-FLAG-APPEND--CAPS" role="constant">
1125
<term><literal>G_IO_FLAG_APPEND</literal></term>
1126
<listitem><simpara>turns on append mode, corresponds to <link linkend="O-APPEND--CAPS"><literal>O_APPEND</literal></link>
1174
1127
(see the documentation of the UNIX <link linkend="open"><function>open()</function></link> syscall).
1175
1128
</simpara></listitem>
1176
1129
</varlistentry>
1178
<term><anchor id="G-IO-FLAG-NONBLOCK:CAPS" role="constant"/><literal>G_IO_FLAG_NONBLOCK</literal></term>
1130
<varlistentry id="G-IO-FLAG-NONBLOCK--CAPS" role="constant">
1131
<term><literal>G_IO_FLAG_NONBLOCK</literal></term>
1179
1132
<listitem><simpara>turns on nonblocking mode, corresponds to
1180
<link linkend="O-NONBLOCK:CAPS"><literal>O_NONBLOCK</literal></link>/<link linkend="O-NDELAY:CAPS"><literal>O_NDELAY</literal></link> (see the documentation of the UNIX <link linkend="open"><function>open()</function></link>
1133
<link linkend="O-NONBLOCK--CAPS"><literal>O_NONBLOCK</literal></link>/<link linkend="O-NDELAY--CAPS"><literal>O_NDELAY</literal></link> (see the documentation of the UNIX <link linkend="open"><function>open()</function></link>
1182
1135
</simpara></listitem>
1183
1136
</varlistentry>
1185
<term><anchor id="G-IO-FLAG-IS-READABLE:CAPS" role="constant"/><literal>G_IO_FLAG_IS_READABLE</literal></term>
1137
<varlistentry id="G-IO-FLAG-IS-READABLE--CAPS" role="constant">
1138
<term><literal>G_IO_FLAG_IS_READABLE</literal></term>
1186
1139
<listitem><simpara>indicates that the io channel is readable.
1187
1140
This flag can not be changed.
1188
1141
</simpara></listitem>
1189
1142
</varlistentry>
1191
<term><anchor id="G-IO-FLAG-IS-WRITEABLE:CAPS" role="constant"/><literal>G_IO_FLAG_IS_WRITEABLE</literal></term>
1143
<varlistentry id="G-IO-FLAG-IS-WRITEABLE--CAPS" role="constant">
1144
<term><literal>G_IO_FLAG_IS_WRITEABLE</literal></term>
1192
1145
<listitem><simpara>indicates that the io channel is writable.
1193
1146
This flag can not be changed.
1194
1147
</simpara></listitem>
1195
1148
</varlistentry>
1197
<term><anchor id="G-IO-FLAG-IS-SEEKABLE:CAPS" role="constant"/><literal>G_IO_FLAG_IS_SEEKABLE</literal></term>
1149
<varlistentry id="G-IO-FLAG-IS-SEEKABLE--CAPS" role="constant">
1150
<term><literal>G_IO_FLAG_IS_SEEKABLE</literal></term>
1198
1151
<listitem><simpara>indicates that the io channel is seekable,
1199
i.e. that <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> can be used on it.
1152
i.e. that <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> can be used on it.
1200
1153
This flag can not be changed.
1201
1154
</simpara></listitem>
1202
1155
</varlistentry>
1204
<term><anchor id="G-IO-FLAG-MASK:CAPS" role="constant"/><literal>G_IO_FLAG_MASK</literal></term>
1206
</simpara></listitem>
1209
<term><anchor id="G-IO-FLAG-GET-MASK:CAPS" role="constant"/><literal>G_IO_FLAG_GET_MASK</literal></term>
1211
</simpara></listitem>
1214
<term><anchor id="G-IO-FLAG-SET-MASK:CAPS" role="constant"/><literal>G_IO_FLAG_SET_MASK</literal></term>
1156
<varlistentry id="G-IO-FLAG-MASK--CAPS" role="constant">
1157
<term><literal>G_IO_FLAG_MASK</literal></term>
1159
</simpara></listitem>
1161
<varlistentry id="G-IO-FLAG-GET-MASK--CAPS" role="constant">
1162
<term><literal>G_IO_FLAG_GET_MASK</literal></term>
1164
</simpara></listitem>
1166
<varlistentry id="G-IO-FLAG-SET-MASK--CAPS" role="constant">
1167
<term><literal>G_IO_FLAG_SET_MASK</literal></term>
1217
1169
</simpara></listitem>
1218
1170
</varlistentry>
1219
1171
</variablelist></refsect2>
1221
<title><anchor id="g-io-channel-get-line-term" role="function"/>g_io_channel_get_line_term ()</title>
1222
<indexterm><primary>g_io_channel_get_line_term</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,
1172
<refsect2 id="g-io-channel-get-line-term" role="function">
1173
<title>g_io_channel_get_line_term ()</title>
1174
<indexterm zone="g-io-channel-get-line-term"><primary sortas="g_io_channel_get_line_term">g_io_channel_get_line_term</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,
1223
1175
<link linkend="gint">gint</link> *length);</programlisting>
1225
1177
This returns the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine
1226
where in the file a line break occurs. A value of <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1178
where in the file a line break occurs. A value of <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1227
1179
indicates autodetection.</para>
1230
1181
</para><variablelist role="params">
1231
<varlistentry><term><parameter>channel</parameter> :</term>
1182
<varlistentry><term><parameter>channel</parameter> :</term>
1232
1183
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1233
1184
</simpara></listitem></varlistentry>
1234
<varlistentry><term><parameter>length</parameter> :</term>
1185
<varlistentry><term><parameter>length</parameter> :</term>
1235
1186
<listitem><simpara> a location to return the length of the line terminator
1236
1187
</simpara></listitem></varlistentry>
1237
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The line termination string. This value
1188
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The line termination string. This value
1238
1189
is owned by GLib and must not be freed.
1239
1190
</simpara></listitem></varlistentry>
1240
1191
</variablelist></refsect2>
1242
<title><anchor id="g-io-channel-set-line-term" role="function"/>g_io_channel_set_line_term ()</title>
1243
<indexterm><primary>g_io_channel_set_line_term</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,
1192
<refsect2 id="g-io-channel-set-line-term" role="function">
1193
<title>g_io_channel_set_line_term ()</title>
1194
<indexterm zone="g-io-channel-set-line-term"><primary sortas="g_io_channel_set_line_term">g_io_channel_set_line_term</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_line_term (<link linkend="GIOChannel">GIOChannel</link> *channel,
1244
1195
const <link linkend="gchar">gchar</link> *line_term,
1245
1196
<link linkend="gint">gint</link> length);</programlisting>
1247
1198
This sets the string that <link linkend="GIOChannel"><type>GIOChannel</type></link> uses to determine
1248
1199
where in the file a line break occurs.</para>
1251
1201
</para><variablelist role="params">
1252
<varlistentry><term><parameter>channel</parameter> :</term>
1202
<varlistentry><term><parameter>channel</parameter> :</term>
1253
1203
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1254
1204
</simpara></listitem></varlistentry>
1255
<varlistentry><term><parameter>line_term</parameter> :</term>
1256
<listitem><simpara> The line termination string. Use <link linkend="NULL:CAPS"><literal>NULL</literal></link> for autodetect.
1205
<varlistentry><term><parameter>line_term</parameter> :</term>
1206
<listitem><simpara> The line termination string. Use <link linkend="NULL--CAPS"><literal>NULL</literal></link> for autodetect.
1257
1207
Autodetection breaks on "\n", "\r\n", "\r", "\0", and
1258
1208
the Unicode paragraph separator. Autodetection should
1259
1209
not be used for anything other than file-based channels.
1260
1210
</simpara></listitem></varlistentry>
1261
<varlistentry><term><parameter>length</parameter> :</term>
1211
<varlistentry><term><parameter>length</parameter> :</term>
1262
1212
<listitem><simpara> The length of the termination string. If -1 is passed, the
1263
1213
string is assumed to be nul-terminated. This option allows
1264
1214
termination strings with embedded nuls.
1265
1215
</simpara></listitem></varlistentry>
1266
1216
</variablelist></refsect2>
1268
<title><anchor id="g-io-channel-get-buffered" role="function"/>g_io_channel_get_buffered ()</title>
1269
<indexterm><primary>g_io_channel_get_buffered</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1217
<refsect2 id="g-io-channel-get-buffered" role="function">
1218
<title>g_io_channel_get_buffered ()</title>
1219
<indexterm zone="g-io-channel-get-buffered"><primary sortas="g_io_channel_get_buffered">g_io_channel_get_buffered</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1271
1221
Returns whether <parameter>channel</parameter> is buffered.</para>
1274
1223
</para><variablelist role="params">
1275
<varlistentry><term><parameter>channel</parameter> :</term>
1224
<varlistentry><term><parameter>channel</parameter> :</term>
1276
1225
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1277
1226
</simpara></listitem></varlistentry>
1278
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the <parameter>channel</parameter> is buffered.
1227
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <parameter>channel</parameter> is buffered.
1279
1228
</simpara></listitem></varlistentry>
1280
1229
</variablelist></refsect2>
1282
<title><anchor id="g-io-channel-set-buffered" role="function"/>g_io_channel_set_buffered ()</title>
1283
<indexterm><primary>g_io_channel_set_buffered</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel,
1230
<refsect2 id="g-io-channel-set-buffered" role="function">
1231
<title>g_io_channel_set_buffered ()</title>
1232
<indexterm zone="g-io-channel-set-buffered"><primary sortas="g_io_channel_set_buffered">g_io_channel_set_buffered</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_buffered (<link linkend="GIOChannel">GIOChannel</link> *channel,
1284
1233
<link linkend="gboolean">gboolean</link> buffered);</programlisting>
1286
1235
The buffering state can only be set if the channel's encoding
1287
is <link linkend="NULL:CAPS"><literal>NULL</literal></link>. For any other encoding, the channel must be buffered.
1236
is <link linkend="NULL--CAPS"><literal>NULL</literal></link>. For any other encoding, the channel must be buffered.
1290
1239
A buffered channel can only be set unbuffered if the channel's
1291
1240
internal buffers have been flushed. Newly created channels or
1292
channels which have returned <link linkend="G-IO-STATUS-EOF:CAPS"><literal>G_IO_STATUS_EOF</literal></link>
1241
channels which have returned <link linkend="G-IO-STATUS-EOF--CAPS"><literal>G_IO_STATUS_EOF</literal></link>
1293
1242
not require such a flush. For write-only channels, a call to
1294
1243
<link linkend="g-io-channel-flush"><function>g_io_channel_flush()</function></link> is sufficient. For all other channels,
1295
1244
the buffers may be flushed by a call to <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link>.
1296
This includes the possibility of seeking with seek type <link linkend="G-SEEK-CUR:CAPS"><literal>G_SEEK_CUR</literal></link>
1245
This includes the possibility of seeking with seek type <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link>
1297
1246
and an offset of zero. Note that this means that socket-based
1298
1247
channels cannot be set unbuffered once they have had data
1299
1248
read from them.
1307
1256
The default state of the channel is buffered.</para>
1310
1258
</para><variablelist role="params">
1311
<varlistentry><term><parameter>channel</parameter> :</term>
1259
<varlistentry><term><parameter>channel</parameter> :</term>
1312
1260
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1313
1261
</simpara></listitem></varlistentry>
1314
<varlistentry><term><parameter>buffered</parameter> :</term>
1262
<varlistentry><term><parameter>buffered</parameter> :</term>
1315
1263
<listitem><simpara> whether to set the channel buffered or unbuffered
1316
1264
</simpara></listitem></varlistentry>
1317
1265
</variablelist></refsect2>
1319
<title><anchor id="g-io-channel-get-encoding" role="function"/>g_io_channel_get_encoding ()</title>
1320
<indexterm><primary>g_io_channel_get_encoding</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1266
<refsect2 id="g-io-channel-get-encoding" role="function">
1267
<title>g_io_channel_get_encoding ()</title>
1268
<indexterm zone="g-io-channel-get-encoding"><primary sortas="g_io_channel_get_encoding">g_io_channel_get_encoding</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_io_channel_get_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1322
1270
Gets the encoding for the input/output of the channel.
1323
The internal encoding is always UTF-8. The encoding <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1271
The internal encoding is always UTF-8. The encoding <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1324
1272
makes the channel safe for binary data.</para>
1327
1274
</para><variablelist role="params">
1328
<varlistentry><term><parameter>channel</parameter> :</term>
1275
<varlistentry><term><parameter>channel</parameter> :</term>
1329
1276
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1330
1277
</simpara></listitem></varlistentry>
1331
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A string containing the encoding, this string is
1278
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A string containing the encoding, this string is
1332
1279
owned by GLib and must not be freed.
1333
1280
</simpara></listitem></varlistentry>
1334
1281
</variablelist></refsect2>
1336
<title><anchor id="g-io-channel-set-encoding" role="function"/>g_io_channel_set_encoding ()</title>
1337
<indexterm><primary>g_io_channel_set_encoding</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel,
1282
<refsect2 id="g-io-channel-set-encoding" role="function">
1283
<title>g_io_channel_set_encoding ()</title>
1284
<indexterm zone="g-io-channel-set-encoding"><primary sortas="g_io_channel_set_encoding">g_io_channel_set_encoding</primary></indexterm><programlisting><link linkend="GIOStatus">GIOStatus</link> g_io_channel_set_encoding (<link linkend="GIOChannel">GIOChannel</link> *channel,
1338
1285
const <link linkend="gchar">gchar</link> *encoding,
1339
1286
<link linkend="GError">GError</link> **error);</programlisting>
1380
1327
</para></listitem>
1381
1328
</itemizedlist>
1382
1329
Channels which do not meet one of the above conditions cannot call
1383
<link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> with an offset of <link linkend="G-SEEK-CUR:CAPS"><literal>G_SEEK_CUR</literal></link>, and, if
1330
<link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> with an offset of <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link>, and, if
1384
1331
they are "seekable", cannot call <link linkend="g-io-channel-write-chars"><function>g_io_channel_write_chars()</function></link> after
1385
1332
calling one of the API "read" functions.</para>
1388
1334
</para><variablelist role="params">
1389
<varlistentry><term><parameter>channel</parameter> :</term>
1335
<varlistentry><term><parameter>channel</parameter> :</term>
1390
1336
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1391
1337
</simpara></listitem></varlistentry>
1392
<varlistentry><term><parameter>encoding</parameter> :</term>
1338
<varlistentry><term><parameter>encoding</parameter> :</term>
1393
1339
<listitem><simpara> the encoding type
1394
1340
</simpara></listitem></varlistentry>
1395
<varlistentry><term><parameter>error</parameter> :</term>
1341
<varlistentry><term><parameter>error</parameter> :</term>
1396
1342
<listitem><simpara> location to store an error of type <link linkend="GConvertError"><type>GConvertError</type></link>
1397
1343
</simpara></listitem></varlistentry>
1398
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL:CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> if the encoding was successfully set.
1344
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-STATUS-NORMAL--CAPS"><literal>G_IO_STATUS_NORMAL</literal></link> if the encoding was successfully set.
1399
1345
</simpara></listitem></varlistentry>
1400
1346
</variablelist></refsect2>
1402
<title><anchor id="g-io-channel-get-close-on-unref" role="function"/>g_io_channel_get_close_on_unref ()</title>
1403
<indexterm><primary>g_io_channel_get_close_on_unref</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1347
<refsect2 id="g-io-channel-get-close-on-unref" role="function">
1348
<title>g_io_channel_get_close_on_unref ()</title>
1349
<indexterm zone="g-io-channel-get-close-on-unref"><primary sortas="g_io_channel_get_close_on_unref">g_io_channel_get_close_on_unref</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_io_channel_get_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1405
1351
Returns whether the file/socket/whatever associated with <parameter>channel</parameter>
1406
1352
will be closed when <parameter>channel</parameter> receives its final unref and is
1407
destroyed. The default value of this is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for channels created
1408
by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>, and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all other channels.</para>
1353
destroyed. The default value of this is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for channels created
1354
by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>, and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.</para>
1411
1356
</para><variablelist role="params">
1412
<varlistentry><term><parameter>channel</parameter> :</term>
1357
<varlistentry><term><parameter>channel</parameter> :</term>
1413
1358
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>.
1414
1359
</simpara></listitem></varlistentry>
1415
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the channel will be closed on the final unref of
1360
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Whether the channel will be closed on the final unref of
1416
1361
the GIOChannel data structure.
1417
1362
</simpara></listitem></varlistentry>
1418
1363
</variablelist></refsect2>
1420
<title><anchor id="g-io-channel-set-close-on-unref" role="function"/>g_io_channel_set_close_on_unref ()</title>
1421
<indexterm><primary>g_io_channel_set_close_on_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel,
1364
<refsect2 id="g-io-channel-set-close-on-unref" role="function">
1365
<title>g_io_channel_set_close_on_unref ()</title>
1366
<indexterm zone="g-io-channel-set-close-on-unref"><primary sortas="g_io_channel_set_close_on_unref">g_io_channel_set_close_on_unref</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_set_close_on_unref (<link linkend="GIOChannel">GIOChannel</link> *channel,
1422
1367
<link linkend="gboolean">gboolean</link> do_close);</programlisting>
1424
Setting this flag to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for a channel you have already closed
1369
Setting this flag to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for a channel you have already closed
1425
1370
can cause problems.</para>
1428
1372
</para><variablelist role="params">
1429
<varlistentry><term><parameter>channel</parameter> :</term>
1373
<varlistentry><term><parameter>channel</parameter> :</term>
1430
1374
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1431
1375
</simpara></listitem></varlistentry>
1432
<varlistentry><term><parameter>do_close</parameter> :</term>
1376
<varlistentry><term><parameter>do_close</parameter> :</term>
1433
1377
<listitem><simpara> Whether to close the channel on the final unref of
1434
1378
the GIOChannel data structure. The default value of
1435
this is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for channels created by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>,
1436
and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all other channels.
1379
this is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for channels created by <link linkend="g-io-channel-new-file"><function>g_io_channel_new_file()</function></link>,
1380
and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all other channels.
1437
1381
</simpara></listitem></varlistentry>
1438
1382
</variablelist></refsect2>
1440
<title><anchor id="g-io-channel-read" role="function" condition="deprecated:2.2: Use g_io_channel_read_chars() instead."/>g_io_channel_read ()</title>
1441
<indexterm role="deprecated"><primary>g_io_channel_read</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_read (<link linkend="GIOChannel">GIOChannel</link> *channel,
1383
<refsect2 id="g-io-channel-read" role="function" condition="deprecated:2.2: Use g_io_channel_read_chars() instead.">
1384
<title>g_io_channel_read ()</title>
1385
<indexterm zone="g-io-channel-read" role="deprecated"><primary sortas="g_io_channel_read">g_io_channel_read</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_read (<link linkend="GIOChannel">GIOChannel</link> *channel,
1442
1386
<link linkend="gchar">gchar</link> *buf,
1443
1387
<link linkend="gsize">gsize</link> count,
1444
1388
<link linkend="gsize">gsize</link> *bytes_read);</programlisting>
1447
1391
Reads data from a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
1449
1393
</para><variablelist role="params">
1450
<varlistentry><term><parameter>channel</parameter> :</term>
1394
<varlistentry><term><parameter>channel</parameter> :</term>
1451
1395
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1452
1396
</simpara></listitem></varlistentry>
1453
<varlistentry><term><parameter>buf</parameter> :</term>
1397
<varlistentry><term><parameter>buf</parameter> :</term>
1454
1398
<listitem><simpara> a buffer to read the data into (which should be at least
1455
1399
count bytes long)
1456
1400
</simpara></listitem></varlistentry>
1457
<varlistentry><term><parameter>count</parameter> :</term>
1401
<varlistentry><term><parameter>count</parameter> :</term>
1458
1402
<listitem><simpara> the number of bytes to read from the <link linkend="GIOChannel"><type>GIOChannel</type></link>
1459
1403
</simpara></listitem></varlistentry>
1460
<varlistentry><term><parameter>bytes_read</parameter> :</term>
1404
<varlistentry><term><parameter>bytes_read</parameter> :</term>
1461
1405
<listitem><simpara> returns the number of bytes actually read
1462
1406
</simpara></listitem></varlistentry>
1463
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE:CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1407
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1465
1409
</simpara></listitem></varlistentry>
1466
1410
</variablelist></refsect2>
1468
<title><anchor id="GIOError" role="enum"/>enum GIOError</title>
1469
<indexterm><primary>GIOError</primary></indexterm><programlisting>typedef enum
1411
<refsect2 id="GIOError" role="enum">
1412
<title>enum GIOError</title>
1413
<indexterm zone="GIOError"><primary sortas="GIOError">GIOError</primary></indexterm><programlisting>typedef enum
1471
1415
G_IO_ERROR_NONE,
1472
1416
G_IO_ERROR_AGAIN,
1478
1422
<link linkend="GIOError"><type>GIOError</type></link> is only used by the deprecated functions <link linkend="g-io-channel-read"><function>g_io_channel_read()</function></link>,
1479
1423
<link linkend="g-io-channel-write"><function>g_io_channel_write()</function></link>, and <link linkend="g-io-channel-seek"><function>g_io_channel_seek()</function></link>.
1480
1424
</para><variablelist role="enum">
1482
<term><anchor id="G-IO-ERROR-NONE:CAPS" role="constant"/><literal>G_IO_ERROR_NONE</literal></term>
1425
<varlistentry id="G-IO-ERROR-NONE--CAPS" role="constant">
1426
<term><literal>G_IO_ERROR_NONE</literal></term>
1483
1427
<listitem><simpara>no error
1484
1428
</simpara></listitem>
1485
1429
</varlistentry>
1487
<term><anchor id="G-IO-ERROR-AGAIN:CAPS" role="constant"/><literal>G_IO_ERROR_AGAIN</literal></term>
1430
<varlistentry id="G-IO-ERROR-AGAIN--CAPS" role="constant">
1431
<term><literal>G_IO_ERROR_AGAIN</literal></term>
1488
1432
<listitem><simpara>an EAGAIN error occurred
1489
1433
</simpara></listitem>
1490
1434
</varlistentry>
1492
<term><anchor id="G-IO-ERROR-INVAL:CAPS" role="constant"/><literal>G_IO_ERROR_INVAL</literal></term>
1435
<varlistentry id="G-IO-ERROR-INVAL--CAPS" role="constant">
1436
<term><literal>G_IO_ERROR_INVAL</literal></term>
1493
1437
<listitem><simpara>an EINVAL error occurred
1494
1438
</simpara></listitem>
1495
1439
</varlistentry>
1497
<term><anchor id="G-IO-ERROR-UNKNOWN:CAPS" role="constant"/><literal>G_IO_ERROR_UNKNOWN</literal></term>
1440
<varlistentry id="G-IO-ERROR-UNKNOWN--CAPS" role="constant">
1441
<term><literal>G_IO_ERROR_UNKNOWN</literal></term>
1498
1442
<listitem><simpara>another error occurred
1500
1443
</simpara></listitem>
1501
1444
</varlistentry>
1502
1445
</variablelist></refsect2>
1504
<title><anchor id="g-io-channel-write" role="function" condition="deprecated:2.2: Use g_io_channel_write_chars() instead."/>g_io_channel_write ()</title>
1505
<indexterm role="deprecated"><primary>g_io_channel_write</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_write (<link linkend="GIOChannel">GIOChannel</link> *channel,
1446
<refsect2 id="g-io-channel-write" role="function" condition="deprecated:2.2: Use g_io_channel_write_chars() instead.">
1447
<title>g_io_channel_write ()</title>
1448
<indexterm zone="g-io-channel-write" role="deprecated"><primary sortas="g_io_channel_write">g_io_channel_write</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_write (<link linkend="GIOChannel">GIOChannel</link> *channel,
1506
1449
const <link linkend="gchar">gchar</link> *buf,
1507
1450
<link linkend="gsize">gsize</link> count,
1508
1451
<link linkend="gsize">gsize</link> *bytes_written);</programlisting>
1511
1454
Writes data to a <link linkend="GIOChannel"><type>GIOChannel</type></link>.</para>
1513
1456
</para><variablelist role="params">
1514
<varlistentry><term><parameter>channel</parameter> :</term>
1457
<varlistentry><term><parameter>channel</parameter> :</term>
1515
1458
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1516
1459
</simpara></listitem></varlistentry>
1517
<varlistentry><term><parameter>buf</parameter> :</term>
1460
<varlistentry><term><parameter>buf</parameter> :</term>
1518
1461
<listitem><simpara> the buffer containing the data to write
1519
1462
</simpara></listitem></varlistentry>
1520
<varlistentry><term><parameter>count</parameter> :</term>
1463
<varlistentry><term><parameter>count</parameter> :</term>
1521
1464
<listitem><simpara> the number of bytes to write
1522
1465
</simpara></listitem></varlistentry>
1523
<varlistentry><term><parameter>bytes_written</parameter> :</term>
1466
<varlistentry><term><parameter>bytes_written</parameter> :</term>
1524
1467
<listitem><simpara> the number of bytes actually written
1525
1468
</simpara></listitem></varlistentry>
1526
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE:CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1469
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1528
1471
</simpara></listitem></varlistentry>
1529
1472
</variablelist></refsect2>
1531
<title><anchor id="g-io-channel-seek" role="function" condition="deprecated:2.2: Use g_io_channel_seek_position() instead."/>g_io_channel_seek ()</title>
1532
<indexterm role="deprecated"><primary>g_io_channel_seek</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_seek (<link linkend="GIOChannel">GIOChannel</link> *channel,
1473
<refsect2 id="g-io-channel-seek" role="function" condition="deprecated:2.2: Use g_io_channel_seek_position() instead.">
1474
<title>g_io_channel_seek ()</title>
1475
<indexterm zone="g-io-channel-seek" role="deprecated"><primary sortas="g_io_channel_seek">g_io_channel_seek</primary></indexterm><programlisting><link linkend="GIOError">GIOError</link> g_io_channel_seek (<link linkend="GIOChannel">GIOChannel</link> *channel,
1533
1476
<link linkend="gint64">gint64</link> offset,
1534
1477
<link linkend="GSeekType">GSeekType</link> type);</programlisting>
1535
1478
<warning><para><literal>g_io_channel_seek</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-seek-position"><function>g_io_channel_seek_position()</function></link> instead.</para></warning>
1538
1481
library function <link linkend="fseek"><function>fseek()</function></link>.</para>
1540
1483
</para><variablelist role="params">
1541
<varlistentry><term><parameter>channel</parameter> :</term>
1484
<varlistentry><term><parameter>channel</parameter> :</term>
1542
1485
<listitem><simpara> a <link linkend="GIOChannel"><type>GIOChannel</type></link>
1543
1486
</simpara></listitem></varlistentry>
1544
<varlistentry><term><parameter>offset</parameter> :</term>
1487
<varlistentry><term><parameter>offset</parameter> :</term>
1545
1488
<listitem><simpara> an offset, in bytes, which is added to the position specified
1546
1489
by <parameter>type</parameter>
1547
1490
</simpara></listitem></varlistentry>
1548
<varlistentry><term><parameter>type</parameter> :</term>
1549
<listitem><simpara> the position in the file, which can be <link linkend="G-SEEK-CUR:CAPS"><literal>G_SEEK_CUR</literal></link> (the current
1550
position), <link linkend="G-SEEK-SET:CAPS"><literal>G_SEEK_SET</literal></link> (the start of the file), or <link linkend="G-SEEK-END:CAPS"><literal>G_SEEK_END</literal></link>
1491
<varlistentry><term><parameter>type</parameter> :</term>
1492
<listitem><simpara> the position in the file, which can be <link linkend="G-SEEK-CUR--CAPS"><literal>G_SEEK_CUR</literal></link> (the current
1493
position), <link linkend="G-SEEK-SET--CAPS"><literal>G_SEEK_SET</literal></link> (the start of the file), or <link linkend="G-SEEK-END--CAPS"><literal>G_SEEK_END</literal></link>
1551
1494
(the end of the file)
1552
1495
</simpara></listitem></varlistentry>
1553
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE:CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1496
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="G-IO-ERROR-NONE--CAPS"><literal>G_IO_ERROR_NONE</literal></link> if the operation was successful.
1555
1498
</simpara></listitem></varlistentry>
1556
1499
</variablelist></refsect2>
1558
<title><anchor id="g-io-channel-close" role="function" condition="deprecated:2.2: Use g_io_channel_shutdown() instead."/>g_io_channel_close ()</title>
1559
<indexterm role="deprecated"><primary>g_io_channel_close</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_close (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1500
<refsect2 id="g-io-channel-close" role="function" condition="deprecated:2.2: Use g_io_channel_shutdown() instead.">
1501
<title>g_io_channel_close ()</title>
1502
<indexterm zone="g-io-channel-close" role="deprecated"><primary sortas="g_io_channel_close">g_io_channel_close</primary></indexterm><programlisting><link linkend="void">void</link> g_io_channel_close (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
1560
1503
<warning><para><literal>g_io_channel_close</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-io-channel-shutdown"><function>g_io_channel_shutdown()</function></link> instead.</para></warning>
1562
1505
Close an IO channel. Any pending data to be written will be