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.1 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, see <http://www.gnu.org/licenses/>.
22 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
23 * file for a list of people on the GLib Team. See the ChangeLog
24 * files for a list of changes. These files are distributed with
25 * GLib at ftp://ftp.gtk.org/pub/gtk/.
37 #include "giochannel.h"
39 #include "gstrfuncs.h"
40 #include "gtestutils.h"
47 * @short_description: portable support for using files, pipes and sockets
48 * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(),
51 * The #GIOChannel data type aims to provide a portable method for
52 * using file descriptors, pipes, and sockets, and integrating them
53 * into the [main event loop][glib-The-Main-Event-Loop]. Currently,
54 * full support is available on UNIX platforms, support for Windows
55 * is only partially complete.
57 * To create a new #GIOChannel on UNIX systems use
58 * g_io_channel_unix_new(). This works for plain file descriptors,
59 * pipes and sockets. Alternatively, a channel can be created for a
60 * file in a system independent manner using g_io_channel_new_file().
62 * Once a #GIOChannel has been created, it can be used in a generic
63 * manner with the functions g_io_channel_read_chars(),
64 * g_io_channel_write_chars(), g_io_channel_seek_position(), and
65 * g_io_channel_shutdown().
67 * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop],
68 * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which
69 * events you are interested in on the #GIOChannel, and provide a
70 * function to be called whenever these events occur.
72 * #GIOChannel instances are created with an initial reference count of 1.
73 * g_io_channel_ref() and g_io_channel_unref() can be used to
74 * increment or decrement the reference count respectively. When the
75 * reference count falls to 0, the #GIOChannel is freed. (Though it
76 * isn't closed automatically, unless it was created using
77 * g_io_channel_new_file().) Using g_io_add_watch() or
78 * g_io_add_watch_full() increments a channel's reference count.
80 * The new functions g_io_channel_read_chars(),
81 * g_io_channel_read_line(), g_io_channel_read_line_string(),
82 * g_io_channel_read_to_end(), g_io_channel_write_chars(),
83 * g_io_channel_seek_position(), and g_io_channel_flush() should not be
84 * mixed with the deprecated functions g_io_channel_read(),
85 * g_io_channel_write(), and g_io_channel_seek() on the same channel.
91 * A data structure representing an IO Channel. The fields should be
92 * considered private and should only be accessed with the following
98 * @io_read: reads raw bytes from the channel. This is called from
99 * various functions such as g_io_channel_read_chars() to
100 * read raw bytes from the channel. Encoding and buffering
101 * issues are dealt with at a higher level.
102 * @io_write: writes raw bytes to the channel. This is called from
103 * various functions such as g_io_channel_write_chars() to
104 * write raw bytes to the channel. Encoding and buffering
105 * issues are dealt with at a higher level.
106 * @io_seek: (optional) seeks the channel. This is called from
107 * g_io_channel_seek() on channels that support it.
108 * @io_close: closes the channel. This is called from
109 * g_io_channel_close() after flushing the buffers.
110 * @io_create_watch: creates a watch on the channel. This call
111 * corresponds directly to g_io_create_watch().
112 * @io_free: called from g_io_channel_unref() when the channel needs to
113 * be freed. This function must free the memory associated
114 * with the channel, including freeing the #GIOChannel
115 * structure itself. The channel buffers have been flushed
116 * and possibly @io_close has been called by the time this
117 * function is called.
118 * @io_set_flags: sets the #GIOFlags on the channel. This is called
119 * from g_io_channel_set_flags() with all flags except
120 * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked
122 * @io_get_flags: gets the #GIOFlags for the channel. This function
123 * need only return the %G_IO_FLAG_APPEND and
124 * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags()
125 * automatically adds the others as appropriate.
127 * A table of functions used to handle different types of #GIOChannel
133 * @G_IO_STATUS_ERROR: An error occurred.
134 * @G_IO_STATUS_NORMAL: Success.
135 * @G_IO_STATUS_EOF: End of file.
136 * @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
138 * Statuses returned by most of the #GIOFuncs functions.
143 * @G_IO_ERROR_NONE: no error
144 * @G_IO_ERROR_AGAIN: an EAGAIN error occurred
145 * @G_IO_ERROR_INVAL: an EINVAL error occurred
146 * @G_IO_ERROR_UNKNOWN: another error occurred
148 * #GIOError is only used by the deprecated functions
149 * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
152 #define G_IO_NICE_BUF_SIZE 1024
154 /* This needs to be as wide as the largest character in any possible encoding */
155 #define MAX_CHAR_SIZE 10
157 /* Some simplifying macros, which reduce the need to worry whether the
158 * buffers have been allocated. These also make USE_BUF () an lvalue,
159 * which is used in g_io_channel_read_to_end ().
161 #define USE_BUF(channel) ((channel)->encoding ? (channel)->encoded_read_buf \
162 : (channel)->read_buf)
163 #define BUF_LEN(string) ((string) ? (string)->len : 0)
165 static GIOError g_io_error_get_from_g_error (GIOStatus status,
167 static void g_io_channel_purge (GIOChannel *channel);
168 static GIOStatus g_io_channel_fill_buffer (GIOChannel *channel,
170 static GIOStatus g_io_channel_read_line_backend (GIOChannel *channel,
172 gsize *terminator_pos,
177 * @channel: a #GIOChannel
179 * Initializes a #GIOChannel struct.
181 * This is called by each of the above functions when creating a
182 * #GIOChannel, and so is not often needed by the application
183 * programmer (unless you are creating a new type of #GIOChannel).
186 g_io_channel_init (GIOChannel *channel)
188 channel->ref_count = 1;
189 channel->encoding = g_strdup ("UTF-8");
190 channel->line_term = NULL;
191 channel->line_term_len = 0;
192 channel->buf_size = G_IO_NICE_BUF_SIZE;
193 channel->read_cd = (GIConv) -1;
194 channel->write_cd = (GIConv) -1;
195 channel->read_buf = NULL; /* Lazy allocate buffers */
196 channel->encoded_read_buf = NULL;
197 channel->write_buf = NULL;
198 channel->partial_write_buf[0] = '\0';
199 channel->use_buffer = TRUE;
200 channel->do_encode = FALSE;
201 channel->close_on_unref = FALSE;
206 * @channel: a #GIOChannel
208 * Increments the reference count of a #GIOChannel.
210 * Returns: the @channel that was passed in (since 2.6)
213 g_io_channel_ref (GIOChannel *channel)
215 g_return_val_if_fail (channel != NULL, NULL);
217 g_atomic_int_inc (&channel->ref_count);
223 * g_io_channel_unref:
224 * @channel: a #GIOChannel
226 * Decrements the reference count of a #GIOChannel.
229 g_io_channel_unref (GIOChannel *channel)
233 g_return_if_fail (channel != NULL);
235 is_zero = g_atomic_int_dec_and_test (&channel->ref_count);
237 if (G_UNLIKELY (is_zero))
239 if (channel->close_on_unref)
240 g_io_channel_shutdown (channel, TRUE, NULL);
242 g_io_channel_purge (channel);
243 g_free (channel->encoding);
244 if (channel->read_cd != (GIConv) -1)
245 g_iconv_close (channel->read_cd);
246 if (channel->write_cd != (GIConv) -1)
247 g_iconv_close (channel->write_cd);
248 g_free (channel->line_term);
249 if (channel->read_buf)
250 g_string_free (channel->read_buf, TRUE);
251 if (channel->write_buf)
252 g_string_free (channel->write_buf, TRUE);
253 if (channel->encoded_read_buf)
254 g_string_free (channel->encoded_read_buf, TRUE);
255 channel->funcs->io_free (channel);
260 g_io_error_get_from_g_error (GIOStatus status,
265 case G_IO_STATUS_NORMAL:
266 case G_IO_STATUS_EOF:
267 return G_IO_ERROR_NONE;
268 case G_IO_STATUS_AGAIN:
269 return G_IO_ERROR_AGAIN;
270 case G_IO_STATUS_ERROR:
271 g_return_val_if_fail (err != NULL, G_IO_ERROR_UNKNOWN);
273 if (err->domain != G_IO_CHANNEL_ERROR)
274 return G_IO_ERROR_UNKNOWN;
277 case G_IO_CHANNEL_ERROR_INVAL:
278 return G_IO_ERROR_INVAL;
280 return G_IO_ERROR_UNKNOWN;
283 g_assert_not_reached ();
289 * @channel: a #GIOChannel
290 * @buf: a buffer to read the data into (which should be at least
292 * @count: the number of bytes to read from the #GIOChannel
293 * @bytes_read: returns the number of bytes actually read
295 * Reads data from a #GIOChannel.
297 * Returns: %G_IO_ERROR_NONE if the operation was successful.
299 * Deprecated:2.2: Use g_io_channel_read_chars() instead.
302 g_io_channel_read (GIOChannel *channel,
311 g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
312 g_return_val_if_fail (bytes_read != NULL, G_IO_ERROR_UNKNOWN);
318 return G_IO_ERROR_NONE;
321 g_return_val_if_fail (buf != NULL, G_IO_ERROR_UNKNOWN);
323 status = channel->funcs->io_read (channel, buf, count, bytes_read, &err);
325 error = g_io_error_get_from_g_error (status, err);
334 * g_io_channel_write:
335 * @channel: a #GIOChannel
336 * @buf: the buffer containing the data to write
337 * @count: the number of bytes to write
338 * @bytes_written: the number of bytes actually written
340 * Writes data to a #GIOChannel.
342 * Returns: %G_IO_ERROR_NONE if the operation was successful.
344 * Deprecated:2.2: Use g_io_channel_write_chars() instead.
347 g_io_channel_write (GIOChannel *channel,
350 gsize *bytes_written)
356 g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
357 g_return_val_if_fail (bytes_written != NULL, G_IO_ERROR_UNKNOWN);
359 status = channel->funcs->io_write (channel, buf, count, bytes_written, &err);
361 error = g_io_error_get_from_g_error (status, err);
371 * @channel: a #GIOChannel
372 * @offset: an offset, in bytes, which is added to the position specified
374 * @type: the position in the file, which can be %G_SEEK_CUR (the current
375 * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END
376 * (the end of the file)
378 * Sets the current position in the #GIOChannel, similar to the standard
379 * library function fseek().
381 * Returns: %G_IO_ERROR_NONE if the operation was successful.
383 * Deprecated:2.2: Use g_io_channel_seek_position() instead.
386 g_io_channel_seek (GIOChannel *channel,
394 g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN);
395 g_return_val_if_fail (channel->is_seekable, G_IO_ERROR_UNKNOWN);
404 g_warning ("g_io_channel_seek: unknown seek type");
405 return G_IO_ERROR_UNKNOWN;
408 status = channel->funcs->io_seek (channel, offset, type, &err);
410 error = g_io_error_get_from_g_error (status, err);
418 /* The function g_io_channel_new_file() is prototyped in both
419 * giounix.c and giowin32.c, so we stick its documentation here.
423 * g_io_channel_new_file:
424 * @filename: (type filename): A string containing the name of a file
425 * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
426 * the same meaning as in fopen()
427 * @error: A location to return an error of type %G_FILE_ERROR
429 * Open a file @filename as a #GIOChannel using mode @mode. This
430 * channel will be closed when the last reference to it is dropped,
431 * so there is no need to call g_io_channel_close() (though doing
432 * so will not cause problems, as long as no attempt is made to
433 * access the channel after it is closed).
435 * Returns: A #GIOChannel on success, %NULL on failure.
439 * g_io_channel_close:
440 * @channel: A #GIOChannel
442 * Close an IO channel. Any pending data to be written will be
443 * flushed, ignoring errors. The channel will not be freed until the
444 * last reference is dropped using g_io_channel_unref().
446 * Deprecated:2.2: Use g_io_channel_shutdown() instead.
449 g_io_channel_close (GIOChannel *channel)
453 g_return_if_fail (channel != NULL);
455 g_io_channel_purge (channel);
457 channel->funcs->io_close (channel, &err);
460 { /* No way to return the error */
461 g_warning ("Error closing channel: %s", err->message);
465 channel->close_on_unref = FALSE; /* Because we already did */
466 channel->is_readable = FALSE;
467 channel->is_writeable = FALSE;
468 channel->is_seekable = FALSE;
472 * g_io_channel_shutdown:
473 * @channel: a #GIOChannel
474 * @flush: if %TRUE, flush pending
475 * @err: location to store a #GIOChannelError
477 * Close an IO channel. Any pending data to be written will be
478 * flushed if @flush is %TRUE. The channel will not be freed until the
479 * last reference is dropped using g_io_channel_unref().
481 * Returns: the status of the operation.
484 g_io_channel_shutdown (GIOChannel *channel,
488 GIOStatus status, result;
489 GError *tmperr = NULL;
491 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
492 g_return_val_if_fail (err == NULL || *err == NULL, G_IO_STATUS_ERROR);
494 if (channel->write_buf && channel->write_buf->len > 0)
500 /* Set the channel to blocking, to avoid a busy loop
502 flags = g_io_channel_get_flags (channel);
503 /* Ignore any errors here, they're irrelevant */
504 g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);
506 result = g_io_channel_flush (channel, &tmperr);
509 result = G_IO_STATUS_NORMAL;
511 g_string_truncate(channel->write_buf, 0);
514 result = G_IO_STATUS_NORMAL;
516 if (channel->partial_write_buf[0] != '\0')
519 g_warning ("Partial character at end of write buffer not flushed.");
520 channel->partial_write_buf[0] = '\0';
523 status = channel->funcs->io_close (channel, err);
525 channel->close_on_unref = FALSE; /* Because we already did */
526 channel->is_readable = FALSE;
527 channel->is_writeable = FALSE;
528 channel->is_seekable = FALSE;
530 if (status != G_IO_STATUS_NORMAL)
532 g_clear_error (&tmperr);
535 else if (result != G_IO_STATUS_NORMAL)
537 g_propagate_error (err, tmperr);
541 return G_IO_STATUS_NORMAL;
544 /* This function is used for the final flush on close or unref */
546 g_io_channel_purge (GIOChannel *channel)
549 GIOStatus status G_GNUC_UNUSED;
551 g_return_if_fail (channel != NULL);
553 if (channel->write_buf && channel->write_buf->len > 0)
557 /* Set the channel to blocking, to avoid a busy loop
559 flags = g_io_channel_get_flags (channel);
560 g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL);
562 status = g_io_channel_flush (channel, &err);
565 { /* No way to return the error */
566 g_warning ("Error flushing string: %s", err->message);
571 /* Flush these in case anyone tries to close without unrefing */
573 if (channel->read_buf)
574 g_string_truncate (channel->read_buf, 0);
575 if (channel->write_buf)
576 g_string_truncate (channel->write_buf, 0);
577 if (channel->encoding)
579 if (channel->encoded_read_buf)
580 g_string_truncate (channel->encoded_read_buf, 0);
582 if (channel->partial_write_buf[0] != '\0')
584 g_warning ("Partial character at end of write buffer not flushed.");
585 channel->partial_write_buf[0] = '\0';
592 * @channel: a #GIOChannel to watch
593 * @condition: conditions to watch for
595 * Creates a #GSource that's dispatched when @condition is met for the
596 * given @channel. For example, if condition is #G_IO_IN, the source will
597 * be dispatched when there's data available for reading.
599 * The callback function invoked by the #GSource should be added with
600 * g_source_set_callback(), but it has type #GIOFunc (not #GSourceFunc).
602 * g_io_add_watch() is a simpler interface to this same functionality, for
603 * the case where you want to add the source to the default main loop context
604 * at the default priority.
606 * On Windows, polling a #GSource created to watch a channel for a socket
607 * puts the socket in non-blocking mode. This is a side-effect of the
608 * implementation and unavoidable.
610 * Returns: a new #GSource
613 g_io_create_watch (GIOChannel *channel,
614 GIOCondition condition)
616 g_return_val_if_fail (channel != NULL, NULL);
618 return channel->funcs->io_create_watch (channel, condition);
622 * g_io_add_watch_full: (rename-to g_io_add_watch)
623 * @channel: a #GIOChannel
624 * @priority: the priority of the #GIOChannel source
625 * @condition: the condition to watch for
626 * @func: the function to call when the condition is satisfied
627 * @user_data: user data to pass to @func
628 * @notify: the function to call when the source is removed
630 * Adds the #GIOChannel into the default main loop context
631 * with the given priority.
633 * This internally creates a main loop source using g_io_create_watch()
634 * and attaches it to the main loop context with g_source_attach().
635 * You can do these steps manually if you need greater control.
637 * Returns: the event source id
640 g_io_add_watch_full (GIOChannel *channel,
642 GIOCondition condition,
645 GDestroyNotify notify)
650 g_return_val_if_fail (channel != NULL, 0);
652 source = g_io_create_watch (channel, condition);
654 if (priority != G_PRIORITY_DEFAULT)
655 g_source_set_priority (source, priority);
656 g_source_set_callback (source, (GSourceFunc)func, user_data, notify);
658 id = g_source_attach (source, NULL);
659 g_source_unref (source);
666 * @channel: a #GIOChannel
667 * @condition: the condition to watch for
668 * @func: the function to call when the condition is satisfied
669 * @user_data: user data to pass to @func
671 * Adds the #GIOChannel into the default main loop context
672 * with the default priority.
674 * Returns: the event source id
678 * @source: the #GIOChannel event source
679 * @condition: the condition which has been satisfied
680 * @data: user data set in g_io_add_watch() or g_io_add_watch_full()
682 * Specifies the type of function passed to g_io_add_watch() or
683 * g_io_add_watch_full(), which is called when the requested condition
684 * on a #GIOChannel is satisfied.
686 * Returns: the function should return %FALSE if the event source
691 * @G_IO_IN: There is data to read.
692 * @G_IO_OUT: Data can be written (without blocking).
693 * @G_IO_PRI: There is urgent data to read.
694 * @G_IO_ERR: Error condition.
695 * @G_IO_HUP: Hung up (the connection has been broken, usually for
696 * pipes and sockets).
697 * @G_IO_NVAL: Invalid request. The file descriptor is not open.
699 * A bitwise combination representing a condition to watch for on an
703 g_io_add_watch (GIOChannel *channel,
704 GIOCondition condition,
708 return g_io_add_watch_full (channel, G_PRIORITY_DEFAULT, condition, func, user_data, NULL);
712 * g_io_channel_get_buffer_condition:
713 * @channel: A #GIOChannel
715 * This function returns a #GIOCondition depending on whether there
716 * is data to be read/space to write data in the internal buffers in
717 * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set.
719 * Returns: A #GIOCondition
722 g_io_channel_get_buffer_condition (GIOChannel *channel)
724 GIOCondition condition = 0;
726 if (channel->encoding)
728 if (channel->encoded_read_buf && (channel->encoded_read_buf->len > 0))
729 condition |= G_IO_IN; /* Only return if we have full characters */
733 if (channel->read_buf && (channel->read_buf->len > 0))
734 condition |= G_IO_IN;
737 if (channel->write_buf && (channel->write_buf->len < channel->buf_size))
738 condition |= G_IO_OUT;
744 * g_io_channel_error_from_errno:
745 * @en: an `errno` error number, e.g. `EINVAL`
747 * Converts an `errno` error number to a #GIOChannelError.
749 * Returns: a #GIOChannelError error number, e.g.
750 * %G_IO_CHANNEL_ERROR_INVAL.
753 g_io_channel_error_from_errno (gint en)
756 g_return_val_if_fail (en != EAGAIN, G_IO_CHANNEL_ERROR_FAILED);
763 g_warning ("Invalid file descriptor.");
764 return G_IO_CHANNEL_ERROR_FAILED;
769 g_warning ("Buffer outside valid address space.");
770 return G_IO_CHANNEL_ERROR_FAILED;
775 return G_IO_CHANNEL_ERROR_FBIG;
779 /* In general, we should catch EINTR before we get here,
780 * but close() is allowed to return EINTR by POSIX, so
781 * we need to catch it here; EINTR from close() is
782 * unrecoverable, because it's undefined whether
783 * the fd was actually closed or not, so we just return
784 * a generic error code.
787 return G_IO_CHANNEL_ERROR_FAILED;
792 return G_IO_CHANNEL_ERROR_INVAL;
797 return G_IO_CHANNEL_ERROR_IO;
802 return G_IO_CHANNEL_ERROR_ISDIR;
807 return G_IO_CHANNEL_ERROR_NOSPC;
812 return G_IO_CHANNEL_ERROR_NXIO;
816 #if EOVERFLOW != EFBIG
818 return G_IO_CHANNEL_ERROR_OVERFLOW;
824 return G_IO_CHANNEL_ERROR_PIPE;
828 return G_IO_CHANNEL_ERROR_FAILED;
833 * g_io_channel_set_buffer_size:
834 * @channel: a #GIOChannel
835 * @size: the size of the buffer, or 0 to let GLib pick a good size
837 * Sets the buffer size.
840 g_io_channel_set_buffer_size (GIOChannel *channel,
843 g_return_if_fail (channel != NULL);
846 size = G_IO_NICE_BUF_SIZE;
848 if (size < MAX_CHAR_SIZE)
849 size = MAX_CHAR_SIZE;
851 channel->buf_size = size;
855 * g_io_channel_get_buffer_size:
856 * @channel: a #GIOChannel
858 * Gets the buffer size.
860 * Returns: the size of the buffer.
863 g_io_channel_get_buffer_size (GIOChannel *channel)
865 g_return_val_if_fail (channel != NULL, 0);
867 return channel->buf_size;
871 * g_io_channel_set_line_term:
872 * @channel: a #GIOChannel
873 * @line_term: (nullable): The line termination string. Use %NULL for
874 * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0",
875 * and the Unicode paragraph separator. Autodetection should not be
876 * used for anything other than file-based channels.
877 * @length: The length of the termination string. If -1 is passed, the
878 * string is assumed to be nul-terminated. This option allows
879 * termination strings with embedded nuls.
881 * This sets the string that #GIOChannel uses to determine
882 * where in the file a line break occurs.
885 g_io_channel_set_line_term (GIOChannel *channel,
886 const gchar *line_term,
889 guint length_unsigned;
891 g_return_if_fail (channel != NULL);
892 g_return_if_fail (line_term == NULL || length != 0); /* Disallow "" */
894 if (line_term == NULL)
896 else if (length >= 0)
897 length_unsigned = (guint) length;
900 /* FIXME: We’re constrained by line_term_len being a guint here */
901 gsize length_size = strlen (line_term);
902 g_return_if_fail (length_size <= G_MAXUINT);
903 length_unsigned = (guint) length_size;
906 g_free (channel->line_term);
907 channel->line_term = line_term ? g_memdup2 (line_term, length_unsigned) : NULL;
908 channel->line_term_len = length_unsigned;
912 * g_io_channel_get_line_term:
913 * @channel: a #GIOChannel
914 * @length: a location to return the length of the line terminator
916 * This returns the string that #GIOChannel uses to determine
917 * where in the file a line break occurs. A value of %NULL
918 * indicates autodetection.
920 * Returns: The line termination string. This value
921 * is owned by GLib and must not be freed.
924 g_io_channel_get_line_term (GIOChannel *channel,
927 g_return_val_if_fail (channel != NULL, NULL);
930 *length = channel->line_term_len;
932 return channel->line_term;
936 * g_io_channel_set_flags:
937 * @channel: a #GIOChannel
938 * @flags: the flags to set on the IO channel
939 * @error: A location to return an error of type #GIOChannelError
941 * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
943 * Returns: the status of the operation.
947 * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
948 * (see the documentation of the UNIX open() syscall)
949 * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
950 * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
952 * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
953 * This flag cannot be changed.
954 * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable.
955 * This flag cannot be changed.
956 * @G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
957 * that existed before the spelling was fixed in GLib 2.30. It is kept
958 * here for compatibility reasons. Deprecated since 2.30
959 * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
960 * i.e. that g_io_channel_seek_position() can be used on it.
961 * This flag cannot be changed.
962 * @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
963 * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
964 * g_io_channel_get_flags()
965 * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
966 * with g_io_channel_set_flags()
968 * Specifies properties of a #GIOChannel. Some of the flags can only be
969 * read with g_io_channel_get_flags(), but not changed with
970 * g_io_channel_set_flags().
973 g_io_channel_set_flags (GIOChannel *channel,
977 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
978 g_return_val_if_fail ((error == NULL) || (*error == NULL),
981 return (*channel->funcs->io_set_flags) (channel,
982 flags & G_IO_FLAG_SET_MASK,
987 * g_io_channel_get_flags:
988 * @channel: a #GIOChannel
990 * Gets the current flags for a #GIOChannel, including read-only
991 * flags such as %G_IO_FLAG_IS_READABLE.
993 * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE
994 * are cached for internal use by the channel when it is created.
995 * If they should change at some later point (e.g. partial shutdown
996 * of a socket with the UNIX shutdown() function), the user
997 * should immediately call g_io_channel_get_flags() to update
998 * the internal values of these flags.
1000 * Returns: the flags which are set on the channel
1003 g_io_channel_get_flags (GIOChannel *channel)
1007 g_return_val_if_fail (channel != NULL, 0);
1009 flags = (* channel->funcs->io_get_flags) (channel);
1011 /* Cross implementation code */
1013 if (channel->is_seekable)
1014 flags |= G_IO_FLAG_IS_SEEKABLE;
1015 if (channel->is_readable)
1016 flags |= G_IO_FLAG_IS_READABLE;
1017 if (channel->is_writeable)
1018 flags |= G_IO_FLAG_IS_WRITABLE;
1024 * g_io_channel_set_close_on_unref:
1025 * @channel: a #GIOChannel
1026 * @do_close: Whether to close the channel on the final unref of
1027 * the GIOChannel data structure.
1029 * Whether to close the channel on the final unref of the #GIOChannel
1030 * data structure. The default value of this is %TRUE for channels
1031 * created by g_io_channel_new_file (), and %FALSE for all other channels.
1033 * Setting this flag to %TRUE for a channel you have already closed
1034 * can cause problems when the final reference to the #GIOChannel is dropped.
1037 g_io_channel_set_close_on_unref (GIOChannel *channel,
1040 g_return_if_fail (channel != NULL);
1042 channel->close_on_unref = do_close;
1046 * g_io_channel_get_close_on_unref:
1047 * @channel: a #GIOChannel.
1049 * Returns whether the file/socket/whatever associated with @channel
1050 * will be closed when @channel receives its final unref and is
1051 * destroyed. The default value of this is %TRUE for channels created
1052 * by g_io_channel_new_file (), and %FALSE for all other channels.
1054 * Returns: %TRUE if the channel will be closed, %FALSE otherwise.
1057 g_io_channel_get_close_on_unref (GIOChannel *channel)
1059 g_return_val_if_fail (channel != NULL, FALSE);
1061 return channel->close_on_unref;
1065 * g_io_channel_seek_position:
1066 * @channel: a #GIOChannel
1067 * @offset: The offset in bytes from the position specified by @type
1068 * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those
1069 * cases where a call to g_io_channel_set_encoding ()
1070 * is allowed. See the documentation for
1071 * g_io_channel_set_encoding () for details.
1072 * @error: A location to return an error of type #GIOChannelError
1074 * Replacement for g_io_channel_seek() with the new API.
1076 * Returns: the status of the operation.
1080 * @G_SEEK_CUR: the current position in the file.
1081 * @G_SEEK_SET: the start of the file.
1082 * @G_SEEK_END: the end of the file.
1084 * An enumeration specifying the base position for a
1085 * g_io_channel_seek_position() operation.
1088 g_io_channel_seek_position (GIOChannel *channel,
1095 /* For files, only one of the read and write buffers can contain data.
1096 * For sockets, both can contain data.
1099 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1100 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1102 g_return_val_if_fail (channel->is_seekable, G_IO_STATUS_ERROR);
1106 case G_SEEK_CUR: /* The user is seeking relative to the head of the buffer */
1107 if (channel->use_buffer)
1109 if (channel->do_encode && channel->encoded_read_buf
1110 && channel->encoded_read_buf->len > 0)
1112 g_warning ("Seek type G_SEEK_CUR not allowed for this"
1113 " channel's encoding.");
1114 return G_IO_STATUS_ERROR;
1116 if (channel->read_buf)
1117 offset -= channel->read_buf->len;
1118 if (channel->encoded_read_buf)
1120 g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
1122 /* If there's anything here, it's because the encoding is UTF-8,
1123 * so we can just subtract the buffer length, the same as for
1124 * the unencoded data.
1127 offset -= channel->encoded_read_buf->len;
1135 g_warning ("g_io_channel_seek_position: unknown seek type");
1136 return G_IO_STATUS_ERROR;
1139 if (channel->use_buffer)
1141 status = g_io_channel_flush (channel, error);
1142 if (status != G_IO_STATUS_NORMAL)
1146 status = channel->funcs->io_seek (channel, offset, type, error);
1148 if ((status == G_IO_STATUS_NORMAL) && (channel->use_buffer))
1150 if (channel->read_buf)
1151 g_string_truncate (channel->read_buf, 0);
1153 /* Conversion state no longer matches position in file */
1154 if (channel->read_cd != (GIConv) -1)
1155 g_iconv (channel->read_cd, NULL, NULL, NULL, NULL);
1156 if (channel->write_cd != (GIConv) -1)
1157 g_iconv (channel->write_cd, NULL, NULL, NULL, NULL);
1159 if (channel->encoded_read_buf)
1161 g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode);
1162 g_string_truncate (channel->encoded_read_buf, 0);
1165 if (channel->partial_write_buf[0] != '\0')
1167 g_warning ("Partial character at end of write buffer not flushed.");
1168 channel->partial_write_buf[0] = '\0';
1176 * g_io_channel_flush:
1177 * @channel: a #GIOChannel
1178 * @error: location to store an error of type #GIOChannelError
1180 * Flushes the write buffer for the GIOChannel.
1182 * Returns: the status of the operation: One of
1183 * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
1184 * #G_IO_STATUS_ERROR.
1187 g_io_channel_flush (GIOChannel *channel,
1191 gsize this_time = 1, bytes_written = 0;
1193 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1194 g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);
1196 if (channel->write_buf == NULL || channel->write_buf->len == 0)
1197 return G_IO_STATUS_NORMAL;
1201 g_assert (this_time > 0);
1203 status = channel->funcs->io_write (channel,
1204 channel->write_buf->str + bytes_written,
1205 channel->write_buf->len - bytes_written,
1207 bytes_written += this_time;
1209 while ((bytes_written < channel->write_buf->len)
1210 && (status == G_IO_STATUS_NORMAL));
1212 g_string_erase (channel->write_buf, 0, bytes_written);
1218 * g_io_channel_set_buffered:
1219 * @channel: a #GIOChannel
1220 * @buffered: whether to set the channel buffered or unbuffered
1222 * The buffering state can only be set if the channel's encoding
1223 * is %NULL. For any other encoding, the channel must be buffered.
1225 * A buffered channel can only be set unbuffered if the channel's
1226 * internal buffers have been flushed. Newly created channels or
1227 * channels which have returned %G_IO_STATUS_EOF
1228 * not require such a flush. For write-only channels, a call to
1229 * g_io_channel_flush () is sufficient. For all other channels,
1230 * the buffers may be flushed by a call to g_io_channel_seek_position ().
1231 * This includes the possibility of seeking with seek type %G_SEEK_CUR
1232 * and an offset of zero. Note that this means that socket-based
1233 * channels cannot be set unbuffered once they have had data
1236 * On unbuffered channels, it is safe to mix read and write
1237 * calls from the new and old APIs, if this is necessary for
1238 * maintaining old code.
1240 * The default state of the channel is buffered.
1243 g_io_channel_set_buffered (GIOChannel *channel,
1246 g_return_if_fail (channel != NULL);
1248 if (channel->encoding != NULL)
1250 g_warning ("Need to have NULL encoding to set the buffering state of the "
1255 g_return_if_fail (!channel->read_buf || channel->read_buf->len == 0);
1256 g_return_if_fail (!channel->write_buf || channel->write_buf->len == 0);
1258 channel->use_buffer = buffered;
1262 * g_io_channel_get_buffered:
1263 * @channel: a #GIOChannel
1265 * Returns whether @channel is buffered.
1267 * Return Value: %TRUE if the @channel is buffered.
1270 g_io_channel_get_buffered (GIOChannel *channel)
1272 g_return_val_if_fail (channel != NULL, FALSE);
1274 return channel->use_buffer;
1278 * g_io_channel_set_encoding:
1279 * @channel: a #GIOChannel
1280 * @encoding: (nullable): the encoding type
1281 * @error: location to store an error of type #GConvertError
1283 * Sets the encoding for the input/output of the channel.
1284 * The internal encoding is always UTF-8. The default encoding
1285 * for the external file is UTF-8.
1287 * The encoding %NULL is safe to use with binary data.
1289 * The encoding can only be set if one of the following conditions
1292 * - The channel was just created, and has not been written to or read from yet.
1294 * - The channel is write-only.
1296 * - The channel is a file, and the file pointer was just repositioned
1297 * by a call to g_io_channel_seek_position(). (This flushes all the
1298 * internal buffers.)
1300 * - The current encoding is %NULL or UTF-8.
1302 * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF
1303 * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
1305 * - One of the functions g_io_channel_read_chars() or
1306 * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
1307 * %G_IO_STATUS_ERROR. This may be useful in the case of
1308 * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
1309 * Returning one of these statuses from g_io_channel_read_line(),
1310 * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
1311 * does not guarantee that the encoding can be changed.
1313 * Channels which do not meet one of the above conditions cannot call
1314 * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
1315 * they are "seekable", cannot call g_io_channel_write_chars() after
1316 * calling one of the API "read" functions.
1318 * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set
1321 g_io_channel_set_encoding (GIOChannel *channel,
1322 const gchar *encoding,
1325 GIConv read_cd, write_cd;
1326 #ifndef G_DISABLE_ASSERT
1327 gboolean did_encode;
1330 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1331 g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);
1333 /* Make sure the encoded buffers are empty */
1335 g_return_val_if_fail (!channel->do_encode || !channel->encoded_read_buf ||
1336 channel->encoded_read_buf->len == 0, G_IO_STATUS_ERROR);
1338 if (!channel->use_buffer)
1340 g_warning ("Need to set the channel buffered before setting the encoding.");
1341 g_warning ("Assuming this is what you meant and acting accordingly.");
1343 channel->use_buffer = TRUE;
1346 if (channel->partial_write_buf[0] != '\0')
1348 g_warning ("Partial character at end of write buffer not flushed.");
1349 channel->partial_write_buf[0] = '\0';
1352 #ifndef G_DISABLE_ASSERT
1353 did_encode = channel->do_encode;
1356 if (!encoding || strcmp (encoding, "UTF8") == 0 || strcmp (encoding, "UTF-8") == 0)
1358 channel->do_encode = FALSE;
1359 read_cd = write_cd = (GIConv) -1;
1364 const gchar *from_enc = NULL, *to_enc = NULL;
1366 if (channel->is_readable)
1368 read_cd = g_iconv_open ("UTF-8", encoding);
1370 if (read_cd == (GIConv) -1)
1373 from_enc = encoding;
1378 read_cd = (GIConv) -1;
1380 if (channel->is_writeable && err == 0)
1382 write_cd = g_iconv_open (encoding, "UTF-8");
1384 if (write_cd == (GIConv) -1)
1392 write_cd = (GIConv) -1;
1396 g_assert (from_enc);
1400 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_CONVERSION,
1401 _("Conversion from character set “%s” to “%s” is not supported"),
1404 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1405 _("Could not open converter from “%s” to “%s”: %s"),
1406 from_enc, to_enc, g_strerror (err));
1408 if (read_cd != (GIConv) -1)
1409 g_iconv_close (read_cd);
1410 if (write_cd != (GIConv) -1)
1411 g_iconv_close (write_cd);
1413 return G_IO_STATUS_ERROR;
1416 channel->do_encode = TRUE;
1419 /* The encoding is ok, so set the fields in channel */
1421 if (channel->read_cd != (GIConv) -1)
1422 g_iconv_close (channel->read_cd);
1423 if (channel->write_cd != (GIConv) -1)
1424 g_iconv_close (channel->write_cd);
1426 if (channel->encoded_read_buf && channel->encoded_read_buf->len > 0)
1428 g_assert (!did_encode); /* Encoding UTF-8, NULL doesn't use encoded_read_buf */
1430 /* This is just validated UTF-8, so we can copy it back into read_buf
1431 * so it can be encoded in whatever the new encoding is.
1434 g_string_prepend_len (channel->read_buf, channel->encoded_read_buf->str,
1435 channel->encoded_read_buf->len);
1436 g_string_truncate (channel->encoded_read_buf, 0);
1439 channel->read_cd = read_cd;
1440 channel->write_cd = write_cd;
1442 g_free (channel->encoding);
1443 channel->encoding = g_strdup (encoding);
1445 return G_IO_STATUS_NORMAL;
1449 * g_io_channel_get_encoding:
1450 * @channel: a #GIOChannel
1452 * Gets the encoding for the input/output of the channel.
1453 * The internal encoding is always UTF-8. The encoding %NULL
1454 * makes the channel safe for binary data.
1456 * Returns: A string containing the encoding, this string is
1457 * owned by GLib and must not be freed.
1460 g_io_channel_get_encoding (GIOChannel *channel)
1462 g_return_val_if_fail (channel != NULL, NULL);
1464 return channel->encoding;
1468 g_io_channel_fill_buffer (GIOChannel *channel,
1471 gsize read_size, cur_len, oldlen;
1474 if (channel->is_seekable && channel->write_buf && channel->write_buf->len > 0)
1476 status = g_io_channel_flush (channel, err);
1477 if (status != G_IO_STATUS_NORMAL)
1480 if (channel->is_seekable && channel->partial_write_buf[0] != '\0')
1482 g_warning ("Partial character at end of write buffer not flushed.");
1483 channel->partial_write_buf[0] = '\0';
1486 if (!channel->read_buf)
1487 channel->read_buf = g_string_sized_new (channel->buf_size);
1489 cur_len = channel->read_buf->len;
1491 g_string_set_size (channel->read_buf, channel->read_buf->len + channel->buf_size);
1493 status = channel->funcs->io_read (channel, channel->read_buf->str + cur_len,
1494 channel->buf_size, &read_size, err);
1496 g_assert ((status == G_IO_STATUS_NORMAL) || (read_size == 0));
1498 g_string_truncate (channel->read_buf, read_size + cur_len);
1500 if ((status != G_IO_STATUS_NORMAL) &&
1501 ((status != G_IO_STATUS_EOF) || (channel->read_buf->len == 0)))
1504 g_assert (channel->read_buf->len > 0);
1506 if (channel->encoded_read_buf)
1507 oldlen = channel->encoded_read_buf->len;
1511 if (channel->encoding)
1512 channel->encoded_read_buf = g_string_sized_new (channel->buf_size);
1515 if (channel->do_encode)
1517 gsize errnum, inbytes_left, outbytes_left;
1518 gchar *inbuf, *outbuf;
1521 g_assert (channel->encoded_read_buf);
1525 inbytes_left = channel->read_buf->len;
1526 outbytes_left = MAX (channel->read_buf->len,
1527 channel->encoded_read_buf->allocated_len
1528 - channel->encoded_read_buf->len - 1); /* 1 for NULL */
1529 outbytes_left = MAX (outbytes_left, 6);
1531 inbuf = channel->read_buf->str;
1532 g_string_set_size (channel->encoded_read_buf,
1533 channel->encoded_read_buf->len + outbytes_left);
1534 outbuf = channel->encoded_read_buf->str + channel->encoded_read_buf->len
1537 errnum = g_iconv (channel->read_cd, &inbuf, &inbytes_left,
1538 &outbuf, &outbytes_left);
1541 g_assert (inbuf + inbytes_left == channel->read_buf->str
1542 + channel->read_buf->len);
1543 g_assert (outbuf + outbytes_left == channel->encoded_read_buf->str
1544 + channel->encoded_read_buf->len);
1546 g_string_erase (channel->read_buf, 0,
1547 channel->read_buf->len - inbytes_left);
1548 g_string_truncate (channel->encoded_read_buf,
1549 channel->encoded_read_buf->len - outbytes_left);
1551 if (errnum == (gsize) -1)
1556 if ((oldlen == channel->encoded_read_buf->len)
1557 && (status == G_IO_STATUS_EOF))
1558 status = G_IO_STATUS_EOF;
1560 status = G_IO_STATUS_NORMAL;
1563 /* Buffer size at least 6, wrote at least on character */
1564 g_assert (inbuf != channel->read_buf->str);
1567 if (oldlen < channel->encoded_read_buf->len)
1568 status = G_IO_STATUS_NORMAL;
1571 g_set_error_literal (err, G_CONVERT_ERROR,
1572 G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1573 _("Invalid byte sequence in conversion input"));
1574 return G_IO_STATUS_ERROR;
1578 g_assert (errval != EBADF); /* The converter should be open */
1579 g_set_error (err, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1580 _("Error during conversion: %s"), g_strerror (errval));
1581 return G_IO_STATUS_ERROR;
1584 g_assert ((status != G_IO_STATUS_NORMAL)
1585 || (channel->encoded_read_buf->len > 0));
1587 else if (channel->encoding) /* UTF-8 */
1589 gchar *nextchar, *lastchar;
1591 g_assert (channel->encoded_read_buf);
1593 nextchar = channel->read_buf->str;
1594 lastchar = channel->read_buf->str + channel->read_buf->len;
1596 while (nextchar < lastchar)
1600 val_char = g_utf8_get_char_validated (nextchar, lastchar - nextchar);
1605 /* stop, leave partial character in buffer */
1606 lastchar = nextchar;
1609 if (oldlen < channel->encoded_read_buf->len)
1610 status = G_IO_STATUS_NORMAL;
1613 g_set_error_literal (err, G_CONVERT_ERROR,
1614 G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1615 _("Invalid byte sequence in conversion input"));
1616 status = G_IO_STATUS_ERROR;
1618 lastchar = nextchar;
1621 nextchar = g_utf8_next_char (nextchar);
1626 if (lastchar > channel->read_buf->str)
1628 gint copy_len = lastchar - channel->read_buf->str;
1630 g_string_append_len (channel->encoded_read_buf, channel->read_buf->str,
1632 g_string_erase (channel->read_buf, 0, copy_len);
1640 * g_io_channel_read_line:
1641 * @channel: a #GIOChannel
1642 * @str_return: (out): The line read from the #GIOChannel, including the
1643 * line terminator. This data should be freed with g_free()
1644 * when no longer needed. This is a nul-terminated string.
1645 * If a @length of zero is returned, this will be %NULL instead.
1646 * @length: (out) (optional): location to store length of the read data, or %NULL
1647 * @terminator_pos: (out) (optional): location to store position of line terminator, or %NULL
1648 * @error: A location to return an error of type #GConvertError
1649 * or #GIOChannelError
1651 * Reads a line, including the terminating character(s),
1652 * from a #GIOChannel into a newly-allocated string.
1653 * @str_return will contain allocated memory if the return
1654 * is %G_IO_STATUS_NORMAL.
1656 * Returns: the status of the operation.
1659 g_io_channel_read_line (GIOChannel *channel,
1662 gsize *terminator_pos,
1668 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1669 g_return_val_if_fail (str_return != NULL, G_IO_STATUS_ERROR);
1670 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1672 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
1674 status = g_io_channel_read_line_backend (channel, &got_length, terminator_pos, error);
1676 if (length && status != G_IO_STATUS_ERROR)
1677 *length = got_length;
1679 if (status == G_IO_STATUS_NORMAL)
1683 /* Copy the read bytes (including any embedded nuls) and nul-terminate.
1684 * `USE_BUF (channel)->str` is guaranteed to be nul-terminated as it’s a
1685 * #GString, so it’s safe to call g_memdup2() with +1 length to allocate
1686 * a nul-terminator. */
1687 g_assert (USE_BUF (channel));
1688 line = g_memdup2 (USE_BUF (channel)->str, got_length + 1);
1689 line[got_length] = '\0';
1690 *str_return = g_steal_pointer (&line);
1691 g_string_erase (USE_BUF (channel), 0, got_length);
1700 * g_io_channel_read_line_string:
1701 * @channel: a #GIOChannel
1702 * @buffer: a #GString into which the line will be written.
1703 * If @buffer already contains data, the old data will
1705 * @terminator_pos: (nullable): location to store position of line terminator, or %NULL
1706 * @error: a location to store an error of type #GConvertError
1707 * or #GIOChannelError
1709 * Reads a line from a #GIOChannel, using a #GString as a buffer.
1711 * Returns: the status of the operation.
1714 g_io_channel_read_line_string (GIOChannel *channel,
1716 gsize *terminator_pos,
1722 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1723 g_return_val_if_fail (buffer != NULL, G_IO_STATUS_ERROR);
1724 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1726 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
1728 if (buffer->len > 0)
1729 g_string_truncate (buffer, 0); /* clear out the buffer */
1731 status = g_io_channel_read_line_backend (channel, &length, terminator_pos, error);
1733 if (status == G_IO_STATUS_NORMAL)
1735 g_assert (USE_BUF (channel));
1736 g_string_append_len (buffer, USE_BUF (channel)->str, length);
1737 g_string_erase (USE_BUF (channel), 0, length);
1745 g_io_channel_read_line_backend (GIOChannel *channel,
1747 gsize *terminator_pos,
1751 gsize checked_to, line_term_len, line_length, got_term_len;
1752 gboolean first_time = TRUE;
1754 if (!channel->use_buffer)
1756 /* Can't do a raw read in read_line */
1757 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1758 _("Can’t do a raw read in g_io_channel_read_line_string"));
1759 return G_IO_STATUS_ERROR;
1762 status = G_IO_STATUS_NORMAL;
1764 if (channel->line_term)
1765 line_term_len = channel->line_term_len;
1768 /* This value used for setting checked_to, it's the longest of the four
1769 * we autodetect for.
1776 gchar *nextchar, *lastchar;
1779 if (!first_time || (BUF_LEN (USE_BUF (channel)) == 0))
1782 status = g_io_channel_fill_buffer (channel, error);
1785 case G_IO_STATUS_NORMAL:
1786 if (BUF_LEN (USE_BUF (channel)) == 0)
1787 /* Can happen when using conversion and only read
1788 * part of a character
1795 case G_IO_STATUS_EOF:
1796 if (BUF_LEN (USE_BUF (channel)) == 0)
1801 if (channel->encoding && channel->read_buf->len != 0)
1803 g_set_error_literal (error, G_CONVERT_ERROR,
1804 G_CONVERT_ERROR_PARTIAL_INPUT,
1805 _("Leftover unconverted data in "
1807 return G_IO_STATUS_ERROR;
1810 return G_IO_STATUS_EOF;
1820 g_assert (BUF_LEN (USE_BUF (channel)) != 0);
1822 use_buf = USE_BUF (channel); /* The buffer has been created by this point */
1826 lastchar = use_buf->str + use_buf->len;
1828 for (nextchar = use_buf->str + checked_to; nextchar < lastchar;
1829 channel->encoding ? nextchar = g_utf8_next_char (nextchar) : nextchar++)
1831 if (channel->line_term)
1833 if (memcmp (channel->line_term, nextchar, line_term_len) == 0)
1835 line_length = nextchar - use_buf->str;
1836 got_term_len = line_term_len;
1840 else /* auto detect */
1844 case '\n': /* unix */
1845 line_length = nextchar - use_buf->str;
1848 case '\r': /* Warning: do not use with sockets */
1849 line_length = nextchar - use_buf->str;
1850 if ((nextchar == lastchar - 1) && (status != G_IO_STATUS_EOF)
1851 && (lastchar == use_buf->str + use_buf->len))
1852 goto read_again; /* Try to read more data */
1853 if ((nextchar < lastchar - 1) && (*(nextchar + 1) == '\n')) /* dos */
1858 case '\xe2': /* Unicode paragraph separator */
1859 if (strncmp ("\xe2\x80\xa9", nextchar, 3) == 0)
1861 line_length = nextchar - use_buf->str;
1866 case '\0': /* Embedded null in input */
1867 line_length = nextchar - use_buf->str;
1870 default: /* no match */
1876 /* If encoding != NULL, valid UTF-8, didn't overshoot */
1877 g_assert (nextchar == lastchar);
1881 if (status == G_IO_STATUS_EOF)
1883 if (channel->encoding && channel->read_buf->len > 0)
1885 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
1886 _("Channel terminates in a partial character"));
1887 return G_IO_STATUS_ERROR;
1889 line_length = use_buf->len;
1894 if (use_buf->len > line_term_len - 1)
1895 checked_to = use_buf->len - (line_term_len - 1);
1903 *terminator_pos = line_length;
1906 *length = line_length + got_term_len;
1908 return G_IO_STATUS_NORMAL;
1912 * g_io_channel_read_to_end:
1913 * @channel: a #GIOChannel
1914 * @str_return: (out) (array length=length) (element-type guint8): Location to
1915 * store a pointer to a string holding the remaining data in the
1916 * #GIOChannel. This data should be freed with g_free() when no
1917 * longer needed. This data is terminated by an extra nul
1918 * character, but there may be other nuls in the intervening data.
1919 * @length: (out): location to store length of the data
1920 * @error: location to return an error of type #GConvertError
1921 * or #GIOChannelError
1923 * Reads all the remaining data from the file.
1925 * Returns: %G_IO_STATUS_NORMAL on success.
1926 * This function never returns %G_IO_STATUS_EOF.
1929 g_io_channel_read_to_end (GIOChannel *channel,
1936 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
1937 g_return_val_if_fail ((error == NULL) || (*error == NULL),
1939 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
1946 if (!channel->use_buffer)
1948 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1949 _("Can’t do a raw read in g_io_channel_read_to_end"));
1950 return G_IO_STATUS_ERROR;
1954 status = g_io_channel_fill_buffer (channel, error);
1955 while (status == G_IO_STATUS_NORMAL);
1957 if (status != G_IO_STATUS_EOF)
1960 if (channel->encoding && channel->read_buf->len > 0)
1962 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
1963 _("Channel terminates in a partial character"));
1964 return G_IO_STATUS_ERROR;
1967 if (USE_BUF (channel) == NULL)
1969 /* length is already set to zero */
1971 *str_return = g_strdup ("");
1976 *length = USE_BUF (channel)->len;
1979 *str_return = g_string_free (USE_BUF (channel), FALSE);
1981 g_string_free (USE_BUF (channel), TRUE);
1983 if (channel->encoding)
1984 channel->encoded_read_buf = NULL;
1986 channel->read_buf = NULL;
1989 return G_IO_STATUS_NORMAL;
1993 * g_io_channel_read_chars:
1994 * @channel: a #GIOChannel
1995 * @buf: (out caller-allocates) (array length=count) (element-type guint8):
1996 * a buffer to read data into
1997 * @count: (in): the size of the buffer. Note that the buffer may not be
1998 * completely filled even if there is data in the buffer if the
1999 * remaining data is not a complete character.
2000 * @bytes_read: (out) (optional): The number of bytes read. This may be
2001 * zero even on success if count < 6 and the channel's encoding
2002 * is non-%NULL. This indicates that the next UTF-8 character is
2003 * too wide for the buffer.
2004 * @error: a location to return an error of type #GConvertError
2005 * or #GIOChannelError.
2007 * Replacement for g_io_channel_read() with the new API.
2009 * Returns: the status of the operation.
2012 g_io_channel_read_chars (GIOChannel *channel,
2021 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2022 g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR);
2023 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
2029 return G_IO_STATUS_NORMAL;
2031 g_return_val_if_fail (buf != NULL, G_IO_STATUS_ERROR);
2033 if (!channel->use_buffer)
2037 g_assert (!channel->read_buf || channel->read_buf->len == 0);
2039 status = channel->funcs->io_read (channel, buf, count, &tmp_bytes, error);
2042 *bytes_read = tmp_bytes;
2047 status = G_IO_STATUS_NORMAL;
2049 while (BUF_LEN (USE_BUF (channel)) < count && status == G_IO_STATUS_NORMAL)
2050 status = g_io_channel_fill_buffer (channel, error);
2052 /* Only return an error if we have no data */
2054 if (BUF_LEN (USE_BUF (channel)) == 0)
2056 g_assert (status != G_IO_STATUS_NORMAL);
2058 if (status == G_IO_STATUS_EOF && channel->encoding
2059 && BUF_LEN (channel->read_buf) > 0)
2061 g_set_error_literal (error, G_CONVERT_ERROR,
2062 G_CONVERT_ERROR_PARTIAL_INPUT,
2063 _("Leftover unconverted data in read buffer"));
2064 status = G_IO_STATUS_ERROR;
2073 if (status == G_IO_STATUS_ERROR)
2074 g_clear_error (error);
2076 got_bytes = MIN (count, BUF_LEN (USE_BUF (channel)));
2078 g_assert (got_bytes > 0);
2080 if (channel->encoding)
2081 /* Don't validate for NULL encoding, binary safe */
2083 gchar *nextchar, *prevchar;
2085 g_assert (USE_BUF (channel) == channel->encoded_read_buf);
2087 nextchar = channel->encoded_read_buf->str;
2091 prevchar = nextchar;
2092 nextchar = g_utf8_next_char (nextchar);
2093 g_assert (nextchar != prevchar); /* Possible for *prevchar of -1 or -2 */
2095 while (nextchar < channel->encoded_read_buf->str + got_bytes);
2097 if (nextchar > channel->encoded_read_buf->str + got_bytes)
2098 got_bytes = prevchar - channel->encoded_read_buf->str;
2100 g_assert (got_bytes > 0 || count < 6);
2103 memcpy (buf, USE_BUF (channel)->str, got_bytes);
2104 g_string_erase (USE_BUF (channel), 0, got_bytes);
2107 *bytes_read = got_bytes;
2109 return G_IO_STATUS_NORMAL;
2113 * g_io_channel_read_unichar:
2114 * @channel: a #GIOChannel
2115 * @thechar: (out): a location to return a character
2116 * @error: a location to return an error of type #GConvertError
2117 * or #GIOChannelError
2119 * Reads a Unicode character from @channel.
2120 * This function cannot be called on a channel with %NULL encoding.
2122 * Returns: a #GIOStatus
2125 g_io_channel_read_unichar (GIOChannel *channel,
2129 GIOStatus status = G_IO_STATUS_NORMAL;
2131 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2132 g_return_val_if_fail (channel->encoding != NULL, G_IO_STATUS_ERROR);
2133 g_return_val_if_fail ((error == NULL) || (*error == NULL),
2135 g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR);
2137 while (BUF_LEN (channel->encoded_read_buf) == 0 && status == G_IO_STATUS_NORMAL)
2138 status = g_io_channel_fill_buffer (channel, error);
2140 /* Only return an error if we have no data */
2142 if (BUF_LEN (USE_BUF (channel)) == 0)
2144 g_assert (status != G_IO_STATUS_NORMAL);
2146 if (status == G_IO_STATUS_EOF && BUF_LEN (channel->read_buf) > 0)
2148 g_set_error_literal (error, G_CONVERT_ERROR,
2149 G_CONVERT_ERROR_PARTIAL_INPUT,
2150 _("Leftover unconverted data in read buffer"));
2151 status = G_IO_STATUS_ERROR;
2155 *thechar = (gunichar) -1;
2160 if (status == G_IO_STATUS_ERROR)
2161 g_clear_error (error);
2164 *thechar = g_utf8_get_char (channel->encoded_read_buf->str);
2166 g_string_erase (channel->encoded_read_buf, 0,
2167 g_utf8_next_char (channel->encoded_read_buf->str)
2168 - channel->encoded_read_buf->str);
2170 return G_IO_STATUS_NORMAL;
2174 * g_io_channel_write_chars:
2175 * @channel: a #GIOChannel
2176 * @buf: (array) (element-type guint8): a buffer to write data from
2177 * @count: the size of the buffer. If -1, the buffer
2178 * is taken to be a nul-terminated string.
2179 * @bytes_written: (out): The number of bytes written. This can be nonzero
2180 * even if the return value is not %G_IO_STATUS_NORMAL.
2181 * If the return value is %G_IO_STATUS_NORMAL and the
2182 * channel is blocking, this will always be equal
2183 * to @count if @count >= 0.
2184 * @error: a location to return an error of type #GConvertError
2185 * or #GIOChannelError
2187 * Replacement for g_io_channel_write() with the new API.
2189 * On seekable channels with encodings other than %NULL or UTF-8, generic
2190 * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
2191 * may only be made on a channel from which data has been read in the
2192 * cases described in the documentation for g_io_channel_set_encoding ().
2194 * Returns: the status of the operation.
2197 g_io_channel_write_chars (GIOChannel *channel,
2200 gsize *bytes_written,
2203 gsize count_unsigned;
2205 gssize wrote_bytes = 0;
2207 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2208 g_return_val_if_fail ((error == NULL) || (*error == NULL),
2210 g_return_val_if_fail (channel->is_writeable, G_IO_STATUS_ERROR);
2212 if ((count < 0) && buf)
2213 count = strlen (buf);
2214 count_unsigned = count;
2216 if (count_unsigned == 0)
2220 return G_IO_STATUS_NORMAL;
2223 g_return_val_if_fail (buf != NULL, G_IO_STATUS_ERROR);
2224 g_return_val_if_fail (count_unsigned > 0, G_IO_STATUS_ERROR);
2226 /* Raw write case */
2228 if (!channel->use_buffer)
2232 g_assert (!channel->write_buf || channel->write_buf->len == 0);
2233 g_assert (channel->partial_write_buf[0] == '\0');
2235 status = channel->funcs->io_write (channel, buf, count_unsigned,
2239 *bytes_written = tmp_bytes;
2246 if (channel->is_seekable && (( BUF_LEN (channel->read_buf) > 0)
2247 || (BUF_LEN (channel->encoded_read_buf) > 0)))
2249 if (channel->do_encode && BUF_LEN (channel->encoded_read_buf) > 0)
2251 g_warning ("Mixed reading and writing not allowed on encoded files");
2252 return G_IO_STATUS_ERROR;
2254 status = g_io_channel_seek_position (channel, 0, G_SEEK_CUR, error);
2255 if (status != G_IO_STATUS_NORMAL)
2263 if (!channel->write_buf)
2264 channel->write_buf = g_string_sized_new (channel->buf_size);
2266 while (wrote_bytes < count)
2270 /* If the buffer is full, try a write immediately. In
2271 * the nonblocking case, this prevents the user from
2272 * writing just a little bit to the buffer every time
2273 * and never receiving an EAGAIN.
2276 if (channel->write_buf->len >= channel->buf_size - MAX_CHAR_SIZE)
2278 gsize did_write = 0, this_time;
2282 status = channel->funcs->io_write (channel, channel->write_buf->str
2283 + did_write, channel->write_buf->len
2284 - did_write, &this_time, error);
2285 did_write += this_time;
2287 while (status == G_IO_STATUS_NORMAL &&
2288 did_write < MIN (channel->write_buf->len, MAX_CHAR_SIZE));
2290 g_string_erase (channel->write_buf, 0, did_write);
2292 if (status != G_IO_STATUS_NORMAL)
2294 if (status == G_IO_STATUS_AGAIN && wrote_bytes > 0)
2295 status = G_IO_STATUS_NORMAL;
2297 *bytes_written = wrote_bytes;
2302 space_in_buf = MAX (channel->buf_size, channel->write_buf->allocated_len - 1)
2303 - channel->write_buf->len; /* 1 for NULL */
2305 /* This is only true because g_io_channel_set_buffer_size ()
2306 * ensures that channel->buf_size >= MAX_CHAR_SIZE.
2308 g_assert (space_in_buf >= MAX_CHAR_SIZE);
2310 if (!channel->encoding)
2312 gssize write_this = MIN (space_in_buf, count_unsigned - wrote_bytes);
2314 g_string_append_len (channel->write_buf, buf, write_this);
2316 wrote_bytes += write_this;
2320 const gchar *from_buf;
2321 gsize from_buf_len, from_buf_old_len, left_len;
2325 if (channel->partial_write_buf[0] != '\0')
2327 g_assert (wrote_bytes == 0);
2329 from_buf = channel->partial_write_buf;
2330 from_buf_old_len = strlen (channel->partial_write_buf);
2331 g_assert (from_buf_old_len > 0);
2332 from_buf_len = MIN (6, from_buf_old_len + count_unsigned);
2334 memcpy (channel->partial_write_buf + from_buf_old_len, buf,
2335 from_buf_len - from_buf_old_len);
2340 from_buf_len = count_unsigned - wrote_bytes;
2341 from_buf_old_len = 0;
2346 if (!channel->do_encode) /* UTF-8 encoding */
2348 const gchar *badchar;
2349 gsize try_len = MIN (from_buf_len, space_in_buf);
2351 /* UTF-8, just validate, emulate g_iconv */
2353 if (!g_utf8_validate_len (from_buf, try_len, &badchar))
2356 gsize incomplete_len = from_buf + try_len - badchar;
2358 left_len = from_buf + from_buf_len - badchar;
2360 try_char = g_utf8_get_char_validated (badchar, incomplete_len);
2365 g_assert (incomplete_len < 6);
2366 if (try_len == from_buf_len)
2378 g_warning ("Invalid UTF-8 passed to g_io_channel_write_chars().");
2379 /* FIXME bail here? */
2384 g_assert_not_reached ();
2386 errnum = 0; /* Don't confuse the compiler */
2393 left_len = from_buf_len - try_len;
2396 g_string_append_len (channel->write_buf, from_buf,
2397 from_buf_len - left_len);
2398 from_buf += from_buf_len - left_len;
2404 left_len = from_buf_len;
2405 g_string_set_size (channel->write_buf, channel->write_buf->len
2407 outbuf = channel->write_buf->str + channel->write_buf->len
2409 err = g_iconv (channel->write_cd, (gchar **) &from_buf, &left_len,
2410 &outbuf, &space_in_buf);
2412 g_string_truncate (channel->write_buf, channel->write_buf->len
2416 if (err == (gsize) -1)
2421 g_assert (left_len < 6);
2423 if (from_buf_old_len == 0)
2425 /* Not from partial_write_buf */
2427 memcpy (channel->partial_write_buf, from_buf, left_len);
2428 channel->partial_write_buf[left_len] = '\0';
2430 *bytes_written = count_unsigned;
2431 return G_IO_STATUS_NORMAL;
2434 /* Working in partial_write_buf */
2436 if (left_len == from_buf_len)
2438 /* Didn't convert anything, must still have
2439 * less than a full character
2442 g_assert (count_unsigned == from_buf_len - from_buf_old_len);
2444 channel->partial_write_buf[from_buf_len] = '\0';
2447 *bytes_written = count_unsigned;
2449 return G_IO_STATUS_NORMAL;
2452 g_assert (from_buf_len - left_len >= from_buf_old_len);
2454 /* We converted all the old data. This is fine */
2458 if (from_buf_len == left_len)
2460 /* Nothing was written, add enough space for
2461 * at least one character.
2463 space_in_buf += MAX_CHAR_SIZE;
2468 g_set_error_literal (error, G_CONVERT_ERROR,
2469 G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
2470 _("Invalid byte sequence in conversion input"));
2471 if (from_buf_old_len > 0 && from_buf_len == left_len)
2472 g_warning ("Illegal sequence due to partial character "
2473 "at the end of a previous write.");
2475 wrote_bytes += from_buf_len - left_len - from_buf_old_len;
2477 *bytes_written = wrote_bytes;
2478 channel->partial_write_buf[0] = '\0';
2479 return G_IO_STATUS_ERROR;
2481 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
2482 _("Error during conversion: %s"), g_strerror (errnum));
2483 if (from_buf_len >= left_len + from_buf_old_len)
2484 wrote_bytes += from_buf_len - left_len - from_buf_old_len;
2486 *bytes_written = wrote_bytes;
2487 channel->partial_write_buf[0] = '\0';
2488 return G_IO_STATUS_ERROR;
2492 g_assert (from_buf_len - left_len >= from_buf_old_len);
2494 wrote_bytes += from_buf_len - left_len - from_buf_old_len;
2496 if (from_buf_old_len > 0)
2498 /* We were working in partial_write_buf */
2500 buf += from_buf_len - left_len - from_buf_old_len;
2501 channel->partial_write_buf[0] = '\0';
2509 *bytes_written = count_unsigned;
2511 return G_IO_STATUS_NORMAL;
2515 * g_io_channel_write_unichar:
2516 * @channel: a #GIOChannel
2517 * @thechar: a character
2518 * @error: location to return an error of type #GConvertError
2519 * or #GIOChannelError
2521 * Writes a Unicode character to @channel.
2522 * This function cannot be called on a channel with %NULL encoding.
2524 * Returns: a #GIOStatus
2527 g_io_channel_write_unichar (GIOChannel *channel,
2532 gchar static_buf[6];
2533 gsize char_len, wrote_len;
2535 g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR);
2536 g_return_val_if_fail (channel->encoding != NULL, G_IO_STATUS_ERROR);
2537 g_return_val_if_fail ((error == NULL) || (*error == NULL),
2539 g_return_val_if_fail (channel->is_writeable, G_IO_STATUS_ERROR);
2541 char_len = g_unichar_to_utf8 (thechar, static_buf);
2543 if (channel->partial_write_buf[0] != '\0')
2545 g_warning ("Partial character written before writing unichar.");
2546 channel->partial_write_buf[0] = '\0';
2549 status = g_io_channel_write_chars (channel, static_buf,
2550 char_len, &wrote_len, error);
2552 /* We validate UTF-8, so we can't get a partial write */
2554 g_assert (wrote_len == char_len || status != G_IO_STATUS_NORMAL);
2560 * G_IO_CHANNEL_ERROR:
2562 * Error domain for #GIOChannel operations. Errors in this domain will
2563 * be from the #GIOChannelError enumeration. See #GError for
2564 * information on error domains.
2568 * @G_IO_CHANNEL_ERROR_FBIG: File too large.
2569 * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
2570 * @G_IO_CHANNEL_ERROR_IO: IO error.
2571 * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
2572 * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
2573 * @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
2574 * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
2575 * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
2576 * @G_IO_CHANNEL_ERROR_FAILED: Some other error.
2578 * Error codes returned by #GIOChannel operations.
2581 G_DEFINE_QUARK (g-io-channel-error-quark, g_io_channel_error)