[glib] gstrfuncs: Expand documentation for errno functions

[Philip Withnall <pwithnall src gnome org>]

commit f2b6c116295e87d1b74ecae86eda0d1a040b936c
Author: Philip Withnall <withnall endlessm com>
Date:   Mon Jul 31 12:16:44 2017 +0100

    gstrfuncs: Expand documentation for errno functions
    
    Mention that it really is a good idea to save errno before doing
    literally anything else after calling a function which could set it.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://bugzilla.gnome.org/show_bug.cgi?id=785577

 gio/gioerror.c   |   12 ++++++++++++
 glib/gstrfuncs.c |   12 +++++++++++-
 2 files changed, 23 insertions(+), 1 deletions(-)
---
diff --git a/gio/gioerror.c b/gio/gioerror.c
index ccdd67d..900553e 100644
--- a/gio/gioerror.c
+++ b/gio/gioerror.c
@@ -52,6 +52,18 @@ G_DEFINE_QUARK (g-io-error-quark, g_io_error)
  * handled (but note that future GLib releases may return a more
  * specific value instead).
  *
+ * As %errno is global and may be modified by intermediate function
+ * calls, you should save its value as soon as the call which sets it
+ * returns:
+ * |[
+ *   int saved_errno;
+ *
+ *   ret = read (blah);
+ *   saved_errno = errno;
+ *
+ *   g_io_error_from_errno (saved_errno);
+ * ]|
+ *
  * Returns: #GIOErrorEnum value for the given errno.h error number.
  **/
 GIOErrorEnum
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index cf89bf5..fbcca14 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -1245,7 +1245,17 @@ g_ascii_strtoll (const gchar *nptr,
  *
  * Note that the string may be translated according to the current locale.
  *
- * The value of %errno will not be changed by this function.
+ * The value of %errno will not be changed by this function. However, it may
+ * be changed by intermediate function calls, so you should save its value
+ * as soon as the call returns:
+ * |[
+ *   int saved_errno;
+ *
+ *   ret = read (blah);
+ *   saved_errno = errno;
+ *
+ *   g_strerror (saved_errno);
+ * ]|
  *
  * Returns: a UTF-8 string describing the error code. If the error code
  *     is unknown, it returns a string like "unknown error (<code>)".