1 /* GLIB - Library of useful routines for C programming

     2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald

     3  *

     4  * giochannel.c: IO Channel abstraction

     5  * Copyright 1998 Owen Taylor

     6  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.

     7  *

     8  * This library is free software; you can redistribute it and/or

     9  * modify it under the terms of the GNU Lesser General Public

    10  * License as published by the Free Software Foundation; either

    11  * version 2 of the License, or (at your option) any later version.

    12  *

    13  * This library is distributed in the hope that it will be useful,

    14  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU

    16  * Lesser General Public License for more details.

    17  *

    18  * You should have received a copy of the GNU Lesser General Public

    19  * License along with this library; if not, write to the

    20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

    21  * Boston, MA 02111-1307, USA.

    22  */

    23 

    24 /*

    25  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS

    26  * file for a list of people on the GLib Team.  See the ChangeLog

    27  * files for a list of changes.  These files are distributed with

    28  * GLib at ftp://ftp.gtk.org/pub/gtk/. 

    29  */

    30 

    31 /* 

    32  * MT safe

    33  */

    34 

    35 #include "config.h"

    36 

    37 #include <string.h>

    38 #include <errno.h>

    39 

    40 #ifdef HAVE_UNISTD_H

    41 #include <unistd.h>

    42 #endif

    43 

    44 #undef G_DISABLE_DEPRECATED

    45 

    46 #include "glib.h"

    47 

    48 #include "giochannel.h"

    49 

    50 #include "glibintl.h"

    51 

    52 #include "galias.h"

    53 

    54 #ifdef __SYMBIAN32__

    55 #include <glib_wsd.h>

    56 #endif

    57 

    58 #define G_IO_NICE_BUF_SIZE	1024

    59 

    60 /* This needs to be as wide as the largest character in any possible encoding */

    61 #define MAX_CHAR_SIZE		10

    62 

    63 /* Some simplifying macros, which reduce the need to worry whether the

    64  * buffers have been allocated. These also make USE_BUF () an lvalue,

    65  * which is used in g_io_channel_read_to_end ().

    66  */

    67 #define USE_BUF(channel)	((channel)->encoding ? (channel)->encoded_read_buf \

    68 				 : (channel)->read_buf)

    69 #define BUF_LEN(string)		((string) ? (string)->len : 0)

    70 

    71 static GIOError		g_io_error_get_from_g_error	(GIOStatus    status,

    72 							 GError      *err);

    73 static void		g_io_channel_purge		(GIOChannel  *channel);

    74 static GIOStatus	g_io_channel_fill_buffer	(GIOChannel  *channel,

    75 							 GError     **err);

    76 static GIOStatus	g_io_channel_read_line_backend	(GIOChannel  *channel,

    77 							 gsize       *length,

    78 							 gsize       *terminator_pos,

    79 							 GError     **error);

    80 

    81 EXPORT_C void

    82 g_io_channel_init (GIOChannel *channel)

    83 {

    84   channel->ref_count = 1;

    85   channel->encoding = g_strdup ("UTF-8");

    86   channel->line_term = NULL;

    87   channel->line_term_len = 0;

    88   channel->buf_size = G_IO_NICE_BUF_SIZE;

    89   channel->read_cd = (GIConv) -1;

    90   channel->write_cd = (GIConv) -1;

    91   channel->read_buf = NULL; /* Lazy allocate buffers */

    92   channel->encoded_read_buf = NULL;

    93   channel->write_buf = NULL;

    94   channel->partial_write_buf[0] = '\0';

    95   channel->use_buffer = TRUE;

    96   channel->do_encode = FALSE;

    97   channel->close_on_unref = FALSE;

    98 }

    99 

   100 EXPORT_C GIOChannel *

   101 g_io_channel_ref (GIOChannel *channel)

   102 {

   103   g_return_val_if_fail (channel != NULL, NULL);

   104 

   105   g_atomic_int_inc (FIX_CASTING(int *)&channel->ref_count);

   106 

   107   return channel;

   108 }

   109 

   110 EXPORT_C void 

   111 g_io_channel_unref (GIOChannel *channel)

   112 {

   113   gboolean is_zero;

   114 

   115   g_return_if_fail (channel != NULL);

   116 

   117   is_zero = g_atomic_int_dec_and_test (FIX_CASTING(int *)&channel->ref_count);

   118 

   119   if (G_UNLIKELY (is_zero))

   120     {

   121       if (channel->close_on_unref)

   122         g_io_channel_shutdown (channel, TRUE, NULL);

   123       else

   124         g_io_channel_purge (channel);

   125       g_free (channel->encoding);

   126       if (channel->read_cd != (GIConv) -1)

   127         g_iconv_close (channel->read_cd);

   128       if (channel->write_cd != (GIConv) -1)

   129         g_iconv_close (channel->write_cd);

   130       if (channel->line_term)

   131         g_free (channel->line_term);

   132       if (channel->read_buf)

   133         g_string_free (channel->read_buf, TRUE);

   134       if (channel->write_buf)

   135         g_string_free (channel->write_buf, TRUE);

   136       if (channel->encoded_read_buf)

   137         g_string_free (channel->encoded_read_buf, TRUE);

   138       channel->funcs->io_free (channel);

   139     }

   140 }

   141 

   142 static GIOError

   143 g_io_error_get_from_g_error (GIOStatus status,

   144 			     GError *err)

   145 {

   146   switch (status)

   147     {

   148       case G_IO_STATUS_NORMAL:

   149       case G_IO_STATUS_EOF:

   150         return G_IO_ERROR_NONE;

   151       case G_IO_STATUS_AGAIN:

   152         return G_IO_ERROR_AGAIN;

   153       case G_IO_STATUS_ERROR:

   154 	g_return_val_if_fail (err != NULL, G_IO_ERROR_UNKNOWN);

   155 	

   156         if (err->domain != G_IO_CHANNEL_ERROR)

   157           return G_IO_ERROR_UNKNOWN;

   158         switch (err->code)

   159           {

   160             case G_IO_CHANNEL_ERROR_INVAL:

   161               return G_IO_ERROR_INVAL;

   162             default:

   163               return G_IO_ERROR_UNKNOWN;

   164           }

   165       default:

   166         g_assert_not_reached ();

   167         return G_IO_ERROR_UNKNOWN; /* Keep the compiler happy */

   168     }

   169 }

   170 

   171 /**

   172  * g_io_channel_read:

   173  * @channel: a #GIOChannel. 

   174  * @buf: a buffer to read the data into (which should be at least count bytes long).

   175  * @count: the number of bytes to read from the #GIOChannel.

   176  * @bytes_read: returns the number of bytes actually read. 

   177  * 

   178  * Reads data from a #GIOChannel. 

   179  * 

   180  * Return value: %G_IO_ERROR_NONE if the operation was successful. 

   181  *

   182  * Deprecated:2.2: Use g_io_channel_read_chars() instead.

   183  **/

   184 EXPORT_C GIOError 

   185 g_io_channel_read (GIOChannel *channel, 

   186 		   gchar      *buf, 

   187 		   gsize       count,

   188 		   gsize      *bytes_read)

   189 {

   190   GError *err = NULL;

   191   GIOError error;

   192   GIOStatus status;

   193 

   194   g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);

   195   g_return_val_if_fail (bytes_read != NULL, G_IO_ERROR_UNKNOWN);

   196 

   197   if (count == 0)

   198     {

   199       if (bytes_read)

   200         *bytes_read = 0;

   201       return G_IO_ERROR_NONE;

   202     }

   203 

   204   g_return_val_if_fail (buf != NULL, G_IO_ERROR_UNKNOWN);

   205 

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

   207 

   208   error = g_io_error_get_from_g_error (status, err);

   209 

   210   if (err)

   211     g_error_free (err);

   212 

   213   return error;

   214 }

   215 

   216 /**

   217  * g_io_channel_write:

   218  * @channel:  a #GIOChannel.

   219  * @buf: the buffer containing the data to write. 

   220  * @count: the number of bytes to write.

   221  * @bytes_written:  the number of bytes actually written.

   222  * 

   223  * Writes data to a #GIOChannel. 

   224  * 

   225  * Return value:  %G_IO_ERROR_NONE if the operation was successful.

   226  *

   227  * Deprecated:2.2: Use g_io_channel_write_chars() instead.

   228  **/

   229 EXPORT_C GIOError 

   230 g_io_channel_write (GIOChannel  *channel, 

   231 		    const gchar *buf, 

   232 		    gsize        count,

   233 		    gsize       *bytes_written)

   234 {

   235   GError *err = NULL;

   236   GIOError error;

   237   GIOStatus status;

   238 

   239   g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);

   240   g_return_val_if_fail (bytes_written != NULL, G_IO_ERROR_UNKNOWN);

   241 

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

   243 

   244   error = g_io_error_get_from_g_error (status, err);

   245 

   246   if (err)

   247     g_error_free (err);

   248 

   249   return error;

   250 }

   251 

   252 /**

   253  * g_io_channel_seek:

   254  * @channel: a #GIOChannel. 

   255  * @offset: an offset, in bytes, which is added to the position specified by @type

   256  * @type: the position in the file, which can be %G_SEEK_CUR (the current

   257  *        position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the

   258  *        file).

   259  * 

   260  * Sets the current position in the #GIOChannel, similar to the standard library

   261  * function fseek(). 

   262  * 

   263  * Return value: %G_IO_ERROR_NONE if the operation was successful.

   264  *

   265  * Deprecated:2.2: Use g_io_channel_seek_position() instead.

   266  **/

   267 EXPORT_C GIOError 

   268 g_io_channel_seek  (GIOChannel   *channel,

   269 		    gint64        offset, 

   270 		    GSeekType     type)

   271 {

   272   GError *err = NULL;

   273   GIOError error;

   274   GIOStatus status;

   275 

   276   g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);

   277   g_return_val_if_fail (channel->is_seekable, G_IO_ERROR_UNKNOWN);

   278 

   279   switch (type)

   280     {

   281       case G_SEEK_CUR:

   282       case G_SEEK_SET:

   283       case G_SEEK_END:

   284         break;

   285       default:

   286         g_warning ("g_io_channel_seek: unknown seek type");

   287         return G_IO_ERROR_UNKNOWN;

   288     }

   289 

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

   291 

   292   error = g_io_error_get_from_g_error (status, err);

   293 

   294   if (err)

   295     g_error_free (err);

   296 

   297   return error;

   298 }

   299 

   300 /* The function g_io_channel_new_file() is prototyped in both

   301  * giounix.c and giowin32.c, so we stick its documentation here.

   302  */

   303 

   304 /**

   305  * g_io_channel_new_file:

   306  * @filename: A string containing the name of a file.

   307  * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have

   308  *        the same meaning as in fopen().

   309  * @error: A location to return an error of type %G_FILE_ERROR.

   310  *

   311  * Open a file @filename as a #GIOChannel using mode @mode. This

   312  * channel will be closed when the last reference to it is dropped,

   313  * so there is no need to call g_io_channel_close() (though doing

   314  * so will not cause problems, as long as no attempt is made to

   315  * access the channel after it is closed).

   316  *

   317  * Return value: A #GIOChannel on success, %NULL on failure.

   318  **/

   319 

   320 /**

   321  * g_io_channel_close:

   322  * @channel: A #GIOChannel

   323  * 

   324  * Close an IO channel. Any pending data to be written will be

   325  * flushed, ignoring errors. The channel will not be freed until the

   326  * last reference is dropped using g_io_channel_unref(). 

   327  *

   328  * Deprecated:2.2: Use g_io_channel_shutdown() instead.

   329  **/

   330 EXPORT_C void

   331 g_io_channel_close (GIOChannel *channel)

   332 {

   333   GError *err = NULL;

   334   

   335   g_return_if_fail (channel != NULL);

   336 

   337   g_io_channel_purge (channel);

   338 

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

   340 

   341   if (err)

   342     { /* No way to return the error */

   343       g_warning ("Error closing channel: %s", err->message);

   344       g_error_free (err);

   345     }

   346   

   347   channel->close_on_unref = FALSE; /* Because we already did */

   348   channel->is_readable = FALSE;

   349   channel->is_writeable = FALSE;

   350   channel->is_seekable = FALSE;

   351 }

   352 

   353 /**

   354  * g_io_channel_shutdown:

   355  * @channel: a #GIOChannel

   356  * @flush: if %TRUE, flush pending

   357  * @err: location to store a #GIOChannelError

   358  * 

   359  * Close an IO channel. Any pending data to be written will be

   360  * flushed if @flush is %TRUE. The channel will not be freed until the

   361  * last reference is dropped using g_io_channel_unref().

   362  *

   363  * Return value: the status of the operation.

   364  **/

   365 EXPORT_C GIOStatus

   366 g_io_channel_shutdown (GIOChannel *channel,

   367 		       gboolean    flush,

   368 		       GError    **err)

   369 {

   370   GIOStatus status, result;

   371   GError *tmperr = NULL;

   372   

   373   g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);

   374   g_return_val_if_fail (err == NULL || *err == NULL, G_IO_STATUS_ERROR);

   375 

   376   if (channel->write_buf && channel->write_buf->len > 0)

   377     {

   378       if (flush)

   379         {

   380           GIOFlags flags;

   381       

   382           /* Set the channel to blocking, to avoid a busy loop

   383            */

   384           flags = g_io_channel_get_flags (channel);

   385           /* Ignore any errors here, they're irrelevant */

   386           g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);

   387 

   388           result = g_io_channel_flush (channel, &tmperr);

   389         }

   390       else

   391         result = G_IO_STATUS_NORMAL;

   392 

   393       g_string_truncate(channel->write_buf, 0);

   394     }

   395   else

   396     result = G_IO_STATUS_NORMAL;

   397 

   398   if (channel->partial_write_buf[0] != '\0')

   399     {

   400       if (flush)

   401         g_warning ("Partial character at end of write buffer not flushed.\n");

   402       channel->partial_write_buf[0] = '\0';

   403     }

   404 

   405   status = channel->funcs->io_close (channel, err);

   406 

   407   channel->close_on_unref = FALSE; /* Because we already did */

   408   channel->is_readable = FALSE;

   409   channel->is_writeable = FALSE;

   410   channel->is_seekable = FALSE;

   411 

   412   if (status != G_IO_STATUS_NORMAL)

   413     {

   414       g_clear_error (&tmperr);

   415       return status;

   416     }

   417   else if (result != G_IO_STATUS_NORMAL)

   418     {

   419       g_propagate_error (err, tmperr);

   420       return result;

   421     }

   422   else

   423     return G_IO_STATUS_NORMAL;

   424 }

   425 

   426 /* This function is used for the final flush on close or unref */

   427 static void

   428 g_io_channel_purge (GIOChannel *channel)

   429 {

   430   GError *err = NULL;

   431   GIOStatus status;

   432 

   433   g_return_if_fail (channel != NULL);

   434 

   435   if (channel->write_buf && channel->write_buf->len > 0)

   436     {

   437       GIOFlags flags;

   438       

   439       /* Set the channel to blocking, to avoid a busy loop

   440        */

   441       flags = g_io_channel_get_flags (channel);

   442       g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);

   443 

   444       status = g_io_channel_flush (channel, &err);

   445 

   446       if (err)

   447 	{ /* No way to return the error */

   448 	  g_warning ("Error flushing string: %s", err->message);

   449 	  g_error_free (err);

   450 	}

   451     }

   452 

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

   454 

   455   if (channel->read_buf)

   456     g_string_truncate (channel->read_buf, 0);

   457   if (channel->write_buf)

   458     g_string_truncate (channel->write_buf, 0);

   459   if (channel->encoding)

   460     {

   461       if (channel->encoded_read_buf)

   462         g_string_truncate (channel->encoded_read_buf, 0);

   463 

   464       if (channel->partial_write_buf[0] != '\0')

   465         {

   466           g_warning ("Partial character at end of write buffer not flushed.\n");

   467           channel->partial_write_buf[0] = '\0';

   468         }

   469     }

   470 }

   471 

   472 EXPORT_C GSource *

   473 g_io_create_watch (GIOChannel  *channel,

   474 		   GIOCondition condition)

   475 {

   476   g_return_val_if_fail (channel != NULL, NULL);

   477 

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

   479 }

   480 

   481 EXPORT_C guint 

   482 g_io_add_watch_full (GIOChannel    *channel,

   483 		     gint           priority,

   484 		     GIOCondition   condition,

   485 		     GIOFunc        func,

   486 		     gpointer       user_data,

   487 		     GDestroyNotify notify)

   488 {

   489   GSource *source;

   490   guint id;

   491   

   492   g_return_val_if_fail (channel != NULL, 0);

   493 

   494   source = g_io_create_watch (channel, condition);

   495 

   496   if (priority != G_PRIORITY_DEFAULT)

   497     g_source_set_priority (source, priority);

   498   g_source_set_callback (source, (GSourceFunc)func, user_data, notify);

   499 

   500   id = g_source_attach (source, NULL);

   501   g_source_unref (source);

   502 

   503   return id;

   504 }

   505 

   506 EXPORT_C guint 

   507 g_io_add_watch (GIOChannel    *channel,

   508 		GIOCondition   condition,

   509 		GIOFunc        func,

   510 		gpointer       user_data)

   511 {

   512   return g_io_add_watch_full (channel, G_PRIORITY_DEFAULT, condition, func, user_data, NULL);

   513 }

   514 

   515 /**

   516  * g_io_channel_get_buffer_condition:

   517  * @channel: A #GIOChannel

   518  *

   519  * This function returns a #GIOCondition depending on whether there

   520  * is data to be read/space to write data in the

   521  * internal buffers in the #GIOChannel. Only the flags %G_IO_IN and

   522  * %G_IO_OUT may be set.

   523  *

   524  * Return value: A #GIOCondition

   525  **/

   526 EXPORT_C GIOCondition

   527 g_io_channel_get_buffer_condition (GIOChannel *channel)

   528 {

   529   GIOCondition condition = 0;

   530 

   531   if (channel->encoding)

   532     {

   533       if (channel->encoded_read_buf && (channel->encoded_read_buf->len > 0))

   534         condition |= G_IO_IN; /* Only return if we have full characters */

   535     }

   536   else

   537     {

   538       if (channel->read_buf && (channel->read_buf->len > 0))

   539         condition |= G_IO_IN;

   540     }

   541 

   542   if (channel->write_buf && (channel->write_buf->len < channel->buf_size))

   543     condition |= G_IO_OUT;

   544 

   545   return condition;

   546 }

   547 

   548 /**

   549  * g_io_channel_error_from_errno:

   550  * @en: an <literal>errno</literal> error number, e.g. %EINVAL.

   551  *

   552  * Converts an <literal>errno</literal> error number to a #GIOChannelError.

   553  *

   554  * Return value: a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL.

   555  **/

   556 EXPORT_C GIOChannelError

   557 g_io_channel_error_from_errno (gint en)

   558 {

   559 #ifdef EAGAIN

   560   g_return_val_if_fail (en != EAGAIN, G_IO_CHANNEL_ERROR_FAILED);

   561 #endif

   562 

   563   switch (en)

   564     {

   565 #ifdef EBADF

   566     case EBADF:

   567       g_warning("Invalid file descriptor.\n");

   568       return G_IO_CHANNEL_ERROR_FAILED;

   569 #endif

   570 

   571 #ifdef EFAULT

   572     case EFAULT:

   573       g_warning("Buffer outside valid address space.\n");

   574       return G_IO_CHANNEL_ERROR_FAILED;

   575 #endif

   576 

   577 #ifdef EFBIG

   578     case EFBIG:

   579       return G_IO_CHANNEL_ERROR_FBIG;

   580 #endif

   581 

   582 #ifdef EINTR

   583     /* In general, we should catch EINTR before we get here,

   584      * but close() is allowed to return EINTR by POSIX, so

   585      * we need to catch it here; EINTR from close() is

   586      * unrecoverable, because it's undefined whether

   587      * the fd was actually closed or not, so we just return

   588      * a generic error code.

   589      */

   590     case EINTR:

   591       return G_IO_CHANNEL_ERROR_FAILED;

   592 #endif

   593 

   594 #ifdef EINVAL

   595     case EINVAL:

   596       return G_IO_CHANNEL_ERROR_INVAL;

   597 #endif

   598 

   599 #ifdef EIO

   600     case EIO:

   601       return G_IO_CHANNEL_ERROR_IO;

   602 #endif

   603 

   604 #ifdef EISDIR

   605     case EISDIR:

   606       return G_IO_CHANNEL_ERROR_ISDIR;

   607 #endif

   608 

   609 #ifdef ENOSPC

   610     case ENOSPC:

   611       return G_IO_CHANNEL_ERROR_NOSPC;

   612 #endif

   613 

   614 #ifdef ENXIO

   615     case ENXIO:

   616       return G_IO_CHANNEL_ERROR_NXIO;

   617 #endif

   618 

   619 #ifdef EOVERFLOW

   620     case EOVERFLOW:

   621       return G_IO_CHANNEL_ERROR_OVERFLOW;

   622 #endif

   623 

   624 #ifdef EPIPE

   625     case EPIPE:

   626       return G_IO_CHANNEL_ERROR_PIPE;

   627 #endif

   628 

   629     default:

   630       return G_IO_CHANNEL_ERROR_FAILED;

   631     }

   632 }

   633 

   634 /**

   635  * g_io_channel_set_buffer_size:

   636  * @channel: a #GIOChannel

   637  * @size: the size of the buffer. 0 == pick a good size

   638  *

   639  * Sets the buffer size.

   640  **/  

   641 EXPORT_C void

   642 g_io_channel_set_buffer_size (GIOChannel	*channel,

   643                               gsize		 size)

   644 {

   645   g_return_if_fail (channel != NULL);

   646 

   647   if (size == 0)

   648     size = G_IO_NICE_BUF_SIZE;

   649 

   650   if (size < MAX_CHAR_SIZE)

   651     size = MAX_CHAR_SIZE;

   652 

   653   channel->buf_size = size;

   654 }

   655 

   656 /**

   657  * g_io_channel_get_buffer_size:

   658  * @channel: a #GIOChannel

   659  *

   660  * Gets the buffer size.

   661  *

   662  * Return value: the size of the buffer.

   663  **/  

   664 EXPORT_C gsize

   665 g_io_channel_get_buffer_size (GIOChannel	*channel)

   666 {

   667   g_return_val_if_fail (channel != NULL, 0);

   668 

   669   return channel->buf_size;

   670 }

   671 

   672 /**

   673  * g_io_channel_set_line_term:

   674  * @channel: a #GIOChannel

   675  * @line_term: The line termination string. Use %NULL for auto detect.

   676  *             Auto detection breaks on "\n", "\r\n", "\r", "\0", and

   677  *             the Unicode paragraph separator. Auto detection should

   678  *             not be used for anything other than file-based channels.

   679  * @length: The length of the termination string. If -1 is passed, the

   680  *          string is assumed to be nul-terminated. This option allows

   681  *          termination strings with embeded nuls.

   682  *

   683  * This sets the string that #GIOChannel uses to determine

   684  * where in the file a line break occurs.

   685  **/

   686 EXPORT_C void

   687 g_io_channel_set_line_term (GIOChannel	*channel,

   688                             const gchar	*line_term,

   689 			    gint         length)

   690 {

   691   g_return_if_fail (channel != NULL);

   692   g_return_if_fail (line_term == NULL || length != 0); /* Disallow "" */

   693 

   694   if (line_term == NULL)

   695     length = 0;

   696   else if (length < 0)

   697     length = strlen (line_term);

   698 

   699   if (channel->line_term)

   700     g_free (channel->line_term);

   701   channel->line_term = line_term ? g_memdup (line_term, length) : NULL;

   702   channel->line_term_len = length;

   703 }

   704 

   705 /**

   706  * g_io_channel_get_line_term:

   707  * @channel: a #GIOChannel

   708  * @length: a location to return the length of the line terminator

   709  *

   710  * This returns the string that #GIOChannel uses to determine

   711  * where in the file a line break occurs. A value of %NULL

   712  * indicates auto detection.

   713  *

   714  * Return value: The line termination string. This value

   715  *   is owned by GLib and must not be freed.

   716  **/

   717 EXPORT_C G_CONST_RETURN gchar*

   718 g_io_channel_get_line_term (GIOChannel	*channel,

   719 			    gint        *length)

   720 {

   721   g_return_val_if_fail (channel != NULL, NULL);

   722 

   723   if (length)

   724     *length = channel->line_term_len;

   725 

   726   return channel->line_term;

   727 }

   728 

   729 /**

   730  * g_io_channel_set_flags:

   731  * @channel: a #GIOChannel.

   732  * @flags: the flags to set on the IO channel.

   733  * @error: A location to return an error of type #GIOChannelError.

   734  *

   735  * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).

   736  *

   737  * Return value: the status of the operation. 

   738  **/

   739 EXPORT_C GIOStatus

   740 g_io_channel_set_flags (GIOChannel *channel,

   741                         GIOFlags    flags,

   742                         GError    **error)

   743 {

   744   g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);

   745   g_return_val_if_fail ((error == NULL) || (*error == NULL),

   746 			G_IO_STATUS_ERROR);

   747 

   748   return (* channel->funcs->io_set_flags)(channel,

   749 					  flags & G_IO_FLAG_SET_MASK,

   750 					  error);

   751 }

   752 

   753 /**

   754  * g_io_channel_get_flags:

   755  * @channel: a #GIOChannel

   756  *

   757  * Gets the current flags for a #GIOChannel, including read-only

   758  * flags such as %G_IO_FLAG_IS_READABLE.

   759  *

   760  * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITEABLE

   761  * are cached for internal use by the channel when it is created.

   762  * If they should change at some later point (e.g. partial shutdown

   763  * of a socket with the UNIX shutdown() function), the user

   764  * should immediately call g_io_channel_get_flags () to update

   765  * the internal values of these flags.

   766  *

   767  * Return value: the flags which are set on the channel

   768  **/

   769 EXPORT_C GIOFlags

   770 g_io_channel_get_flags (GIOChannel *channel)

   771 {

   772   GIOFlags flags;

   773 

   774   g_return_val_if_fail (channel != NULL, 0);

   775 

   776   flags = (* channel->funcs->io_get_flags) (channel);

   777 

   778   /* Cross implementation code */

   779 

   780   if (channel->is_seekable)

   781     flags |= G_IO_FLAG_IS_SEEKABLE;

   782   if (channel->is_readable)

   783     flags |= G_IO_FLAG_IS_READABLE;

   784   if (channel->is_writeable)

   785     flags |= G_IO_FLAG_IS_WRITEABLE;

   786 

   787   return flags;

   788 }

   789 

   790 /**

   791  * g_io_channel_set_close_on_unref:

   792  * @channel: a #GIOChannel

   793  * @do_close: Whether to close the channel on the final unref of

   794  *            the GIOChannel data structure. The default value of

   795  *            this is %TRUE for channels created by g_io_channel_new_file (),

   796  *            and %FALSE for all other channels.

   797  *

   798  * Setting this flag to %TRUE for a channel you have already closed

   799  * can cause problems.

   800  **/

   801 EXPORT_C void

   802 g_io_channel_set_close_on_unref	(GIOChannel *channel,

   803 				 gboolean    do_close)

   804 {

   805   g_return_if_fail (channel != NULL);

   806 

   807   channel->close_on_unref = do_close;

   808 }

   809 

   810 /**

   811  * g_io_channel_get_close_on_unref:

   812  * @channel: a #GIOChannel.

   813  *

   814  * Returns whether the file/socket/whatever associated with @channel

   815  * will be closed when @channel receives its final unref and is

   816  * destroyed. The default value of this is %TRUE for channels created

   817  * by g_io_channel_new_file (), and %FALSE for all other channels.

   818  *

   819  * Return value: Whether the channel will be closed on the final unref of

   820  *               the GIOChannel data structure.

   821  **/

   822 EXPORT_C gboolean

   823 g_io_channel_get_close_on_unref	(GIOChannel *channel)

   824 {

   825   g_return_val_if_fail (channel != NULL, FALSE);

   826 

   827   return channel->close_on_unref;

   828 }

   829 

   830 /**

   831  * g_io_channel_seek_position:

   832  * @channel: a #GIOChannel

   833  * @offset: The offset in bytes from the position specified by @type

   834  * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those

   835  *                      cases where a call to g_io_channel_set_encoding ()

   836  *                      is allowed. See the documentation for

   837  *                      g_io_channel_set_encoding () for details.

   838  * @error: A location to return an error of type #GIOChannelError

   839  *

   840  * Replacement for g_io_channel_seek() with the new API.

   841  *

   842  * Return value: the status of the operation.

   843  **/

   844 EXPORT_C GIOStatus

   845 g_io_channel_seek_position	(GIOChannel* channel,

   846 				 gint64      offset,

   847 				 GSeekType   type,

   848 				 GError    **error)

   849 {

   850   GIOStatus status;

   851 

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

   853    * For sockets, both can contain data.

   854    */

   855 

   856   g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);

   857   g_return_val_if_fail ((error == NULL) || (*error == NULL),

   858 			G_IO_STATUS_ERROR);

   859   g_return_val_if_fail (channel->is_seekable, G_IO_STATUS_ERROR);

   860 

   861   switch (type)

   862     {

   863       case G_SEEK_CUR: /* The user is seeking relative to the head of the buffer */

   864         if (channel->use_buffer)

   865           {

   866             if (channel->do_encode && channel->encoded_read_buf

   867                 && channel->encoded_read_buf->len > 0)

   868               {

   869                 g_warning ("Seek type G_SEEK_CUR not allowed for this"

   870                   " channel's encoding.\n");

   871                 return G_IO_STATUS_ERROR;

   872               }

   873           if (channel->read_buf)

   874             offset -= channel->read_buf->len;

   875           if (channel->encoded_read_buf)

   876             {

   877               g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);

   878 

   879               /* If there's anything here, it's because the encoding is UTF-8,

   880                * so we can just subtract the buffer length, the same as for

   881                * the unencoded data.

   882                */

   883 

   884               offset -= channel->encoded_read_buf->len;

   885             }

   886           }

   887         break;

   888       case G_SEEK_SET:

   889       case G_SEEK_END:

   890         break;

   891       default:

   892         g_warning ("g_io_channel_seek_position: unknown seek type");

   893         return G_IO_STATUS_ERROR;

   894     }

   895 

   896   if (channel->use_buffer)

   897     {

   898       status = g_io_channel_flush (channel, error);

   899       if (status != G_IO_STATUS_NORMAL)

   900         return status;

   901     }

   902 

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

   904 

   905   if ((status == G_IO_STATUS_NORMAL) && (channel->use_buffer))

   906     {

   907       if (channel->read_buf)

   908         g_string_truncate (channel->read_buf, 0);

   909 

   910       /* Conversion state no longer matches position in file */

   911       if (channel->read_cd != (GIConv) -1)

   912         g_iconv (channel->read_cd, NULL, NULL, NULL, NULL);

   913       if (channel->write_cd != (GIConv) -1)

   914         g_iconv (channel->write_cd, NULL, NULL, NULL, NULL);

   915 

   916       if (channel->encoded_read_buf)

   917         {

   918           g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);

   919           g_string_truncate (channel->encoded_read_buf, 0);

   920         }

   921 

   922       if (channel->partial_write_buf[0] != '\0')

   923         {

   924           g_warning ("Partial character at end of write buffer not flushed.\n");

   925           channel->partial_write_buf[0] = '\0';

   926         }

   927     }

   928 

   929   return status;

   930 }

   931 

   932 /**

   933  * g_io_channel_flush:

   934  * @channel: a #GIOChannel

   935  * @error: location to store an error of type #GIOChannelError

   936  *

   937  * Flushes the write buffer for the GIOChannel.

   938  *

   939  * Return value: the status of the operation: One of

   940  *   #G_IO_CHANNEL_NORMAL, #G_IO_CHANNEL_AGAIN, or

   941  *   #G_IO_CHANNEL_ERROR.

   942  **/

   943 EXPORT_C GIOStatus

   944 g_io_channel_flush (GIOChannel	*channel,

   945 		    GError     **error)

   946 {

   947   GIOStatus status;

   948   gsize this_time = 1, bytes_written = 0;

   949 

   950   g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);

   951   g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);

   952 

   953   if (channel->write_buf == NULL || channel->write_buf->len == 0)

   954     return G_IO_STATUS_NORMAL;

   955 

   956   do

   957     {

   958       g_assert (this_time > 0);

   959 

   960       status = channel->funcs->io_write (channel,

   961 					 channel->write_buf->str + bytes_written,

   962 					 channel->write_buf->len - bytes_written,

   963 					 &this_time, error);

   964       bytes_written += this_time;

   965     }

   966   while ((bytes_written < channel->write_buf->len)

   967          && (status == G_IO_STATUS_NORMAL));

   968 

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

   970 

   971   return status;

   972 }

   973 

   974 /**

   975  * g_io_channel_set_buffered:

   976  * @channel: a #GIOChannel

   977  * @buffered: whether to set the channel buffered or unbuffered

   978  *

   979  * The buffering state can only be set if the channel's encoding

   980  * is %NULL. For any other encoding, the channel must be buffered.

   981  *

   982  * A buffered channel can only be set unbuffered if the channel's

   983  * internal buffers have been flushed. Newly created channels or

   984  * channels which have returned %G_IO_STATUS_EOF

   985  * not require such a flush. For write-only channels, a call to

   986  * g_io_channel_flush () is sufficient. For all other channels,

   987  * the buffers may be flushed by a call to g_io_channel_seek_position ().

   988  * This includes the possibility of seeking with seek type %G_SEEK_CUR

   989  * and an offset of zero. Note that this means that socket-based

   990  * channels cannot be set unbuffered once they have had data

   991  * read from them.

   992  *

   993  * On unbuffered channels, it is safe to mix read and write

   994  * calls from the new and old APIs, if this is necessary for

   995  * maintaining old code.

   996  *

   997  * The default state of the channel is buffered.

   998  **/

   999 EXPORT_C void

  1000 g_io_channel_set_buffered	(GIOChannel *channel,

  1001 				 gboolean    buffered)

  1002 {

  1003   g_return_if_fail (channel != NULL);

  1004 

  1005   if (channel->encoding != NULL)

  1006     {

  1007       g_warning ("Need to have NULL encoding to set the buffering state of the "

  1008                  "channel.\n");

  1009       return;

  1010     }

  1011 

  1012   g_return_if_fail (!channel->read_buf || channel->read_buf->len == 0);

  1013   g_return_if_fail (!channel->write_buf || channel->write_buf->len == 0);

  1014 

  1015   channel->use_buffer = buffered;

  1016 }

  1017 

  1018 /**

  1019  * g_io_channel_get_buffered:

  1020  * @channel: a #GIOChannel.

  1021  *

  1022  * Returns whether @channel is buffered.

  1023  *

  1024  * Return Value: %TRUE if the @channel is buffered. 

  1025  **/

  1026 EXPORT_C gboolean

  1027 g_io_channel_get_buffered	(GIOChannel *channel)

  1028 {

  1029   g_return_val_if_fail (channel != NULL, FALSE);

  1030 

  1031   return channel->use_buffer;

  1032 }

  1033 

  1034 /**

  1035  * g_io_channel_set_encoding:

  1036  * @channel: a #GIOChannel

  1037  * @encoding: the encoding type

  1038  * @error: location to store an error of type #GConvertError.

  1039  *

  1040  * Sets the encoding for the input/output of the channel. The internal

  1041  * encoding is always UTF-8. The default encoding for the

  1042  * external file is UTF-8.

  1043  *

  1044  * The encoding %NULL is safe to use with binary data.

  1045  *

  1046  * The encoding can only be set if one of the following conditions

  1047  * is true:

  1048  *

  1049  * 1. The channel was just created, and has not been written to

  1050  *    or read from yet.

  1051  *

  1052  * 2. The channel is write-only.

  1053  *

  1054  * 3. The channel is a file, and the file pointer was just

  1055  *    repositioned by a call to g_io_channel_seek_position().

  1056  *    (This flushes all the internal buffers.)

  1057  *

  1058  * 4. The current encoding is %NULL or UTF-8.

  1059  *

  1060  * 5. One of the (new API) read functions has just returned %G_IO_STATUS_EOF

  1061  *    (or, in the case of g_io_channel_read_to_end (), %G_IO_STATUS_NORMAL).

  1062  *

  1063  * 6. One of the functions g_io_channel_read_chars () or g_io_channel_read_unichar ()

  1064  *    has returned %G_IO_STATUS_AGAIN or %G_IO_STATUS_ERROR. This may be

  1065  *    useful in the case of %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.

  1066  *    Returning one of these statuses from g_io_channel_read_line (),

  1067  *    g_io_channel_read_line_string (), or g_io_channel_read_to_end ()

  1068  *    does <emphasis>not</emphasis> guarantee that the encoding can be changed.

  1069  *

  1070  * Channels which do not meet one of the above conditions cannot call

  1071  * g_io_channel_seek_position () with an offset of %G_SEEK_CUR,

  1072  * and, if they are "seekable", cannot

  1073  * call g_io_channel_write_chars () after calling one

  1074  * of the API "read" functions.

  1075  *

  1076  * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set.

  1077  **/

  1078 EXPORT_C GIOStatus

  1079 g_io_channel_set_encoding (GIOChannel	*channel,

  1080                            const gchar	*encoding,

  1081 			   GError      **error)

  1082 {

  1083   GIConv read_cd, write_cd;

  1084   gboolean did_encode;

  1085 

  1086   g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);

  1087   g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);

  1088 

  1089   /* Make sure the encoded buffers are empty */

  1090 

  1091   g_return_val_if_fail (!channel->do_encode || !channel->encoded_read_buf ||

  1092 			channel->encoded_read_buf->len == 0, G_IO_STATUS_ERROR);

  1093 

  1094   if (!channel->use_buffer)

  1095     {

  1096       g_warning ("Need to set the channel buffered before setting the encoding.\n");

  1097       g_warning ("Assuming this is what you meant and acting accordingly.\n");

  1098 

  1099       channel->use_buffer = TRUE;

  1100     }

  1101 

  1102   if (channel->partial_write_buf[0] != '\0')

  1103     {

  1104       g_warning ("Partial character at end of write buffer not flushed.\n");

  1105       channel->partial_write_buf[0] = '\0';

  1106     }

  1107 

  1108   did_encode = channel->do_encode;

  1109 

  1110   if (!encoding || strcmp (encoding, "UTF8") == 0 || strcmp (encoding, "UTF-8") == 0)

  1111     {

  1112       channel->do_encode = FALSE;

  1113       read_cd = write_cd = (GIConv) -1;

  1114     }

  1115   else

  1116     {

  1117       gint err = 0;

  1118       const gchar *from_enc = NULL, *to_enc = NULL;

  1119 

  1120       if (channel->is_readable)

  1121         {

  1122           read_cd = g_iconv_open ("UTF-8", encoding);

  1123 

  1124           if (read_cd == (GIConv) -1)

  1125             {

  1126               err = errno;

  1127               from_enc = "UTF-8";

  1128               to_enc = encoding;

  1129             }

  1130         }

  1131       else

  1132         read_cd = (GIConv) -1;

  1133 

  1134       if (channel->is_writeable && err == 0)

  1135         {