Document that the result is guaranteed to be non-NULL.

2004-11-04  Tor Lillqvist  <tml@iki.fi>

	* glib/gconvert.c (g_filename_display_name): Document that the
	result is guaranteed to be non-NULL.

	* glib/gfileutils.c (get_contents_stdio, get_contents_regfile,
	get_contents_posix, get_contents_win32, g_file_open_tmp,
	g_file_read_link): Use g_filename_display_name() for error
	messages.
	(g_mkstemp): Document that the template should be in the GLib file
	name encoding.
	(g_file_open_tmp): Ditto. Also document that the actual name
	returned is also in the GLib file name encoding.

7 files changed, 120 insertions, 40 deletions

diff --git a/ChangeLog b/ChangeLog
index cd0fb948f..ef5c40e2d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2004-11-04  Tor Lillqvist  <tml@iki.fi>
+
+	* glib/gconvert.c (g_filename_display_name): Document that the
+	result is guaranteed to be non-NULL.
+
+	* glib/gfileutils.c (get_contents_stdio, get_contents_regfile,
+	get_contents_posix, get_contents_win32, g_file_open_tmp,
+	g_file_read_link): Use g_filename_display_name() for error
+	messages.
+	(g_mkstemp): Document that the template should be in the GLib file
+	name encoding.
+	(g_file_open_tmp): Ditto. Also document that the actual name
+	returned is also in the GLib file name encoding.
+
 2004-11-02  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gconvert.c (g_filename_display_name): New function 
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index cd0fb948f..ef5c40e2d 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,17 @@
+2004-11-04  Tor Lillqvist  <tml@iki.fi>
+
+	* glib/gconvert.c (g_filename_display_name): Document that the
+	result is guaranteed to be non-NULL.
+
+	* glib/gfileutils.c (get_contents_stdio, get_contents_regfile,
+	get_contents_posix, get_contents_win32, g_file_open_tmp,
+	g_file_read_link): Use g_filename_display_name() for error
+	messages.
+	(g_mkstemp): Document that the template should be in the GLib file
+	name encoding.
+	(g_file_open_tmp): Ditto. Also document that the actual name
+	returned is also in the GLib file name encoding.
+
 2004-11-02  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gconvert.c (g_filename_display_name): New function 
diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12
index cd0fb948f..ef5c40e2d 100644
--- a/ChangeLog.pre-2-12
+++ b/ChangeLog.pre-2-12
@@ -1,3 +1,17 @@
+2004-11-04  Tor Lillqvist  <tml@iki.fi>
+
+	* glib/gconvert.c (g_filename_display_name): Document that the
+	result is guaranteed to be non-NULL.
+
+	* glib/gfileutils.c (get_contents_stdio, get_contents_regfile,
+	get_contents_posix, get_contents_win32, g_file_open_tmp,
+	g_file_read_link): Use g_filename_display_name() for error
+	messages.
+	(g_mkstemp): Document that the template should be in the GLib file
+	name encoding.
+	(g_file_open_tmp): Ditto. Also document that the actual name
+	returned is also in the GLib file name encoding.
+
 2004-11-02  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gconvert.c (g_filename_display_name): New function 
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index cd0fb948f..ef5c40e2d 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,17 @@
+2004-11-04  Tor Lillqvist  <tml@iki.fi>
+
+	* glib/gconvert.c (g_filename_display_name): Document that the
+	result is guaranteed to be non-NULL.
+
+	* glib/gfileutils.c (get_contents_stdio, get_contents_regfile,
+	get_contents_posix, get_contents_win32, g_file_open_tmp,
+	g_file_read_link): Use g_filename_display_name() for error
+	messages.
+	(g_mkstemp): Document that the template should be in the GLib file
+	name encoding.
+	(g_file_open_tmp): Ditto. Also document that the actual name
+	returned is also in the GLib file name encoding.
+
 2004-11-02  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gconvert.c (g_filename_display_name): New function 
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index cd0fb948f..ef5c40e2d 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,17 @@
+2004-11-04  Tor Lillqvist  <tml@iki.fi>
+
+	* glib/gconvert.c (g_filename_display_name): Document that the
+	result is guaranteed to be non-NULL.
+
+	* glib/gfileutils.c (get_contents_stdio, get_contents_regfile,
+	get_contents_posix, get_contents_win32, g_file_open_tmp,
+	g_file_read_link): Use g_filename_display_name() for error
+	messages.
+	(g_mkstemp): Document that the template should be in the GLib file
+	name encoding.
+	(g_file_open_tmp): Ditto. Also document that the actual name
+	returned is also in the GLib file name encoding.
+
 2004-11-02  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gconvert.c (g_filename_display_name): New function 
diff --git a/glib/gconvert.c b/glib/gconvert.c
index c0f41bd43..0f041cde3 100644
--- a/glib/gconvert.c
+++ b/glib/gconvert.c
@@ -1857,12 +1857,15 @@ make_valid_utf8 (const gchar *name)
 
 /**
  * g_filename_display_name:
- * @filename: a pathname in the GLib filename encoding
+ * @filename: a pathname hopefully in the GLib file name encoding
  * 
  * Converts a filename into a valid UTF-8 string. The 
  * conversion is not necessarily reversible, so you 
  * should keep the original around and use the return
  * value of this function only for display purposes.
+ * Unlike g_filename_to_utf8(), the result is guaranteed 
+ * to be non-NULL even if the filename actually isn't in the GLib
+ * file name encoding.
  *
  * Return value: a newly allocated string containing
  *   a rendition of the filename in valid UTF-8
diff --git a/glib/gfileutils.c b/glib/gfileutils.c
index 8a37968c9..10e5edeec 100644
--- a/glib/gfileutils.c
+++ b/glib/gfileutils.c
@@ -465,7 +465,7 @@ g_file_error_from_errno (gint err_no)
 }
 
 static gboolean
-get_contents_stdio (const gchar *utf8_filename,
+get_contents_stdio (const gchar *display_filename,
                     FILE        *f,
                     gchar      **contents,
                     gsize       *length, 
@@ -501,7 +501,7 @@ get_contents_stdio (const gchar *utf8_filename,
                            G_FILE_ERROR_NOMEM,
                            _("Could not allocate %lu bytes to read file \"%s\""),
                            (gulong) total_allocated, 
-			   utf8_filename ? utf8_filename : "???");
+			   display_filename);
 
               goto error;
             }
@@ -513,7 +513,7 @@ get_contents_stdio (const gchar *utf8_filename,
                        G_FILE_ERROR,
                        g_file_error_from_errno (errno),
                        _("Error reading file '%s': %s"),
-                       utf8_filename ? utf8_filename : "???", 
+                       display_filename,
 		       g_strerror (errno));
 
           goto error;
@@ -545,7 +545,7 @@ get_contents_stdio (const gchar *utf8_filename,
 #ifndef G_OS_WIN32
 
 static gboolean
-get_contents_regfile (const gchar *utf8_filename,
+get_contents_regfile (const gchar *display_filename,
                       struct stat *stat_buf,
                       gint         fd,
                       gchar      **contents,
@@ -569,7 +569,7 @@ get_contents_regfile (const gchar *utf8_filename,
                    G_FILE_ERROR_NOMEM,
                    _("Could not allocate %lu bytes to read file \"%s\""),
                    (gulong) alloc_size, 
-		   utf8_filename ? utf8_filename : "???");
+		   display_filename);
 
       goto error;
     }
@@ -590,7 +590,7 @@ get_contents_regfile (const gchar *utf8_filename,
                            G_FILE_ERROR,
                            g_file_error_from_errno (errno),
                            _("Failed to read from file '%s': %s"),
-                           utf8_filename ? utf8_filename : "???", 
+                           display_filename, 
 			   g_strerror (errno));
 
 	      goto error;
@@ -628,7 +628,7 @@ get_contents_posix (const gchar *filename,
 {
   struct stat stat_buf;
   gint fd;
-  gchar *utf8_filename = g_filename_to_utf8 (filename, -1, NULL, NULL, NULL);
+  gchar *display_filename = g_filename_display_name (filename);
 
   /* O_BINARY useful on Cygwin */
   fd = open (filename, O_RDONLY|O_BINARY);
@@ -639,9 +639,9 @@ get_contents_posix (const gchar *filename,
                    G_FILE_ERROR,
                    g_file_error_from_errno (errno),
                    _("Failed to open file '%s': %s"),
-                   utf8_filename ? utf8_filename : "???", 
+                   display_filename, 
 		   g_strerror (errno));
-      g_free (utf8_filename);
+      g_free (display_filename);
 
       return FALSE;
     }
@@ -654,22 +654,22 @@ get_contents_posix (const gchar *filename,
                    G_FILE_ERROR,
                    g_file_error_from_errno (errno),
                    _("Failed to get attributes of file '%s': fstat() failed: %s"),
-                   utf8_filename ? utf8_filename : "???", 
+                   display_filename, 
 		   g_strerror (errno));
-      g_free (utf8_filename);
+      g_free (display_filename);
 
       return FALSE;
     }
 
   if (stat_buf.st_size > 0 && S_ISREG (stat_buf.st_mode))
     {
-      gboolean retval = get_contents_regfile (utf8_filename,
+      gboolean retval = get_contents_regfile (display_filename,
 					      &stat_buf,
 					      fd,
 					      contents,
 					      length,
 					      error);
-      g_free (utf8_filename);
+      g_free (display_filename);
 
       return retval;
     }
@@ -686,15 +686,15 @@ get_contents_posix (const gchar *filename,
                        G_FILE_ERROR,
                        g_file_error_from_errno (errno),
                        _("Failed to open file '%s': fdopen() failed: %s"),
-                       utf8_filename ? utf8_filename : "???", 
+                       display_filename, 
 		       g_strerror (errno));
-          g_free (utf8_filename);
+          g_free (display_filename);
 
           return FALSE;
         }
   
-      retval = get_contents_stdio (utf8_filename, f, contents, length, error);
-      g_free (utf8_filename);
+      retval = get_contents_stdio (display_filename, f, contents, length, error);
+      g_free (display_filename);
 
       return retval;
     }
@@ -711,27 +711,26 @@ get_contents_win32 (const gchar *filename,
   FILE *f;
   gboolean retval;
   wchar_t *wfilename = g_utf8_to_utf16 (filename, -1, NULL, NULL, NULL);
+  gchar *display_filename = g_filename_display_name (filename);
   
   f = _wfopen (wfilename, L"rb");
   g_free (wfilename);
 
   if (f == NULL)
     {
-      gchar *utf8_filename = g_filename_to_utf8 (filename, -1,
-						 NULL, NULL, NULL);
-      
       g_set_error (error,
                    G_FILE_ERROR,
                    g_file_error_from_errno (errno),
                    _("Failed to open file '%s': %s"),
-                   utf8_filename ? utf8_filename : "???", 
+                   display_filename,
 		   g_strerror (errno));
-      g_free (utf8_filename);
+      g_free (display_filename);
 
       return FALSE;
     }
   
-  retval = get_contents_stdio (filename, f, contents, length, error);
+  retval = get_contents_stdio (display_filename, f, contents, length, error);
+  g_free (display_filename);
 
   return retval;
 }
@@ -740,7 +739,7 @@ get_contents_win32 (const gchar *filename,
 
 /**
  * g_file_get_contents:
- * @filename: name of a file to read contents from, in the encoding used for filenames
+ * @filename: name of a file to read contents from, in the GLib file name encoding
  * @contents: location to store an allocated string
  * @length: location to store length in bytes of the contents
  * @error: return location for a #GError
@@ -818,6 +817,8 @@ g_file_get_contents (const gchar *filename,
  * The parameter is a string that should match the rules for
  * mkstemp(), i.e. end in "XXXXXX". The X string will 
  * be modified to form the name of a file that didn't exist.
+ * The string should be in the GLib file name encoding. Most importantly, 
+ * on Windows it should be in UTF-8.
  *
  * Return value: A file handle (as from open()) to the file
  * opened for reading and writing. The file is opened in binary mode
@@ -961,17 +962,18 @@ g_mkstemp (gchar *tmpl)
  * Opens a file for writing in the preferred directory for temporary
  * files (as returned by g_get_tmp_dir()). 
  *
- * @tmpl should be a string ending with six 'X' characters, as the
- * parameter to g_mkstemp() (or mkstemp()). 
- * However, unlike these functions, the template should only be a 
- * basename, no directory components are allowed. If template is %NULL, 
- * a default template is used.
+ * @tmpl should be a string in the GLib file name encoding ending with
+ * six 'X' characters, as the parameter to g_mkstemp() (or mkstemp()).
+ * However, unlike these functions, the template should only be a
+ * basename, no directory components are allowed. If template is
+ * %NULL, a default template is used.
  *
  * Note that in contrast to g_mkstemp() (and mkstemp()) 
  * @tmpl is not modified, and might thus be a read-only literal string.
  *
  * The actual name used is returned in @name_used if non-%NULL. This
  * string should be freed with g_free() when not needed any longer.
+ * The returned name is in the GLib file name encoding.
  *
  * Return value: A file handle (as from open()) to 
  * the file opened for reading and writing. The file is opened in binary 
@@ -999,6 +1001,7 @@ g_file_open_tmp (const gchar *tmpl,
 #endif
       )
     {
+      gchar *display_tmpl = g_filename_display_name (tmpl);
       char c[2];
       c[0] = *slash;
       c[1] = '\0';
@@ -1007,7 +1010,8 @@ g_file_open_tmp (const gchar *tmpl,
 		   G_FILE_ERROR,
 		   G_FILE_ERROR_FAILED,
 		   _("Template '%s' invalid, should not contain a '%s'"),
-		   tmpl, c);
+		   display_tmpl, c);
+      g_free (display_tmpl);
 
       return -1;
     }
@@ -1015,11 +1019,13 @@ g_file_open_tmp (const gchar *tmpl,
   if (strlen (tmpl) < 6 ||
       strcmp (tmpl + strlen (tmpl) - 6, "XXXXXX") != 0)
     {
+      gchar *display_tmpl = g_filename_display_name (tmpl);
       g_set_error (error,
 		   G_FILE_ERROR,
 		   G_FILE_ERROR_FAILED,
 		   _("Template '%s' doesn't end with XXXXXX"),
-		   tmpl);
+		   display_tmpl);
+      g_free (display_tmpl);
       return -1;
     }
 
@@ -1036,11 +1042,13 @@ g_file_open_tmp (const gchar *tmpl,
 
   if (retval == -1)
     {
+      gchar *display_fulltemplate = g_filename_display_name (fulltemplate);
       g_set_error (error,
 		   G_FILE_ERROR,
 		   g_file_error_from_errno (errno),
 		   _("Failed to create file '%s': %s"),
-		   fulltemplate, g_strerror (errno));
+		   display_fulltemplate, g_strerror (errno));
+      g_free (display_fulltemplate);
       g_free (fulltemplate);
       return -1;
     }
@@ -1384,9 +1392,9 @@ g_build_filename (const gchar *first_element,
  * @filename: the symbolic link
  * @error: return location for a #GError
  *
- * Reads the contents of the symbolic link @filename like the POSIX readlink() function.
- * The returned string is in the encoding used for filenames. Use g_filename_to_utf8() to 
- * convert it to UTF-8.
+ * Reads the contents of the symbolic link @filename like the POSIX
+ * readlink() function.  The returned string is in the encoding used
+ * for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
  *
  * Returns: A newly allocated string with the contents of the symbolic link, 
  *          or %NULL if an error occurred.
@@ -1409,16 +1417,15 @@ g_file_read_link (const gchar *filename,
     {
       read_size = readlink (filename, buffer, size);
       if (read_size < 0) {
-	gchar *utf8_filename = g_filename_to_utf8 (filename, -1,
-						   NULL, NULL, NULL);
+	gchar *display_filename = g_filename_display_name (filename);
 	g_free (buffer);
 	g_set_error (error,
 		     G_FILE_ERROR,
 		     g_file_error_from_errno (errno),
 		     _("Failed to read the symbolic link '%s': %s"),
-		     utf8_filename ? utf8_filename : "???", 
+		     display_filename, 
 		     g_strerror (errno));
-	g_free (utf8_filename);
+	g_free (display_filename);
 	
 	return NULL;
       }