* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
- * version 2 of the License, or (at your option) any later version.
+ * version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
*
* The #GIOChannel data type aims to provide a portable method for
* using file descriptors, pipes, and sockets, and integrating them
- * into the <link linkend="glib-The-Main-Event-Loop">main event
- * loop</link>. Currently full support is available on UNIX platforms,
- * support for Windows is only partially complete.
+ * 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,
* g_io_channel_write_chars(), g_io_channel_seek_position(), and
* g_io_channel_shutdown().
*
- * To add a #GIOChannel to the <link
- * linkend="glib-The-Main-Event-Loop">main event loop</link> use
- * g_io_add_watch() or g_io_add_watch_full(). Here you specify which
+ * 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
+ * #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
* 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
+ * @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.
*
* 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.
**/
*
* 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.
**/
* 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.
**/
/**
* g_io_channel_new_file:
- * @filename: A string containing the name of a file
+ * @filename: (type 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_FILE_ERROR
* 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.
**/
/**
* flushed if @flush is %TRUE. The channel will not be freed until the
* last reference is dropped using g_io_channel_unref().
*
- * Return value: the status of the operation.
+ * Returns: the status of the operation.
**/
GIOStatus
g_io_channel_shutdown (GIOChannel *channel,
}
/**
- * g_io_add_watch_full:
+ * g_io_add_watch_full: (rename-to g_io_add_watch)
* @channel: a #GIOChannel
* @priority: the priority of the #GIOChannel source
* @condition: the condition to watch for
* 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,
* 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)
/**
* g_io_channel_error_from_errno:
- * @en: an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal>
+ * @en: an `errno` error number, e.g. `EINVAL`
*
- * Converts an <literal>errno</literal> error number to a #GIOChannelError.
+ * Converts an `errno` error number to a #GIOChannelError.
*
- * Return value: a #GIOChannelError error number, e.g.
+ * Returns: a #GIOChannelError error number, e.g.
* %G_IO_CHANNEL_ERROR_INVAL.
**/
GIOChannelError
*
* 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_set_line_term:
* @channel: a #GIOChannel
- * @line_term: (allow-none): The line termination string. Use %NULL for
+ * @line_term: (nullable): 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.
* where in the file a line break occurs. A value of %NULL
* 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.
**/
const gchar *
*
* Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
*
- * Return value: the status of the operation.
+ * Returns: the status of the operation.
**/
/**
* GIOFlags:
* 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
+ * @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,
* should immediately call g_io_channel_get_flags() to update
* the internal values of these flags.
*
- * Return value: the flags which are set on the channel
+ * Returns: the flags which are set on the channel
**/
GIOFlags
g_io_channel_get_flags (GIOChannel *channel)
* destroyed. The default value of this is %TRUE for channels created
* by g_io_channel_new_file (), and %FALSE for all other channels.
*
- * Return value: Whether the channel will be closed on the final unref of
+ * Returns: Whether the channel will be closed on the final unref of
* the GIOChannel data structure.
**/
gboolean
*
* Replacement for g_io_channel_seek() with the new API.
*
- * Return value: the status of the operation.
+ * Returns: the status of the operation.
**/
/**
* GSeekType:
*
* Flushes the write buffer for the GIOChannel.
*
- * Return value: the status of the operation: One of
+ * Returns: the status of the operation: One of
* #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
* #G_IO_STATUS_ERROR.
**/
/**
* g_io_channel_set_encoding:
* @channel: a #GIOChannel
- * @encoding: (allow-none): the encoding type
+ * @encoding: (nullable): the encoding type
* @error: location to store an error of type #GConvertError
*
* Sets the encoding for the input/output of the 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"),
+ _("Could not open converter from “%s” to “%s”: %s"),
from_enc, to_enc, g_strerror (err));
if (read_cd != (GIConv) -1)
* 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.
**/
const gchar *
* line terminator. This data should be freed with g_free()
* 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
+ * @length: (out) (optional): location to store length of the read data, or %NULL
+ * @terminator_pos: (out) (optional): location to store position of line terminator, or %NULL
* @error: A location to return an error of type #GConvertError
* or #GIOChannelError
*
* @str_return will contain allocated memory if the return
* is %G_IO_STATUS_NORMAL.
*
- * Return value: the status of the operation.
+ * Returns: the status of the operation.
**/
GIOStatus
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)
* @buffer: a #GString into which the line will be written.
* If @buffer already contains data, the old data will
* be overwritten.
- * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL
+ * @terminator_pos: (nullable): location to store position of line terminator, or %NULL
* @error: a location to store an error of type #GConvertError
* or #GIOChannelError
*
* Reads a line from a #GIOChannel, using a #GString as a buffer.
*
- * Return value: the status of the operation.
+ * Returns: the status of the operation.
**/
GIOStatus
g_io_channel_read_line_string (GIOChannel *channel,
{
/* Can't do a raw read in read_line */
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"));
+ _("Can’t do a raw read in g_io_channel_read_line_string"));
return G_IO_STATUS_ERROR;
}
*
* Reads all the remaining data from the file.
*
- * Return value: %G_IO_STATUS_NORMAL on success.
+ * Returns: %G_IO_STATUS_NORMAL on success.
* This function never returns %G_IO_STATUS_EOF.
**/
GIOStatus
if (!channel->use_buffer)
{
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"));
+ _("Can’t do a raw read in g_io_channel_read_to_end"));
return G_IO_STATUS_ERROR;
}
* @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
+ * @bytes_read: (out) (optional): 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.
*
* Replacement for g_io_channel_read() with the new API.
*
- * Return value: the status of the operation.
+ * Returns: the status of the operation.
*/
GIOStatus
g_io_channel_read_chars (GIOChannel *channel,
* Reads a Unicode character from @channel.
* This function cannot be called on a channel with %NULL encoding.
*
- * Return value: a #GIOStatus
+ * Returns: a #GIOStatus
**/
GIOStatus
g_io_channel_read_unichar (GIOChannel *channel,
* 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 ().
*
- * Return value: the status of the operation.
+ * Returns: the status of the operation.
**/
GIOStatus
g_io_channel_write_chars (GIOChannel *channel,
* Writes a Unicode character to @channel.
* This function cannot be called on a channel with %NULL encoding.
*
- * Return value: a #GIOStatus
+ * Returns: a #GIOStatus
**/
GIOStatus
g_io_channel_write_unichar (GIOChannel *channel,
}
/**
- * g_io_channel_error_quark:
- *
- * Return value: the quark used as %G_IO_CHANNEL_ERROR
- **/
-/**
* G_IO_CHANNEL_ERROR:
*
* Error domain for #GIOChannel operations. Errors in this domain will
projects / platform / upstream / glib.git / blobdiff