2007-06-18 Matthias Clasen <mclasen@redhat.com>
+ * glib/gutils.c (g_get_home_dir): Add some motivation.
+
+2007-06-18 Matthias Clasen <mclasen@redhat.com>
+
* configure.in: Bump version
* === Released 2.13.5 ===
*
* Note that in contrast to traditional UNIX tools, this function
* prefers <filename>passwd</filename> entries over the <envar>HOME</envar>
- * environment variable.
- *
- * Returns: the current user's home directory.
+ * environment variable.
+ *
+ * One of the reasons for this decision is that applications in many
+ * cases need special handling to deal with the case where
+ * <envar>HOME</envar> is
+ * <simplelist>
+ * <member>Not owned by the user</member>
+ * <member>Not writeable</member>
+ * <member>Not even readable</member>
+ * </simplelist>
+ * Since applications are in general <emphasis>not</emphasis> written
+ * to deal with these situations it was considered better to make
+ * g_get_homedir() not pay attention to <envar>HOME</envar> and to
+ * return the real home directory for the user. If applications
+ * want to pay attention to <envar>HOME</envar>, they can do:
+ * <informalexample><programlisting>
+ * const char *homedir = g_getenv ("HOME");
+ * if (!homedir)
+ * homedir = g_get_homedir (<!-- -->);
+ * </programlisting></informalexample>
+ *
+ * Returns: the current user's home directory
*/
G_CONST_RETURN gchar*
g_get_home_dir (void)