X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fgiochannel.c;h=19fc1d4e7fb28830e4acfea2903e5a308dcd5526;hb=4454b815367831a71b1ae00b0182b5b389a78df2;hp=4c40bbde8a7bd7cb0ac93d3ead7243c525b81322;hpb=4cfd423a9010b97255b3a6a2e3182fa508b8b2ea;p=platform%2Fupstream%2Fglib.git diff --git a/glib/giochannel.c b/glib/giochannel.c index 4c40bbd..19fc1d4 100644 --- a/glib/giochannel.c +++ b/glib/giochannel.c @@ -15,9 +15,7 @@ * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library; if not, see . */ /* @@ -32,20 +30,124 @@ */ #include "config.h" -#include "giochannel.h" #include #include -#ifdef HAVE_UNISTD_H -#include -#endif +#include "giochannel.h" -#undef G_DISABLE_DEPRECATED +#include "gstrfuncs.h" +#include "gtestutils.h" +#include "glibintl.h" -#include "glib.h" -#include "glibintl.h" +/** + * SECTION:iochannels + * @title: IO Channels + * @short_description: portable support for using files, pipes and sockets + * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(), + * #GMainLoop + * + * The #GIOChannel data type aims to provide a portable method for + * using file descriptors, pipes, and sockets, and integrating them + * into the [main event loop][glib-The-Main-Event-Loop]. Currently, + * full support is available on UNIX platforms, support for Windows + * is only partially complete. + * + * To create a new #GIOChannel on UNIX systems use + * g_io_channel_unix_new(). This works for plain file descriptors, + * pipes and sockets. Alternatively, a channel can be created for a + * file in a system independent manner using g_io_channel_new_file(). + * + * Once a #GIOChannel has been created, it can be used in a generic + * manner with the functions g_io_channel_read_chars(), + * g_io_channel_write_chars(), g_io_channel_seek_position(), and + * g_io_channel_shutdown(). + * + * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], + * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which + * events you are interested in on the #GIOChannel, and provide a + * function to be called whenever these events occur. + * + * #GIOChannel instances are created with an initial reference count of 1. + * g_io_channel_ref() and g_io_channel_unref() can be used to + * increment or decrement the reference count respectively. When the + * reference count falls to 0, the #GIOChannel is freed. (Though it + * isn't closed automatically, unless it was created using + * g_io_channel_new_file().) Using g_io_add_watch() or + * g_io_add_watch_full() increments a channel's reference count. + * + * The new functions g_io_channel_read_chars(), + * g_io_channel_read_line(), g_io_channel_read_line_string(), + * g_io_channel_read_to_end(), g_io_channel_write_chars(), + * g_io_channel_seek_position(), and g_io_channel_flush() should not be + * mixed with the deprecated functions g_io_channel_read(), + * g_io_channel_write(), and g_io_channel_seek() on the same channel. + **/ + +/** + * GIOChannel: + * + * A data structure representing an IO Channel. The fields should be + * considered private and should only be accessed with the following + * functions. + **/ + +/** + * GIOFuncs: + * @io_read: reads raw bytes from the channel. This is called from + * various functions such as g_io_channel_read_chars() to + * read raw bytes from the channel. Encoding and buffering + * issues are dealt with at a higher level. + * @io_write: writes raw bytes to the channel. This is called from + * various functions such as g_io_channel_write_chars() to + * write raw bytes to the channel. Encoding and buffering + * issues are dealt with at a higher level. + * @io_seek: (optional) seeks the channel. This is called from + * g_io_channel_seek() on channels that support it. + * @io_close: closes the channel. This is called from + * g_io_channel_close() after flushing the buffers. + * @io_create_watch: creates a watch on the channel. This call + * corresponds directly to g_io_create_watch(). + * @io_free: called from g_io_channel_unref() when the channel needs to + * be freed. This function must free the memory associated + * with the channel, including freeing the #GIOChannel + * structure itself. The channel buffers have been flushed + * and possibly @io_close has been called by the time this + * function is called. + * @io_set_flags: sets the #GIOFlags on the channel. This is called + * from g_io_channel_set_flags() with all flags except + * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked + * out. + * @io_get_flags: gets the #GIOFlags for the channel. This function + * need only return the %G_IO_FLAG_APPEND and + * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() + * automatically adds the others as appropriate. + * + * A table of functions used to handle different types of #GIOChannel + * in a generic way. + **/ + +/** + * GIOStatus: + * @G_IO_STATUS_ERROR: An error occurred. + * @G_IO_STATUS_NORMAL: Success. + * @G_IO_STATUS_EOF: End of file. + * @G_IO_STATUS_AGAIN: Resource temporarily unavailable. + * + * Stati returned by most of the #GIOFuncs functions. + **/ + +/** + * GIOError: + * @G_IO_ERROR_NONE: no error + * @G_IO_ERROR_AGAIN: an EAGAIN error occurred + * @G_IO_ERROR_INVAL: an EINVAL error occurred + * @G_IO_ERROR_UNKNOWN: another error occurred + * + * #GIOError is only used by the deprecated functions + * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). + **/ #define G_IO_NICE_BUF_SIZE 1024 @@ -70,12 +172,23 @@ static GIOStatus g_io_channel_read_line_backend (GIOChannel *channel, gsize *terminator_pos, GError **error); +/** + * g_io_channel_init: + * @channel: a #GIOChannel + * + * Initializes a #GIOChannel struct. + * + * This is called by each of the above functions when creating a + * #GIOChannel, and so is not often needed by the application + * programmer (unless you are creating a new type of #GIOChannel). + */ void g_io_channel_init (GIOChannel *channel) { channel->ref_count = 1; channel->encoding = g_strdup ("UTF-8"); channel->line_term = NULL; + channel->line_term_len = 0; channel->buf_size = G_IO_NICE_BUF_SIZE; channel->read_cd = (GIConv) -1; channel->write_cd = (GIConv) -1; @@ -88,21 +201,40 @@ g_io_channel_init (GIOChannel *channel) channel->close_on_unref = FALSE; } -void +/** + * g_io_channel_ref: + * @channel: a #GIOChannel + * + * Increments the reference count of a #GIOChannel. + * + * Returns: the @channel that was passed in (since 2.6) + */ +GIOChannel * g_io_channel_ref (GIOChannel *channel) { - g_return_if_fail (channel != NULL); + g_return_val_if_fail (channel != NULL, NULL); + + g_atomic_int_inc (&channel->ref_count); - channel->ref_count++; + return channel; } +/** + * g_io_channel_unref: + * @channel: a #GIOChannel + * + * Decrements the reference count of a #GIOChannel. + */ void g_io_channel_unref (GIOChannel *channel) { + gboolean is_zero; + g_return_if_fail (channel != NULL); - channel->ref_count--; - if (channel->ref_count == 0) + is_zero = g_atomic_int_dec_and_test (&channel->ref_count); + + if (G_UNLIKELY (is_zero)) { if (channel->close_on_unref) g_io_channel_shutdown (channel, TRUE, NULL); @@ -125,8 +257,8 @@ g_io_channel_unref (GIOChannel *channel) } static GIOError -g_io_error_get_from_g_error (GIOStatus status, - GError *err) +g_io_error_get_from_g_error (GIOStatus status, + GError *err) { switch (status) { @@ -136,6 +268,8 @@ g_io_error_get_from_g_error (GIOStatus status, case G_IO_STATUS_AGAIN: return G_IO_ERROR_AGAIN; case G_IO_STATUS_ERROR: + g_return_val_if_fail (err != NULL, G_IO_ERROR_UNKNOWN); + if (err->domain != G_IO_CHANNEL_ERROR) return G_IO_ERROR_UNKNOWN; switch (err->code) @@ -147,21 +281,22 @@ g_io_error_get_from_g_error (GIOStatus status, } default: g_assert_not_reached (); - return G_IO_ERROR_UNKNOWN; /* Keep the compiler happy */ } } /** * g_io_channel_read: - * @channel: a #GIOChannel. - * @buf: a buffer to read the data into (which should be at least count bytes long). - * @count: the number of bytes to read from the #GIOChannel. - * @bytes_read: returns the number of bytes actually read. + * @channel: a #GIOChannel + * @buf: a buffer to read the data into (which should be at least + * count bytes long) + * @count: the number of bytes to read from the #GIOChannel + * @bytes_read: returns the number of bytes actually read * - * Reads data from a #GIOChannel. This function is depricated. New code should - * use g_io_channel_read_chars() instead. + * Reads data from a #GIOChannel. * - * Return value: %G_IO_ERROR_NONE if the operation was successful. + * Returns: %G_IO_ERROR_NONE if the operation was successful. + * + * Deprecated:2.2: Use g_io_channel_read_chars() instead. **/ GIOError g_io_channel_read (GIOChannel *channel, @@ -176,6 +311,15 @@ g_io_channel_read (GIOChannel *channel, g_return_val_if_fail (channel != NULL, G_IO_ERROR_UNKNOWN); g_return_val_if_fail (bytes_read != NULL, G_IO_ERROR_UNKNOWN); + if (count == 0) + { + if (bytes_read) + *bytes_read = 0; + return G_IO_ERROR_NONE; + } + + g_return_val_if_fail (buf != NULL, G_IO_ERROR_UNKNOWN); + status = channel->funcs->io_read (channel, buf, count, bytes_read, &err); error = g_io_error_get_from_g_error (status, err); @@ -188,15 +332,16 @@ g_io_channel_read (GIOChannel *channel, /** * g_io_channel_write: - * @channel: a #GIOChannel. - * @buf: the buffer containing the data to write. - * @count: the number of bytes to write. - * @bytes_written: the number of bytes actually written. + * @channel: a #GIOChannel + * @buf: the buffer containing the data to write + * @count: the number of bytes to write + * @bytes_written: the number of bytes actually written * - * Writes data to a #GIOChannel. This function is depricated. New code should - * use g_io_channel_write_chars() instead. + * Writes data to a #GIOChannel. * - * Return value: %G_IO_ERROR_NONE if the operation was successful. + * Returns: %G_IO_ERROR_NONE if the operation was successful. + * + * Deprecated:2.2: Use g_io_channel_write_chars() instead. **/ GIOError g_io_channel_write (GIOChannel *channel, @@ -223,22 +368,24 @@ g_io_channel_write (GIOChannel *channel, /** * g_io_channel_seek: - * @channel: a #GIOChannel. - * @offset: an offset, in bytes, which is added to the position specified by @type + * @channel: a #GIOChannel + * @offset: an offset, in bytes, which is added to the position specified + * by @type * @type: the position in the file, which can be %G_SEEK_CUR (the current - * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the - * file). + * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END + * (the end of the file) * - * Sets the current position in the #GIOChannel, similar to the standard library - * function fseek(). This function is depricated. New code should - * use g_io_channel_seek_position() instead. + * Sets the current position in the #GIOChannel, similar to the standard + * library function fseek(). * - * Return value: %G_IO_ERROR_NONE if the operation was successful. + * Returns: %G_IO_ERROR_NONE if the operation was successful. + * + * Deprecated:2.2: Use g_io_channel_seek_position() instead. **/ GIOError -g_io_channel_seek (GIOChannel *channel, - glong offset, - GSeekType type) +g_io_channel_seek (GIOChannel *channel, + gint64 offset, + GSeekType type) { GError *err = NULL; GIOError error; @@ -274,10 +421,10 @@ g_io_channel_seek (GIOChannel *channel, /** * g_io_channel_new_file: - * @filename: A string containing the name of a file. + * @filename: A string containing the name of a file * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have - * the same meaning as in fopen(). - * @error: A location to return an error of type %G_IO_FILE_ERROR. + * the same meaning as in fopen() + * @error: A location to return an error of type %G_FILE_ERROR * * Open a file @filename as a #GIOChannel using mode @mode. This * channel will be closed when the last reference to it is dropped, @@ -285,7 +432,7 @@ g_io_channel_seek (GIOChannel *channel, * so will not cause problems, as long as no attempt is made to * access the channel after it is closed). * - * Return value: A #GIOChannel on success, %NULL on failure. + * Returns: A #GIOChannel on success, %NULL on failure. **/ /** @@ -294,9 +441,9 @@ g_io_channel_seek (GIOChannel *channel, * * Close an IO channel. Any pending data to be written will be * flushed, ignoring errors. The channel will not be freed until the - * last reference is dropped using g_io_channel_unref(). This - * function is deprecated: you should use g_io_channel_shutdown() - * instead. + * last reference is dropped using g_io_channel_unref(). + * + * Deprecated:2.2: Use g_io_channel_shutdown() instead. **/ void g_io_channel_close (GIOChannel *channel) @@ -328,15 +475,15 @@ g_io_channel_close (GIOChannel *channel) * @err: location to store a #GIOChannelError * * Close an IO channel. Any pending data to be written will be - * flushed. The channel will not be freed until the + * flushed if @flush is %TRUE. The channel will not be freed until the * last reference is dropped using g_io_channel_unref(). * - * Return value: + * Returns: the status of the operation. **/ GIOStatus -g_io_channel_shutdown (GIOChannel *channel, - gboolean flush, - GError **err) +g_io_channel_shutdown (GIOChannel *channel, + gboolean flush, + GError **err) { GIOStatus status, result; GError *tmperr = NULL; @@ -344,27 +491,35 @@ g_io_channel_shutdown (GIOChannel *channel, g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR); g_return_val_if_fail (err == NULL || *err == NULL, G_IO_STATUS_ERROR); - if (flush && channel->write_buf && channel->write_buf->len > 0) + if (channel->write_buf && channel->write_buf->len > 0) { - GIOFlags flags; + if (flush) + { + GIOFlags flags; - /* Set the channel to blocking, to avoid a busy loop - */ - flags = g_io_channel_get_flags (channel); - /* Ignore any errors here, they're irrelevant */ - g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL); + /* Set the channel to blocking, to avoid a busy loop + */ + flags = g_io_channel_get_flags (channel); + /* Ignore any errors here, they're irrelevant */ + g_io_channel_set_flags (channel, flags & ~G_IO_FLAG_NONBLOCK, NULL); - result = g_io_channel_flush (channel, &tmperr); - - if (channel->partial_write_buf[0] != '\0') - { - g_warning ("Partial character at end of write buffer not flushed.\n"); - channel->partial_write_buf[0] = '\0'; + result = g_io_channel_flush (channel, &tmperr); } + else + result = G_IO_STATUS_NORMAL; + + g_string_truncate(channel->write_buf, 0); } else result = G_IO_STATUS_NORMAL; + if (channel->partial_write_buf[0] != '\0') + { + if (flush) + g_warning ("Partial character at end of write buffer not flushed.\n"); + channel->partial_write_buf[0] = '\0'; + } + status = channel->funcs->io_close (channel, err); channel->close_on_unref = FALSE; /* Because we already did */ @@ -391,14 +546,14 @@ static void g_io_channel_purge (GIOChannel *channel) { GError *err = NULL; - GIOStatus status; + GIOStatus status G_GNUC_UNUSED; g_return_if_fail (channel != NULL); if (channel->write_buf && channel->write_buf->len > 0) { GIOFlags flags; - + /* Set the channel to blocking, to avoid a busy loop */ flags = g_io_channel_get_flags (channel); @@ -407,10 +562,10 @@ g_io_channel_purge (GIOChannel *channel) status = g_io_channel_flush (channel, &err); if (err) - { /* No way to return the error */ - g_warning ("Error flushing string: %s", err->message); - g_error_free (err); - } + { /* No way to return the error */ + g_warning ("Error flushing string: %s", err->message); + g_error_free (err); + } } /* Flush these in case anyone tries to close without unrefing */ @@ -432,15 +587,53 @@ g_io_channel_purge (GIOChannel *channel) } } +/** + * g_io_create_watch: + * @channel: a #GIOChannel to watch + * @condition: conditions to watch for + * + * Creates a #GSource that's dispatched when @condition is met for the + * given @channel. For example, if condition is #G_IO_IN, the source will + * be dispatched when there's data available for reading. + * + * g_io_add_watch() is a simpler interface to this same functionality, for + * the case where you want to add the source to the default main loop context + * at the default priority. + * + * On Windows, polling a #GSource created to watch a channel for a socket + * puts the socket in non-blocking mode. This is a side-effect of the + * implementation and unavoidable. + * + * Returns: a new #GSource + */ GSource * -g_io_create_watch (GIOChannel *channel, - GIOCondition condition) +g_io_create_watch (GIOChannel *channel, + GIOCondition condition) { g_return_val_if_fail (channel != NULL, NULL); return channel->funcs->io_create_watch (channel, condition); } +/** + * g_io_add_watch_full: + * @channel: a #GIOChannel + * @priority: the priority of the #GIOChannel source + * @condition: the condition to watch for + * @func: the function to call when the condition is satisfied + * @user_data: user data to pass to @func + * @notify: the function to call when the source is removed + * + * Adds the #GIOChannel into the default main loop context + * with the given priority. + * + * This internally creates a main loop source using g_io_create_watch() + * and attaches it to the main loop context with g_source_attach(). + * You can do these steps manually if you need greater control. + * + * Returns: the event source id + * Rename to: g_io_add_watch + */ guint g_io_add_watch_full (GIOChannel *channel, gint priority, @@ -466,11 +659,49 @@ g_io_add_watch_full (GIOChannel *channel, return id; } +/** + * g_io_add_watch: + * @channel: a #GIOChannel + * @condition: the condition to watch for + * @func: the function to call when the condition is satisfied + * @user_data: user data to pass to @func + * + * Adds the #GIOChannel into the default main loop context + * with the default priority. + * + * Returns: the event source id + */ +/** + * GIOFunc: + * @source: the #GIOChannel event source + * @condition: the condition which has been satisfied + * @data: user data set in g_io_add_watch() or g_io_add_watch_full() + * + * Specifies the type of function passed to g_io_add_watch() or + * g_io_add_watch_full(), which is called when the requested condition + * on a #GIOChannel is satisfied. + * + * Returns: the function should return %FALSE if the event source + * should be removed + **/ +/** + * GIOCondition: + * @G_IO_IN: There is data to read. + * @G_IO_OUT: Data can be written (without blocking). + * @G_IO_PRI: There is urgent data to read. + * @G_IO_ERR: Error condition. + * @G_IO_HUP: Hung up (the connection has been broken, usually for + * pipes and sockets). + * @G_IO_NVAL: Invalid request. The file descriptor is not open. + * + * A bitwise combination representing a condition to watch for on an + * event source. + **/ guint -g_io_add_watch (GIOChannel *channel, - GIOCondition condition, - GIOFunc func, - gpointer user_data) +g_io_add_watch (GIOChannel *channel, + GIOCondition condition, + GIOFunc func, + gpointer user_data) { return g_io_add_watch_full (channel, G_PRIORITY_DEFAULT, condition, func, user_data, NULL); } @@ -479,11 +710,11 @@ g_io_add_watch (GIOChannel *channel, * g_io_channel_get_buffer_condition: * @channel: A #GIOChannel * - * This function returns a #GIOCondition depending on the status of the - * internal buffers in the #GIOChannel. Only the flags %G_IO_IN and - * %G_IO_OUT will be set. + * This function returns a #GIOCondition depending on whether there + * is data to be read/space to write data in the internal buffers in + * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. * - * Return value: A #GIOCondition + * Returns: A #GIOCondition **/ GIOCondition g_io_channel_get_buffer_condition (GIOChannel *channel) @@ -509,9 +740,12 @@ g_io_channel_get_buffer_condition (GIOChannel *channel) /** * g_io_channel_error_from_errno: - * @en: An errno error number, e.g. EINVAL + * @en: an `errno` error number, e.g. `EINVAL` + * + * Converts an `errno` error number to a #GIOChannelError. * - * Return value: A #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL + * Returns: a #GIOChannelError error number, e.g. + * %G_IO_CHANNEL_ERROR_INVAL. **/ GIOChannelError g_io_channel_error_from_errno (gint en) @@ -519,9 +753,6 @@ g_io_channel_error_from_errno (gint en) #ifdef EAGAIN g_return_val_if_fail (en != EAGAIN, G_IO_CHANNEL_ERROR_FAILED); #endif -#ifdef EINTR - g_return_val_if_fail (en != EINTR, G_IO_CHANNEL_ERROR_FAILED); -#endif switch (en) { @@ -533,7 +764,7 @@ g_io_channel_error_from_errno (gint en) #ifdef EFAULT case EFAULT: - g_warning("File descriptor outside valid address space.\n"); + g_warning("Buffer outside valid address space.\n"); return G_IO_CHANNEL_ERROR_FAILED; #endif @@ -542,6 +773,18 @@ g_io_channel_error_from_errno (gint en) return G_IO_CHANNEL_ERROR_FBIG; #endif +#ifdef EINTR + /* In general, we should catch EINTR before we get here, + * but close() is allowed to return EINTR by POSIX, so + * we need to catch it here; EINTR from close() is + * unrecoverable, because it's undefined whether + * the fd was actually closed or not, so we just return + * a generic error code. + */ + case EINTR: + return G_IO_CHANNEL_ERROR_FAILED; +#endif + #ifdef EINVAL case EINVAL: return G_IO_CHANNEL_ERROR_INVAL; @@ -568,9 +811,11 @@ g_io_channel_error_from_errno (gint en) #endif #ifdef EOVERFLOW +#if EOVERFLOW != EFBIG case EOVERFLOW: return G_IO_CHANNEL_ERROR_OVERFLOW; #endif +#endif #ifdef EPIPE case EPIPE: @@ -585,13 +830,13 @@ g_io_channel_error_from_errno (gint en) /** * g_io_channel_set_buffer_size: * @channel: a #GIOChannel - * @size: the size of the buffer. 0 == pick a good size + * @size: the size of the buffer, or 0 to let GLib pick a good size * - * Set the buffer size. + * Sets the buffer size. **/ void -g_io_channel_set_buffer_size (GIOChannel *channel, - gsize size) +g_io_channel_set_buffer_size (GIOChannel *channel, + gsize size) { g_return_if_fail (channel != NULL); @@ -608,12 +853,12 @@ g_io_channel_set_buffer_size (GIOChannel *channel, * g_io_channel_get_buffer_size: * @channel: a #GIOChannel * - * Get the buffer size. + * Gets the buffer size. * - * Return value: the size of the buffer. + * Returns: the size of the buffer. **/ gsize -g_io_channel_get_buffer_size (GIOChannel *channel) +g_io_channel_get_buffer_size (GIOChannel *channel) { g_return_val_if_fail (channel != NULL, 0); @@ -623,39 +868,55 @@ g_io_channel_get_buffer_size (GIOChannel *channel) /** * g_io_channel_set_line_term: * @channel: a #GIOChannel - * @line_term: The line termination string. Use %NULL for auto detect. + * @line_term: (allow-none): The line termination string. Use %NULL for + * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", + * and the Unicode paragraph separator. Autodetection should not be + * used for anything other than file-based channels. + * @length: The length of the termination string. If -1 is passed, the + * string is assumed to be nul-terminated. This option allows + * termination strings with embedded nuls. * * This sets the string that #GIOChannel uses to determine * where in the file a line break occurs. **/ void g_io_channel_set_line_term (GIOChannel *channel, - const gchar *line_term) + const gchar *line_term, + gint length) { g_return_if_fail (channel != NULL); - g_return_if_fail (!line_term || line_term[0]); /* Disallow "" */ - g_return_if_fail (!line_term || g_utf8_validate (line_term, -1, NULL)); - /* Require valid UTF-8 */ + g_return_if_fail (line_term == NULL || length != 0); /* Disallow "" */ + + if (line_term == NULL) + length = 0; + else if (length < 0) + length = strlen (line_term); g_free (channel->line_term); - channel->line_term = g_strdup (line_term); + channel->line_term = line_term ? g_memdup (line_term, length) : NULL; + channel->line_term_len = length; } /** * g_io_channel_get_line_term: * @channel: a #GIOChannel + * @length: a location to return the length of the line terminator * * This returns the string that #GIOChannel uses to determine * where in the file a line break occurs. A value of %NULL - * indicates auto detection. + * indicates autodetection. * - * Return value: The line termination string. This value + * Returns: The line termination string. This value * is owned by GLib and must not be freed. **/ -G_CONST_RETURN gchar* -g_io_channel_get_line_term (GIOChannel *channel) +const gchar * +g_io_channel_get_line_term (GIOChannel *channel, + gint *length) { - g_return_val_if_fail (channel != NULL, 0); + g_return_val_if_fail (channel != NULL, NULL); + + if (length) + *length = channel->line_term_len; return channel->line_term; } @@ -663,21 +924,50 @@ g_io_channel_get_line_term (GIOChannel *channel) /** * g_io_channel_set_flags: * @channel: a #GIOChannel - * @flags: the flags to set on the channel + * @flags: the flags to set on the IO channel * @error: A location to return an error of type #GIOChannelError * - * Return value: + * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). + * + * Returns: the status of the operation. **/ +/** + * GIOFlags: + * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND + * (see the documentation of the UNIX open() syscall) + * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to + * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() + * syscall) + * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. + * This flag cannot be changed. + * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. + * This flag cannot be changed. + * @G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE + * that existed before the spelling was fixed in GLib 2.30. It is kept + * here for compatibility reasons. Deprecated since 2.30 + * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, + * i.e. that g_io_channel_seek_position() can be used on it. + * This flag cannot be changed. + * @G_IO_FLAG_MASK: the mask that specifies all the valid flags. + * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from + * g_io_channel_get_flags() + * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify + * with g_io_channel_set_flags() + * + * Specifies properties of a #GIOChannel. Some of the flags can only be + * read with g_io_channel_get_flags(), but not changed with + * g_io_channel_set_flags(). + */ GIOStatus -g_io_channel_set_flags (GIOChannel *channel, - GIOFlags flags, - GError **error) +g_io_channel_set_flags (GIOChannel *channel, + GIOFlags flags, + GError **error) { g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR); g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR); - return (* channel->funcs->io_set_flags)(channel, + return (*channel->funcs->io_set_flags) (channel, flags & G_IO_FLAG_SET_MASK, error); } @@ -689,14 +979,21 @@ g_io_channel_set_flags (GIOChannel *channel, * Gets the current flags for a #GIOChannel, including read-only * flags such as %G_IO_FLAG_IS_READABLE. * - * Return value: the flags which are set on the channel + * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE + * are cached for internal use by the channel when it is created. + * If they should change at some later point (e.g. partial shutdown + * of a socket with the UNIX shutdown() function), the user + * should immediately call g_io_channel_get_flags() to update + * the internal values of these flags. + * + * Returns: the flags which are set on the channel **/ GIOFlags g_io_channel_get_flags (GIOChannel *channel) { GIOFlags flags; - g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR); + g_return_val_if_fail (channel != NULL, 0); flags = (* channel->funcs->io_get_flags) (channel); @@ -707,29 +1004,79 @@ g_io_channel_get_flags (GIOChannel *channel) if (channel->is_readable) flags |= G_IO_FLAG_IS_READABLE; if (channel->is_writeable) - flags |= G_IO_FLAG_IS_WRITEABLE; + flags |= G_IO_FLAG_IS_WRITABLE; return flags; } /** + * g_io_channel_set_close_on_unref: + * @channel: a #GIOChannel + * @do_close: Whether to close the channel on the final unref of + * the GIOChannel data structure. The default value of + * this is %TRUE for channels created by g_io_channel_new_file (), + * and %FALSE for all other channels. + * + * Setting this flag to %TRUE for a channel you have already closed + * can cause problems. + **/ +void +g_io_channel_set_close_on_unref (GIOChannel *channel, + gboolean do_close) +{ + g_return_if_fail (channel != NULL); + + channel->close_on_unref = do_close; +} + +/** + * g_io_channel_get_close_on_unref: + * @channel: a #GIOChannel. + * + * Returns whether the file/socket/whatever associated with @channel + * will be closed when @channel receives its final unref and is + * destroyed. The default value of this is %TRUE for channels created + * by g_io_channel_new_file (), and %FALSE for all other channels. + * + * Returns: Whether the channel will be closed on the final unref of + * the GIOChannel data structure. + **/ +gboolean +g_io_channel_get_close_on_unref (GIOChannel *channel) +{ + g_return_val_if_fail (channel != NULL, FALSE); + + return channel->close_on_unref; +} + +/** * g_io_channel_seek_position: * @channel: a #GIOChannel * @offset: The offset in bytes from the position specified by @type - * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed if - * the channel has the default encoding or the - * encoding %G_IO_CHANNEL_ENCODE_RAW for raw file access. + * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those + * cases where a call to g_io_channel_set_encoding () + * is allowed. See the documentation for + * g_io_channel_set_encoding () for details. * @error: A location to return an error of type #GIOChannelError * * Replacement for g_io_channel_seek() with the new API. * - * Return value: + * Returns: the status of the operation. + **/ +/** + * GSeekType: + * @G_SEEK_CUR: the current position in the file. + * @G_SEEK_SET: the start of the file. + * @G_SEEK_END: the end of the file. + * + * An enumeration specifying the base position for a + * g_io_channel_seek_position() operation. **/ GIOStatus -g_io_channel_seek_position (GIOChannel* channel, - glong offset, - GSeekType type, - GError **error) +g_io_channel_seek_position (GIOChannel *channel, + gint64 offset, + GSeekType type, + GError **error) { GIOStatus status; @@ -758,7 +1105,7 @@ g_io_channel_seek_position (GIOChannel* channel, offset -= channel->read_buf->len; if (channel->encoded_read_buf) { - g_assert (channel->encoded_read_buf->len == 0 && !channel->do_encode); + g_assert (channel->encoded_read_buf->len == 0 || !channel->do_encode); /* If there's anything here, it's because the encoding is UTF-8, * so we can just subtract the buffer length, the same as for @@ -818,11 +1165,11 @@ g_io_channel_seek_position (GIOChannel* channel, * @channel: a #GIOChannel * @error: location to store an error of type #GIOChannelError * - * Flush the write buffer for the GIOChannel. + * Flushes the write buffer for the GIOChannel. * - * Return value: the status of the operation: One of - * G_IO_CHANNEL_NORMAL, G_IO_CHANNEL_AGAIN, or - * G_IO_CHANNEL_ERROR. + * Returns: the status of the operation: One of + * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or + * #G_IO_STATUS_ERROR. **/ GIOStatus g_io_channel_flush (GIOChannel *channel, @@ -842,9 +1189,9 @@ g_io_channel_flush (GIOChannel *channel, g_assert (this_time > 0); status = channel->funcs->io_write (channel, - channel->write_buf->str + bytes_written, - channel->write_buf->len - bytes_written, - &this_time, error); + channel->write_buf->str + bytes_written, + channel->write_buf->len - bytes_written, + &this_time, error); bytes_written += this_time; } while ((bytes_written < channel->write_buf->len) @@ -863,11 +1210,26 @@ g_io_channel_flush (GIOChannel *channel, * The buffering state can only be set if the channel's encoding * is %NULL. For any other encoding, the channel must be buffered. * + * A buffered channel can only be set unbuffered if the channel's + * internal buffers have been flushed. Newly created channels or + * channels which have returned %G_IO_STATUS_EOF + * not require such a flush. For write-only channels, a call to + * g_io_channel_flush () is sufficient. For all other channels, + * the buffers may be flushed by a call to g_io_channel_seek_position (). + * This includes the possibility of seeking with seek type %G_SEEK_CUR + * and an offset of zero. Note that this means that socket-based + * channels cannot be set unbuffered once they have had data + * read from them. + * + * On unbuffered channels, it is safe to mix read and write + * calls from the new and old APIs, if this is necessary for + * maintaining old code. + * * The default state of the channel is buffered. **/ void -g_io_channel_set_buffered (GIOChannel *channel, - gboolean buffered) +g_io_channel_set_buffered (GIOChannel *channel, + gboolean buffered) { g_return_if_fail (channel != NULL); @@ -888,10 +1250,12 @@ g_io_channel_set_buffered (GIOChannel *channel, * g_io_channel_get_buffered: * @channel: a #GIOChannel * - * Return Value: the buffering state of the channel + * Returns whether @channel is buffered. + * + * Return Value: %TRUE if the @channel is buffered. **/ gboolean -g_io_channel_get_buffered (GIOChannel *channel) +g_io_channel_get_buffered (GIOChannel *channel) { g_return_val_if_fail (channel != NULL, FALSE); @@ -901,34 +1265,46 @@ g_io_channel_get_buffered (GIOChannel *channel) /** * g_io_channel_set_encoding: * @channel: a #GIOChannel - * @encoding: the encoding type - * @error: location to store an error of type #GConvertError. + * @encoding: (allow-none): the encoding type + * @error: location to store an error of type #GConvertError * - * Set the encoding for the input/output of the channel. The internal - * encoding is always UTF-8. The default encoding for the - * external file is UTF-8. + * Sets the encoding for the input/output of the channel. + * The internal encoding is always UTF-8. The default encoding + * for the external file is UTF-8. * * The encoding %NULL is safe to use with binary data. - * Encodings other than %NULL must use a buffered channel. - * Encodings other than %NULL and UTF-8 cannot - * use g_io_channel_seek_position() with seek type %G_SEEK_CUR, - * and cannot mix reading and writing if the channel is - * a file without first doing a seek of type %G_SEEK_SET or - * %G_SEEK_END. * - * The encoding can only be set under three conditions: + * The encoding can only be set if one of the following conditions + * is true: + * + * - The channel was just created, and has not been written to or read from yet. * - * 1. The channel was just created, and has not been written to - * or read from yet. + * - The channel is write-only. * - * 2. The channel is a file, and the file pointer was just - * repositioned by a call to g_io_channel_seek_position(). - * (This flushes all the internal buffers.) + * - The channel is a file, and the file pointer was just repositioned + * by a call to g_io_channel_seek_position(). (This flushes all the + * internal buffers.) * - * 3. The current encoding is %NULL or UTF-8. + * - The current encoding is %NULL or UTF-8. * - * Return Value: %G_IO_STATUS_NORMAL if the encoding was succesfully set. - **/ + * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF + * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). + * + * - One of the functions g_io_channel_read_chars() or + * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or + * %G_IO_STATUS_ERROR. This may be useful in the case of + * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. + * Returning one of these statuses from g_io_channel_read_line(), + * g_io_channel_read_line_string(), or g_io_channel_read_to_end() + * does not guarantee that the encoding can be changed. + * + * Channels which do not meet one of the above conditions cannot call + * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if + * they are "seekable", cannot call g_io_channel_write_chars() after + * calling one of the API "read" functions. + * + * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set + */ GIOStatus g_io_channel_set_encoding (GIOChannel *channel, const gchar *encoding, @@ -978,8 +1354,8 @@ g_io_channel_set_encoding (GIOChannel *channel, if (read_cd == (GIConv) -1) { err = errno; - from_enc = "UTF-8"; - to_enc = encoding; + from_enc = encoding; + to_enc = "UTF-8"; } } else @@ -992,8 +1368,8 @@ g_io_channel_set_encoding (GIOChannel *channel, if (write_cd == (GIConv) -1) { err = errno; - from_enc = encoding; - to_enc = "UTF-8"; + from_enc = "UTF-8"; + to_enc = encoding; } } else @@ -1006,12 +1382,12 @@ g_io_channel_set_encoding (GIOChannel *channel, if (err == EINVAL) g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_CONVERSION, - _("Conversion from character set `%s' to `%s' is not supported"), + _("Conversion from character set '%s' to '%s' is not supported"), from_enc, to_enc); else g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED, - _("Could not open converter from `%s' to `%s': %s"), - from_enc, to_enc, strerror (errno)); + _("Could not open converter from '%s' to '%s': %s"), + from_enc, to_enc, g_strerror (err)); if (read_cd != (GIConv) -1) g_iconv_close (read_cd); @@ -1057,17 +1433,15 @@ g_io_channel_set_encoding (GIOChannel *channel, * g_io_channel_get_encoding: * @channel: a #GIOChannel * - * Get the encoding for the input/output of the channel. The internal - * encoding is always UTF-8. The encoding %G_IO_CHANNEL_ENCODE_RAW - * disables encoding and turns off internal buffering. Both - * %G_IO_CHANNEL_ENCODE_RAW and the default (no encoding, but buffered) - * are safe to use with binary data. + * Gets the encoding for the input/output of the channel. + * The internal encoding is always UTF-8. The encoding %NULL + * makes the channel safe for binary data. * - * Return value: A string containing the encoding, this string is + * Returns: A string containing the encoding, this string is * owned by GLib and must not be freed. **/ -G_CONST_RETURN gchar* -g_io_channel_get_encoding (GIOChannel *channel) +const gchar * +g_io_channel_get_encoding (GIOChannel *channel) { g_return_val_if_fail (channel != NULL, NULL); @@ -1075,8 +1449,8 @@ g_io_channel_get_encoding (GIOChannel *channel) } static GIOStatus -g_io_channel_fill_buffer (GIOChannel *channel, - GError **err) +g_io_channel_fill_buffer (GIOChannel *channel, + GError **err) { gsize read_size, cur_len, oldlen; GIOStatus status; @@ -1107,8 +1481,8 @@ g_io_channel_fill_buffer (GIOChannel *channel, g_string_truncate (channel->read_buf, read_size + cur_len); - if ((status != G_IO_STATUS_NORMAL) - && ((status != G_IO_STATUS_EOF) || (channel->read_buf->len == 0))) + if ((status != G_IO_STATUS_NORMAL) && + ((status != G_IO_STATUS_EOF) || (channel->read_buf->len == 0))) return status; g_assert (channel->read_buf->len > 0); @@ -1124,36 +1498,43 @@ g_io_channel_fill_buffer (GIOChannel *channel, if (channel->do_encode) { - size_t errnum, inbytes_left, outbytes_left; + gsize errnum, inbytes_left, outbytes_left; gchar *inbuf, *outbuf; + int errval; g_assert (channel->encoded_read_buf); reencode: inbytes_left = channel->read_buf->len; - outbytes_left = MIN (channel->buf_size / 4, + outbytes_left = MAX (channel->read_buf->len, channel->encoded_read_buf->allocated_len - - channel->encoded_read_buf->len); + - channel->encoded_read_buf->len - 1); /* 1 for NULL */ + outbytes_left = MAX (outbytes_left, 6); + inbuf = channel->read_buf->str; g_string_set_size (channel->encoded_read_buf, channel->encoded_read_buf->len + outbytes_left); - - inbuf = channel->read_buf->str; outbuf = channel->encoded_read_buf->str + channel->encoded_read_buf->len - outbytes_left; errnum = g_iconv (channel->read_cd, &inbuf, &inbytes_left, &outbuf, &outbytes_left); + errval = errno; + + g_assert (inbuf + inbytes_left == channel->read_buf->str + + channel->read_buf->len); + g_assert (outbuf + outbytes_left == channel->encoded_read_buf->str + + channel->encoded_read_buf->len); g_string_erase (channel->read_buf, 0, channel->read_buf->len - inbytes_left); g_string_truncate (channel->encoded_read_buf, channel->encoded_read_buf->len - outbytes_left); - if (errnum == (size_t) -1) + if (errnum == (gsize) -1) { - switch (errno) + switch (errval) { case EINVAL: if ((oldlen == channel->encoded_read_buf->len) @@ -1163,21 +1544,24 @@ reencode: status = G_IO_STATUS_NORMAL; break; case E2BIG: + /* Buffer size at least 6, wrote at least on character */ + g_assert (inbuf != channel->read_buf->str); goto reencode; case EILSEQ: if (oldlen < channel->encoded_read_buf->len) status = G_IO_STATUS_NORMAL; else { - g_set_error (err, G_CONVERT_ERROR, + g_set_error_literal (err, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE, _("Invalid byte sequence in conversion input")); return G_IO_STATUS_ERROR; } break; default: + g_assert (errval != EBADF); /* The converter should be open */ g_set_error (err, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED, - _("Error during conversion: %s"), strerror (errno)); + _("Error during conversion: %s"), g_strerror (errval)); return G_IO_STATUS_ERROR; } } @@ -1206,11 +1590,11 @@ reencode: lastchar = nextchar; break; case -1: - if (oldlen > channel->encoded_read_buf->len) + if (oldlen < channel->encoded_read_buf->len) status = G_IO_STATUS_NORMAL; else { - g_set_error (err, G_CONVERT_ERROR, + g_set_error_literal (err, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE, _("Invalid byte sequence in conversion input")); status = G_IO_STATUS_ERROR; @@ -1239,30 +1623,28 @@ reencode: /** * g_io_channel_read_line: * @channel: a #GIOChannel - * @str_return: The line read from the #GIOChannel, not including the + * @str_return: (out): The line read from the #GIOChannel, including the * line terminator. This data should be freed with g_free() - * when no longer needed. This - * is a null terminated string. If a @length of zero is - * returned, this will be %NULL instead. - * @length: location to store length of the read data, or %NULL - * @terminator_pos: location to store position of line terminator, or %NULL + * when no longer needed. This is a nul-terminated string. + * If a @length of zero is returned, this will be %NULL instead. + * @length: (allow-none) (out): location to store length of the read data, or %NULL + * @terminator_pos: (allow-none) (out): location to store position of line terminator, or %NULL * @error: A location to return an error of type #GConvertError * or #GIOChannelError * - * Read a line, not including the terminating character(s), - * from a #GIOChannel into a newly allocated string. - * @length will contain allocated memory if the return + * Reads a line, including the terminating character(s), + * from a #GIOChannel into a newly-allocated string. + * @str_return will contain allocated memory if the return * is %G_IO_STATUS_NORMAL. * - * Return value: a newly allocated string. Free this string - * with g_free() when you are done with it. + * Returns: the status of the operation. **/ GIOStatus -g_io_channel_read_line (GIOChannel *channel, - gchar **str_return, - gsize *length, - gsize *terminator_pos, - GError **error) +g_io_channel_read_line (GIOChannel *channel, + gchar **str_return, + gsize *length, + gsize *terminator_pos, + GError **error) { GIOStatus status; gsize got_length; @@ -1275,7 +1657,7 @@ g_io_channel_read_line (GIOChannel *channel, status = g_io_channel_read_line_backend (channel, &got_length, terminator_pos, error); - if (length) + if (length && status != G_IO_STATUS_ERROR) *length = got_length; if (status == G_IO_STATUS_NORMAL) @@ -1294,21 +1676,21 @@ g_io_channel_read_line (GIOChannel *channel, * g_io_channel_read_line_string: * @channel: a #GIOChannel * @buffer: a #GString into which the line will be written. - * If @buffer already contains data, the new data will - * be appended to it. - * @terminator_pos: location to store position of line terminator, or %NULL + * If @buffer already contains data, the old data will + * be overwritten. + * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL * @error: a location to store an error of type #GConvertError * or #GIOChannelError * - * Read a line from a #GIOChannel, using a #GString as a buffer. + * Reads a line from a #GIOChannel, using a #GString as a buffer. * - * Return value: + * Returns: the status of the operation. **/ GIOStatus -g_io_channel_read_line_string (GIOChannel *channel, - GString *buffer, - gsize *terminator_pos, - GError **error) +g_io_channel_read_line_string (GIOChannel *channel, + GString *buffer, + gsize *terminator_pos, + GError **error) { gsize length; GIOStatus status; @@ -1336,10 +1718,10 @@ g_io_channel_read_line_string (GIOChannel *channel, static GIOStatus -g_io_channel_read_line_backend (GIOChannel *channel, - gsize *length, - gsize *terminator_pos, - GError **error) +g_io_channel_read_line_backend (GIOChannel *channel, + gsize *length, + gsize *terminator_pos, + GError **error) { GIOStatus status; gsize checked_to, line_term_len, line_length, got_term_len; @@ -1348,15 +1730,15 @@ g_io_channel_read_line_backend (GIOChannel *channel, if (!channel->use_buffer) { /* Can't do a raw read in read_line */ - g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED, - _("Can't do a raw read in g_io_channel_read_line_string")); + g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED, + _("Can't do a raw read in g_io_channel_read_line_string")); return G_IO_STATUS_ERROR; } status = G_IO_STATUS_NORMAL; if (channel->line_term) - line_term_len = strlen (channel->line_term); + line_term_len = channel->line_term_len; else line_term_len = 3; /* This value used for setting checked_to, it's the longest of the four @@ -1394,9 +1776,10 @@ read_again: if (channel->encoding && channel->read_buf->len != 0) { - g_set_error (error, G_CONVERT_ERROR, - G_CONVERT_ERROR_PARTIAL_INPUT, - "Leftover unconverted data in read buffer"); + g_set_error_literal (error, G_CONVERT_ERROR, + G_CONVERT_ERROR_PARTIAL_INPUT, + _("Leftover unconverted data in " + "read buffer")); return G_IO_STATUS_ERROR; } else @@ -1416,14 +1799,14 @@ read_again: first_time = FALSE; - lastchar = use_buf->str + strlen (use_buf->str); + lastchar = use_buf->str + use_buf->len; for (nextchar = use_buf->str + checked_to; nextchar < lastchar; channel->encoding ? nextchar = g_utf8_next_char (nextchar) : nextchar++) { if (channel->line_term) { - if (strncmp (channel->line_term, nextchar, line_term_len) == 0) + if (memcmp (channel->line_term, nextchar, line_term_len) == 0) { line_length = nextchar - use_buf->str; got_term_len = line_term_len; @@ -1456,22 +1839,18 @@ read_again: goto done; } break; + case '\0': /* Embeded null in input */ + line_length = nextchar - use_buf->str; + got_term_len = 1; + goto done; default: /* no match */ break; } } } - g_assert (nextchar == lastchar); /* Valid UTF-8, didn't overshoot */ - - /* Also terminate on '\0' */ - - line_length = lastchar - use_buf->str; - if (line_length < use_buf->len) - { - got_term_len = 0; - break; - } + /* If encoding != NULL, valid UTF-8, didn't overshoot */ + g_assert (nextchar == lastchar); /* Check for EOF */ @@ -1479,8 +1858,8 @@ read_again: { if (channel->encoding && channel->read_buf->len > 0) { - g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT, - "Channel terminates in a partial character"); + g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT, + _("Channel terminates in a partial character")); return G_IO_STATUS_ERROR; } line_length = use_buf->len; @@ -1508,26 +1887,25 @@ done: /** * g_io_channel_read_to_end: * @channel: a #GIOChannel - * @str_return: Location to store a pointer to a string holding - * the remaining data in the #GIOChannel. This data should - * be freed with g_free() when no longer needed. This - * data is terminated by an extra null, but there may be other - * nulls in the intervening data. - * @length: Location to store length of the data - * @error: A location to return an error of type #GConvertError + * @str_return: (out) (array length=length) (element-type guint8): Location to + * store a pointer to a string holding the remaining data in the + * #GIOChannel. This data should be freed with g_free() when no + * longer needed. This data is terminated by an extra nul + * character, but there may be other nuls in the intervening data. + * @length: (out): location to store length of the data + * @error: location to return an error of type #GConvertError * or #GIOChannelError * - * Read all the remaining data from the file. Parameters as - * for g_io_channel_read_line. + * Reads all the remaining data from the file. * - * Return value: One of #G_IO_STATUS_EOF or #G_IO_STATUS_PARTIAL_CHARS - * on success + * Returns: %G_IO_STATUS_NORMAL on success. + * This function never returns %G_IO_STATUS_EOF. **/ GIOStatus -g_io_channel_read_to_end (GIOChannel *channel, - gchar **str_return, - gsize *length, - GError **error) +g_io_channel_read_to_end (GIOChannel *channel, + gchar **str_return, + gsize *length, + GError **error) { GIOStatus status; @@ -1543,8 +1921,8 @@ g_io_channel_read_to_end (GIOChannel *channel, if (!channel->use_buffer) { - g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED, - _("Can't do a raw read in g_io_channel_read_to_end")); + g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED, + _("Can't do a raw read in g_io_channel_read_to_end")); return G_IO_STATUS_ERROR; } @@ -1557,8 +1935,8 @@ g_io_channel_read_to_end (GIOChannel *channel, if (channel->encoding && channel->read_buf->len > 0) { - g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT, - "Channel terminates in a partial character"); + g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT, + _("Channel terminates in a partial character")); return G_IO_STATUS_ERROR; } @@ -1578,8 +1956,10 @@ g_io_channel_read_to_end (GIOChannel *channel, else g_string_free (USE_BUF (channel), TRUE); - /* This only works because USE_BUF () is a macro */ - USE_BUF (channel) = NULL; + if (channel->encoding) + channel->encoded_read_buf = NULL; + else + channel->read_buf = NULL; } return G_IO_STATUS_NORMAL; @@ -1588,46 +1968,56 @@ g_io_channel_read_to_end (GIOChannel *channel, /** * g_io_channel_read_chars: * @channel: a #GIOChannel - * @buf: a buffer to read data into - * @count: the size of the buffer. Note that the buffer may - * not be complelely filled even if there is data - * in the buffer if the remaining data is not a - * complete character. - * @bytes_read: The number of bytes read. - * @error: A location to return an error of type #GConvertError - * or #GIOChannelError. + * @buf: (out caller-allocates) (array length=count) (element-type guint8): + * a buffer to read data into + * @count: (in): the size of the buffer. Note that the buffer may not be + * complelely filled even if there is data in the buffer if the + * remaining data is not a complete character. + * @bytes_read: (allow-none) (out): The number of bytes read. This may be + * zero even on success if count < 6 and the channel's encoding + * is non-%NULL. This indicates that the next UTF-8 character is + * too wide for the buffer. + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError. * * Replacement for g_io_channel_read() with the new API. * - * Return value: - **/ + * Returns: the status of the operation. + */ GIOStatus -g_io_channel_read_chars (GIOChannel *channel, - gchar *buf, - gsize count, - gsize *bytes_read, - GError **error) +g_io_channel_read_chars (GIOChannel *channel, + gchar *buf, + gsize count, + gsize *bytes_read, + GError **error) { GIOStatus status; gsize got_bytes; g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR); - g_return_val_if_fail ((error == NULL) || (*error == NULL), - G_IO_STATUS_ERROR); + g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR); g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR); if (count == 0) { - *bytes_read = 0; + if (bytes_read) + *bytes_read = 0; return G_IO_STATUS_NORMAL; } g_return_val_if_fail (buf != NULL, G_IO_STATUS_ERROR); if (!channel->use_buffer) { + gsize tmp_bytes; + g_assert (!channel->read_buf || channel->read_buf->len == 0); - return channel->funcs->io_read (channel, buf, count, bytes_read, error); + status = channel->funcs->io_read (channel, buf, count, &tmp_bytes, error); + + if (bytes_read) + *bytes_read = tmp_bytes; + + return status; } status = G_IO_STATUS_NORMAL; @@ -1644,9 +2034,9 @@ g_io_channel_read_chars (GIOChannel *channel, if (status == G_IO_STATUS_EOF && channel->encoding && BUF_LEN (channel->read_buf) > 0) { - g_set_error (error, G_CONVERT_ERROR, - G_CONVERT_ERROR_PARTIAL_INPUT, - "Leftover unconverted data in read buffer"); + g_set_error_literal (error, G_CONVERT_ERROR, + G_CONVERT_ERROR_PARTIAL_INPUT, + _("Leftover unconverted data in read buffer")); status = G_IO_STATUS_ERROR; } @@ -1676,6 +2066,7 @@ g_io_channel_read_chars (GIOChannel *channel, { prevchar = nextchar; nextchar = g_utf8_next_char (nextchar); + g_assert (nextchar != prevchar); /* Possible for *prevchar of -1 or -2 */ } while (nextchar < channel->encoded_read_buf->str + got_bytes); @@ -1695,32 +2086,100 @@ g_io_channel_read_chars (GIOChannel *channel, } /** + * g_io_channel_read_unichar: + * @channel: a #GIOChannel + * @thechar: (out): a location to return a character + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError + * + * Reads a Unicode character from @channel. + * This function cannot be called on a channel with %NULL encoding. + * + * Returns: a #GIOStatus + **/ +GIOStatus +g_io_channel_read_unichar (GIOChannel *channel, + gunichar *thechar, + GError **error) +{ + GIOStatus status = G_IO_STATUS_NORMAL; + + g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR); + g_return_val_if_fail (channel->encoding != NULL, G_IO_STATUS_ERROR); + g_return_val_if_fail ((error == NULL) || (*error == NULL), + G_IO_STATUS_ERROR); + g_return_val_if_fail (channel->is_readable, G_IO_STATUS_ERROR); + + while (BUF_LEN (channel->encoded_read_buf) == 0 && status == G_IO_STATUS_NORMAL) + status = g_io_channel_fill_buffer (channel, error); + + /* Only return an error if we have no data */ + + if (BUF_LEN (USE_BUF (channel)) == 0) + { + g_assert (status != G_IO_STATUS_NORMAL); + + if (status == G_IO_STATUS_EOF && BUF_LEN (channel->read_buf) > 0) + { + g_set_error_literal (error, G_CONVERT_ERROR, + G_CONVERT_ERROR_PARTIAL_INPUT, + _("Leftover unconverted data in read buffer")); + status = G_IO_STATUS_ERROR; + } + + if (thechar) + *thechar = (gunichar) -1; + + return status; + } + + if (status == G_IO_STATUS_ERROR) + g_clear_error (error); + + if (thechar) + *thechar = g_utf8_get_char (channel->encoded_read_buf->str); + + g_string_erase (channel->encoded_read_buf, 0, + g_utf8_next_char (channel->encoded_read_buf->str) + - channel->encoded_read_buf->str); + + return G_IO_STATUS_NORMAL; +} + +/** * g_io_channel_write_chars: * @channel: a #GIOChannel - * @buf: a buffer to write data from + * @buf: (array) (element-type guint8): a buffer to write data from * @count: the size of the buffer. If -1, the buffer - * is taken to be a nul terminated string. - * @bytes_written: The number of bytes written. This can be nonzero + * is taken to be a nul-terminated string. + * @bytes_written: (out): The number of bytes written. This can be nonzero * even if the return value is not %G_IO_STATUS_NORMAL. - * @error: A location to return an error of type #GConvertError + * If the return value is %G_IO_STATUS_NORMAL and the + * channel is blocking, this will always be equal + * to @count if @count >= 0. + * @error: a location to return an error of type #GConvertError * or #GIOChannelError * * Replacement for g_io_channel_write() with the new API. * - * Return value: + * On seekable channels with encodings other than %NULL or UTF-8, generic + * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars () + * may only be made on a channel from which data has been read in the + * cases described in the documentation for g_io_channel_set_encoding (). + * + * Returns: the status of the operation. **/ GIOStatus -g_io_channel_write_chars (GIOChannel *channel, - const gchar *buf, - gssize count, - gsize *bytes_written, - GError **error) +g_io_channel_write_chars (GIOChannel *channel, + const gchar *buf, + gssize count, + gsize *bytes_written, + GError **error) { GIOStatus status; gssize wrote_bytes = 0; g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR); - g_return_val_if_fail (bytes_written != NULL, G_IO_STATUS_ERROR); g_return_val_if_fail ((error == NULL) || (*error == NULL), G_IO_STATUS_ERROR); g_return_val_if_fail (channel->is_writeable, G_IO_STATUS_ERROR); @@ -1729,7 +2188,11 @@ g_io_channel_write_chars (GIOChannel *channel, count = strlen (buf); if (count == 0) - return G_IO_STATUS_NORMAL; + { + if (bytes_written) + *bytes_written = 0; + return G_IO_STATUS_NORMAL; + } g_return_val_if_fail (buf != NULL, G_IO_STATUS_ERROR); g_return_val_if_fail (count > 0, G_IO_STATUS_ERROR); @@ -1738,9 +2201,17 @@ g_io_channel_write_chars (GIOChannel *channel, if (!channel->use_buffer) { + gsize tmp_bytes; + g_assert (!channel->write_buf || channel->write_buf->len == 0); g_assert (channel->partial_write_buf[0] == '\0'); - return channel->funcs->io_write (channel, buf, count, bytes_written, error); + + status = channel->funcs->io_write (channel, buf, count, &tmp_bytes, error); + + if (bytes_written) + *bytes_written = tmp_bytes; + + return status; } /* General case */ @@ -1755,7 +2226,11 @@ g_io_channel_write_chars (GIOChannel *channel, } status = g_io_channel_seek_position (channel, 0, G_SEEK_CUR, error); if (status != G_IO_STATUS_NORMAL) - return status; + { + if (bytes_written) + *bytes_written = 0; + return status; + } } if (!channel->write_buf) @@ -1771,7 +2246,7 @@ g_io_channel_write_chars (GIOChannel *channel, * and never receiving an EAGAIN. */ - if (channel->write_buf->len >= channel->buf_size) + if (channel->write_buf->len >= channel->buf_size - MAX_CHAR_SIZE) { gsize did_write = 0, this_time; @@ -1783,8 +2258,7 @@ g_io_channel_write_chars (GIOChannel *channel, did_write += this_time; } while (status == G_IO_STATUS_NORMAL && - did_write < MIN (channel->write_buf->len, - MAX (MAX_CHAR_SIZE, channel->buf_size / 4))); + did_write < MIN (channel->write_buf->len, MAX_CHAR_SIZE)); g_string_erase (channel->write_buf, 0, did_write); @@ -1798,8 +2272,8 @@ g_io_channel_write_chars (GIOChannel *channel, } } - space_in_buf = MAX (channel->buf_size, channel->write_buf->allocated_len) - - channel->write_buf->len; + space_in_buf = MAX (channel->buf_size, channel->write_buf->allocated_len - 1) + - channel->write_buf->len; /* 1 for NULL */ /* This is only true because g_io_channel_set_buffer_size () * ensures that channel->buf_size >= MAX_CHAR_SIZE. @@ -1818,7 +2292,7 @@ g_io_channel_write_chars (GIOChannel *channel, { const gchar *from_buf; gsize from_buf_len, from_buf_old_len, left_len; - size_t err; + gsize err; gint errnum; if (channel->partial_write_buf[0] != '\0') @@ -1842,40 +2316,54 @@ g_io_channel_write_chars (GIOChannel *channel, reconvert: - if (!channel->do_encode) + if (!channel->do_encode) /* UTF-8 encoding */ { const gchar *badchar; + gsize try_len = MIN (from_buf_len, space_in_buf); /* UTF-8, just validate, emulate g_iconv */ - if (!g_utf8_validate (from_buf, from_buf_len, &badchar)) + if (!g_utf8_validate (from_buf, try_len, &badchar)) { gunichar try_char; + gsize incomplete_len = from_buf + try_len - badchar; left_len = from_buf + from_buf_len - badchar; - try_char = g_utf8_get_char_validated (badchar, left_len); + try_char = g_utf8_get_char_validated (badchar, incomplete_len); switch (try_char) { case -2: - g_assert (left_len < 6); - errnum = EINVAL; + g_assert (incomplete_len < 6); + if (try_len == from_buf_len) + { + errnum = EINVAL; + err = (gsize) -1; + } + else + { + errnum = 0; + err = (gsize) 0; + } break; case -1: + g_warning ("Invalid UTF-8 passed to g_io_channel_write_chars()."); + /* FIXME bail here? */ errnum = EILSEQ; + err = (gsize) -1; break; default: g_assert_not_reached (); + err = (gsize) -1; errnum = 0; /* Don't confunse the compiler */ } - err = (size_t) -1; } else { - err = (size_t) 0; + err = (gsize) 0; errnum = 0; - left_len = 0; + left_len = from_buf_len - try_len; } g_string_append_len (channel->write_buf, from_buf, @@ -1887,9 +2375,10 @@ reconvert: gchar *outbuf; left_len = from_buf_len; - outbuf = channel->write_buf->str + channel->write_buf->len; g_string_set_size (channel->write_buf, channel->write_buf->len + space_in_buf); + outbuf = channel->write_buf->str + channel->write_buf->len + - space_in_buf; err = g_iconv (channel->write_cd, (gchar **) &from_buf, &left_len, &outbuf, &space_in_buf); errnum = errno; @@ -1897,7 +2386,7 @@ reconvert: - space_in_buf); } - if (err == (size_t) -1) + if (err == (gsize) -1) { switch (errnum) { @@ -1910,6 +2399,8 @@ reconvert: memcpy (channel->partial_write_buf, from_buf, left_len); channel->partial_write_buf[left_len] = '\0'; + if (bytes_written) + *bytes_written = count; return G_IO_STATUS_NORMAL; } @@ -1947,7 +2438,7 @@ reconvert: } break; case EILSEQ: - g_set_error (error, G_CONVERT_ERROR, + g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE, _("Invalid byte sequence in conversion input")); if (from_buf_old_len > 0 && from_buf_len == left_len) @@ -1961,7 +2452,7 @@ reconvert: return G_IO_STATUS_ERROR; default: g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED, - _("Error during conversion: %s"), strerror (errno)); + _("Error during conversion: %s"), g_strerror (errnum)); if (from_buf_len >= left_len + from_buf_old_len) wrote_bytes += from_buf_len - left_len - from_buf_old_len; if (bytes_written) @@ -1988,23 +2479,76 @@ reconvert: } if (bytes_written) - *bytes_written = wrote_bytes; + *bytes_written = count; return G_IO_STATUS_NORMAL; } - /** - * g_io_channel_error_quark: + * g_io_channel_write_unichar: + * @channel: a #GIOChannel + * @thechar: a character + * @error: location to return an error of type #GConvertError + * or #GIOChannelError * - * Return value: The quark used as %G_IO_CHANNEL_ERROR + * Writes a Unicode character to @channel. + * This function cannot be called on a channel with %NULL encoding. + * + * Returns: a #GIOStatus **/ -GQuark -g_io_channel_error_quark (void) +GIOStatus +g_io_channel_write_unichar (GIOChannel *channel, + gunichar thechar, + GError **error) { - static GQuark q = 0; - if (q == 0) - q = g_quark_from_static_string ("g-io-channel-error-quark"); + GIOStatus status; + gchar static_buf[6]; + gsize char_len, wrote_len; + + g_return_val_if_fail (channel != NULL, G_IO_STATUS_ERROR); + g_return_val_if_fail (channel->encoding != NULL, G_IO_STATUS_ERROR); + g_return_val_if_fail ((error == NULL) || (*error == NULL), + G_IO_STATUS_ERROR); + g_return_val_if_fail (channel->is_writeable, G_IO_STATUS_ERROR); + + char_len = g_unichar_to_utf8 (thechar, static_buf); - return q; + if (channel->partial_write_buf[0] != '\0') + { + g_warning ("Partial charater written before writing unichar.\n"); + channel->partial_write_buf[0] = '\0'; + } + + status = g_io_channel_write_chars (channel, static_buf, + char_len, &wrote_len, error); + + /* We validate UTF-8, so we can't get a partial write */ + + g_assert (wrote_len == char_len || status != G_IO_STATUS_NORMAL); + + return status; } + +/** + * G_IO_CHANNEL_ERROR: + * + * Error domain for #GIOChannel operations. Errors in this domain will + * be from the #GIOChannelError enumeration. See #GError for + * information on error domains. + **/ +/** + * GIOChannelError: + * @G_IO_CHANNEL_ERROR_FBIG: File too large. + * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument. + * @G_IO_CHANNEL_ERROR_IO: IO error. + * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory. + * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device. + * @G_IO_CHANNEL_ERROR_NXIO: No such device or address. + * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype. + * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe. + * @G_IO_CHANNEL_ERROR_FAILED: Some other error. + * + * Error codes returned by #GIOChannel operations. + **/ + +G_DEFINE_QUARK (g-io-channel-error-quark, g_io_channel_error)