[glib: 1/2] gutils: Document caching of XDG directory variables

[Sebastian Dröge <sdroege src gnome org>]

commit 0e6467af5de8fa346744cd3a18353fd029a6d3af
Author: Philip Withnall <pwithnall endlessos org>
Date:   Thu Jan 14 11:31:40 2021 +0000

    gutils: Document caching of XDG directory variables
    
    See: #2278.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 glib/gutils.c | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
---
diff --git a/glib/gutils.c b/glib/gutils.c
index d3e4e1953..8a5dece33 100644
--- a/glib/gutils.c
+++ b/glib/gutils.c
@@ -1732,6 +1732,9 @@ g_build_user_data_dir (void)
  * Note that in this case on Windows it will be the same
  * as what g_get_user_config_dir() returns.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename) (transfer none): a string owned by GLib that must
  *   not be modified or freed.
  *
@@ -1793,6 +1796,9 @@ g_build_user_config_dir (void)
  * Note that in this case on Windows it will be  the same
  * as what g_get_user_data_dir() returns.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename) (transfer none): a string owned by GLib that
  *   must not be modified or freed.
  * Since: 2.6
@@ -1852,6 +1858,9 @@ g_build_user_cache_dir (void)
  * `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
  * See the [documentation for 
`CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache).
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename) (transfer none): a string owned by GLib that
  *   must not be modified or freed.
  * Since: 2.6
@@ -1914,6 +1923,9 @@ g_build_user_runtime_dir (void)
  * In the case that this variable is not set, we return the value of
  * g_get_user_cache_dir(), after verifying that it exists.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename): a string owned by GLib that must not be
  *     modified or freed.
  *
@@ -2536,6 +2548,9 @@ g_build_system_data_dirs (void)
  * Note that on Windows the returned list can vary depending on where
  * this function is called.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
  *     a %NULL-terminated array of strings owned by GLib that must not be
  *     modified or freed.
@@ -2611,6 +2626,9 @@ g_build_system_config_dirs (void)
  * CSIDL_COMMON_APPDATA folder. This information will not roam and is available
  * to anyone using the computer.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
  *     a %NULL-terminated array of strings owned by GLib that must not be
  *     modified or freed.