diff --git a/gio/gioerror.c b/gio/gioerror.c
index ccdd67dbc..900553e98 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 cf89bf5d0..fbcca14c0 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>)".