giochannel.c 67.2 KB
Newer Older
1
2
3
4
5
6
7
/* GLIB - Library of useful routines for C programming
 * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
 *
 * giochannel.c: IO Channel abstraction
 * Copyright 1998 Owen Taylor
 *
 * This library is free software; you can redistribute it and/or
8
 * modify it under the terms of the GNU Lesser General Public
9
10
11
12
13
14
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
15
 * Lesser General Public License for more details.
16
 *
17
 * You should have received a copy of the GNU Lesser General Public
18
19
20
21
22
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

23
/*
24
 * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
25
26
27
28
29
 * file for a list of people on the GLib Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
 * GLib at ftp://ftp.gtk.org/pub/gtk/. 
 */

30
31
32
33
/* 
 * MT safe
 */

34
35
#include "config.h"

36
37
#include <string.h>
#include <errno.h>
38
39

#ifdef HAVE_UNISTD_H
40
#include <unistd.h>
41
#endif
42

43
44
#undef G_DISABLE_DEPRECATED

45
#include "galias.h"
46
47
#include "glib.h"

48
49
#include "giochannel.h"

50
51
52
53
#include "glibintl.h"

#define G_IO_NICE_BUF_SIZE	1024

54
55
56
57
58
59
60
61
62
63
64
/* This needs to be as wide as the largest character in any possible encoding */
#define MAX_CHAR_SIZE		10

/* Some simplifying macros, which reduce the need to worry whether the
 * buffers have been allocated. These also make USE_BUF () an lvalue,
 * which is used in g_io_channel_read_to_end ().
 */
#define USE_BUF(channel)	((channel)->encoding ? (channel)->encoded_read_buf \
				 : (channel)->read_buf)
#define BUF_LEN(string)		((string) ? (string)->len : 0)

65
static GIOError		g_io_error_get_from_g_error	(GIOStatus    status,
66
67
68
69
							 GError      *err);
static void		g_io_channel_purge		(GIOChannel  *channel);
static GIOStatus	g_io_channel_fill_buffer	(GIOChannel  *channel,
							 GError     **err);
70
71
72
73
static GIOStatus	g_io_channel_read_line_backend	(GIOChannel  *channel,
							 gsize       *length,
							 gsize       *terminator_pos,
							 GError     **error);
74

75
76
void
g_io_channel_init (GIOChannel *channel)
77
{
78
  channel->ref_count = 1;
79
  channel->encoding = g_strdup ("UTF-8");
80
  channel->line_term = NULL;
81
  channel->line_term_len = 0;
82
  channel->buf_size = G_IO_NICE_BUF_SIZE;
83
84
85
86
87
88
  channel->read_cd = (GIConv) -1;
  channel->write_cd = (GIConv) -1;
  channel->read_buf = NULL; /* Lazy allocate buffers */
  channel->encoded_read_buf = NULL;
  channel->write_buf = NULL;
  channel->partial_write_buf[0] = '\0';
89
90
91
  channel->use_buffer = TRUE;
  channel->do_encode = FALSE;
  channel->close_on_unref = FALSE;
92
93
94
95
96
97
98
}

void 
g_io_channel_ref (GIOChannel *channel)
{
  g_return_if_fail (channel != NULL);

99
  channel->ref_count++;
100
101
102
103
104
105
106
}

void 
g_io_channel_unref (GIOChannel *channel)
{
  g_return_if_fail (channel != NULL);

107
108
  channel->ref_count--;
  if (channel->ref_count == 0)
109
110
    {
      if (channel->close_on_unref)
111
        g_io_channel_shutdown (channel, TRUE, NULL);
112
113
114
      else
        g_io_channel_purge (channel);
      g_free (channel->encoding);
115
116
117
118
      if (channel->read_cd != (GIConv) -1)
        g_iconv_close (channel->read_cd);
      if (channel->write_cd != (GIConv) -1)
        g_iconv_close (channel->write_cd);
119
120
      if (channel->line_term)
        g_free (channel->line_term);
121
122
123
124
125
126
      if (channel->read_buf)
        g_string_free (channel->read_buf, TRUE);
      if (channel->write_buf)
        g_string_free (channel->write_buf, TRUE);
      if (channel->encoded_read_buf)
        g_string_free (channel->encoded_read_buf, TRUE);
127
128
      channel->funcs->io_free (channel);
    }
129
130
}

131
132
133
134
135
136
137
138
139
140
141
142
static GIOError
g_io_error_get_from_g_error (GIOStatus status,
			     GError *err)
{
  switch (status)
    {
      case G_IO_STATUS_NORMAL:
      case G_IO_STATUS_EOF:
        return G_IO_ERROR_NONE;
      case G_IO_STATUS_AGAIN:
        return G_IO_ERROR_AGAIN;
      case G_IO_STATUS_ERROR:
143
144
	g_return_val_if_fail (err != NULL, G_IO_ERROR_UNKNOWN);
	
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
        if (err->domain != G_IO_CHANNEL_ERROR)
          return G_IO_ERROR_UNKNOWN;
        switch (err->code)
          {
            case G_IO_CHANNEL_ERROR_INVAL:
              return G_IO_ERROR_INVAL;
            default:
              return G_IO_ERROR_UNKNOWN;
          }
      default:
        g_assert_not_reached ();
        return G_IO_ERROR_UNKNOWN; /* Keep the compiler happy */
    }
}

/**
 * g_io_channel_read:
 * @channel: a #GIOChannel. 
 * @buf: a buffer to read the data into (which should be at least count bytes long).
 * @count: the number of bytes to read from the #GIOChannel.
 * @bytes_read: returns the number of bytes actually read. 
 * 
167
 * Reads data from a #GIOChannel. 
168
169
 * 
 * Return value: %G_IO_ERROR_NONE if the operation was successful. 
170
171
 *
 * Deprecated: Use g_io_channel_read_chars() instead.
172
 **/
173
174
175
GIOError 
g_io_channel_read (GIOChannel *channel, 
		   gchar      *buf, 
176
177
		   gsize       count,
		   gsize      *bytes_read)
178
{
179
180
181
182
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

183
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
184
185
  g_return_val_if_fail (bytes_read != NULL, G_IO_ERROR_UNKNOWN);

186
187
188
189
  if (count == 0)
    {
      if (bytes_read)
        *bytes_read = 0;
190
      return G_IO_ERROR_NONE;
191
192
193
194
    }

  g_return_val_if_fail (buf != NULL, G_IO_ERROR_UNKNOWN);

195
  status = channel->funcs->io_read (channel, buf, count, bytes_read, &err);
196

197
198
199
200
201
202
  error = g_io_error_get_from_g_error (status, err);

  if (err)
    g_error_free (err);

  return error;
203
204
}

205
206
207
208
209
210
211
/**
 * g_io_channel_write:
 * @channel:  a #GIOChannel.
 * @buf: the buffer containing the data to write. 
 * @count: the number of bytes to write.
 * @bytes_written:  the number of bytes actually written.
 * 
212
 * Writes data to a #GIOChannel. 
213
214
 * 
 * Return value:  %G_IO_ERROR_NONE if the operation was successful.
215
216
 *
 * Deprecated: Use g_io_channel_write_chars() instead.
217
 **/
218
GIOError 
219
220
221
222
g_io_channel_write (GIOChannel  *channel, 
		    const gchar *buf, 
		    gsize        count,
		    gsize       *bytes_written)
223
{
224
225
226
227
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

228
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
229
230
231
232
233
  g_return_val_if_fail (bytes_written != NULL, G_IO_ERROR_UNKNOWN);

  status = channel->funcs->io_write (channel, buf, count, bytes_written, &err);

  error = g_io_error_get_from_g_error (status, err);
234

235
236
237
238
  if (err)
    g_error_free (err);

  return error;
239
240
}

241
242
243
244
245
246
247
248
249
/**
 * g_io_channel_seek:
 * @channel: a #GIOChannel. 
 * @offset: an offset, in bytes, which is added to the position specified by @type
 * @type: the position in the file, which can be %G_SEEK_CUR (the current
 *        position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the
 *        file).
 * 
 * Sets the current position in the #GIOChannel, similar to the standard library
250
 * function fseek(). 
251
252
 * 
 * Return value: %G_IO_ERROR_NONE if the operation was successful.
253
254
 *
 * Deprecated: Use g_io_channel_seek_position() instead.
255
 **/
256
257
GIOError 
g_io_channel_seek  (GIOChannel   *channel,
Owen Taylor's avatar
Owen Taylor committed
258
		    gint64        offset, 
259
		    GSeekType     type)
260
{
261
262
263
264
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

265
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
266
  g_return_val_if_fail (channel->is_seekable, G_IO_ERROR_UNKNOWN);
267

268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
  switch (type)
    {
      case G_SEEK_CUR:
      case G_SEEK_SET:
      case G_SEEK_END:
        break;
      default:
        g_warning ("g_io_channel_seek: unknown seek type");
        return G_IO_ERROR_UNKNOWN;
    }

  status = channel->funcs->io_seek (channel, offset, type, &err);

  error = g_io_error_get_from_g_error (status, err);

  if (err)
    g_error_free (err);

  return error;
287
}
288
289
290
291
292
293
294
295

/* The function g_io_channel_new_file() is prototyped in both
 * giounix.c and giowin32.c, so we stick its documentation here.
 */

/**
 * g_io_channel_new_file:
 * @filename: A string containing the name of a file.
296
 * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
297
 *        the same meaning as in fopen().
298
 * @error: A location to return an error of type %G_FILE_ERROR.
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 *
 * Open a file @filename as a #GIOChannel using mode @mode. This
 * channel will be closed when the last reference to it is dropped,
 * so there is no need to call g_io_channel_close() (though doing
 * so will not cause problems, as long as no attempt is made to
 * access the channel after it is closed).
 *
 * Return value: A #GIOChannel on success, %NULL on failure.
 **/

/**
 * g_io_channel_close:
 * @channel: A #GIOChannel
 * 
 * Close an IO channel. Any pending data to be written will be
 * flushed, ignoring errors. The channel will not be freed until the
315
316
317
 * last reference is dropped using g_io_channel_unref(). 
 *
 * Deprecated: Use g_io_channel_shutdown() instead.
318
 **/
319
320
321
void
g_io_channel_close (GIOChannel *channel)
{
322
323
  GError *err = NULL;
  
324
325
  g_return_if_fail (channel != NULL);

326
327
328
329
330
331
332
333
334
335
336
  g_io_channel_purge (channel);

  channel->funcs->io_close (channel, &err);

  if (err)
    { /* No way to return the error */
      g_warning ("Error closing channel: %s", err->message);
      g_error_free (err);
    }
  
  channel->close_on_unref = FALSE; /* Because we already did */
337
338
339
  channel->is_readable = FALSE;
  channel->is_writeable = FALSE;
  channel->is_seekable = FALSE;
340
341
342
343
344
345
346
347
348
}

/**
 * g_io_channel_shutdown:
 * @channel: a #GIOChannel
 * @flush: if %TRUE, flush pending
 * @err: location to store a #GIOChannelError
 * 
 * Close an IO channel. Any pending data to be written will be
349
 * flushed if @flush is %TRUE. The channel will not be freed until the
350
 * last reference is dropped using g_io_channel_unref().
351
 *
352
 * Return value: the status of the operation.
353
354
355
356
 **/
GIOStatus
g_io_channel_shutdown (GIOChannel *channel,
		       gboolean    flush,
357
		       GError    **err)
358
{
359
360
  GIOStatus status, result;
  GError *tmperr = NULL;
361
362
  
  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
363
  g_return_val_if_fail (err == NULL || *err == NULL, G_IO_STATUS_ERROR);
364

365
  if (channel->write_buf && channel->write_buf->len > 0)
366
    {
367
368
369
      if (flush)
        {
          GIOFlags flags;
370
      
371
372
373
374
375
          /* Set the channel to blocking, to avoid a busy loop
           */
          flags = g_io_channel_get_flags (channel);
          /* Ignore any errors here, they're irrelevant */
          g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);
376

377
          result = g_io_channel_flush (channel, &tmperr);
378
        }
379
380
381
382
      else
        result = G_IO_STATUS_NORMAL;

      g_string_truncate(channel->write_buf, 0);
383
    }
384
385
  else
    result = G_IO_STATUS_NORMAL;
386

387
388
389
390
391
392
393
  if (channel->partial_write_buf[0] != '\0')
    {
      if (flush)
        g_warning ("Partial character at end of write buffer not flushed.\n");
      channel->partial_write_buf[0] = '\0';
    }

394
  status = channel->funcs->io_close (channel, err);
395
396

  channel->close_on_unref = FALSE; /* Because we already did */
397
398
399
  channel->is_readable = FALSE;
  channel->is_writeable = FALSE;
  channel->is_seekable = FALSE;
400

401
402
403
404
405
406
407
408
409
410
411
412
  if (status != G_IO_STATUS_NORMAL)
    {
      g_clear_error (&tmperr);
      return status;
    }
  else if (result != G_IO_STATUS_NORMAL)
    {
      g_propagate_error (err, tmperr);
      return result;
    }
  else
    return G_IO_STATUS_NORMAL;
413
414
415
416
417
418
419
}

/* This function is used for the final flush on close or unref */
static void
g_io_channel_purge (GIOChannel *channel)
{
  GError *err = NULL;
420
  GIOStatus status;
421
422
423

  g_return_if_fail (channel != NULL);

424
  if (channel->write_buf && channel->write_buf->len > 0)
425
426
427
428
429
430
431
432
    {
      GIOFlags flags;
      
      /* Set the channel to blocking, to avoid a busy loop
       */
      flags = g_io_channel_get_flags (channel);
      g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);

433
      status = g_io_channel_flush (channel, &err);
434
435
436
437
438
439
440
441
442
443

      if (err)
	{ /* No way to return the error */
	  g_warning ("Error flushing string: %s", err->message);
	  g_error_free (err);
	}
    }

  /* Flush these in case anyone tries to close without unrefing */

444
445
446
447
  if (channel->read_buf)
    g_string_truncate (channel->read_buf, 0);
  if (channel->write_buf)
    g_string_truncate (channel->write_buf, 0);
448
  if (channel->encoding)
449
450
451
452
453
454
455
456
457
458
    {
      if (channel->encoded_read_buf)
        g_string_truncate (channel->encoded_read_buf, 0);

      if (channel->partial_write_buf[0] != '\0')
        {
          g_warning ("Partial character at end of write buffer not flushed.\n");
          channel->partial_write_buf[0] = '\0';
        }
    }
459
460
}

461
462
463
464
465
466
467
468
469
GSource *
g_io_create_watch (GIOChannel  *channel,
		   GIOCondition condition)
{
  g_return_val_if_fail (channel != NULL, NULL);

  return channel->funcs->io_create_watch (channel, condition);
}

470
guint 
471
g_io_add_watch_full (GIOChannel    *channel,
472
473
474
475
476
477
		     gint           priority,
		     GIOCondition   condition,
		     GIOFunc        func,
		     gpointer       user_data,
		     GDestroyNotify notify)
{
478
  GSource *source;
479
  guint id;
480
  
481
482
  g_return_val_if_fail (channel != NULL, 0);

483
484
485
486
487
488
  source = g_io_create_watch (channel, condition);

  if (priority != G_PRIORITY_DEFAULT)
    g_source_set_priority (source, priority);
  g_source_set_callback (source, (GSourceFunc)func, user_data, notify);

489
490
491
492
  id = g_source_attach (source, NULL);
  g_source_unref (source);

  return id;
493
494
495
}

guint 
496
g_io_add_watch (GIOChannel    *channel,
497
498
499
500
		GIOCondition   condition,
		GIOFunc        func,
		gpointer       user_data)
{
501
  return g_io_add_watch_full (channel, G_PRIORITY_DEFAULT, condition, func, user_data, NULL);
502
}
503
504
505
506
507

/**
 * g_io_channel_get_buffer_condition:
 * @channel: A #GIOChannel
 *
508
509
 * This function returns a #GIOCondition depending on whether there
 * is data to be read/space to write data in the
510
 * internal buffers in the #GIOChannel. Only the flags %G_IO_IN and
511
 * %G_IO_OUT may be set.
512
513
514
515
516
517
 *
 * Return value: A #GIOCondition
 **/
GIOCondition
g_io_channel_get_buffer_condition (GIOChannel *channel)
{
518
519
  GIOCondition condition = 0;

520
521
522
523
524
525
526
527
528
529
  if (channel->encoding)
    {
      if (channel->encoded_read_buf && (channel->encoded_read_buf->len > 0))
        condition |= G_IO_IN; /* Only return if we have full characters */
    }
  else
    {
      if (channel->read_buf && (channel->read_buf->len > 0))
        condition |= G_IO_IN;
    }
530
531

  if (channel->write_buf && (channel->write_buf->len < channel->buf_size))
532
    condition |= G_IO_OUT;
533
534

  return condition;
535
536
537
}

/**
538
 * g_io_channel_error_from_errno:
539
 * @en: an <literal>errno</literal> error number, e.g. %EINVAL.
540
 *
541
542
543
 * Converts an <literal>errno</literal> error number to a #GIOChannelError.
 *
 * Return value: a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL.
544
545
 **/
GIOChannelError
546
g_io_channel_error_from_errno (gint en)
547
548
549
550
551
552
553
554
555
{
#ifdef EAGAIN
  g_return_val_if_fail (en != EAGAIN, G_IO_CHANNEL_ERROR_FAILED);
#endif

  switch (en)
    {
#ifdef EBADF
    case EBADF:
556
557
      g_warning("Invalid file descriptor.\n");
      return G_IO_CHANNEL_ERROR_FAILED;
558
559
560
561
#endif

#ifdef EFAULT
    case EFAULT:
562
      g_warning("Buffer outside valid address space.\n");
563
564
565
566
567
568
      return G_IO_CHANNEL_ERROR_FAILED;
#endif

#ifdef EFBIG
    case EFBIG:
      return G_IO_CHANNEL_ERROR_FBIG;
569
570
#endif

571
572
573
574
575
576
577
578
579
580
581
582
#ifdef EINTR
    /* In general, we should catch EINTR before we get here,
     * but close() is allowed to return EINTR by POSIX, so
     * we need to catch it here; EINTR from close() is
     * unrecoverable, because it's undefined whether
     * the fd was actually closed or not, so we just return
     * a generic error code.
     */
    case EINTR:
      return G_IO_CHANNEL_ERROR_FAILED;
#endif

583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
#ifdef EINVAL
    case EINVAL:
      return G_IO_CHANNEL_ERROR_INVAL;
#endif

#ifdef EIO
    case EIO:
      return G_IO_CHANNEL_ERROR_IO;
#endif

#ifdef EISDIR
    case EISDIR:
      return G_IO_CHANNEL_ERROR_ISDIR;
#endif

#ifdef ENOSPC
    case ENOSPC:
      return G_IO_CHANNEL_ERROR_NOSPC;
#endif

603
604
605
#ifdef ENXIO
    case ENXIO:
      return G_IO_CHANNEL_ERROR_NXIO;
606
#endif
607
608
609
610
611
612

#ifdef EOVERFLOW
    case EOVERFLOW:
      return G_IO_CHANNEL_ERROR_OVERFLOW;
#endif

613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
#ifdef EPIPE
    case EPIPE:
      return G_IO_CHANNEL_ERROR_PIPE;
#endif

    default:
      return G_IO_CHANNEL_ERROR_FAILED;
    }
}

/**
 * g_io_channel_set_buffer_size:
 * @channel: a #GIOChannel
 * @size: the size of the buffer. 0 == pick a good size
 *
Matthias Clasen's avatar
Matthias Clasen committed
628
 * Sets the buffer size.
629
630
631
632
633
634
635
636
637
638
 **/  
void
g_io_channel_set_buffer_size (GIOChannel	*channel,
                              gsize		 size)
{
  g_return_if_fail (channel != NULL);

  if (size == 0)
    size = G_IO_NICE_BUF_SIZE;

639
640
  if (size < MAX_CHAR_SIZE)
    size = MAX_CHAR_SIZE;
641

642
643
644
645
646
647
648
  channel->buf_size = size;
}

/**
 * g_io_channel_get_buffer_size:
 * @channel: a #GIOChannel
 *
Matthias Clasen's avatar
Matthias Clasen committed
649
 * Gets the buffer size.
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
 *
 * Return value: the size of the buffer.
 **/  
gsize
g_io_channel_get_buffer_size (GIOChannel	*channel)
{
  g_return_val_if_fail (channel != NULL, 0);

  return channel->buf_size;
}

/**
 * g_io_channel_set_line_term:
 * @channel: a #GIOChannel
 * @line_term: The line termination string. Use %NULL for auto detect.
665
 *             Auto detection breaks on "\n", "\r\n", "\r", "\0", and
Matthias Clasen's avatar
Matthias Clasen committed
666
 *             the Unicode paragraph separator. Auto detection should
667
 *             not be used for anything other than file-based channels.
668
 * @length: The length of the termination string. If -1 is passed, the
Matthias Clasen's avatar
Matthias Clasen committed
669
670
 *          string is assumed to be nul-terminated. This option allows
 *          termination strings with embeded nuls.
671
672
673
674
675
676
 *
 * This sets the string that #GIOChannel uses to determine
 * where in the file a line break occurs.
 **/
void
g_io_channel_set_line_term (GIOChannel	*channel,
677
678
                            const gchar	*line_term,
			    gint         length)
679
680
{
  g_return_if_fail (channel != NULL);
681
  g_return_if_fail (line_term == NULL || length != 0); /* Disallow "" */
682

683
684
685
686
687
688
689
690
691
  if (line_term == NULL)
    length = 0;
  else if (length < 0)
    length = strlen (line_term);

  if (channel->line_term)
    g_free (channel->line_term);
  channel->line_term = line_term ? g_memdup (line_term, length) : NULL;
  channel->line_term_len = length;
692
693
694
695
696
}

/**
 * g_io_channel_get_line_term:
 * @channel: a #GIOChannel
697
 * @length: a location to return the length of the line terminator
698
699
700
701
702
703
704
705
706
 *
 * This returns the string that #GIOChannel uses to determine
 * where in the file a line break occurs. A value of %NULL
 * indicates auto detection.
 *
 * Return value: The line termination string. This value
 *   is owned by GLib and must not be freed.
 **/
G_CONST_RETURN gchar*
707
708
g_io_channel_get_line_term (GIOChannel	*channel,
			    gint        *length)
709
710
711
{
  g_return_val_if_fail (channel != NULL, 0);

712
713
714
  if (length)
    *length = channel->line_term_len;

715
716
717
718
719
  return channel->line_term;
}

/**
 * g_io_channel_set_flags:
720
 * @channel: a #GIOChannel.
Matthias Clasen's avatar
Matthias Clasen committed
721
 * @flags: the flags to set on the IO channel.
722
723
 * @error: A location to return an error of type #GIOChannelError.
 *
724
 * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).
725
 *
726
 * Return value: the status of the operation. 
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
 **/
GIOStatus
g_io_channel_set_flags (GIOChannel *channel,
                        GIOFlags    flags,
                        GError    **error)
{
  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
  g_return_val_if_fail ((error == NULL) || (*error == NULL),
			G_IO_STATUS_ERROR);

  return (* channel->funcs->io_set_flags)(channel,
					  flags & G_IO_FLAG_SET_MASK,
					  error);
}

/**
 * g_io_channel_get_flags:
 * @channel: a #GIOChannel
 *
 * Gets the current flags for a #GIOChannel, including read-only
 * flags such as %G_IO_FLAG_IS_READABLE.
748
 *
749
750
751
 * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITEABLE
 * are cached for internal use by the channel when it is created.
 * If they should change at some later point (e.g. partial shutdown
752
 * of a socket with the UNIX shutdown() function), the user
753
754
755
 * should immediately call g_io_channel_get_flags () to update
 * the internal values of these flags.
 *
756
 * Return value: the flags which are set on the channel
757
758
759
760
 **/
GIOFlags
g_io_channel_get_flags (GIOChannel *channel)
{
761
762
  GIOFlags flags;

763
  g_return_val_if_fail (channel != NULL, 0);
764

765
766
767
768
769
770
771
772
773
774
775
776
  flags = (* channel->funcs->io_get_flags) (channel);

  /* Cross implementation code */

  if (channel->is_seekable)
    flags |= G_IO_FLAG_IS_SEEKABLE;
  if (channel->is_readable)
    flags |= G_IO_FLAG_IS_READABLE;
  if (channel->is_writeable)
    flags |= G_IO_FLAG_IS_WRITEABLE;

  return flags;
777
778
}

779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
/**
 * g_io_channel_set_close_on_unref:
 * @channel: a #GIOChannel
 * @do_close: Whether to close the channel on the final unref of
 *            the GIOChannel data structure. The default value of
 *            this is %TRUE for channels created by g_io_channel_new_file (),
 *            and %FALSE for all other channels.
 *
 * Setting this flag to %TRUE for a channel you have already closed
 * can cause problems.
 **/
void
g_io_channel_set_close_on_unref	(GIOChannel *channel,
				 gboolean    do_close)
{
  g_return_if_fail (channel != NULL);

  channel->close_on_unref = do_close;
}

/**
 * g_io_channel_get_close_on_unref:
801
 * @channel: a #GIOChannel.
802
 *
803
804
805
806
807
808
809
 * Returns whether the file/socket/whatever associated with @channel
 * will be closed when @channel receives its final unref and is
 * destroyed. The default value of this is %TRUE for channels created
 * by g_io_channel_new_file (), and %FALSE for all other channels.
 *
 * Return value: Whether the channel will be closed on the final unref of
 *               the GIOChannel data structure.
810
811
812
813
814
815
816
817
818
 **/
gboolean
g_io_channel_get_close_on_unref	(GIOChannel *channel)
{
  g_return_val_if_fail (channel != NULL, FALSE);

  return channel->close_on_unref;
}

819
820
821
822
/**
 * g_io_channel_seek_position:
 * @channel: a #GIOChannel
 * @offset: The offset in bytes from the position specified by @type
823
824
825
826
 * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those
 *                      cases where a call to g_io_channel_set_encoding ()
 *                      is allowed. See the documentation for
 *                      g_io_channel_set_encoding () for details.
827
828
829
830
 * @error: A location to return an error of type #GIOChannelError
 *
 * Replacement for g_io_channel_seek() with the new API.
 *
831
 * Return value: the status of the operation.
832
833
834
 **/
GIOStatus
g_io_channel_seek_position	(GIOChannel* channel,
Owen Taylor's avatar
Owen Taylor committed
835
				 gint64      offset,
836
837
838
839
840
841
842
843
844
845
846
847
				 GSeekType   type,
				 GError    **error)
{
  GIOStatus status;

  /* For files, only one of the read and write buffers can contain data.
   * For sockets, both can contain data.
   */

  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
  g_return_val_if_fail ((error == NULL) || (*error == NULL),
			G_IO_STATUS_ERROR);
848
  g_return_val_if_fail (channel->is_seekable, G_IO_STATUS_ERROR);
849
850
851
852

  switch (type)
    {
      case G_SEEK_CUR: /* The user is seeking relative to the head of the buffer */
853
        if (channel->use_buffer)
854
          {
855
856
            if (channel->do_encode && channel->encoded_read_buf
                && channel->encoded_read_buf->len > 0)
857
858
859
860
861
862
863
              {
                g_warning ("Seek type G_SEEK_CUR not allowed for this"
                  " channel's encoding.\n");
                return G_IO_STATUS_ERROR;
              }
          if (channel->read_buf)
            offset -= channel->read_buf->len;
864
865
          if (channel->encoded_read_buf)
            {
866
              g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
867
868
869
870
871
872
873
874

              /* If there's anything here, it's because the encoding is UTF-8,
               * so we can just subtract the buffer length, the same as for
               * the unencoded data.
               */

              offset -= channel->encoded_read_buf->len;
            }
875
          }
876
        break;
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
      case G_SEEK_SET:
      case G_SEEK_END:
        break;
      default:
        g_warning ("g_io_channel_seek_position: unknown seek type");
        return G_IO_STATUS_ERROR;
    }

  if (channel->use_buffer)
    {
      status = g_io_channel_flush (channel, error);
      if (status != G_IO_STATUS_NORMAL)
        return status;
    }

  status = channel->funcs->io_seek (channel, offset, type, error);

  if ((status == G_IO_STATUS_NORMAL) && (channel->use_buffer))
    {
896
897
      if (channel->read_buf)
        g_string_truncate (channel->read_buf, 0);
898
899
900
901
902
903
904
905

      /* Conversion state no longer matches position in file */
      if (channel->read_cd != (GIConv) -1)
        g_iconv (channel->read_cd, NULL, NULL, NULL, NULL);
      if (channel->write_cd != (GIConv) -1)
        g_iconv (channel->write_cd, NULL, NULL, NULL, NULL);

      if (channel->encoded_read_buf)
906
        {
907
908
          g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
          g_string_truncate (channel->encoded_read_buf, 0);
909
        }
910

911
912
913
914
      if (channel->partial_write_buf[0] != '\0')
        {
          g_warning ("Partial character at end of write buffer not flushed.\n");
          channel->partial_write_buf[0] = '\0';
915
916
917
918
919
920
921
922
923
924
925
        }
    }

  return status;
}

/**
 * g_io_channel_flush:
 * @channel: a #GIOChannel
 * @error: location to store an error of type #GIOChannelError
 *
Matthias Clasen's avatar
Matthias Clasen committed
926
 * Flushes the write buffer for the GIOChannel.
927
928
 *
 * Return value: the status of the operation: One of
Matthias Clasen's avatar
Matthias Clasen committed
929
930
 *   #G_IO_CHANNEL_NORMAL, #G_IO_CHANNEL_AGAIN, or
 *   #G_IO_CHANNEL_ERROR.
931
932
933
934
935
936
 **/
GIOStatus
g_io_channel_flush (GIOChannel	*channel,
		    GError     **error)
{
  GIOStatus status;
937
  gsize this_time = 1, bytes_written = 0;
938
939
940
941

  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
  g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);

942
  if (channel->write_buf == NULL || channel->write_buf->len == 0)
943
    return G_IO_STATUS_NORMAL;
944
945
946

  do
    {
947
948
      g_assert (this_time > 0);

949
      status = channel->funcs->io_write (channel,
950
951
952
					 channel->write_buf->str + bytes_written,
					 channel->write_buf->len - bytes_written,
					 &this_time, error);
953
954
955
      bytes_written += this_time;
    }
  while ((bytes_written < channel->write_buf->len)
956
         && (status == G_IO_STATUS_NORMAL));
957
958
959

  g_string_erase (channel->write_buf, 0, bytes_written);

960
961
  return status;
}
962

963
964
965
966
967
968
969
970
/**
 * g_io_channel_set_buffered:
 * @channel: a #GIOChannel
 * @buffered: whether to set the channel buffered or unbuffered
 *
 * The buffering state can only be set if the channel's encoding
 * is %NULL. For any other encoding, the channel must be buffered.
 *
971
972
 * A buffered channel can only be set unbuffered if the channel's
 * internal buffers have been flushed. Newly created channels or
Matthias Clasen's avatar
Matthias Clasen committed
973
 * channels which have returned %G_IO_STATUS_EOF
974
975
976
977
978
979
980
981
982
983
984
985
 * not require such a flush. For write-only channels, a call to
 * g_io_channel_flush () is sufficient. For all other channels,
 * the buffers may be flushed by a call to g_io_channel_seek_position ().
 * This includes the possibility of seeking with seek type %G_SEEK_CUR
 * and an offset of zero. Note that this means that socket-based
 * channels cannot be set unbuffered once they have had data
 * read from them.
 *
 * On unbuffered channels, it is safe to mix read and write
 * calls from the new and old APIs, if this is necessary for
 * maintaining old code.
 *
986
987
988
989
990
991
992
 * The default state of the channel is buffered.
 **/
void
g_io_channel_set_buffered	(GIOChannel *channel,
				 gboolean    buffered)
{
  g_return_if_fail (channel != NULL);
993

994
995
996
997
998
999
  if (channel->encoding != NULL)
    {
      g_warning ("Need to have NULL encoding to set the buffering state of the "
                 "channel.\n");
      return;
    }
1000

1001
1002
1003
1004
1005
1006
1007
1008
  g_return_if_fail (!channel->read_buf || channel->read_buf->len == 0);
  g_return_if_fail (!channel->write_buf || channel->write_buf->len == 0);

  channel->use_buffer = buffered;
}

/**
 * g_io_channel_get_buffered:
1009
1010
 * @channel: a #GIOChannel.
 *
1011
 * Returns whether @channel is buffered.
1012
 *
1013
 * Return Value: %TRUE if the @channel is buffered. 
1014
1015
1016
1017
1018
1019
1020
 **/
gboolean
g_io_channel_get_buffered	(GIOChannel *channel)
{
  g_return_val_if_fail (channel != NULL, FALSE);

  return channel->use_buffer;
1021
1022
1023
1024
1025
1026
1027
1028
}

/**
 * g_io_channel_set_encoding:
 * @channel: a #GIOChannel
 * @encoding: the encoding type
 * @error: location to store an error of type #GConvertError.
 *
Matthias Clasen's avatar
Matthias Clasen committed
1029
 * Sets the encoding for the input/output of the channel. The internal
1030
1031
 * encoding is always UTF-8. The default encoding for the
 * external file is UTF-8.
1032
 *
1033
 * The encoding %NULL is safe to use with binary data.
1034
 *
1035
1036
 * The encoding can only be set if one of the following conditions
 * is true:
1037
1038
1039
1040
 *
 * 1. The channel was just created, and has not been written to
 *    or read from yet.
 *
1041
1042
1043
 * 2. The channel is write-only.
 *
 * 3. The channel is a file, and the file pointer was just
1044
1045
1046
 *    repositioned by a call to g_io_channel_seek_position().
 *    (This flushes all the internal buffers.)
 *
1047
1048
 * 4. The current encoding is %NULL or UTF-8.
 *
Matthias Clasen's avatar
Matthias Clasen committed
1049
1050
 * 5. One of the (new API) read functions has just returned %G_IO_STATUS_EOF
 *    (or, in the case of g_io_channel_read_to_end (), %G_IO_STATUS_NORMAL).
1051
1052
 *
 * 6. One of the functions g_io_channel_read_chars () or g_io_channel_read_unichar ()
Matthias Clasen's avatar
Matthias Clasen committed
1053
1054
 *    has returned %G_IO_STATUS_AGAIN or %G_IO_STATUS_ERROR. This may be
 *    useful in the case of %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
1055
1056
 *    Returning one of these statuses from g_io_channel_read_line (),
 *    g_io_channel_read_line_string (), or g_io_channel_read_to_end ()
Matthias Clasen's avatar
Matthias Clasen committed
1057
 *    does <emphasis>not</emphasis> guarantee that the encoding can be changed.
1058
 *
1059
 * Channels which do not meet one of the above conditions cannot call
1060
 * g_io_channel_seek_position () with an offset of %G_SEEK_CUR,
1061
 * and, if they are "seekable", cannot
1062
1063
 * call g_io_channel_write_chars () after calling one
 * of the API "read" functions.
1064
 *
Matthias Clasen's avatar
Matthias Clasen committed
1065
 * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set.
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
 **/
GIOStatus
g_io_channel_set_encoding (GIOChannel	*channel,
                           const gchar	*encoding,
			   GError      **error)
{
  GIConv read_cd, write_cd;
  gboolean did_encode;

  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
  g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);

1078
  /* Make sure the encoded buffers are empty */
1079

1080
  g_return_val_if_fail (!channel->do_encode || !channel->encoded_read_buf ||
1081
1082
			channel->encoded_read_buf->len == 0, G_IO_STATUS_ERROR);

1083
  if (!channel->use_buffer)
1084
    {
1085
1086
1087
      g_warning ("Need to set the channel buffered before setting the encoding.\n");
      g_warning ("Assuming this is what you meant and acting accordingly.\n");

1088
1089
      channel->use_buffer = TRUE;
    }
1090

1091
1092
1093
1094
1095
1096
  if (channel->partial_write_buf[0] != '\0')
    {
      g_warning ("Partial character at end of write buffer not flushed.\n");
      channel->partial_write_buf[0] = '\0';
    }

1097
1098
1099
  did_encode = channel->do_encode;

  if (!encoding || strcmp (encoding, "UTF8") == 0 || strcmp (encoding, "UTF-8") == 0)
1100
1101
    {
      channel->do_encode = FALSE;
1102
      read_cd = write_cd = (GIConv) -1;
1103
1104
1105
    }
  else
    {
1106
1107
      gint err = 0;
      const gchar *from_enc = NULL, *to_enc = NULL;
1108

1109
      if (channel->is_readable)
1110
        {
1111
1112
1113
1114
1115
1116
1117
1118
          read_cd = g_iconv_open ("UTF-8", encoding);

          if (read_cd == (GIConv) -1)
            {
              err = errno;
              from_enc = "UTF-8";
              to_enc = encoding;
            }
1119
1120
        }
      else
1121
1122
1123
        read_cd = (GIConv) -1;

      if (channel->is_writeable && err == 0)
1124
1125
        {
          write_cd = g_iconv_open (encoding, "UTF-8");
1126

1127
1128
1129
1130
1131
1132
1133
          if (write_cd == (GIConv) -1)
            {
              err = errno;
              from_enc = encoding;
              to_enc = "UTF-8";
            }
        }
1134
1135
      else
        write_cd = (GIConv) -1;
1136

1137
      if (err != 0)
1138
        {
1139
1140
1141
          g_assert (from_enc);
          g_assert (to_enc);

1142
1143
1144
1145
1146
1147
1148
          if (err == EINVAL)
            g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_CONVERSION,
                         _("Conversion from character set `%s' to `%s' is not supported"),
                         from_enc, to_enc);
          else
            g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
                         _("Could not open converter from `%s' to `%s': %s"),
Owen Taylor's avatar
Owen Taylor committed
1149
                         from_enc, to_enc, g_strerror (err));
1150
1151
1152
1153
1154
1155

          if (read_cd != (GIConv) -1)
            g_iconv_close (read_cd);
          if (write_cd != (GIConv) -1)
            g_iconv_close (write_cd);

1156
1157
1158
1159
1160
1161
1162
1163
          return G_IO_STATUS_ERROR;
        }

      channel->do_encode = TRUE;
    }

  /* The encoding is ok, so set the fields in channel */

1164
1165
1166
1167
  if (channel->read_cd != (GIConv) -1)
    g_iconv_close (channel->read_cd);
  if (channel->write_cd != (GIConv) -1)
    g_iconv_close (channel->write_cd);
1168

1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
  if (channel->encoded_read_buf && channel->encoded_read_buf->len > 0)
    {
      g_assert (!did_encode); /* Encoding UTF-8, NULL doesn't use encoded_read_buf */

      /* This is just validated UTF-8, so we can copy it back into read_buf
       * so it can be encoded in whatever the new encoding is.
       */

      g_string_prepend_len (channel->read_buf, channel->encoded_read_buf->str,
                            channel->encoded_read_buf->len);
      g_string_truncate (channel->encoded_read_buf, 0);
    }

1182
1183
  channel->read_cd = read_cd;
  channel->write_cd = write_cd;
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194

  g_free (channel->encoding);
  channel->encoding = g_strdup (encoding);

  return G_IO_STATUS_NORMAL;
}

/**
 * g_io_channel_get_encoding:
 * @channel: a #GIOChannel
 *
Matthias Clasen's avatar
Matthias Clasen committed
1195
 * Gets the encoding for the input/output of the channel. The internal
1196
1197
 * encoding is always UTF-8. The encoding %NULL makes the
 * channel safe for binary data.
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
 *
 * Return value: A string containing the encoding, this string is
 *   owned by GLib and must not be freed.
 **/
G_CONST_RETURN gchar*
g_io_channel_get_encoding (GIOChannel      *channel)
{
  g_return_val_if_fail (channel != NULL, NULL);

  return channel->encoding;
}

static GIOStatus
g_io_channel_fill_buffer (GIOChannel *channel,
                          GError    **err)
{
  gsize read_size, cur_len, oldlen;
  GIOStatus status;

1217
  if (channel->is_seekable && channel->write_buf && channel->write_buf->len > 0)
1218
    {
1219
1220
1221
1222
1223
1224
1225
1226
      status = g_io_channel_flush (channel, err);
      if (status != G_IO_STATUS_NORMAL)
        return status;
    }
  if (channel->is_seekable && channel->partial_write_buf[0] != '\0')
    {
      g_warning ("Partial character at end of write buffer not flushed.\n");
      channel->partial_write_buf[0] = '\0';
1227
1228
    }

1229
1230
  if (!channel->read_buf)
    channel->read_buf = g_string_sized_new (channel->buf_size);
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248

  cur_len = channel->read_buf->len;

  g_string_set_size (channel->read_buf, channel->read_buf->len + channel->buf_size);

  status = channel->funcs->io_read (channel, channel->read_buf->str + cur_len,
                                    channel->buf_size, &read_size, err);

  g_assert ((status == G_IO_STATUS_NORMAL) || (read_size == 0));

  g_string_truncate (channel->read_buf, read_size + cur_len);

  if ((status != G_IO_STATUS_NORMAL)
    && ((status != G_IO_STATUS_EOF) || (channel->read_buf->len == 0)))
    return status;

  g_assert (channel->read_buf->len > 0);

1249
1250
1251
  if (channel->encoded_read_buf)
    oldlen = channel->encoded_read_buf->len;
  else
1252
1253
    {
      oldlen = 0;
1254
1255
      if (channel->encoding)
        channel->encoded_read_buf = g_string_sized_new (channel->buf_size);
1256
    }
1257

1258
1259
1260
1261
  if (channel->do_encode)
    {
      size_t errnum, inbytes_left, outbytes_left;
      gchar *inbuf, *outbuf;
1262
      int errval;
1263

1264
1265
      g_assert (channel->encoded_read_buf);

1266
1267
1268
reencode:

      inbytes_left = channel->read_buf->len;
1269
      outbytes_left = MAX (channel->read_buf->len,
1270
                           channel->encoded_read_buf->allocated_len
1271
1272
                           - channel->encoded_read_buf->len - 1); /* 1 for NULL */
      outbytes_left = MAX (outbytes_left, 6);
1273
1274

      inbuf = channel->read_buf->str;
1275
1276
      g_string_set_size (channel->encoded_read_buf,
                         channel->encoded_read_buf->len + outbytes_left);
1277
1278
      outbuf = channel->encoded_read_buf->str + channel->encoded_read_buf->len
               - outbytes_left;
1279
1280
1281

      errnum = g_iconv (channel->read_cd, &inbuf, &inbytes_left,
			&outbuf, &outbytes_left);
1282
1283
1284
1285
1286
1287
      errval = errno;

      g_assert (inbuf + inbytes_left == channel->read_buf->str
                + channel->read_buf->len);
      g_assert (outbuf + outbytes_left == channel->encoded_read_buf->str
                + channel->encoded_read_buf->len);
1288
1289
1290
1291
1292
1293
1294
1295

      g_string_erase (channel->read_buf, 0,
		      channel->read_buf->len - inbytes_left);
      g_string_truncate (channel->encoded_read_buf,
			 channel->encoded_read_buf->len - outbytes_left);

      if (errnum == (size_t) -1)
        {
1296
          switch (errval)
1297
1298
1299
1300
            {
              case EINVAL:
                if ((oldlen == channel->encoded_read_buf->len)
                  && (status == G_IO_STATUS_EOF))
1301
                  status = G_IO_STATUS_EOF;
1302
1303
1304
1305
                else
                  status = G_IO_STATUS_NORMAL;
                break;
              case E2BIG:
1306
1307
                /* Buffer size at least 6, wrote at least on character */
                g_assert (inbuf != channel->read_buf->str);
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
                goto reencode;
              case EILSEQ:
                if (oldlen < channel->encoded_read_buf->len)
                  status = G_IO_STATUS_NORMAL;
                else
                  {
                    g_set_error (err, G_CONVERT_ERROR,
                      G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
                      _("Invalid byte sequence in conversion input"));
                    return G_IO_STATUS_ERROR;
                  }
                break;
              default:
1321
                g_assert (errval != EBADF); /* The converter should be open */
1322
                g_set_error (err, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
Owen Taylor's avatar
Owen Taylor committed
1323
                  _("Error during conversion: %s"), g_strerror (errval));