giochannel.c 67.8 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 45 46
#undef G_DISABLE_DEPRECATED

#include "glib.h"

47 48
#include "giochannel.h"

49 50
#include "glibintl.h"

51 52
#include "galias.h"

53 54
#define G_IO_NICE_BUF_SIZE	1024

55 56 57 58 59 60 61 62 63 64 65
/* 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)

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

76 77
void
g_io_channel_init (GIOChannel *channel)
78
{
79
  channel->ref_count = 1;
80
  channel->encoding = g_strdup ("UTF-8");
81
  channel->line_term = NULL;
82
  channel->line_term_len = 0;
83
  channel->buf_size = G_IO_NICE_BUF_SIZE;
84 85 86 87 88 89
  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';
90 91 92
  channel->use_buffer = TRUE;
  channel->do_encode = FALSE;
  channel->close_on_unref = FALSE;
93 94
}

95
GIOChannel *
96 97
g_io_channel_ref (GIOChannel *channel)
{
98
  g_return_val_if_fail (channel != NULL, NULL);
99

100
  g_atomic_int_inc (&channel->ref_count);
101 102

  return channel;
103 104 105 106 107
}

void 
g_io_channel_unref (GIOChannel *channel)
{
108 109
  gboolean is_zero;

110 111
  g_return_if_fail (channel != NULL);

112 113 114
  is_zero = g_atomic_int_dec_and_test (&channel->ref_count);

  if (G_UNLIKELY (is_zero))
115 116
    {
      if (channel->close_on_unref)
117
        g_io_channel_shutdown (channel, TRUE, NULL);
118 119 120
      else
        g_io_channel_purge (channel);
      g_free (channel->encoding);
121 122 123 124
      if (channel->read_cd != (GIConv) -1)
        g_iconv_close (channel->read_cd);
      if (channel->write_cd != (GIConv) -1)
        g_iconv_close (channel->write_cd);
125
      g_free (channel->line_term);
126 127 128 129 130 131
      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);
132 133
      channel->funcs->io_free (channel);
    }
134 135
}

136
static GIOError
137 138
g_io_error_get_from_g_error (GIOStatus  status,
			     GError    *err)
139 140 141 142 143 144 145 146 147
{
  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:
148 149
	g_return_val_if_fail (err != NULL, G_IO_ERROR_UNKNOWN);
	
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:
167 168 169 170 171
 * @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
172
 * 
173
 * Reads data from a #GIOChannel. 
174 175
 * 
 * Return value: %G_IO_ERROR_NONE if the operation was successful. 
176
 *
177
 * Deprecated:2.2: Use g_io_channel_read_chars() instead.
178
 **/
179 180 181
GIOError 
g_io_channel_read (GIOChannel *channel, 
		   gchar      *buf, 
182 183
		   gsize       count,
		   gsize      *bytes_read)
184
{
185 186 187 188
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

189
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
190 191
  g_return_val_if_fail (bytes_read != NULL, G_IO_ERROR_UNKNOWN);

192 193 194 195
  if (count == 0)
    {
      if (bytes_read)
        *bytes_read = 0;
196
      return G_IO_ERROR_NONE;
197 198 199 200
    }

  g_return_val_if_fail (buf != NULL, G_IO_ERROR_UNKNOWN);

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

203 204 205 206 207 208
  error = g_io_error_get_from_g_error (status, err);

  if (err)
    g_error_free (err);

  return error;
209 210
}

211 212
/**
 * g_io_channel_write:
213 214 215 216
 * @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
217
 * 
218
 * Writes data to a #GIOChannel. 
219 220
 * 
 * Return value:  %G_IO_ERROR_NONE if the operation was successful.
221
 *
222
 * Deprecated:2.2: Use g_io_channel_write_chars() instead.
223
 **/
224
GIOError 
225 226 227 228
g_io_channel_write (GIOChannel  *channel, 
		    const gchar *buf, 
		    gsize        count,
		    gsize       *bytes_written)
229
{
230 231 232 233
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

234
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
235 236 237 238 239
  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);
240

241 242 243 244
  if (err)
    g_error_free (err);

  return error;
245 246
}

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

272
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
273
  g_return_val_if_fail (channel->is_seekable, G_IO_ERROR_UNKNOWN);
274

275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293
  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;
294
}
295 296 297 298 299 300 301

/* 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:
302
 * @filename: A string containing the name of a file
303
 * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
304 305
 *        the same meaning as in fopen()
 * @error: A location to return an error of type %G_FILE_ERROR
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
 *
 * 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
322 323
 * last reference is dropped using g_io_channel_unref(). 
 *
324
 * Deprecated:2.2: Use g_io_channel_shutdown() instead.
325
 **/
326 327 328
void
g_io_channel_close (GIOChannel *channel)
{
329 330
  GError *err = NULL;
  
331 332
  g_return_if_fail (channel != NULL);

333 334 335 336 337 338 339 340 341 342 343
  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 */
344 345 346
  channel->is_readable = FALSE;
  channel->is_writeable = FALSE;
  channel->is_seekable = FALSE;
347 348 349 350 351 352 353 354 355
}

/**
 * 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
356
 * flushed if @flush is %TRUE. The channel will not be freed until the
357
 * last reference is dropped using g_io_channel_unref().
358
 *
359
 * Return value: the status of the operation.
360 361
 **/
GIOStatus
362 363 364
g_io_channel_shutdown (GIOChannel  *channel,
		       gboolean     flush,
		       GError     **err)
365
{
366 367
  GIOStatus status, result;
  GError *tmperr = NULL;
368 369
  
  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
370
  g_return_val_if_fail (err == NULL || *err == NULL, G_IO_STATUS_ERROR);
371

372
  if (channel->write_buf && channel->write_buf->len > 0)
373
    {
374 375 376
      if (flush)
        {
          GIOFlags flags;
377
      
378 379 380 381 382
          /* 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);
383

384
          result = g_io_channel_flush (channel, &tmperr);
385
        }
386 387 388 389
      else
        result = G_IO_STATUS_NORMAL;

      g_string_truncate(channel->write_buf, 0);
390
    }
391 392
  else
    result = G_IO_STATUS_NORMAL;
393

394 395 396 397 398 399 400
  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';
    }

401
  status = channel->funcs->io_close (channel, err);
402 403

  channel->close_on_unref = FALSE; /* Because we already did */
404 405 406
  channel->is_readable = FALSE;
  channel->is_writeable = FALSE;
  channel->is_seekable = FALSE;
407

408 409 410 411 412 413 414 415 416 417 418 419
  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;
420 421 422 423 424 425 426
}

/* This function is used for the final flush on close or unref */
static void
g_io_channel_purge (GIOChannel *channel)
{
  GError *err = NULL;
427
  GIOStatus status;
428 429 430

  g_return_if_fail (channel != NULL);

431
  if (channel->write_buf && channel->write_buf->len > 0)
432 433 434 435 436 437 438 439
    {
      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);

440
      status = g_io_channel_flush (channel, &err);
441 442 443 444 445 446 447 448 449 450

      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 */

451 452 453 454
  if (channel->read_buf)
    g_string_truncate (channel->read_buf, 0);
  if (channel->write_buf)
    g_string_truncate (channel->write_buf, 0);
455
  if (channel->encoding)
456 457 458 459 460 461 462 463 464 465
    {
      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';
        }
    }
466 467
}

468
GSource *
469 470
g_io_create_watch (GIOChannel   *channel,
		   GIOCondition  condition)
471 472 473 474 475 476
{
  g_return_val_if_fail (channel != NULL, NULL);

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

477
guint 
478
g_io_add_watch_full (GIOChannel    *channel,
479 480 481 482 483 484
		     gint           priority,
		     GIOCondition   condition,
		     GIOFunc        func,
		     gpointer       user_data,
		     GDestroyNotify notify)
{
485
  GSource *source;
486
  guint id;
487
  
488 489
  g_return_val_if_fail (channel != NULL, 0);

490 491 492 493 494 495
  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);

496 497 498 499
  id = g_source_attach (source, NULL);
  g_source_unref (source);

  return id;
500 501 502
}

guint 
503 504 505 506
g_io_add_watch (GIOChannel   *channel,
		GIOCondition  condition,
		GIOFunc       func,
		gpointer      user_data)
507
{
508
  return g_io_add_watch_full (channel, G_PRIORITY_DEFAULT, condition, func, user_data, NULL);
509
}
510 511 512 513 514

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

526 527 528 529 530 531 532 533 534 535
  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;
    }
536 537

  if (channel->write_buf && (channel->write_buf->len < channel->buf_size))
538
    condition |= G_IO_OUT;
539 540

  return condition;
541 542 543
}

/**
544
 * g_io_channel_error_from_errno:
545
 * @en: an <literal>errno</literal> error number, e.g. %EINVAL
546
 *
547 548
 * Converts an <literal>errno</literal> error number to a #GIOChannelError.
 *
549 550
 * Return value: a #GIOChannelError error number, e.g. 
 *      %G_IO_CHANNEL_ERROR_INVAL.
551 552
 **/
GIOChannelError
553
g_io_channel_error_from_errno (gint en)
554 555 556 557 558 559 560 561 562
{
#ifdef EAGAIN
  g_return_val_if_fail (en != EAGAIN, G_IO_CHANNEL_ERROR_FAILED);
#endif

  switch (en)
    {
#ifdef EBADF
    case EBADF:
563 564
      g_warning("Invalid file descriptor.\n");
      return G_IO_CHANNEL_ERROR_FAILED;
565 566 567 568
#endif

#ifdef EFAULT
    case EFAULT:
569
      g_warning("Buffer outside valid address space.\n");
570 571 572 573 574 575
      return G_IO_CHANNEL_ERROR_FAILED;
#endif

#ifdef EFBIG
    case EFBIG:
      return G_IO_CHANNEL_ERROR_FBIG;
576 577
#endif

578 579 580 581 582 583 584 585 586 587 588 589
#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

590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609
#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

610 611 612
#ifdef ENXIO
    case ENXIO:
      return G_IO_CHANNEL_ERROR_NXIO;
613
#endif
614 615 616 617 618 619

#ifdef EOVERFLOW
    case EOVERFLOW:
      return G_IO_CHANNEL_ERROR_OVERFLOW;
#endif

620 621 622 623 624 625 626 627 628 629 630 631 632
#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
633
 * @size: the size of the buffer, or 0 to let GLib pick a good size
634
 *
Matthias Clasen's avatar
Matthias Clasen committed
635
 * Sets the buffer size.
636 637
 **/  
void
638 639
g_io_channel_set_buffer_size (GIOChannel *channel,
                              gsize       size)
640 641 642 643 644 645
{
  g_return_if_fail (channel != NULL);

  if (size == 0)
    size = G_IO_NICE_BUF_SIZE;

646 647
  if (size < MAX_CHAR_SIZE)
    size = MAX_CHAR_SIZE;
648

649 650 651 652 653 654 655
  channel->buf_size = size;
}

/**
 * g_io_channel_get_buffer_size:
 * @channel: a #GIOChannel
 *
Matthias Clasen's avatar
Matthias Clasen committed
656
 * Gets the buffer size.
657 658 659 660
 *
 * Return value: the size of the buffer.
 **/  
gsize
661
g_io_channel_get_buffer_size (GIOChannel *channel)
662 663 664 665 666 667 668 669 670
{
  g_return_val_if_fail (channel != NULL, 0);

  return channel->buf_size;
}

/**
 * g_io_channel_set_line_term:
 * @channel: a #GIOChannel
671 672 673
 * @line_term: The line termination string. Use %NULL for autodetect.
 *             Autodetection breaks on "\n", "\r\n", "\r", "\0", and
 *             the Unicode paragraph separator. Autodetection should
674
 *             not be used for anything other than file-based channels.
675
 * @length: The length of the termination string. If -1 is passed, the
Matthias Clasen's avatar
Matthias Clasen committed
676
 *          string is assumed to be nul-terminated. This option allows
677
 *          termination strings with embedded nuls.
678 679 680 681 682 683
 *
 * 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,
684 685
                            const gchar	*line_term,
			    gint         length)
686 687
{
  g_return_if_fail (channel != NULL);
688
  g_return_if_fail (line_term == NULL || length != 0); /* Disallow "" */
689

690 691 692 693 694
  if (line_term == NULL)
    length = 0;
  else if (length < 0)
    length = strlen (line_term);

695
  g_free (channel->line_term);
696 697
  channel->line_term = line_term ? g_memdup (line_term, length) : NULL;
  channel->line_term_len = length;
698 699 700 701 702
}

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

718 719 720
  if (length)
    *length = channel->line_term_len;

721 722 723 724 725
  return channel->line_term;
}

/**
 * g_io_channel_set_flags:
726 727 728
 * @channel: a #GIOChannel
 * @flags: the flags to set on the IO channel
 * @error: A location to return an error of type #GIOChannelError
729
 *
730
 * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).
731
 *
732
 * Return value: the status of the operation. 
733 734
 **/
GIOStatus
735 736 737
g_io_channel_set_flags (GIOChannel  *channel,
                        GIOFlags     flags,
                        GError     **error)
738 739 740 741 742
{
  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
  g_return_val_if_fail ((error == NULL) || (*error == NULL),
			G_IO_STATUS_ERROR);

743
  return (*channel->funcs->io_set_flags) (channel,
744 745 746 747 748 749 750 751 752 753
					  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.
754
 *
755 756 757
 * 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
758
 * of a socket with the UNIX shutdown() function), the user
759
 * should immediately call g_io_channel_get_flags() to update
760 761
 * the internal values of these flags.
 *
762
 * Return value: the flags which are set on the channel
763 764 765 766
 **/
GIOFlags
g_io_channel_get_flags (GIOChannel *channel)
{
767 768
  GIOFlags flags;

769
  g_return_val_if_fail (channel != NULL, 0);
770

771 772 773 774 775 776 777 778 779 780 781 782
  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;
783 784
}

785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806
/**
 * 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:
807
 * @channel: a #GIOChannel.
808
 *
809 810 811 812 813 814 815
 * 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.
816 817 818 819 820 821 822 823 824
 **/
gboolean
g_io_channel_get_close_on_unref	(GIOChannel *channel)
{
  g_return_val_if_fail (channel != NULL, FALSE);

  return channel->close_on_unref;
}

825 826 827 828
/**
 * g_io_channel_seek_position:
 * @channel: a #GIOChannel
 * @offset: The offset in bytes from the position specified by @type
829 830 831 832
 * @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.
833 834 835 836
 * @error: A location to return an error of type #GIOChannelError
 *
 * Replacement for g_io_channel_seek() with the new API.
 *
837
 * Return value: the status of the operation.
838 839
 **/
GIOStatus
840 841 842 843
g_io_channel_seek_position (GIOChannel  *channel,
                            gint64       offset,
                            GSeekType    type,
                            GError     **error)
844 845 846 847 848 849 850 851 852 853
{
  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);
854
  g_return_val_if_fail (channel->is_seekable, G_IO_STATUS_ERROR);
855 856 857 858

  switch (type)
    {
      case G_SEEK_CUR: /* The user is seeking relative to the head of the buffer */
859
        if (channel->use_buffer)
860
          {
861 862
            if (channel->do_encode && channel->encoded_read_buf
                && channel->encoded_read_buf->len > 0)
863 864 865 866 867 868 869
              {
                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;
870 871
          if (channel->encoded_read_buf)
            {
872
              g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
873 874 875 876 877 878 879 880

              /* 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;
            }
881
          }
882
        break;
883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901
      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))
    {
902 903
      if (channel->read_buf)
        g_string_truncate (channel->read_buf, 0);
904 905 906 907 908 909 910 911

      /* 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)
912
        {
913 914
          g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
          g_string_truncate (channel->encoded_read_buf, 0);
915
        }
916

917 918 919 920
      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';
921 922 923 924 925 926 927 928 929 930 931
        }
    }

  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
932
 * Flushes the write buffer for the GIOChannel.
933 934
 *
 * Return value: the status of the operation: One of
Matthias Clasen's avatar
Matthias Clasen committed
935 936
 *   #G_IO_CHANNEL_NORMAL, #G_IO_CHANNEL_AGAIN, or
 *   #G_IO_CHANNEL_ERROR.
937 938 939 940 941 942
 **/
GIOStatus
g_io_channel_flush (GIOChannel	*channel,
		    GError     **error)
{
  GIOStatus status;
943
  gsize this_time = 1, bytes_written = 0;
944 945 946 947

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

948
  if (channel->write_buf == NULL || channel->write_buf->len == 0)
949
    return G_IO_STATUS_NORMAL;
950 951 952

  do
    {
953 954
      g_assert (this_time > 0);

955
      status = channel->funcs->io_write (channel,
956 957 958
					 channel->write_buf->str + bytes_written,
					 channel->write_buf->len - bytes_written,
					 &this_time, error);
959 960 961
      bytes_written += this_time;
    }
  while ((bytes_written < channel->write_buf->len)
962
         && (status == G_IO_STATUS_NORMAL));
963 964 965

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

966 967
  return status;
}
968

969 970 971 972 973 974 975 976
/**
 * 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.
 *
977 978
 * 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
979
 * channels which have returned %G_IO_STATUS_EOF
980 981 982 983 984 985 986 987 988 989 990 991
 * 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.
 *
992 993 994
 * The default state of the channel is buffered.
 **/
void
995 996
g_io_channel_set_buffered (GIOChannel *channel,
                           gboolean    buffered)
997 998
{
  g_return_if_fail (channel != NULL);
999

1000 1001 1002 1003 1004 1005
  if (channel->encoding != NULL)
    {
      g_warning ("Need to have NULL encoding to set the buffering state of the "
                 "channel.\n");
      return;
    }
1006

1007 1008 1009 1010 1011 1012 1013 1014
  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:
1015
 * @channel: a #GIOChannel
1016
 *
1017
 * Returns whether @channel is buffered.
1018
 *
1019
 * Return Value: %TRUE if the @channel is buffered. 
1020 1021
 **/
gboolean
1022
g_io_channel_get_buffered (GIOChannel *channel)
1023 1024 1025 1026
{
  g_return_val_if_fail (channel != NULL, FALSE);

  return channel->use_buffer;
1027 1028 1029 1030 1031 1032
}

/**
 * g_io_channel_set_encoding:
 * @channel: a #GIOChannel
 * @encoding: the encoding type
1033
 * @error: location to store an error of type #GConvertError
1034
 *
1035 1036 1037
 * Sets the encoding for the input/output of the channel. 
 * The internal encoding is always UTF-8. The default encoding 
 * for the external file is UTF-8.
1038
 *
1039
 * The encoding %NULL is safe to use with binary data.
1040
 *
1041 1042
 * The encoding can only be set if one of the following conditions
 * is true:
1043 1044 1045 1046 1047 1048 1049 1050 1051 1052
 * <itemizedlist>
 * <listitem><para>
 *    The channel was just created, and has not been written to or read 
 *    from yet.
 * </para></listitem>
 * <listitem><para>
 *    The channel is write-only.
 * </para></listitem>
 * <listitem><para>
 *    The channel is a file, and the file pointer was just
1053 1054
 *    repositioned by a call to g_io_channel_seek_position().
 *    (This flushes all the internal buffers.)
1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073
 * </para></listitem>
 * <listitem><para>
 *    The current encoding is %NULL or UTF-8.
 * </para></listitem>
 * <listitem><para>
 *    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).
 * </para></listitem>
 * <listitem><para>
 *    One of the functions g_io_channel_read_chars() or 
 *    g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or 
 *    %G_IO_STATUS_ERROR. This may be useful in the case of 
 *    %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
 *    Returning one of these statuses from g_io_channel_read_line(),
 *    g_io_channel_read_line_string(), or g_io_channel_read_to_end()
 *    does <emphasis>not</emphasis> guarantee that the encoding can 
 *    be changed.
 * </para></listitem>
 * </itemizedlist>
1074
 * Channels which do not meet one of the above conditions cannot call
1075 1076 1077
 * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if 
 * they are "seekable", cannot call g_io_channel_write_chars() after 
 * calling one of the API "read" functions.
1078
 *
Matthias Clasen's avatar
Matthias Clasen committed
1079
 * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set.
1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091
 **/
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);

1092
  /* Make sure the encoded buffers are empty */
1093

1094
  g_return_val_if_fail (!channel->do_encode || !channel->encoded_read_buf ||
1095 1096
			channel->encoded_read_buf->len == 0, G_IO_STATUS_ERROR);

1097
  if (!channel->use_buffer)
1098
    {
1099 1100 1101
      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");

1102 1103
      channel->use_buffer = TRUE;
    }
1104

1105 1106 1107 1108 1109 1110
  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';
    }

1111 1112 1113
  did_encode = channel->do_encode;

  if (!encoding || strcmp (encoding, "UTF8") == 0 || strcmp (encoding, "UTF-8") == 0)
1114 1115
    {
      channel->do_encode = FALSE;
1116
      read_cd = write_cd = (GIConv) -1;
1117 1118 1119
    }
  else
    {
1120 1121
      gint err = 0;
      const gchar *from_enc = NULL, *to_enc = NULL;
1122

1123
      if (channel->is_readable)
1124
        {
1125 1126 1127 1128 1129 1130 1131 1132
          read_cd = g_iconv_open ("UTF-8", encoding);

          if (read_cd == (GIConv) -1)
            {
              err = errno;
              from_enc = "UTF-8";
              to_enc = encoding;
            }
1133 1134
        }
      else
1135 1136 1137
        read_cd = (GIConv) -1;

      if (channel->is_writeable && err == 0)
1138 1139
        {
          write_cd = g_iconv_open (encoding, "UTF-8");
1140

1141 1142 1143 1144 1145 1146 1147
          if (write_cd == (GIConv) -1)
            {
              err = errno;
              from_enc = encoding;
              to_enc = "UTF-8";
            }
        }
1148 1149
      else
        write_cd = (GIConv) -1;
1150

1151
      if (err != 0)
1152
        {
1153 1154 1155
          g_assert (from_enc);
          g_assert (to_enc);

1156 1157
          if (err == EINVAL)
            g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_CONVERSION,
1158
                         _("Conversion from character set '%s' to '%s' is not supported"),
1159 1160 1161
                         from_enc, to_enc);
          else
            g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1162
                         _("Could not open converter from '%s' to '%s': %s"),
Owen Taylor's avatar
Owen Taylor committed
1163
                         from_enc, to_enc, g_strerror (err));
1164 1165 1166 1167 1168 1169

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

1170 1171 1172 1173 1174 1175 1176 1177
          return G_IO_STATUS_ERROR;
        }

      channel->do_encode = TRUE;
    }

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

1178 1179 1180 1181
  if (channel->read_cd != (GIConv) -1)
    g_iconv_close (channel->read_cd);
  if (channel->write_cd != (GIConv) -1)
    g_iconv_close (channel->write_cd);
1182

1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195
  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);
    }

1196 1197
  channel->read_cd = read_cd;
  channel->write_cd = write_cd;
1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208

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

  return G_IO_STATUS_NORMAL;
}

/**
 * g_io_channel_get_encoding:
 * @channel: a #GIOChannel
 *
1209 1210 1211
 * Gets the encoding for the input/output of the channel. 
 * The internal encoding is always UTF-8. The encoding %NULL 
 * makes the channel safe for binary data.
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*
1217
g_io_channel_get_encoding (GIOChannel *channel)
1218 1219 1220 1221 1222 1223 1224
{
  g_return_val_if_fail (channel != NULL, NULL);

  return channel->encoding;
}

static GIOStatus
1225 1226
g_io_channel_fill_buffer (GIOChannel  *channel,
                          GError     **err)
1227 1228 1229 1230
{
  gsize read_size, cur_len, oldlen;
  GIOStatus status;

1231
  if (channel->is_seekable && channel->write_buf && channel->write_buf->len > 0)
1232
    {
1233 1234 1235 1236 1237 1238 1239 1240
      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';
1241 1242
    }

1243 1244
  if (!channel->read_buf)
    channel->read_buf = g_string_sized_new (channel->buf_size);
1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256

  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);

1257 1258
  if ((status != G_IO_STATUS_NORMAL) &&
      ((status != G_IO_STATUS_EOF) || (channel->read_buf->len == 0)))
1259 1260 1261 1262
    return status;

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

1263 1264 1265
  if (channel->encoded_read_buf)
    oldlen = channel->encoded_read_buf->len;
  else
1266 1267
    {
      oldlen = 0;
1268 1269
      if (channel->encoding)
        channel->encoded_read_buf = g_string_sized_new (channel->buf_size);
1270
    }
1271

1272 1273
  if (channel->do_encode)
    {
1274
      gsize errnum, inbytes_left, outbytes_left;
1275
      gchar *inbuf, *outbuf;
1276
      int errval;
1277

1278 1279
      g_assert (channel->encoded_read_buf);

1280 1281 1282
reencode:

      inbytes_left = channel->read_buf->len;
1283
      outbytes_left = MAX (channel->read_buf->len,
1284
                           channel->encoded_read_buf->allocated_len
1285 1286
                           - channel->encoded_read_buf->len - 1); /* 1 for NULL */
      outbytes_left = MAX (outbytes_left, 6);
1287 1288

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

      errnum = g_iconv (channel->read_cd, &inbuf, &inbytes_left,
			&outbuf, &outbytes_left);
1296 1297 1298 1299 1300 1301
      errval = errno;

      g_assert (inbuf + inbytes_left == channel->read_buf->str
                + channel->read_buf->len