From 223b5f757fe07cdec2879315965297a31edc3478 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Mon, 29 Sep 2014 11:50:05 -0400 Subject: [PATCH] docs: explain inconsistency of _{read,write}_all() These functions are inconsistent with our normal conventions in that they set an output variable to a specified value, even in the case that an error is thrown. Document very clearly that this should be considered exceptional. https://bugzilla.gnome.org/show_bug.cgi?id=737451 --- gio/ginputstream.c | 10 ++++++++-- gio/goutputstream.c | 11 +++++++++-- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/gio/ginputstream.c b/gio/ginputstream.c index ab8ceb4db..a1ba73608 100644 --- a/gio/ginputstream.c +++ b/gio/ginputstream.c @@ -223,8 +223,14 @@ g_input_stream_read (GInputStream *stream, * read into @buffer. * * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status, @bytes_read is updated to contain - * the number of bytes read into @buffer before the error occurred. + * is set to indicate the error status. + * + * As a special exception to the normal conventions for functions that + * use #GError, if this function returns %FALSE (and sets @error) then + * @bytes_read will be set to the number of bytes that were successfully + * read before the error was encountered. This functionality is only + * available from C. If you need it from another language then you must + * write your own loop around g_input_stream_read(). * * Returns: %TRUE on success, %FALSE if there was an error **/ diff --git a/gio/goutputstream.c b/gio/goutputstream.c index dc15ff8cd..2bec89e7e 100644 --- a/gio/goutputstream.c +++ b/gio/goutputstream.c @@ -246,8 +246,15 @@ g_output_stream_write (GOutputStream *stream, * is set to @count. * * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status, @bytes_written is updated to contain - * the number of bytes written into the stream before the error occurred. + * is set to indicate the error status. + * + * As a special exception to the normal conventions for functions that + * use #GError, if this function returns %FALSE (and sets @error) then + * @bytes_written will be set to the number of bytes that were + * successfully written before the error was encountered. This + * functionality is only available from C. If you need it from another + * language then you must write your own loop around + * g_output_stream_write(). * * Returns: %TRUE on success, %FALSE if there was an error **/