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

@@ -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

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>)".