1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * giochannel.c: IO Channel abstraction
5 * Copyright 1998 Owen Taylor
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
24 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
25 * file for a list of people on the GLib Team. See the ChangeLog
26 * files for a list of changes. These files are distributed with
27 * GLib at ftp://ftp.gtk.org/pub/gtk/.
43 #undef G_DISABLE_DEPRECATED
45 #include "giochannel.h"
47 #include "gtestutils.h"
54 * @short_description: portable support for using files, pipes and
56 * @see_also: <para> <variablelist> <varlistentry>
57 * <term>g_io_add_watch(), g_io_add_watch_full(),
58 * g_source_remove()</term> <listitem><para> Convenience
59 * functions for creating #GIOChannel instances and adding
60 * them to the <link linkend="glib-The-Main-Event-Loop">main
61 * event loop</link>. </para></listitem> </varlistentry>
62 * </variablelist> </para>
64 * The #GIOChannel data type aims to provide a portable method for
65 * using file descriptors, pipes, and sockets, and integrating them
66 * into the <link linkend="glib-The-Main-Event-Loop">main event
67 * loop</link>. Currently full support is available on UNIX platforms,
68 * support for Windows is only partially complete.
70 * To create a new #GIOChannel on UNIX systems use
71 * g_io_channel_unix_new(). This works for plain file descriptors,
72 * pipes and sockets. Alternatively, a channel can be created for a
73 * file in a system independent manner using g_io_channel_new_file().
75 * Once a #GIOChannel has been created, it can be used in a generic
76 * manner with the functions g_io_channel_read_chars(),
77 * g_io_channel_write_chars(), g_io_channel_seek_position(), and
78 * g_io_channel_shutdown().
80 * To add a #GIOChannel to the <link
81 * linkend="glib-The-Main-Event-Loop">main event loop</link> use
82 * g_io_add_watch() or g_io_add_watch_full(). Here you specify which
83 * events you are interested in on the #GIOChannel, and provide a
84 * function to be called whenever these events occur.
86 * #GIOChannel instances are created with an initial reference count of
87 * 1. g_io_channel_ref() and g_io_channel_unref() can be used to
88 * increment or decrement the reference count respectively. When the
89 * reference count falls to 0, the #GIOChannel is freed. (Though it
90 * isn't closed automatically, unless it was created using
91 * g_io_channel_new_from_file().) Using g_io_add_watch() or
92 * g_io_add_watch_full() increments a channel's reference count.
94 * The new functions g_io_channel_read_chars(),
95 * g_io_channel_read_line(), g_io_channel_read_line_string(),
96 * g_io_channel_read_to_end(), g_io_channel_write_chars(),
97 * g_io_channel_seek_position(), and g_io_channel_flush() should not be
98 * mixed with the deprecated functions g_io_channel_read(),
99 * g_io_channel_write(), and g_io_channel_seek() on the same channel.
105 * A data structure representing an IO Channel. The fields should be
106 * considered private and should only be accessed with the following
112 * @io_read: reads raw bytes from the channel. This is called from
113 * various functions such as g_io_channel_read_chars() to
114 * read raw bytes from the channel. Encoding and buffering
115 * issues are dealt with at a higher level.
116 * @io_write: writes raw bytes to the channel. This is called from
117 * various functions such as g_io_channel_write_chars() to
118 * write raw bytes to the channel. Encoding and buffering
119 * issues are dealt with at a higher level.
120 * @io_seek: (optional) seeks the channel. This is called from
121 * g_io_channel_seek() on channels that support it.
122 * @io_close: closes the channel. This is called from
123 * g_io_channel_close() after flushing the buffers.
124 * @io_create_watch: creates a watch on the channel. This call
125 * corresponds directly to g_io_create_watch().
126 * @io_free: called from g_io_channel_unref() when the channel needs to
127 * be freed. This function must free the memory associated
128 * with the channel, including freeing the #GIOChannel
129 * structure itself. The channel buffers have been flushed
130 * and possibly @io_close has been called by the time this
131 * function is called.
132 * @io_set_flags: sets the #GIOFlags on the channel. This is called
133 * from g_io_channel_set_flags() with all flags except
134 * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked
136 * @io_get_flags: gets the #GIOFlags for the channel. This function
137 * need only return the %G_IO_FLAG_APPEND and
138 * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags()
139 * automatically adds the others as appropriate.
141 * A table of functions used to handle different types of #GIOChannel
147 * @G_IO_STATUS_ERROR: An error occurred.
148 * @G_IO_STATUS_NORMAL: Success.
149 * @G_IO_STATUS_EOF: End of file.
150 * @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
152 * Stati returned by most of the #GIOFuncs functions.
157 * @G_IO_ERROR_NONE: no error
158 * @G_IO_ERROR_AGAIN: an EAGAIN error occurred
159 * @G_IO_ERROR_INVAL: an EINVAL error occurred
160 * @G_IO_ERROR_UNKNOWN: another error occurred
162 * #GIOError is only used by the deprecated functions
163 * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
166 #define G_IO_NICE_BUF_SIZE 1024
168 /* This needs to be as wide as the largest character in any possible encoding */
169 #define MAX_CHAR_SIZE 10
171 /* Some simplifying macros, which reduce the need to worry whether the
172 * buffers have been allocated. These also make USE_BUF () an lvalue,
173 * which is used in g_io_channel_read_to_end ().
175 #define USE_BUF(channel) ((channel)->encoding ? (channel)->encoded_read_buf \
176 : (channel)->read_buf)
177 #define BUF_LEN(string) ((string) ? (string)->len : 0)
179 static GIOError g_io_error_get_from_g_error (GIOStatus status,
181 static void g_io_channel_purge (GIOChannel *channel);
182 static GIOStatus g_io_channel_fill_buffer (GIOChannel *channel,
184 static GIOStatus g_io_channel_read_line_backend (GIOChannel *channel,
186 gsize *terminator_pos,
191 * @channel: a #GIOChannel
193 * Initializes a #GIOChannel struct.
195 * This is called by each of the above functions when creating a
196 * #GIOChannel, and so is not often needed by the application
197 * programmer (unless you are creating a new type of #GIOChannel).
200 g_io_channel_init (GIOChannel *channel)
202 channel->ref_count = 1;
203 channel->encoding = g_strdup ("UTF-8");
204 channel->line_term = NULL;
205 channel->line_term_len = 0;
206 channel->buf_size = G_IO_NICE_BUF_SIZE;
207 channel->read_cd = (GIConv) -1;
208 channel->write_cd = (GIConv) -1;
209 channel->read_buf = NULL; /* Lazy allocate buffers */
210 channel->encoded_read_buf = NULL;
211 channel->write_buf = NULL;
212 channel->partial_write_buf[0] = '\0';
213 channel->use_buffer = TRUE;
214 channel->do_encode = FALSE;
215 channel->close_on_unref = FALSE;
220 * @channel: a #GIOChannel
222 * Increments the reference count of a #GIOChannel.
224 * Returns: the @channel that was passed in (since 2.6)
227 g_io_channel_ref (GIOChannel *channel)
229 g_return_val_if_fail (channel != NULL, NULL);
231 g_atomic_int_inc (&channel->ref_count);
237 * g_io_channel_unref:
238 * @channel: a #GIOChannel
240 * Decrements the reference count of a #GIOChannel.
243 g_io_channel_unref (GIOChannel *channel)
247 g_return_if_fail (channel != NULL);
249 is_zero = g_atomic_int_dec_and_test (&channel->ref_count);
251 if (G_UNLIKELY (is_zero))
253 if (channel->close_on_unref)
254 g_io_channel_shutdown (channel, TRUE, NULL);
256 g_io_channel_purge (channel);
257 g_free (channel->encoding);
258 if (channel->read_cd != (GIConv) -1)
259 g_iconv_close (channel->read_cd);
260 if (channel->write_cd != (GIConv) -1)
261 g_iconv_close (channel->write_cd);
262 g_free (channel->line_term);
263 if (channel->read_buf)
264 g_string_free (channel->read_buf, TRUE);
265 if (channel->write_buf)
266 g_string_free (channel->write_buf, TRUE);
267 if (channel->encoded_read_buf)
268 g_string_free (channel->encoded_read_buf, TRUE);
269 channel->funcs->io_free (channel);
274 g_io_error_get_from_g_error (GIOStatus status,
279 case G_IO_STATUS_NORMAL:
280 case G_IO_STATUS_EOF:
281 return G_IO_ERROR_NONE;
282 case G_IO_STATUS_AGAIN:
283 return G_IO_ERROR_AGAIN;
284 case G_IO_STATUS_ERROR:
285 g_return_val_if_fail (err != NULL, G_IO_ERROR_UNKNOWN);
287 if (err->domain != G_IO_CHANNEL_ERROR)
288 return G_IO_ERROR_UNKNOWN;
291 case G_IO_CHANNEL_ERROR_INVAL:
292 return G_IO_ERROR_INVAL;
294 return G_IO_ERROR_UNKNOWN;
297 g_assert_not_reached ();
303 * @channel: a #GIOChannel
304 * @buf: a buffer to read the data into (which should be at least
306 * @count: the number of bytes to read from the #GIOChannel
307 * @bytes_read: returns the number of bytes actually read
309 * Reads data from a #GIOChannel.
311 * Return value: %G_IO_ERROR_NONE if the operation was successful.
313 * Deprecated:2.2: Use g_io_channel_read_chars() instead.
316 g_io_channel_read (GIOChannel *channel,
325 g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
326 g_return_val_if_fail (bytes_read != NULL, G_IO_ERROR_UNKNOWN);
332 return G_IO_ERROR_NONE;
335 g_return_val_if_fail (buf != NULL, G_IO_ERROR_UNKNOWN);
337 status = channel->funcs->io_read (channel, buf, count, bytes_read, &err);
339 error = g_io_error_get_from_g_error (status, err);
348 * g_io_channel_write:
349 * @channel: a #GIOChannel
350 * @buf: the buffer containing the data to write
351 * @count: the number of bytes to write
352 * @bytes_written: the number of bytes actually written
354 * Writes data to a #GIOChannel.
356 * Return value: %G_IO_ERROR_NONE if the operation was successful.
358 * Deprecated:2.2: Use g_io_channel_write_chars() instead.
361 g_io_channel_write (GIOChannel *channel,
364 gsize *bytes_written)
370 g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
371 g_return_val_if_fail (bytes_written != NULL, G_IO_ERROR_UNKNOWN);
373 status = channel->funcs->io_write (channel, buf, count, bytes_written, &err);
375 error = g_io_error_get_from_g_error (status, err);
385 * @channel: a #GIOChannel
386 * @offset: an offset, in bytes, which is added to the position specified
388 * @type: the position in the file, which can be %G_SEEK_CUR (the current
389 * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END
390 * (the end of the file)
392 * Sets the current position in the #GIOChannel, similar to the standard
393 * library function fseek().
395 * Return value: %G_IO_ERROR_NONE if the operation was successful.
397 * Deprecated:2.2: Use g_io_channel_seek_position() instead.
400 g_io_channel_seek (GIOChannel *channel,
408 g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
409 g_return_val_if_fail (channel->is_seekable, G_IO_ERROR_UNKNOWN);
418 g_warning ("g_io_channel_seek: unknown seek type");
419 return G_IO_ERROR_UNKNOWN;
422 status = channel->funcs->io_seek (channel, offset, type, &err);
424 error = g_io_error_get_from_g_error (status, err);
432 /* The function g_io_channel_new_file() is prototyped in both
433 * giounix.c and giowin32.c, so we stick its documentation here.
437 * g_io_channel_new_file:
438 * @filename: A string containing the name of a file
439 * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
440 * the same meaning as in fopen()
441 * @error: A location to return an error of type %G_FILE_ERROR
443 * Open a file @filename as a #GIOChannel using mode @mode. This
444 * channel will be closed when the last reference to it is dropped,
445 * so there is no need to call g_io_channel_close() (though doing
446 * so will not cause problems, as long as no attempt is made to
447 * access the channel after it is closed).
449 * Return value: A #GIOChannel on success, %NULL on failure.
453 * g_io_channel_close:
454 * @channel: A #GIOChannel
456 * Close an IO channel. Any pending data to be written will be
457 * flushed, ignoring errors. The channel will not be freed until the
458 * last reference is dropped using g_io_channel_unref().
460 * Deprecated:2.2: Use g_io_channel_shutdown() instead.
463 g_io_channel_close (GIOChannel *channel)
467 g_return_if_fail (channel != NULL);
469 g_io_channel_purge (channel);
471 channel->funcs->io_close (channel, &err);
474 { /* No way to return the error */
475 g_warning ("Error closing channel: %s", err->message);
479 channel->close_on_unref = FALSE; /* Because we already did */
480 channel->is_readable = FALSE;
481 channel->is_writeable = FALSE;
482 channel->is_seekable = FALSE;
486 * g_io_channel_shutdown:
487 * @channel: a #GIOChannel
488 * @flush: if %TRUE, flush pending
489 * @err: location to store a #GIOChannelError
491 * Close an IO channel. Any pending data to be written will be
492 * flushed if @flush is %TRUE. The channel will not be freed until the
493 * last reference is dropped using g_io_channel_unref().
495 * Return value: the status of the operation.
498 g_io_channel_shutdown (GIOChannel *channel,
502 GIOStatus status, result;
503 GError *tmperr = NULL;
505 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
506 g_return_val_if_fail (err == NULL || *err == NULL, G_IO_STATUS_ERROR);
508 if (channel->write_buf && channel->write_buf->len > 0)
514 /* Set the channel to blocking, to avoid a busy loop
516 flags = g_io_channel_get_flags (channel);
517 /* Ignore any errors here, they're irrelevant */
518 g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);
520 result = g_io_channel_flush (channel, &tmperr);
523 result = G_IO_STATUS_NORMAL;
525 g_string_truncate(channel->write_buf, 0);
528 result = G_IO_STATUS_NORMAL;
530 if (channel->partial_write_buf[0] != '\0')
533 g_warning ("Partial character at end of write buffer not flushed.\n");
534 channel->partial_write_buf[0] = '\0';
537 status = channel->funcs->io_close (channel, err);
539 channel->close_on_unref = FALSE; /* Because we already did */
540 channel->is_readable = FALSE;
541 channel->is_writeable = FALSE;
542 channel->is_seekable = FALSE;
544 if (status != G_IO_STATUS_NORMAL)
546 g_clear_error (&tmperr);
549 else if (result != G_IO_STATUS_NORMAL)
551 g_propagate_error (err, tmperr);
555 return G_IO_STATUS_NORMAL;
558 /* This function is used for the final flush on close or unref */
560 g_io_channel_purge (GIOChannel *channel)
565 g_return_if_fail (channel != NULL);
567 if (channel->write_buf && channel->write_buf->len > 0)
571 /* Set the channel to blocking, to avoid a busy loop
573 flags = g_io_channel_get_flags (channel);
574 g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);
576 status = g_io_channel_flush (channel, &err);
579 { /* No way to return the error */
580 g_warning ("Error flushing string: %s", err->message);
585 /* Flush these in case anyone tries to close without unrefing */
587 if (channel->read_buf)
588 g_string_truncate (channel->read_buf, 0);
589 if (channel->write_buf)
590 g_string_truncate (channel->write_buf, 0);
591 if (channel->encoding)
593 if (channel->encoded_read_buf)
594 g_string_truncate (channel->encoded_read_buf, 0);
596 if (channel->partial_write_buf[0] != '\0')
598 g_warning ("Partial character at end of write buffer not flushed.\n");
599 channel->partial_write_buf[0] = '\0';
606 * @channel: a #GIOChannel to watch
607 * @condition: conditions to watch for
609 * Creates a #GSource that's dispatched when @condition is met for the
610 * given @channel. For example, if condition is #G_IO_IN, the source will
611 * be dispatched when there's data available for reading.
613 * g_io_add_watch() is a simpler interface to this same functionality, for
614 * the case where you want to add the source to the default main loop context
615 * at the default priority.
617 * On Windows, polling a #GSource created to watch a channel for a socket
618 * puts the socket in non-blocking mode. This is a side-effect of the
619 * implementation and unavoidable.
621 * Returns: a new #GSource
624 g_io_create_watch (GIOChannel *channel,
625 GIOCondition condition)
627 g_return_val_if_fail (channel != NULL, NULL);
629 return channel->funcs->io_create_watch (channel, condition);
633 * g_io_add_watch_full:
634 * @channel: a #GIOChannel
635 * @priority: the priority of the #GIOChannel source
636 * @condition: the condition to watch for
637 * @func: the function to call when the condition is satisfied
638 * @user_data: user data to pass to @func
639 * @notify: the function to call when the source is removed
641 * Adds the #GIOChannel into the default main loop context
642 * with the given priority.
644 * This internally creates a main loop source using g_io_create_watch()
645 * and attaches it to the main loop context with g_source_attach().
646 * You can do these steps manuallt if you need greater control.
648 * Returns: the event source id
651 g_io_add_watch_full (GIOChannel *channel,
653 GIOCondition condition,
656 GDestroyNotify notify)
661 g_return_val_if_fail (channel != NULL, 0);
663 source = g_io_create_watch (channel, condition);
665 if (priority != G_PRIORITY_DEFAULT)
666 g_source_set_priority (source, priority);
667 g_source_set_callback (source, (GSourceFunc)func, user_data, notify);
669 id = g_source_attach (source, NULL);
670 g_source_unref (source);
677 * @channel: a #GIOChannel
678 * @condition: the condition to watch for
679 * @func: the function to call when the condition is satisfied
680 * @user_data: user data to pass to @func
682 * Adds the #GIOChannel into the default main loop context
683 * with the default priority.
685 * Returns: the event source id
689 * @source: the #GIOChannel event source
690 * @condition: the condition which has been satisfied
691 * @data: user data set in g_io_add_watch() or g_io_add_watch_full()
692 * @Returns: the function should return %FALSE if the event source
695 * Specifies the type of function passed to g_io_add_watch() or
696 * g_io_add_watch_full(), which is called when the requested condition
697 * on a #GIOChannel is satisfied.
701 * @G_IO_IN: There is data to read.
702 * @G_IO_OUT: Data can be written (without blocking).
703 * @G_IO_PRI: There is urgent data to read.
704 * @G_IO_ERR: Error condition.
705 * @G_IO_HUP: Hung up (the connection has been broken, usually for
706 * pipes and sockets).
707 * @G_IO_NVAL: Invalid request. The file descriptor is not open.
709 * A bitwise combination representing a condition to watch for on an
713 g_io_add_watch (GIOChannel *channel,
714 GIOCondition condition,
718 return g_io_add_watch_full (channel, G_PRIORITY_DEFAULT, condition, func, user_data, NULL);
722 * g_io_channel_get_buffer_condition:
723 * @channel: A #GIOChannel
725 * This function returns a #GIOCondition depending on whether there
726 * is data to be read/space to write data in the internal buffers in
727 * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set.
729 * Return value: A #GIOCondition
732 g_io_channel_get_buffer_condition (GIOChannel *channel)
734 GIOCondition condition = 0;
736 if (channel->encoding)
738 if (channel->encoded_read_buf && (channel->encoded_read_buf->len > 0))
739 condition |= G_IO_IN; /* Only return if we have full characters */
743 if (channel->read_buf && (channel->read_buf->len > 0))
744 condition |= G_IO_IN;
747 if (channel->write_buf && (channel->write_buf->len < channel->buf_size))
748 condition |= G_IO_OUT;
754 * g_io_channel_error_from_errno:
755 * @en: an <literal>errno</literal> error number, e.g. %EINVAL
757 * Converts an <literal>errno</literal> error number to a #GIOChannelError.
759 * Return value: a #GIOChannelError error number, e.g.
760 * %G_IO_CHANNEL_ERROR_INVAL.
763 g_io_channel_error_from_errno (gint en)
766 g_return_val_if_fail (en != EAGAIN, G_IO_CHANNEL_ERROR_FAILED);
773 g_warning("Invalid file descriptor.\n");
774 return G_IO_CHANNEL_ERROR_FAILED;
779 g_warning("Buffer outside valid address space.\n");
780 return G_IO_CHANNEL_ERROR_FAILED;
785 return G_IO_CHANNEL_ERROR_FBIG;
789 /* In general, we should catch EINTR before we get here,
790 * but close() is allowed to return EINTR by POSIX, so
791 * we need to catch it here; EINTR from close() is
792 * unrecoverable, because it's undefined whether
793 * the fd was actually closed or not, so we just return
794 * a generic error code.
797 return G_IO_CHANNEL_ERROR_FAILED;
802 return G_IO_CHANNEL_ERROR_INVAL;
807 return G_IO_CHANNEL_ERROR_IO;
812 return G_IO_CHANNEL_ERROR_ISDIR;
817 return G_IO_CHANNEL_ERROR_NOSPC;
822 return G_IO_CHANNEL_ERROR_NXIO;
827 return G_IO_CHANNEL_ERROR_OVERFLOW;
832 return G_IO_CHANNEL_ERROR_PIPE;
836 return G_IO_CHANNEL_ERROR_FAILED;
841 * g_io_channel_set_buffer_size:
842 * @channel: a #GIOChannel
843 * @size: the size of the buffer, or 0 to let GLib pick a good size
845 * Sets the buffer size.
848 g_io_channel_set_buffer_size (GIOChannel *channel,
851 g_return_if_fail (channel != NULL);
854 size = G_IO_NICE_BUF_SIZE;
856 if (size < MAX_CHAR_SIZE)
857 size = MAX_CHAR_SIZE;
859 channel->buf_size = size;
863 * g_io_channel_get_buffer_size:
864 * @channel: a #GIOChannel
866 * Gets the buffer size.
868 * Return value: the size of the buffer.
871 g_io_channel_get_buffer_size (GIOChannel *channel)
873 g_return_val_if_fail (channel != NULL, 0);
875 return channel->buf_size;
879 * g_io_channel_set_line_term:
880 * @channel: a #GIOChannel
881 * @line_term: The line termination string. Use %NULL for autodetect.
882 * Autodetection breaks on "\n", "\r\n", "\r", "\0", and
883 * the Unicode paragraph separator. Autodetection should
884 * not be used for anything other than file-based channels.
885 * @length: The length of the termination string. If -1 is passed, the
886 * string is assumed to be nul-terminated. This option allows
887 * termination strings with embedded nuls.
889 * This sets the string that #GIOChannel uses to determine
890 * where in the file a line break occurs.
893 g_io_channel_set_line_term (GIOChannel *channel,
894 const gchar *line_term,
897 g_return_if_fail (channel != NULL);
898 g_return_if_fail (line_term == NULL || length != 0); /* Disallow "" */
900 if (line_term == NULL)
903 length = strlen (line_term);
905 g_free (channel->line_term);
906 channel->line_term = line_term ? g_memdup (line_term, length) : NULL;
907 channel->line_term_len = length;
911 * g_io_channel_get_line_term:
912 * @channel: a #GIOChannel
913 * @length: a location to return the length of the line terminator
915 * This returns the string that #GIOChannel uses to determine
916 * where in the file a line break occurs. A value of %NULL
917 * indicates autodetection.
919 * Return value: The line termination string. This value
920 * is owned by GLib and must not be freed.
922 G_CONST_RETURN gchar*
923 g_io_channel_get_line_term (GIOChannel *channel,
926 g_return_val_if_fail (channel != NULL, NULL);
929 *length = channel->line_term_len;
931 return channel->line_term;
935 * g_io_channel_set_flags:
936 * @channel: a #GIOChannel
937 * @flags: the flags to set on the IO channel
938 * @error: A location to return an error of type #GIOChannelError
940 * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).
942 * Return value: the status of the operation.
946 * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
947 * (see the documentation of the UNIX open()
949 * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
950 * %O_NONBLOCK/%O_NDELAY (see the documentation of
951 * the UNIX open() syscall).
952 * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
953 * This flag can not be changed.
954 * @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
955 * This flag can not be changed.
956 * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
957 * i.e. that g_io_channel_seek_position() can
958 * be used on it. This flag can not be changed.
959 * @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
960 * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
961 * g_io_channel_get_flags().
962 * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
963 * with g_io_channel_set_flags().
965 * Specifies properties of a #GIOChannel. Some of the flags can only be
966 * read with g_io_channel_get_flags(), but not changed with
967 * g_io_channel_set_flags().
970 g_io_channel_set_flags (GIOChannel *channel,
974 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
975 g_return_val_if_fail ((error == NULL) || (*error == NULL),
978 return (*channel->funcs->io_set_flags) (channel,
979 flags & G_IO_FLAG_SET_MASK,
984 * g_io_channel_get_flags:
985 * @channel: a #GIOChannel
987 * Gets the current flags for a #GIOChannel, including read-only
988 * flags such as %G_IO_FLAG_IS_READABLE.
990 * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITEABLE
991 * are cached for internal use by the channel when it is created.
992 * If they should change at some later point (e.g. partial shutdown
993 * of a socket with the UNIX shutdown() function), the user
994 * should immediately call g_io_channel_get_flags() to update
995 * the internal values of these flags.
997 * Return value: the flags which are set on the channel
1000 g_io_channel_get_flags (GIOChannel *channel)
1004 g_return_val_if_fail (channel != NULL, 0);
1006 flags = (* channel->funcs->io_get_flags) (channel);
1008 /* Cross implementation code */
1010 if (channel->is_seekable)
1011 flags |= G_IO_FLAG_IS_SEEKABLE;
1012 if (channel->is_readable)
1013 flags |= G_IO_FLAG_IS_READABLE;
1014 if (channel->is_writeable)
1015 flags |= G_IO_FLAG_IS_WRITEABLE;
1021 * g_io_channel_set_close_on_unref:
1022 * @channel: a #GIOChannel
1023 * @do_close: Whether to close the channel on the final unref of
1024 * the GIOChannel data structure. The default value of
1025 * this is %TRUE for channels created by g_io_channel_new_file (),
1026 * and %FALSE for all other channels.
1028 * Setting this flag to %TRUE for a channel you have already closed
1029 * can cause problems.
1032 g_io_channel_set_close_on_unref (GIOChannel *channel,
1035 g_return_if_fail (channel != NULL);
1037 channel->close_on_unref = do_close;
1041 * g_io_channel_get_close_on_unref:
1042 * @channel: a #GIOChannel.
1044 * Returns whether the file/socket/whatever associated with @channel
1045 * will be closed when @channel receives its final unref and is
1046 * destroyed. The default value of this is %TRUE for channels created
1047 * by g_io_channel_new_file (), and %FALSE for all other channels.
1049 * Return value: Whether the channel will be closed on the final unref of
1050 * the GIOChannel data structure.
1053 g_io_channel_get_close_on_unref (GIOChannel *channel)
1055 g_return_val_if_fail (channel != NULL, FALSE);
1057 return channel->close_on_unref;
1061 * g_io_channel_seek_position:
1062 * @channel: a #GIOChannel
1063 * @offset: The offset in bytes from the position specified by @type
1064 * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those
1065 * cases where a call to g_io_channel_set_encoding ()
1066 * is allowed. See the documentation for
1067 * g_io_channel_set_encoding () for details.
1068 * @error: A location to return an error of type #GIOChannelError
1070 * Replacement for g_io_channel_seek() with the new API.
1072 * Return value: the status of the operation.
1076 * @G_SEEK_CUR: the current position in the file.
1077 * @G_SEEK_SET: the start of the file.
1078 * @G_SEEK_END: the end of the file.
1080 * An enumeration specifying the base position for a
1081 * g_io_channel_seek_position() operation.
1084 g_io_channel_seek_position (GIOChannel *channel,
1091 /* For files, only one of the read and write buffers can contain data.
1092 * For sockets, both can contain data.
1095 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1096 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1098 g_return_val_if_fail (channel->is_seekable, G_IO_STATUS_ERROR);
1102 case G_SEEK_CUR: /* The user is seeking relative to the head of the buffer */
1103 if (channel->use_buffer)
1105 if (channel->do_encode && channel->encoded_read_buf
1106 && channel->encoded_read_buf->len > 0)
1108 g_warning ("Seek type G_SEEK_CUR not allowed for this"
1109 " channel's encoding.\n");
1110 return G_IO_STATUS_ERROR;
1112 if (channel->read_buf)
1113 offset -= channel->read_buf->len;
1114 if (channel->encoded_read_buf)
1116 g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
1118 /* If there's anything here, it's because the encoding is UTF-8,
1119 * so we can just subtract the buffer length, the same as for
1120 * the unencoded data.
1123 offset -= channel->encoded_read_buf->len;
1131 g_warning ("g_io_channel_seek_position: unknown seek type");
1132 return G_IO_STATUS_ERROR;
1135 if (channel->use_buffer)
1137 status = g_io_channel_flush (channel, error);
1138 if (status != G_IO_STATUS_NORMAL)
1142 status = channel->funcs->io_seek (channel, offset, type, error);
1144 if ((status == G_IO_STATUS_NORMAL) && (channel->use_buffer))
1146 if (channel->read_buf)
1147 g_string_truncate (channel->read_buf, 0);
1149 /* Conversion state no longer matches position in file */
1150 if (channel->read_cd != (GIConv) -1)
1151 g_iconv (channel->read_cd, NULL, NULL, NULL, NULL);
1152 if (channel->write_cd != (GIConv) -1)
1153 g_iconv (channel->write_cd, NULL, NULL, NULL, NULL);
1155 if (channel->encoded_read_buf)
1157 g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
1158 g_string_truncate (channel->encoded_read_buf, 0);
1161 if (channel->partial_write_buf[0] != '\0')
1163 g_warning ("Partial character at end of write buffer not flushed.\n");
1164 channel->partial_write_buf[0] = '\0';
1172 * g_io_channel_flush:
1173 * @channel: a #GIOChannel
1174 * @error: location to store an error of type #GIOChannelError
1176 * Flushes the write buffer for the GIOChannel.
1178 * Return value: the status of the operation: One of
1179 * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
1180 * #G_IO_STATUS_ERROR.
1183 g_io_channel_flush (GIOChannel *channel,
1187 gsize this_time = 1, bytes_written = 0;
1189 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1190 g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);
1192 if (channel->write_buf == NULL || channel->write_buf->len == 0)
1193 return G_IO_STATUS_NORMAL;
1197 g_assert (this_time > 0);
1199 status = channel->funcs->io_write (channel,
1200 channel->write_buf->str + bytes_written,
1201 channel->write_buf->len - bytes_written,
1203 bytes_written += this_time;
1205 while ((bytes_written < channel->write_buf->len)
1206 && (status == G_IO_STATUS_NORMAL));
1208 g_string_erase (channel->write_buf, 0, bytes_written);
1214 * g_io_channel_set_buffered:
1215 * @channel: a #GIOChannel
1216 * @buffered: whether to set the channel buffered or unbuffered
1218 * The buffering state can only be set if the channel's encoding
1219 * is %NULL. For any other encoding, the channel must be buffered.
1221 * A buffered channel can only be set unbuffered if the channel's
1222 * internal buffers have been flushed. Newly created channels or
1223 * channels which have returned %G_IO_STATUS_EOF
1224 * not require such a flush. For write-only channels, a call to
1225 * g_io_channel_flush () is sufficient. For all other channels,
1226 * the buffers may be flushed by a call to g_io_channel_seek_position ().
1227 * This includes the possibility of seeking with seek type %G_SEEK_CUR
1228 * and an offset of zero. Note that this means that socket-based
1229 * channels cannot be set unbuffered once they have had data
1232 * On unbuffered channels, it is safe to mix read and write
1233 * calls from the new and old APIs, if this is necessary for
1234 * maintaining old code.
1236 * The default state of the channel is buffered.
1239 g_io_channel_set_buffered (GIOChannel *channel,
1242 g_return_if_fail (channel != NULL);
1244 if (channel->encoding != NULL)
1246 g_warning ("Need to have NULL encoding to set the buffering state of the "
1251 g_return_if_fail (!channel->read_buf || channel->read_buf->len == 0);
1252 g_return_if_fail (!channel->write_buf || channel->write_buf->len == 0);
1254 channel->use_buffer = buffered;
1258 * g_io_channel_get_buffered:
1259 * @channel: a #GIOChannel
1261 * Returns whether @channel is buffered.
1263 * Return Value: %TRUE if the @channel is buffered.
1266 g_io_channel_get_buffered (GIOChannel *channel)
1268 g_return_val_if_fail (channel != NULL, FALSE);
1270 return channel->use_buffer;
1274 * g_io_channel_set_encoding:
1275 * @channel: a #GIOChannel
1276 * @encoding: the encoding type
1277 * @error: location to store an error of type #GConvertError
1279 * Sets the encoding for the input/output of the channel.
1280 * The internal encoding is always UTF-8. The default encoding
1281 * for the external file is UTF-8.
1283 * The encoding %NULL is safe to use with binary data.
1285 * The encoding can only be set if one of the following conditions
1289 * The channel was just created, and has not been written to or read
1291 * </para></listitem>
1293 * The channel is write-only.
1294 * </para></listitem>
1296 * The channel is a file, and the file pointer was just
1297 * repositioned by a call to g_io_channel_seek_position().
1298 * (This flushes all the internal buffers.)
1299 * </para></listitem>
1301 * The current encoding is %NULL or UTF-8.
1302 * </para></listitem>
1304 * One of the (new API) read functions has just returned %G_IO_STATUS_EOF
1305 * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
1306 * </para></listitem>
1308 * One of the functions g_io_channel_read_chars() or
1309 * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
1310 * %G_IO_STATUS_ERROR. This may be useful in the case of
1311 * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
1312 * Returning one of these statuses from g_io_channel_read_line(),
1313 * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
1314 * does <emphasis>not</emphasis> guarantee that the encoding can
1316 * </para></listitem>
1318 * Channels which do not meet one of the above conditions cannot call
1319 * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
1320 * they are "seekable", cannot call g_io_channel_write_chars() after
1321 * calling one of the API "read" functions.
1323 * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set.
1326 g_io_channel_set_encoding (GIOChannel *channel,
1327 const gchar *encoding,
1330 GIConv read_cd, write_cd;
1331 gboolean did_encode;
1333 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1334 g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);
1336 /* Make sure the encoded buffers are empty */
1338 g_return_val_if_fail (!channel->do_encode || !channel->encoded_read_buf ||
1339 channel->encoded_read_buf->len == 0, G_IO_STATUS_ERROR);
1341 if (!channel->use_buffer)
1343 g_warning ("Need to set the channel buffered before setting the encoding.\n");
1344 g_warning ("Assuming this is what you meant and acting accordingly.\n");
1346 channel->use_buffer = TRUE;
1349 if (channel->partial_write_buf[0] != '\0')
1351 g_warning ("Partial character at end of write buffer not flushed.\n");
1352 channel->partial_write_buf[0] = '\0';
1355 did_encode = channel->do_encode;
1357 if (!encoding || strcmp (encoding, "UTF8") == 0 || strcmp (encoding, "UTF-8") == 0)
1359 channel->do_encode = FALSE;
1360 read_cd = write_cd = (GIConv) -1;
1365 const gchar *from_enc = NULL, *to_enc = NULL;
1367 if (channel->is_readable)
1369 read_cd = g_iconv_open ("UTF-8", encoding);
1371 if (read_cd == (GIConv) -1)
1374 from_enc = encoding;
1379 read_cd = (GIConv) -1;
1381 if (channel->is_writeable && err == 0)
1383 write_cd = g_iconv_open (encoding, "UTF-8");
1385 if (write_cd == (GIConv) -1)
1393 write_cd = (GIConv) -1;
1397 g_assert (from_enc);
1401 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_CONVERSION,
1402 _("Conversion from character set '%s' to '%s' is not supported"),
1405 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1406 _("Could not open converter from '%s' to '%s': %s"),
1407 from_enc, to_enc, g_strerror (err));
1409 if (read_cd != (GIConv) -1)
1410 g_iconv_close (read_cd);
1411 if (write_cd != (GIConv) -1)
1412 g_iconv_close (write_cd);
1414 return G_IO_STATUS_ERROR;
1417 channel->do_encode = TRUE;
1420 /* The encoding is ok, so set the fields in channel */
1422 if (channel->read_cd != (GIConv) -1)
1423 g_iconv_close (channel->read_cd);
1424 if (channel->write_cd != (GIConv) -1)
1425 g_iconv_close (channel->write_cd);
1427 if (channel->encoded_read_buf && channel->encoded_read_buf->len > 0)
1429 g_assert (!did_encode); /* Encoding UTF-8, NULL doesn't use encoded_read_buf */
1431 /* This is just validated UTF-8, so we can copy it back into read_buf
1432 * so it can be encoded in whatever the new encoding is.
1435 g_string_prepend_len (channel->read_buf, channel->encoded_read_buf->str,
1436 channel->encoded_read_buf->len);
1437 g_string_truncate (channel->encoded_read_buf, 0);
1440 channel->read_cd = read_cd;
1441 channel->write_cd = write_cd;
1443 g_free (channel->encoding);
1444 channel->encoding = g_strdup (encoding);
1446 return G_IO_STATUS_NORMAL;
1450 * g_io_channel_get_encoding:
1451 * @channel: a #GIOChannel
1453 * Gets the encoding for the input/output of the channel.
1454 * The internal encoding is always UTF-8. The encoding %NULL
1455 * makes the channel safe for binary data.
1457 * Return value: A string containing the encoding, this string is
1458 * owned by GLib and must not be freed.
1460 G_CONST_RETURN gchar*
1461 g_io_channel_get_encoding (GIOChannel *channel)
1463 g_return_val_if_fail (channel != NULL, NULL);
1465 return channel->encoding;
1469 g_io_channel_fill_buffer (GIOChannel *channel,
1472 gsize read_size, cur_len, oldlen;
1475 if (channel->is_seekable && channel->write_buf && channel->write_buf->len > 0)
1477 status = g_io_channel_flush (channel, err);
1478 if (status != G_IO_STATUS_NORMAL)
1481 if (channel->is_seekable && channel->partial_write_buf[0] != '\0')
1483 g_warning ("Partial character at end of write buffer not flushed.\n");
1484 channel->partial_write_buf[0] = '\0';
1487 if (!channel->read_buf)
1488 channel->read_buf = g_string_sized_new (channel->buf_size);
1490 cur_len = channel->read_buf->len;
1492 g_string_set_size (channel->read_buf, channel->read_buf->len + channel->buf_size);
1494 status = channel->funcs->io_read (channel, channel->read_buf->str + cur_len,
1495 channel->buf_size, &read_size, err);
1497 g_assert ((status == G_IO_STATUS_NORMAL) || (read_size == 0));
1499 g_string_truncate (channel->read_buf, read_size + cur_len);
1501 if ((status != G_IO_STATUS_NORMAL) &&
1502 ((status != G_IO_STATUS_EOF) || (channel->read_buf->len == 0)))
1505 g_assert (channel->read_buf->len > 0);
1507 if (channel->encoded_read_buf)
1508 oldlen = channel->encoded_read_buf->len;
1512 if (channel->encoding)
1513 channel->encoded_read_buf = g_string_sized_new (channel->buf_size);
1516 if (channel->do_encode)
1518 gsize errnum, inbytes_left, outbytes_left;
1519 gchar *inbuf, *outbuf;
1522 g_assert (channel->encoded_read_buf);
1526 inbytes_left = channel->read_buf->len;
1527 outbytes_left = MAX (channel->read_buf->len,
1528 channel->encoded_read_buf->allocated_len
1529 - channel->encoded_read_buf->len - 1); /* 1 for NULL */
1530 outbytes_left = MAX (outbytes_left, 6);
1532 inbuf = channel->read_buf->str;
1533 g_string_set_size (channel->encoded_read_buf,
1534 channel->encoded_read_buf->len + outbytes_left);
1535 outbuf = channel->encoded_read_buf->str + channel->encoded_read_buf->len
1538 errnum = g_iconv (channel->read_cd, &inbuf, &inbytes_left,
1539 &outbuf, &outbytes_left);
1542 g_assert (inbuf + inbytes_left == channel->read_buf->str
1543 + channel->read_buf->len);
1544 g_assert (outbuf + outbytes_left == channel->encoded_read_buf->str
1545 + channel->encoded_read_buf->len);
1547 g_string_erase (channel->read_buf, 0,
1548 channel->read_buf->len - inbytes_left);
1549 g_string_truncate (channel->encoded_read_buf,
1550 channel->encoded_read_buf->len - outbytes_left);
1552 if (errnum == (gsize) -1)
1557 if ((oldlen == channel->encoded_read_buf->len)
1558 && (status == G_IO_STATUS_EOF))
1559 status = G_IO_STATUS_EOF;
1561 status = G_IO_STATUS_NORMAL;
1564 /* Buffer size at least 6, wrote at least on character */
1565 g_assert (inbuf != channel->read_buf->str);
1568 if (oldlen < channel->encoded_read_buf->len)
1569 status = G_IO_STATUS_NORMAL;
1572 g_set_error_literal (err, G_CONVERT_ERROR,
1573 G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1574 _("Invalid byte sequence in conversion input"));
1575 return G_IO_STATUS_ERROR;
1579 g_assert (errval != EBADF); /* The converter should be open */
1580 g_set_error (err, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1581 _("Error during conversion: %s"), g_strerror (errval));
1582 return G_IO_STATUS_ERROR;
1585 g_assert ((status != G_IO_STATUS_NORMAL)
1586 || (channel->encoded_read_buf->len > 0));
1588 else if (channel->encoding) /* UTF-8 */
1590 gchar *nextchar, *lastchar;
1592 g_assert (channel->encoded_read_buf);
1594 nextchar = channel->read_buf->str;
1595 lastchar = channel->read_buf->str + channel->read_buf->len;
1597 while (nextchar < lastchar)
1601 val_char = g_utf8_get_char_validated (nextchar, lastchar - nextchar);
1606 /* stop, leave partial character in buffer */
1607 lastchar = nextchar;
1610 if (oldlen < channel->encoded_read_buf->len)
1611 status = G_IO_STATUS_NORMAL;
1614 g_set_error_literal (err, G_CONVERT_ERROR,
1615 G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1616 _("Invalid byte sequence in conversion input"));
1617 status = G_IO_STATUS_ERROR;
1619 lastchar = nextchar;
1622 nextchar = g_utf8_next_char (nextchar);
1627 if (lastchar > channel->read_buf->str)
1629 gint copy_len = lastchar - channel->read_buf->str;
1631 g_string_append_len (channel->encoded_read_buf, channel->read_buf->str,
1633 g_string_erase (channel->read_buf, 0, copy_len);
1641 * g_io_channel_read_line:
1642 * @channel: a #GIOChannel
1643 * @str_return: The line read from the #GIOChannel, including the
1644 * line terminator. This data should be freed with g_free()
1645 * when no longer needed. This is a nul-terminated string.
1646 * If a @length of zero is returned, this will be %NULL instead.
1647 * @length: location to store length of the read data, or %NULL
1648 * @terminator_pos: location to store position of line terminator, or %NULL
1649 * @error: A location to return an error of type #GConvertError
1650 * or #GIOChannelError
1652 * Reads a line, including the terminating character(s),
1653 * from a #GIOChannel into a newly-allocated string.
1654 * @str_return will contain allocated memory if the return
1655 * is %G_IO_STATUS_NORMAL.
1657 * Return value: the status of the operation.
1660 g_io_channel_read_line (GIOChannel *channel,
1663 gsize *terminator_pos,
1669 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1670 g_return_val_if_fail (str_return != NULL, G_IO_STATUS_ERROR);
1671 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1673 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
1675 status = g_io_channel_read_line_backend (channel, &got_length, terminator_pos, error);
1678 *length = got_length;
1680 if (status == G_IO_STATUS_NORMAL)
1682 g_assert (USE_BUF (channel));
1683 *str_return = g_strndup (USE_BUF (channel)->str, got_length);
1684 g_string_erase (USE_BUF (channel), 0, got_length);
1693 * g_io_channel_read_line_string:
1694 * @channel: a #GIOChannel
1695 * @buffer: a #GString into which the line will be written.
1696 * If @buffer already contains data, the old data will
1698 * @terminator_pos: location to store position of line terminator, or %NULL
1699 * @error: a location to store an error of type #GConvertError
1700 * or #GIOChannelError
1702 * Reads a line from a #GIOChannel, using a #GString as a buffer.
1704 * Return value: the status of the operation.
1707 g_io_channel_read_line_string (GIOChannel *channel,
1709 gsize *terminator_pos,
1715 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1716 g_return_val_if_fail (buffer != NULL, G_IO_STATUS_ERROR);
1717 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1719 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
1721 if (buffer->len > 0)
1722 g_string_truncate (buffer, 0); /* clear out the buffer */
1724 status = g_io_channel_read_line_backend (channel, &length, terminator_pos, error);
1726 if (status == G_IO_STATUS_NORMAL)
1728 g_assert (USE_BUF (channel));
1729 g_string_append_len (buffer, USE_BUF (channel)->str, length);
1730 g_string_erase (USE_BUF (channel), 0, length);
1738 g_io_channel_read_line_backend (GIOChannel *channel,
1740 gsize *terminator_pos,
1744 gsize checked_to, line_term_len, line_length, got_term_len;
1745 gboolean first_time = TRUE;
1747 if (!channel->use_buffer)
1749 /* Can't do a raw read in read_line */
1750 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1751 _("Can't do a raw read in g_io_channel_read_line_string"));
1752 return G_IO_STATUS_ERROR;
1755 status = G_IO_STATUS_NORMAL;
1757 if (channel->line_term)
1758 line_term_len = channel->line_term_len;
1761 /* This value used for setting checked_to, it's the longest of the four
1762 * we autodetect for.
1769 gchar *nextchar, *lastchar;
1772 if (!first_time || (BUF_LEN (USE_BUF (channel)) == 0))
1775 status = g_io_channel_fill_buffer (channel, error);
1778 case G_IO_STATUS_NORMAL:
1779 if (BUF_LEN (USE_BUF (channel)) == 0)
1780 /* Can happen when using conversion and only read
1781 * part of a character
1788 case G_IO_STATUS_EOF:
1789 if (BUF_LEN (USE_BUF (channel)) == 0)
1794 if (channel->encoding && channel->read_buf->len != 0)
1796 g_set_error_literal (error, G_CONVERT_ERROR,
1797 G_CONVERT_ERROR_PARTIAL_INPUT,
1798 _("Leftover unconverted data in "
1800 return G_IO_STATUS_ERROR;
1803 return G_IO_STATUS_EOF;
1813 g_assert (BUF_LEN (USE_BUF (channel)) != 0);
1815 use_buf = USE_BUF (channel); /* The buffer has been created by this point */
1819 lastchar = use_buf->str + use_buf->len;
1821 for (nextchar = use_buf->str + checked_to; nextchar < lastchar;
1822 channel->encoding ? nextchar = g_utf8_next_char (nextchar) : nextchar++)
1824 if (channel->line_term)
1826 if (memcmp (channel->line_term, nextchar, line_term_len) == 0)
1828 line_length = nextchar - use_buf->str;
1829 got_term_len = line_term_len;
1833 else /* auto detect */
1837 case '\n': /* unix */
1838 line_length = nextchar - use_buf->str;
1841 case '\r': /* Warning: do not use with sockets */
1842 line_length = nextchar - use_buf->str;
1843 if ((nextchar == lastchar - 1) && (status != G_IO_STATUS_EOF)
1844 && (lastchar == use_buf->str + use_buf->len))
1845 goto read_again; /* Try to read more data */
1846 if ((nextchar < lastchar - 1) && (*(nextchar + 1) == '\n')) /* dos */
1851 case '\xe2': /* Unicode paragraph separator */
1852 if (strncmp ("\xe2\x80\xa9", nextchar, 3) == 0)
1854 line_length = nextchar - use_buf->str;
1859 case '\0': /* Embeded null in input */
1860 line_length = nextchar - use_buf->str;
1863 default: /* no match */
1869 /* If encoding != NULL, valid UTF-8, didn't overshoot */
1870 g_assert (nextchar == lastchar);
1874 if (status == G_IO_STATUS_EOF)
1876 if (channel->encoding && channel->read_buf->len > 0)
1878 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
1879 _("Channel terminates in a partial character"));
1880 return G_IO_STATUS_ERROR;
1882 line_length = use_buf->len;
1887 if (use_buf->len > line_term_len - 1)
1888 checked_to = use_buf->len - (line_term_len - 1);
1896 *terminator_pos = line_length;
1899 *length = line_length + got_term_len;
1901 return G_IO_STATUS_NORMAL;
1905 * g_io_channel_read_to_end:
1906 * @channel: a #GIOChannel
1907 * @str_return: Location to store a pointer to a string holding
1908 * the remaining data in the #GIOChannel. This data should
1909 * be freed with g_free() when no longer needed. This
1910 * data is terminated by an extra nul character, but there
1911 * may be other nuls in the intervening data.
1912 * @length: location to store length of the data
1913 * @error: location to return an error of type #GConvertError
1914 * or #GIOChannelError
1916 * Reads all the remaining data from the file.
1918 * Return value: %G_IO_STATUS_NORMAL on success.
1919 * This function never returns %G_IO_STATUS_EOF.
1922 g_io_channel_read_to_end (GIOChannel *channel,
1929 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1930 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1932 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
1939 if (!channel->use_buffer)
1941 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1942 _("Can't do a raw read in g_io_channel_read_to_end"));
1943 return G_IO_STATUS_ERROR;
1947 status = g_io_channel_fill_buffer (channel, error);
1948 while (status == G_IO_STATUS_NORMAL);
1950 if (status != G_IO_STATUS_EOF)
1953 if (channel->encoding && channel->read_buf->len > 0)
1955 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
1956 _("Channel terminates in a partial character"));
1957 return G_IO_STATUS_ERROR;
1960 if (USE_BUF (channel) == NULL)
1962 /* length is already set to zero */
1964 *str_return = g_strdup ("");
1969 *length = USE_BUF (channel)->len;
1972 *str_return = g_string_free (USE_BUF (channel), FALSE);
1974 g_string_free (USE_BUF (channel), TRUE);
1976 if (channel->encoding)
1977 channel->encoded_read_buf = NULL;
1979 channel->read_buf = NULL;
1982 return G_IO_STATUS_NORMAL;
1986 * g_io_channel_read_chars:
1987 * @channel: a #GIOChannel
1988 * @buf: a buffer to read data into
1989 * @count: the size of the buffer. Note that the buffer may
1990 * not be complelely filled even if there is data
1991 * in the buffer if the remaining data is not a
1992 * complete character.
1993 * @bytes_read: The number of bytes read. This may be zero even on
1994 * success if count < 6 and the channel's encoding is non-%NULL.
1995 * This indicates that the next UTF-8 character is too wide for
1997 * @error: a location to return an error of type #GConvertError
1998 * or #GIOChannelError.
2000 * Replacement for g_io_channel_read() with the new API.
2002 * Return value: the status of the operation.
2005 g_io_channel_read_chars (GIOChannel *channel,
2014 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2015 g_return_val_if_fail ((error == NULL) || (*error == NULL),
2017 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
2022 return G_IO_STATUS_NORMAL;
2024 g_return_val_if_fail (buf != NULL, G_IO_STATUS_ERROR);
2026 if (!channel->use_buffer)
2030 g_assert (!channel->read_buf || channel->read_buf->len == 0);
2032 status = channel->funcs->io_read (channel, buf, count, &tmp_bytes, error);
2035 *bytes_read = tmp_bytes;
2040 status = G_IO_STATUS_NORMAL;
2042 while (BUF_LEN (USE_BUF (channel)) < count && status == G_IO_STATUS_NORMAL)
2043 status = g_io_channel_fill_buffer (channel, error);
2045 /* Only return an error if we have no data */
2047 if (BUF_LEN (USE_BUF (channel)) == 0)
2049 g_assert (status != G_IO_STATUS_NORMAL);
2051 if (status == G_IO_STATUS_EOF && channel->encoding
2052 && BUF_LEN (channel->read_buf) > 0)
2054 g_set_error_literal (error, G_CONVERT_ERROR,
2055 G_CONVERT_ERROR_PARTIAL_INPUT,
2056 _("Leftover unconverted data in read buffer"));
2057 status = G_IO_STATUS_ERROR;
2066 if (status == G_IO_STATUS_ERROR)
2067 g_clear_error (error);
2069 got_bytes = MIN (count, BUF_LEN (USE_BUF (channel)));
2071 g_assert (got_bytes > 0);
2073 if (channel->encoding)
2074 /* Don't validate for NULL encoding, binary safe */
2076 gchar *nextchar, *prevchar;
2078 g_assert (USE_BUF (channel) == channel->encoded_read_buf);
2080 nextchar = channel->encoded_read_buf->str;
2084 prevchar = nextchar;
2085 nextchar = g_utf8_next_char (nextchar);
2086 g_assert (nextchar != prevchar); /* Possible for *prevchar of -1 or -2 */
2088 while (nextchar < channel->encoded_read_buf->str + got_bytes);
2090 if (nextchar > channel->encoded_read_buf->str + got_bytes)
2091 got_bytes = prevchar - channel->encoded_read_buf->str;
2093 g_assert (got_bytes > 0 || count < 6);
2096 memcpy (buf, USE_BUF (channel)->str, got_bytes);
2097 g_string_erase (USE_BUF (channel), 0, got_bytes);
2100 *bytes_read = got_bytes;
2102 return G_IO_STATUS_NORMAL;
2106 * g_io_channel_read_unichar:
2107 * @channel: a #GIOChannel
2108 * @thechar: a location to return a character
2109 * @error: a location to return an error of type #GConvertError
2110 * or #GIOChannelError
2112 * Reads a Unicode character from @channel.
2113 * This function cannot be called on a channel with %NULL encoding.
2115 * Return value: a #GIOStatus
2118 g_io_channel_read_unichar (GIOChannel *channel,
2122 GIOStatus status = G_IO_STATUS_NORMAL;
2124 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2125 g_return_val_if_fail (channel->encoding != NULL, G_IO_STATUS_ERROR);
2126 g_return_val_if_fail ((error == NULL) || (*error == NULL),
2128 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
2130 while (BUF_LEN (channel->encoded_read_buf) == 0 && status == G_IO_STATUS_NORMAL)
2131 status = g_io_channel_fill_buffer (channel, error);
2133 /* Only return an error if we have no data */
2135 if (BUF_LEN (USE_BUF (channel)) == 0)
2137 g_assert (status != G_IO_STATUS_NORMAL);
2139 if (status == G_IO_STATUS_EOF && BUF_LEN (channel->read_buf) > 0)
2141 g_set_error_literal (error, G_CONVERT_ERROR,
2142 G_CONVERT_ERROR_PARTIAL_INPUT,
2143 _("Leftover unconverted data in read buffer"));
2144 status = G_IO_STATUS_ERROR;
2148 *thechar = (gunichar) -1;
2153 if (status == G_IO_STATUS_ERROR)
2154 g_clear_error (error);
2157 *thechar = g_utf8_get_char (channel->encoded_read_buf->str);
2159 g_string_erase (channel->encoded_read_buf, 0,
2160 g_utf8_next_char (channel->encoded_read_buf->str)
2161 - channel->encoded_read_buf->str);
2163 return G_IO_STATUS_NORMAL;
2167 * g_io_channel_write_chars:
2168 * @channel: a #GIOChannel
2169 * @buf: a buffer to write data from
2170 * @count: the size of the buffer. If -1, the buffer
2171 * is taken to be a nul-terminated string.
2172 * @bytes_written: The number of bytes written. This can be nonzero
2173 * even if the return value is not %G_IO_STATUS_NORMAL.
2174 * If the return value is %G_IO_STATUS_NORMAL and the
2175 * channel is blocking, this will always be equal
2176 * to @count if @count >= 0.
2177 * @error: a location to return an error of type #GConvertError
2178 * or #GIOChannelError
2180 * Replacement for g_io_channel_write() with the new API.
2182 * On seekable channels with encodings other than %NULL or UTF-8, generic
2183 * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
2184 * may only be made on a channel from which data has been read in the
2185 * cases described in the documentation for g_io_channel_set_encoding ().
2187 * Return value: the status of the operation.
2190 g_io_channel_write_chars (GIOChannel *channel,
2193 gsize *bytes_written,
2197 gssize wrote_bytes = 0;
2199 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2200 g_return_val_if_fail ((error == NULL) || (*error == NULL),
2202 g_return_val_if_fail (channel->is_writeable, G_IO_STATUS_ERROR);
2204 if ((count < 0) && buf)
2205 count = strlen (buf);
2211 return G_IO_STATUS_NORMAL;
2214 g_return_val_if_fail (buf != NULL, G_IO_STATUS_ERROR);
2215 g_return_val_if_fail (count > 0, G_IO_STATUS_ERROR);
2217 /* Raw write case */
2219 if (!channel->use_buffer)
2223 g_assert (!channel->write_buf || channel->write_buf->len == 0);
2224 g_assert (channel->partial_write_buf[0] == '\0');
2226 status = channel->funcs->io_write (channel, buf, count, &tmp_bytes, error);
2229 *bytes_written = tmp_bytes;
2236 if (channel->is_seekable && (( BUF_LEN (channel->read_buf) > 0)
2237 || (BUF_LEN (channel->encoded_read_buf) > 0)))
2239 if (channel->do_encode && BUF_LEN (channel->encoded_read_buf) > 0)
2241 g_warning("Mixed reading and writing not allowed on encoded files");
2242 return G_IO_STATUS_ERROR;
2244 status = g_io_channel_seek_position (channel, 0, G_SEEK_CUR, error);
2245 if (status != G_IO_STATUS_NORMAL)
2253 if (!channel->write_buf)
2254 channel->write_buf = g_string_sized_new (channel->buf_size);
2256 while (wrote_bytes < count)
2260 /* If the buffer is full, try a write immediately. In
2261 * the nonblocking case, this prevents the user from
2262 * writing just a little bit to the buffer every time
2263 * and never receiving an EAGAIN.
2266 if (channel->write_buf->len >= channel->buf_size - MAX_CHAR_SIZE)
2268 gsize did_write = 0, this_time;
2272 status = channel->funcs->io_write (channel, channel->write_buf->str
2273 + did_write, channel->write_buf->len
2274 - did_write, &this_time, error);
2275 did_write += this_time;
2277 while (status == G_IO_STATUS_NORMAL &&
2278 did_write < MIN (channel->write_buf->len, MAX_CHAR_SIZE));
2280 g_string_erase (channel->write_buf, 0, did_write);
2282 if (status != G_IO_STATUS_NORMAL)
2284 if (status == G_IO_STATUS_AGAIN && wrote_bytes > 0)
2285 status = G_IO_STATUS_NORMAL;
2287 *bytes_written = wrote_bytes;
2292 space_in_buf = MAX (channel->buf_size, channel->write_buf->allocated_len - 1)
2293 - channel->write_buf->len; /* 1 for NULL */
2295 /* This is only true because g_io_channel_set_buffer_size ()
2296 * ensures that channel->buf_size >= MAX_CHAR_SIZE.
2298 g_assert (space_in_buf >= MAX_CHAR_SIZE);
2300 if (!channel->encoding)
2302 gssize write_this = MIN (space_in_buf, count - wrote_bytes);
2304 g_string_append_len (channel->write_buf, buf, write_this);
2306 wrote_bytes += write_this;
2310 const gchar *from_buf;
2311 gsize from_buf_len, from_buf_old_len, left_len;
2315 if (channel->partial_write_buf[0] != '\0')
2317 g_assert (wrote_bytes == 0);
2319 from_buf = channel->partial_write_buf;
2320 from_buf_old_len = strlen (channel->partial_write_buf);
2321 g_assert (from_buf_old_len > 0);
2322 from_buf_len = MIN (6, from_buf_old_len + count);
2324 memcpy (channel->partial_write_buf + from_buf_old_len, buf,
2325 from_buf_len - from_buf_old_len);
2330 from_buf_len = count - wrote_bytes;
2331 from_buf_old_len = 0;
2336 if (!channel->do_encode) /* UTF-8 encoding */
2338 const gchar *badchar;
2339 gsize try_len = MIN (from_buf_len, space_in_buf);
2341 /* UTF-8, just validate, emulate g_iconv */
2343 if (!g_utf8_validate (from_buf, try_len, &badchar))
2346 gsize incomplete_len = from_buf + try_len - badchar;
2348 left_len = from_buf + from_buf_len - badchar;
2350 try_char = g_utf8_get_char_validated (badchar, incomplete_len);
2355 g_assert (incomplete_len < 6);
2356 if (try_len == from_buf_len)
2368 g_warning ("Invalid UTF-8 passed to g_io_channel_write_chars().");
2369 /* FIXME bail here? */
2374 g_assert_not_reached ();
2376 errnum = 0; /* Don't confunse the compiler */
2383 left_len = from_buf_len - try_len;
2386 g_string_append_len (channel->write_buf, from_buf,
2387 from_buf_len - left_len);
2388 from_buf += from_buf_len - left_len;
2394 left_len = from_buf_len;
2395 g_string_set_size (channel->write_buf, channel->write_buf->len
2397 outbuf = channel->write_buf->str + channel->write_buf->len
2399 err = g_iconv (channel->write_cd, (gchar **) &from_buf, &left_len,
2400 &outbuf, &space_in_buf);
2402 g_string_truncate (channel->write_buf, channel->write_buf->len
2406 if (err == (gsize) -1)
2411 g_assert (left_len < 6);
2413 if (from_buf_old_len == 0)
2415 /* Not from partial_write_buf */
2417 memcpy (channel->partial_write_buf, from_buf, left_len);
2418 channel->partial_write_buf[left_len] = '\0';
2420 *bytes_written = count;
2421 return G_IO_STATUS_NORMAL;
2424 /* Working in partial_write_buf */
2426 if (left_len == from_buf_len)
2428 /* Didn't convert anything, must still have
2429 * less than a full character
2432 g_assert (count == from_buf_len - from_buf_old_len);
2434 channel->partial_write_buf[from_buf_len] = '\0';
2437 *bytes_written = count;
2439 return G_IO_STATUS_NORMAL;
2442 g_assert (from_buf_len - left_len >= from_buf_old_len);
2444 /* We converted all the old data. This is fine */
2448 if (from_buf_len == left_len)
2450 /* Nothing was written, add enough space for
2451 * at least one character.
2453 space_in_buf += MAX_CHAR_SIZE;
2458 g_set_error_literal (error, G_CONVERT_ERROR,
2459 G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
2460 _("Invalid byte sequence in conversion input"));
2461 if (from_buf_old_len > 0 && from_buf_len == left_len)
2462 g_warning ("Illegal sequence due to partial character "
2463 "at the end of a previous write.\n");
2465 wrote_bytes += from_buf_len - left_len - from_buf_old_len;
2467 *bytes_written = wrote_bytes;
2468 channel->partial_write_buf[0] = '\0';
2469 return G_IO_STATUS_ERROR;
2471 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
2472 _("Error during conversion: %s"), g_strerror (errnum));
2473 if (from_buf_len >= left_len + from_buf_old_len)
2474 wrote_bytes += from_buf_len - left_len - from_buf_old_len;
2476 *bytes_written = wrote_bytes;
2477 channel->partial_write_buf[0] = '\0';
2478 return G_IO_STATUS_ERROR;
2482 g_assert (from_buf_len - left_len >= from_buf_old_len);
2484 wrote_bytes += from_buf_len - left_len - from_buf_old_len;
2486 if (from_buf_old_len > 0)
2488 /* We were working in partial_write_buf */
2490 buf += from_buf_len - left_len - from_buf_old_len;
2491 channel->partial_write_buf[0] = '\0';
2499 *bytes_written = count;
2501 return G_IO_STATUS_NORMAL;
2505 * g_io_channel_write_unichar:
2506 * @channel: a #GIOChannel
2507 * @thechar: a character
2508 * @error: location to return an error of type #GConvertError
2509 * or #GIOChannelError
2511 * Writes a Unicode character to @channel.
2512 * This function cannot be called on a channel with %NULL encoding.
2514 * Return value: a #GIOStatus
2517 g_io_channel_write_unichar (GIOChannel *channel,
2522 gchar static_buf[6];
2523 gsize char_len, wrote_len;
2525 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2526 g_return_val_if_fail (channel->encoding != NULL, G_IO_STATUS_ERROR);
2527 g_return_val_if_fail ((error == NULL) || (*error == NULL),
2529 g_return_val_if_fail (channel->is_writeable, G_IO_STATUS_ERROR);
2531 char_len = g_unichar_to_utf8 (thechar, static_buf);
2533 if (channel->partial_write_buf[0] != '\0')
2535 g_warning ("Partial charater written before writing unichar.\n");
2536 channel->partial_write_buf[0] = '\0';
2539 status = g_io_channel_write_chars (channel, static_buf,
2540 char_len, &wrote_len, error);
2542 /* We validate UTF-8, so we can't get a partial write */
2544 g_assert (wrote_len == char_len || status != G_IO_STATUS_NORMAL);
2550 * g_io_channel_error_quark:
2552 * Return value: the quark used as %G_IO_CHANNEL_ERROR
2555 * G_IO_CHANNEL_ERROR:
2557 * Error domain for #GIOChannel operations. Errors in this domain will
2558 * be from the #GIOChannelError enumeration. See #GError for
2559 * information on error domains.
2563 * @G_IO_CHANNEL_ERROR_FBIG: File too large.
2564 * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
2565 * @G_IO_CHANNEL_ERROR_IO: IO error.
2566 * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
2567 * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
2568 * @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
2569 * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
2570 * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
2571 * @G_IO_CHANNEL_ERROR_FAILED: Some other error.
2573 * Error codes returned by #GIOChannel operations.
2576 g_io_channel_error_quark (void)
2578 return g_quark_from_static_string ("g-io-channel-error-quark");