giochannel.c 78.3 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 46
#include "giochannel.h"

47
#include "gstrfuncs.h"
Matthias Clasen's avatar
Matthias Clasen committed
48
#include "gtestutils.h"
49 50
#include "glibintl.h"

51

52
/**
Johan Dahlin's avatar
Johan Dahlin committed
53
 * SECTION:iochannels
54 55 56 57
 * @title: IO Channels
 * @short_description: portable support for using files, pipes and
 *                     sockets
 * @see_also: <para> <variablelist> <varlistentry>
58 59
 *            <term>g_io_add_watch(), g_io_add_watch_full(),
 *            g_source_remove()</term> <listitem><para> Convenience
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
 *            functions for creating #GIOChannel instances and adding
 *            them to the <link linkend="glib-The-Main-Event-Loop">main
 *            event loop</link>. </para></listitem> </varlistentry>
 *            </variablelist> </para>
 *
 * The #GIOChannel data type aims to provide a portable method for
 * using file descriptors, pipes, and sockets, and integrating them
 * into the <link linkend="glib-The-Main-Event-Loop">main event
 * loop</link>. Currently full support is available on UNIX platforms,
 * support for Windows is only partially complete.
 *
 * To create a new #GIOChannel on UNIX systems use
 * g_io_channel_unix_new(). This works for plain file descriptors,
 * pipes and sockets. Alternatively, a channel can be created for a
 * file in a system independent manner using g_io_channel_new_file().
 *
 * Once a #GIOChannel has been created, it can be used in a generic
 * manner with the functions g_io_channel_read_chars(),
 * g_io_channel_write_chars(), g_io_channel_seek_position(), and
 * g_io_channel_shutdown().
 *
 * To add a #GIOChannel to the <link
 * linkend="glib-The-Main-Event-Loop">main event loop</link> use
 * g_io_add_watch() or g_io_add_watch_full(). Here you specify which
 * events you are interested in on the #GIOChannel, and provide a
 * function to be called whenever these events occur.
 *
 * #GIOChannel instances are created with an initial reference count of
 * 1. g_io_channel_ref() and g_io_channel_unref() can be used to
 * increment or decrement the reference count respectively. When the
 * reference count falls to 0, the #GIOChannel is freed. (Though it
 * isn't closed automatically, unless it was created using
 * g_io_channel_new_from_file().) Using g_io_add_watch() or
 * g_io_add_watch_full() increments a channel's reference count.
 *
 * The new functions g_io_channel_read_chars(),
 * g_io_channel_read_line(), g_io_channel_read_line_string(),
 * g_io_channel_read_to_end(), g_io_channel_write_chars(),
 * g_io_channel_seek_position(), and g_io_channel_flush() should not be
 * mixed with the deprecated functions g_io_channel_read(),
 * g_io_channel_write(), and g_io_channel_seek() on the same channel.
 **/

/**
 * GIOChannel:
 *
 * A data structure representing an IO Channel. The fields should be
 * considered private and should only be accessed with the following
 * functions.
 **/

/**
 * GIOFuncs:
 * @io_read: reads raw bytes from the channel.  This is called from
 *           various functions such as g_io_channel_read_chars() to
 *           read raw bytes from the channel.  Encoding and buffering
 *           issues are dealt with at a higher level.
 * @io_write: writes raw bytes to the channel.  This is called from
 *            various functions such as g_io_channel_write_chars() to
 *            write raw bytes to the channel.  Encoding and buffering
 *            issues are dealt with at a higher level.
 * @io_seek: (optional) seeks the channel.  This is called from
 *           g_io_channel_seek() on channels that support it.
 * @io_close: closes the channel.  This is called from
 *            g_io_channel_close() after flushing the buffers.
 * @io_create_watch: creates a watch on the channel.  This call
 *                   corresponds directly to g_io_create_watch().
 * @io_free: called from g_io_channel_unref() when the channel needs to
 *           be freed.  This function must free the memory associated
 *           with the channel, including freeing the #GIOChannel
 *           structure itself.  The channel buffers have been flushed
 *           and possibly @io_close has been called by the time this
 *           function is called.
 * @io_set_flags: sets the #GIOFlags on the channel.  This is called
 *                from g_io_channel_set_flags() with all flags except
 *                for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked
 *                out.
 * @io_get_flags: gets the #GIOFlags for the channel.  This function
 *                need only return the %G_IO_FLAG_APPEND and
 *                %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags()
 *                automatically adds the others as appropriate.
 *
 * A table of functions used to handle different types of #GIOChannel
 * in a generic way.
 **/

/**
 * GIOStatus:
 * @G_IO_STATUS_ERROR: An error occurred.
 * @G_IO_STATUS_NORMAL: Success.
 * @G_IO_STATUS_EOF: End of file.
 * @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
 *
 * Stati returned by most of the #GIOFuncs functions.
 **/

/**
 * GIOError:
 * @G_IO_ERROR_NONE: no error
 * @G_IO_ERROR_AGAIN: an EAGAIN error occurred
 * @G_IO_ERROR_INVAL: an EINVAL error occurred
 * @G_IO_ERROR_UNKNOWN: another error occurred
 *
 * #GIOError is only used by the deprecated functions
 * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
 **/

167 168
#define G_IO_NICE_BUF_SIZE	1024

169 170 171 172 173 174 175 176 177 178 179
/* 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)

180
static GIOError		g_io_error_get_from_g_error	(GIOStatus    status,
181 182 183 184
							 GError      *err);
static void		g_io_channel_purge		(GIOChannel  *channel);
static GIOStatus	g_io_channel_fill_buffer	(GIOChannel  *channel,
							 GError     **err);
185 186 187 188
static GIOStatus	g_io_channel_read_line_backend	(GIOChannel  *channel,
							 gsize       *length,
							 gsize       *terminator_pos,
							 GError     **error);
189

Matthias Clasen's avatar
Matthias Clasen committed
190 191 192 193 194 195 196 197 198 199
/**
 * g_io_channel_init:
 * @channel: a #GIOChannel
 *
 * Initializes a #GIOChannel struct. 
 *
 * This is called by each of the above functions when creating a 
 * #GIOChannel, and so is not often needed by the application 
 * programmer (unless you are creating a new type of #GIOChannel).
 */
200 201
void
g_io_channel_init (GIOChannel *channel)
202
{
203
  channel->ref_count = 1;
204
  channel->encoding = g_strdup ("UTF-8");
205
  channel->line_term = NULL;
206
  channel->line_term_len = 0;
207
  channel->buf_size = G_IO_NICE_BUF_SIZE;
208 209 210 211 212 213
  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';
214 215 216
  channel->use_buffer = TRUE;
  channel->do_encode = FALSE;
  channel->close_on_unref = FALSE;
217 218
}

Matthias Clasen's avatar
Matthias Clasen committed
219 220 221 222 223 224 225 226
/**
 * g_io_channel_ref:
 * @channel: a #GIOChannel
 *
 * Increments the reference count of a #GIOChannel.
 *
 * Returns: the @channel that was passed in (since 2.6)
 */
227
GIOChannel *
228 229
g_io_channel_ref (GIOChannel *channel)
{
230
  g_return_val_if_fail (channel != NULL, NULL);
231

232
  g_atomic_int_inc (&channel->ref_count);
233 234

  return channel;
235 236
}

Matthias Clasen's avatar
Matthias Clasen committed
237 238 239 240 241 242
/**
 * g_io_channel_unref:
 * @channel: a #GIOChannel
 *
 * Decrements the reference count of a #GIOChannel.
 */
243 244 245
void 
g_io_channel_unref (GIOChannel *channel)
{
246 247
  gboolean is_zero;

248 249
  g_return_if_fail (channel != NULL);

250 251 252
  is_zero = g_atomic_int_dec_and_test (&channel->ref_count);

  if (G_UNLIKELY (is_zero))
253 254
    {
      if (channel->close_on_unref)
255
        g_io_channel_shutdown (channel, TRUE, NULL);
256 257 258
      else
        g_io_channel_purge (channel);
      g_free (channel->encoding);
259 260 261 262
      if (channel->read_cd != (GIConv) -1)
        g_iconv_close (channel->read_cd);
      if (channel->write_cd != (GIConv) -1)
        g_iconv_close (channel->write_cd);
Matthias Clasen's avatar
Matthias Clasen committed
263
      g_free (channel->line_term);
264 265 266 267 268 269
      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);
270 271
      channel->funcs->io_free (channel);
    }
272 273
}

274
static GIOError
275 276
g_io_error_get_from_g_error (GIOStatus  status,
			     GError    *err)
277 278 279 280 281 282 283 284 285
{
  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:
286 287
	g_return_val_if_fail (err != NULL, G_IO_ERROR_UNKNOWN);
	
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
        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 ();
    }
}

/**
 * g_io_channel_read:
304 305 306 307 308
 * @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
309
 * 
310
 * Reads data from a #GIOChannel. 
311 312
 * 
 * Return value: %G_IO_ERROR_NONE if the operation was successful. 
313
 *
314
 * Deprecated:2.2: Use g_io_channel_read_chars() instead.
315
 **/
316 317 318
GIOError 
g_io_channel_read (GIOChannel *channel, 
		   gchar      *buf, 
319 320
		   gsize       count,
		   gsize      *bytes_read)
321
{
322 323 324 325
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

326
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
327 328
  g_return_val_if_fail (bytes_read != NULL, G_IO_ERROR_UNKNOWN);

329 330 331 332
  if (count == 0)
    {
      if (bytes_read)
        *bytes_read = 0;
333
      return G_IO_ERROR_NONE;
334 335 336 337
    }

  g_return_val_if_fail (buf != NULL, G_IO_ERROR_UNKNOWN);

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

340 341 342 343 344 345
  error = g_io_error_get_from_g_error (status, err);

  if (err)
    g_error_free (err);

  return error;
346 347
}

348 349
/**
 * g_io_channel_write:
350 351 352 353
 * @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
354
 * 
355
 * Writes data to a #GIOChannel. 
356 357
 * 
 * Return value:  %G_IO_ERROR_NONE if the operation was successful.
358
 *
359
 * Deprecated:2.2: Use g_io_channel_write_chars() instead.
360
 **/
361
GIOError 
362 363 364 365
g_io_channel_write (GIOChannel  *channel, 
		    const gchar *buf, 
		    gsize        count,
		    gsize       *bytes_written)
366
{
367 368 369 370
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

371
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
372 373 374 375 376
  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);
377

378 379 380 381
  if (err)
    g_error_free (err);

  return error;
382 383
}

384 385
/**
 * g_io_channel_seek:
386 387 388
 * @channel: a #GIOChannel
 * @offset: an offset, in bytes, which is added to the position specified 
 *          by @type
389
 * @type: the position in the file, which can be %G_SEEK_CUR (the current
390 391
 *        position), %G_SEEK_SET (the start of the file), or %G_SEEK_END 
 *        (the end of the file)
392
 * 
393 394
 * Sets the current position in the #GIOChannel, similar to the standard 
 * library function fseek(). 
395 396
 * 
 * Return value: %G_IO_ERROR_NONE if the operation was successful.
397
 *
398
 * Deprecated:2.2: Use g_io_channel_seek_position() instead.
399
 **/
400
GIOError 
401 402 403
g_io_channel_seek (GIOChannel *channel,
		   gint64      offset, 
		   GSeekType   type)
404
{
405 406 407 408
  GError *err = NULL;
  GIOError error;
  GIOStatus status;

409
  g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
410
  g_return_val_if_fail (channel->is_seekable, G_IO_ERROR_UNKNOWN);
411

412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
  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;
431
}
432 433 434 435 436 437 438

/* 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:
439
 * @filename: A string containing the name of a file
440
 * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
441 442
 *        the same meaning as in fopen()
 * @error: A location to return an error of type %G_FILE_ERROR
443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458
 *
 * 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
459 460
 * last reference is dropped using g_io_channel_unref(). 
 *
461
 * Deprecated:2.2: Use g_io_channel_shutdown() instead.
462
 **/
463 464 465
void
g_io_channel_close (GIOChannel *channel)
{
466 467
  GError *err = NULL;
  
468 469
  g_return_if_fail (channel != NULL);

470 471 472 473 474 475 476 477 478 479 480
  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 */
481 482 483
  channel->is_readable = FALSE;
  channel->is_writeable = FALSE;
  channel->is_seekable = FALSE;
484 485 486 487 488 489 490 491 492
}

/**
 * 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
493
 * flushed if @flush is %TRUE. The channel will not be freed until the
494
 * last reference is dropped using g_io_channel_unref().
495
 *
496
 * Return value: the status of the operation.
497 498
 **/
GIOStatus
499 500 501
g_io_channel_shutdown (GIOChannel  *channel,
		       gboolean     flush,
		       GError     **err)
502
{
503 504
  GIOStatus status, result;
  GError *tmperr = NULL;
505 506
  
  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
507
  g_return_val_if_fail (err == NULL || *err == NULL, G_IO_STATUS_ERROR);
508

509
  if (channel->write_buf && channel->write_buf->len > 0)
510
    {
511 512 513
      if (flush)
        {
          GIOFlags flags;
514
      
515 516 517 518 519
          /* 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);
520

521
          result = g_io_channel_flush (channel, &tmperr);
522
        }
523 524 525 526
      else
        result = G_IO_STATUS_NORMAL;

      g_string_truncate(channel->write_buf, 0);
527
    }
528 529
  else
    result = G_IO_STATUS_NORMAL;
530

531 532 533 534 535 536 537
  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';
    }

538
  status = channel->funcs->io_close (channel, err);
539 540

  channel->close_on_unref = FALSE; /* Because we already did */
541 542 543
  channel->is_readable = FALSE;
  channel->is_writeable = FALSE;
  channel->is_seekable = FALSE;
544

545 546 547 548 549 550 551 552 553 554 555 556
  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;
557 558 559 560 561 562 563
}

/* This function is used for the final flush on close or unref */
static void
g_io_channel_purge (GIOChannel *channel)
{
  GError *err = NULL;
Matthias Clasen's avatar
Matthias Clasen committed
564
  GIOStatus status G_GNUC_UNUSED;
565 566 567

  g_return_if_fail (channel != NULL);

568
  if (channel->write_buf && channel->write_buf->len > 0)
569 570
    {
      GIOFlags flags;
Matthias Clasen's avatar
Matthias Clasen committed
571

572 573 574 575 576
      /* 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);

577
      status = g_io_channel_flush (channel, &err);
578 579

      if (err)
Matthias Clasen's avatar
Matthias Clasen committed
580 581 582 583
        { /* No way to return the error */
          g_warning ("Error flushing string: %s", err->message);
          g_error_free (err);
        }
584 585 586 587
    }

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

588 589 590 591
  if (channel->read_buf)
    g_string_truncate (channel->read_buf, 0);
  if (channel->write_buf)
    g_string_truncate (channel->write_buf, 0);
592
  if (channel->encoding)
593 594 595 596 597 598 599 600 601 602
    {
      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';
        }
    }
603 604
}

Matthias Clasen's avatar
Matthias Clasen committed
605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623
/**
 * g_io_create_watch:
 * @channel: a #GIOChannel to watch
 * @condition: conditions to watch for
 *
 * Creates a #GSource that's dispatched when @condition is met for the 
 * given @channel. For example, if condition is #G_IO_IN, the source will 
 * be dispatched when there's data available for reading.
 *
 * g_io_add_watch() is a simpler interface to this same functionality, for 
 * the case where you want to add the source to the default main loop context 
 * at the default priority.
 *
 * On Windows, polling a #GSource created to watch a channel for a socket
 * puts the socket in non-blocking mode. This is a side-effect of the
 * implementation and unavoidable.
 *
 * Returns: a new #GSource
 */
624
GSource *
625 626
g_io_create_watch (GIOChannel   *channel,
		   GIOCondition  condition)
627 628 629 630 631 632
{
  g_return_val_if_fail (channel != NULL, NULL);

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

Matthias Clasen's avatar
Matthias Clasen committed
633 634 635 636 637 638 639 640 641 642 643 644 645 646
/**
 * g_io_add_watch_full:
 * @channel: a #GIOChannel
 * @priority: the priority of the #GIOChannel source
 * @condition: the condition to watch for
 * @func: the function to call when the condition is satisfied
 * @user_data: user data to pass to @func
 * @notify: the function to call when the source is removed
 *
 * Adds the #GIOChannel into the default main loop context
 * with the given priority.
 *
 * This internally creates a main loop source using g_io_create_watch()
 * and attaches it to the main loop context with g_source_attach().
Behdad Esfahbod's avatar
Behdad Esfahbod committed
647
 * You can do these steps manually if you need greater control.
Matthias Clasen's avatar
Matthias Clasen committed
648 649 650
 *
 * Returns: the event source id
 */
651
guint 
652
g_io_add_watch_full (GIOChannel    *channel,
653 654 655 656 657 658
		     gint           priority,
		     GIOCondition   condition,
		     GIOFunc        func,
		     gpointer       user_data,
		     GDestroyNotify notify)
{
659
  GSource *source;
660
  guint id;
661
  
662 663
  g_return_val_if_fail (channel != NULL, 0);

664 665 666 667 668 669
  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);

670 671 672 673
  id = g_source_attach (source, NULL);
  g_source_unref (source);

  return id;
674 675
}

Matthias Clasen's avatar
Matthias Clasen committed
676 677 678 679 680 681 682 683 684 685 686 687
/**
 * g_io_add_watch:
 * @channel: a #GIOChannel
 * @condition: the condition to watch for
 * @func: the function to call when the condition is satisfied
 * @user_data: user data to pass to @func
 *
 * Adds the #GIOChannel into the default main loop context
 * with the default priority.
 *
 * Returns: the event source id
 */
688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712
/**
 * GIOFunc:
 * @source: the #GIOChannel event source
 * @condition: the condition which has been satisfied
 * @data: user data set in g_io_add_watch() or g_io_add_watch_full()
 * @Returns: the function should return %FALSE if the event source
 *           should be removed
 *
 * Specifies the type of function passed to g_io_add_watch() or
 * g_io_add_watch_full(), which is called when the requested condition
 * on a #GIOChannel is satisfied.
 **/
/**
 * GIOCondition:
 * @G_IO_IN: There is data to read.
 * @G_IO_OUT: Data can be written (without blocking).
 * @G_IO_PRI: There is urgent data to read.
 * @G_IO_ERR: Error condition.
 * @G_IO_HUP: Hung up (the connection has been broken, usually for
 *            pipes and sockets).
 * @G_IO_NVAL: Invalid request. The file descriptor is not open.
 *
 * A bitwise combination representing a condition to watch for on an
 * event source.
 **/
713
guint 
714 715 716 717
g_io_add_watch (GIOChannel   *channel,
		GIOCondition  condition,
		GIOFunc       func,
		gpointer      user_data)
718
{
719
  return g_io_add_watch_full (channel, G_PRIORITY_DEFAULT, condition, func, user_data, NULL);
720
}
721 722 723 724 725

/**
 * g_io_channel_get_buffer_condition:
 * @channel: A #GIOChannel
 *
726
 * This function returns a #GIOCondition depending on whether there
727 728
 * 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.
729 730 731 732 733 734
 *
 * Return value: A #GIOCondition
 **/
GIOCondition
g_io_channel_get_buffer_condition (GIOChannel *channel)
{
735 736
  GIOCondition condition = 0;

737 738 739 740 741 742 743 744 745 746
  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;
    }
747 748

  if (channel->write_buf && (channel->write_buf->len < channel->buf_size))
749
    condition |= G_IO_OUT;
750 751

  return condition;
752 753 754
}

/**
755
 * g_io_channel_error_from_errno:
756
 * @en: an <literal>errno</literal> error number, e.g. %EINVAL
757
 *
758 759
 * Converts an <literal>errno</literal> error number to a #GIOChannelError.
 *
760 761
 * Return value: a #GIOChannelError error number, e.g. 
 *      %G_IO_CHANNEL_ERROR_INVAL.
762 763
 **/
GIOChannelError
764
g_io_channel_error_from_errno (gint en)
765 766 767 768 769 770 771 772 773
{
#ifdef EAGAIN
  g_return_val_if_fail (en != EAGAIN, G_IO_CHANNEL_ERROR_FAILED);
#endif

  switch (en)
    {
#ifdef EBADF
    case EBADF:
774 775
      g_warning("Invalid file descriptor.\n");
      return G_IO_CHANNEL_ERROR_FAILED;
776 777 778 779
#endif

#ifdef EFAULT
    case EFAULT:
780
      g_warning("Buffer outside valid address space.\n");
781 782 783 784 785 786
      return G_IO_CHANNEL_ERROR_FAILED;
#endif

#ifdef EFBIG
    case EFBIG:
      return G_IO_CHANNEL_ERROR_FBIG;
787 788
#endif

789 790 791 792 793 794 795 796 797 798 799 800
#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

801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820
#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

821 822 823
#ifdef ENXIO
    case ENXIO:
      return G_IO_CHANNEL_ERROR_NXIO;
824
#endif
825 826 827 828 829 830

#ifdef EOVERFLOW
    case EOVERFLOW:
      return G_IO_CHANNEL_ERROR_OVERFLOW;
#endif

831 832 833 834 835 836 837 838 839 840 841 842 843
#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
844
 * @size: the size of the buffer, or 0 to let GLib pick a good size
845
 *
Matthias Clasen's avatar
Matthias Clasen committed
846
 * Sets the buffer size.
847 848
 **/  
void
849 850
g_io_channel_set_buffer_size (GIOChannel *channel,
                              gsize       size)
851 852 853 854 855 856
{
  g_return_if_fail (channel != NULL);

  if (size == 0)
    size = G_IO_NICE_BUF_SIZE;

857 858
  if (size < MAX_CHAR_SIZE)
    size = MAX_CHAR_SIZE;
859

860 861 862 863 864 865 866
  channel->buf_size = size;
}

/**
 * g_io_channel_get_buffer_size:
 * @channel: a #GIOChannel
 *
Matthias Clasen's avatar
Matthias Clasen committed
867
 * Gets the buffer size.
868 869 870 871
 *
 * Return value: the size of the buffer.
 **/  
gsize
872
g_io_channel_get_buffer_size (GIOChannel *channel)
873 874 875 876 877 878 879 880 881
{
  g_return_val_if_fail (channel != NULL, 0);

  return channel->buf_size;
}

/**
 * g_io_channel_set_line_term:
 * @channel: a #GIOChannel
882 883 884
 * @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
885
 *             not be used for anything other than file-based channels.
886
 * @length: The length of the termination string. If -1 is passed, the
Matthias Clasen's avatar
Matthias Clasen committed
887
 *          string is assumed to be nul-terminated. This option allows
888
 *          termination strings with embedded nuls.
889 890 891 892 893 894
 *
 * 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,
895 896
                            const gchar	*line_term,
			    gint         length)
897 898
{
  g_return_if_fail (channel != NULL);
899
  g_return_if_fail (line_term == NULL || length != 0); /* Disallow "" */
900

901 902 903 904 905
  if (line_term == NULL)
    length = 0;
  else if (length < 0)
    length = strlen (line_term);

Matthias Clasen's avatar
Matthias Clasen committed
906
  g_free (channel->line_term);
907 908
  channel->line_term = line_term ? g_memdup (line_term, length) : NULL;
  channel->line_term_len = length;
909 910 911 912 913
}

/**
 * g_io_channel_get_line_term:
 * @channel: a #GIOChannel
914
 * @length: a location to return the length of the line terminator
915 916 917
 *
 * This returns the string that #GIOChannel uses to determine
 * where in the file a line break occurs. A value of %NULL
918
 * indicates autodetection.
919 920 921 922
 *
 * Return value: The line termination string. This value
 *   is owned by GLib and must not be freed.
 **/
923
const gchar *
924 925
g_io_channel_get_line_term (GIOChannel *channel,
			    gint       *length)
926
{
927
  g_return_val_if_fail (channel != NULL, NULL);
928

929 930 931
  if (length)
    *length = channel->line_term_len;

932 933 934 935 936
  return channel->line_term;
}

/**
 * g_io_channel_set_flags:
937 938 939
 * @channel: a #GIOChannel
 * @flags: the flags to set on the IO channel
 * @error: A location to return an error of type #GIOChannelError
940
 *
941
 * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).
942
 *
943
 * Return value: the status of the operation. 
944
 **/
945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969
/**
 * GIOFlags:
 * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
 *                    (see the documentation of the UNIX open()
 *                    syscall).
 * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
 *                      %O_NONBLOCK/%O_NDELAY (see the documentation of
 *                      the UNIX open() syscall).
 * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
 *                         This flag can not be changed.
 * @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
 *                          This flag can not be changed.
 * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
 *                         i.e. that g_io_channel_seek_position() can
 *                         be used on it.  This flag can not be changed.
 * @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
 * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
 *                      g_io_channel_get_flags().
 * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
 *                      with g_io_channel_set_flags().
 *
 * Specifies properties of a #GIOChannel. Some of the flags can only be
 * read with g_io_channel_get_flags(), but not changed with
 * g_io_channel_set_flags().
 **/
970
GIOStatus
971 972 973
g_io_channel_set_flags (GIOChannel  *channel,
                        GIOFlags     flags,
                        GError     **error)
974 975 976 977 978
{
  g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
  g_return_val_if_fail ((error == NULL) || (*error == NULL),
			G_IO_STATUS_ERROR);

979
  return (*channel->funcs->io_set_flags) (channel,
980 981 982 983 984 985 986 987 988 989
					  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.
990
 *
991 992 993
 * 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
994
 * of a socket with the UNIX shutdown() function), the user
995
 * should immediately call g_io_channel_get_flags() to update
996 997
 * the internal values of these flags.
 *
998
 * Return value: the flags which are set on the channel
999 1000 1001 1002
 **/
GIOFlags
g_io_channel_get_flags (GIOChannel *channel)
{
1003 1004
  GIOFlags flags;

1005
  g_return_val_if_fail (channel != NULL, 0);
1006

1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018
  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;
1019 1020
}

1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042
/**
 * 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:
1043
 * @channel: a #GIOChannel.
1044
 *
1045 1046 1047 1048 1049 1050 1051
 * 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.
1052 1053 1054 1055 1056 1057 1058 1059 1060
 **/
gboolean
g_io_channel_get_close_on_unref	(GIOChannel *channel)
{
  g_return_val_if_fail (channel != NULL, FALSE);

  return channel->close_on_unref;
}

1061 1062 1063 1064
/**
 * g_io_channel_seek_position:
 * @channel: a #GIOChannel
 * @offset: The offset in bytes from the position specified by @type
1065 1066 1067 1068
 * @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.
1069 1070 1071 1072
 * @error: A location to return an error of type #GIOChannelError
 *
 * Replacement for g_io_channel_seek() with the new API.
 *
1073
 * Return value: the status of the operation.
1074
 **/
1075 1076 1077 1078 1079 1080 1081 1082 1083
/**
 * GSeekType:
 * @G_SEEK_CUR: the current position in the file.
 * @G_SEEK_SET: the start of the file.
 * @G_SEEK_END: the end of the file.
 *
 * An enumeration specifying the base position for a
 * g_io_channel_seek_position() operation.
 **/
1084
GIOStatus
1085 1086 1087 1088
g_io_channel_seek_position (GIOChannel  *channel,
                            gint64       offset,
                            GSeekType    type,
                            GError     **error)
1089 1090 1091 1092 1093 1094 1095 1096 1097 1098
{
  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);
1099
  g_return_val_if_fail (channel->is_seekable, G_IO_STATUS_ERROR);
1100 1101 1102 1103

  switch (type)
    {
      case G_SEEK_CUR: /* The user is seeking relative to the head of the buffer */
1104
        if (channel->use_buffer)
1105
          {
1106 1107
            if (channel->do_encode && channel->encoded_read_buf
                && channel->encoded_read_buf->len > 0)
1108 1109 1110 1111 1112 1113 1114
              {
                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;
1115 1116
          if (channel->encoded_read_buf)
            {
1117
              g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
1118 1119 1120 1121 1122 1123 1124 1125

              /* 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;
            }
1126
          }
1127
        break;
1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146
      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))
    {
1147 1148
      if (channel->read_buf)
        g_string_truncate (channel->read_buf, 0);
1149 1150 1151 1152 1153 1154 1155 1156

      /* 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)
1157
        {
1158