1 /* GLIB - Library of useful routines for C programming
3 * gconvert.c: Convert between character sets using iconv
4 * Copyright Red Hat Inc., 2000
5 * Authors: Havoc Pennington <hp@redhat.com>, Owen Taylor <otaylor@redhat.com>
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
24 #include "glibconfig.h"
35 #include "win_iconv.c"
38 #ifdef G_PLATFORM_WIN32
48 #include "gstrfuncs.h"
49 #include "gtestutils.h"
52 #include "gfileutils.h"
54 #ifdef NEED_ICONV_CACHE
61 #if defined(USE_LIBICONV_GNU) && !defined (_LIBICONV_H)
62 #error GNU libiconv in use but included iconv.h not from libiconv
64 #if !defined(USE_LIBICONV_GNU) && defined (_LIBICONV_H) \
65 && !defined (__APPLE_CC__) && !defined (__LP_64__)
66 #error GNU libiconv not in use but included iconv.h is from libiconv
72 * @title: Character Set Conversion
73 * @short_description: convert strings between different character sets
75 * The g_convert() family of function wraps the functionality of iconv(). In
76 * addition to pure character set conversions, GLib has functions to deal
77 * with the extra complications of encodings for file names.
79 * <refsect2 id="file-name-encodings">
80 * <title>File Name Encodings</title>
82 * Historically, Unix has not had a defined encoding for file
83 * names: a file name is valid as long as it does not have path
84 * separators in it ("/"). However, displaying file names may
85 * require conversion: from the character set in which they were
86 * created, to the character set in which the application
87 * operates. Consider the Spanish file name
88 * "<filename>Presentación.sxi</filename>". If the
89 * application which created it uses ISO-8859-1 for its encoding,
91 * <programlisting id="filename-iso8859-1">
92 * Character: P r e s e n t a c i ó n . s x i
93 * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
96 * However, if the application use UTF-8, the actual file name on
97 * disk would look like this:
99 * <programlisting id="filename-utf-8">
100 * Character: P r e s e n t a c i ó n . s x i
101 * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
104 * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+
105 * that use Glib do the same thing. If you get a file name from
106 * the file system, for example, from readdir(3) or from g_dir_read_name(),
107 * and you wish to display the file name to the user, you
108 * <emphasis>will</emphasis> need to convert it into UTF-8. The
109 * opposite case is when the user types the name of a file he
110 * wishes to save: the toolkit will give you that string in
111 * UTF-8 encoding, and you will need to convert it to the
112 * character set used for file names before you can create the
113 * file with open(2) or fopen(3).
116 * By default, Glib assumes that file names on disk are in UTF-8
117 * encoding. This is a valid assumption for file systems which
118 * were created relatively recently: most applications use UTF-8
119 * encoding for their strings, and that is also what they use for
120 * the file names they create. However, older file systems may
121 * still contain file names created in "older" encodings, such as
122 * ISO-8859-1. In this case, for compatibility reasons, you may
123 * want to instruct Glib to use that particular encoding for file
124 * names rather than UTF-8. You can do this by specifying the
125 * encoding for file names in the <link
126 * linkend="G_FILENAME_ENCODING"><envar>G_FILENAME_ENCODING</envar></link>
127 * environment variable. For example, if your installation uses
128 * ISO-8859-1 for file names, you can put this in your
129 * <filename>~/.profile</filename>:
132 * export G_FILENAME_ENCODING=ISO-8859-1
135 * Glib provides the functions g_filename_to_utf8() and
136 * g_filename_from_utf8() to perform the necessary conversions. These
137 * functions convert file names from the encoding specified in
138 * <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa.
139 * <xref linkend="file-name-encodings-diagram"/> illustrates how
140 * these functions are used to convert between UTF-8 and the
141 * encoding for file names in the file system.
143 * <figure id="file-name-encodings-diagram">
144 * <title>Conversion between File Name Encodings</title>
145 * <graphic fileref="file-name-encodings.png" format="PNG"/>
147 * <refsect3 id="file-name-encodings-checklist">
148 * <title>Checklist for Application Writers</title>
150 * This section is a practical summary of the detailed
151 * description above. You can use this as a checklist of
152 * things to do to make sure your applications process file
153 * name encodings correctly.
157 * If you get a file name from the file system from a function
158 * such as readdir(3) or gtk_file_chooser_get_filename(),
159 * you do not need to do any conversion to pass that
160 * file name to functions like open(2), rename(2), or
161 * fopen(3) — those are "raw" file names which the file
162 * system understands.
165 * If you need to display a file name, convert it to UTF-8 first by
166 * using g_filename_to_utf8(). If conversion fails, display a string like
167 * "<literal>Unknown file name</literal>". <emphasis>Do not</emphasis>
168 * convert this string back into the encoding used for file names if you
169 * wish to pass it to the file system; use the original file name instead.
170 * For example, the document window of a word processor could display
171 * "Unknown file name" in its title bar but still let the user save the
172 * file, as it would keep the raw file name internally. This can happen
173 * if the user has not set the <envar>G_FILENAME_ENCODING</envar>
174 * environment variable even though he has files whose names are not
178 * If your user interface lets the user type a file name for saving or
179 * renaming, convert it to the encoding used for file names in the file
180 * system by using g_filename_from_utf8(). Pass the converted file name
181 * to functions like fopen(3). If conversion fails, ask the user to enter
182 * a different file name. This can happen if the user types Japanese
183 * characters when <envar>G_FILENAME_ENCODING</envar> is set to
184 * <literal>ISO-8859-1</literal>, for example.
191 /* We try to terminate strings in unknown charsets with this many zero bytes
192 * to ensure that multibyte strings really are nul-terminated when we return
193 * them from g_convert() and friends.
195 #define NUL_TERMINATOR_LENGTH 4
198 g_convert_error_quark (void)
200 return g_quark_from_static_string ("g_convert_error");
204 try_conversion (const char *to_codeset,
205 const char *from_codeset,
208 *cd = iconv_open (to_codeset, from_codeset);
210 if (*cd == (iconv_t)-1 && errno == EINVAL)
217 try_to_aliases (const char **to_aliases,
218 const char *from_codeset,
223 const char **p = to_aliases;
226 if (try_conversion (*p, from_codeset, cd))
236 G_GNUC_INTERNAL extern const char **
237 _g_charset_get_aliases (const char *canonical_name);
241 * @to_codeset: destination codeset
242 * @from_codeset: source codeset
244 * Same as the standard UNIX routine iconv_open(), but
245 * may be implemented via libiconv on UNIX flavors that lack
246 * a native implementation.
248 * GLib provides g_convert() and g_locale_to_utf8() which are likely
249 * more convenient than the raw iconv wrappers.
251 * Return value: a "conversion descriptor", or (GIConv)-1 if
252 * opening the converter failed.
255 g_iconv_open (const gchar *to_codeset,
256 const gchar *from_codeset)
260 if (!try_conversion (to_codeset, from_codeset, &cd))
262 const char **to_aliases = _g_charset_get_aliases (to_codeset);
263 const char **from_aliases = _g_charset_get_aliases (from_codeset);
267 const char **p = from_aliases;
270 if (try_conversion (to_codeset, *p, &cd))
273 if (try_to_aliases (to_aliases, *p, &cd))
280 if (try_to_aliases (to_aliases, from_codeset, &cd))
285 return (cd == (iconv_t)-1) ? (GIConv)-1 : (GIConv)cd;
290 * @converter: conversion descriptor from g_iconv_open()
291 * @inbuf: bytes to convert
292 * @inbytes_left: inout parameter, bytes remaining to convert in @inbuf
293 * @outbuf: converted output bytes
294 * @outbytes_left: inout parameter, bytes available to fill in @outbuf
296 * Same as the standard UNIX routine iconv(), but
297 * may be implemented via libiconv on UNIX flavors that lack
298 * a native implementation.
300 * GLib provides g_convert() and g_locale_to_utf8() which are likely
301 * more convenient than the raw iconv wrappers.
303 * Return value: count of non-reversible conversions, or -1 on error
306 g_iconv (GIConv converter,
310 gsize *outbytes_left)
312 iconv_t cd = (iconv_t)converter;
314 return iconv (cd, inbuf, inbytes_left, outbuf, outbytes_left);
319 * @converter: a conversion descriptor from g_iconv_open()
321 * Same as the standard UNIX routine iconv_close(), but
322 * may be implemented via libiconv on UNIX flavors that lack
323 * a native implementation. Should be called to clean up
324 * the conversion descriptor from g_iconv_open() when
325 * you are done converting things.
327 * GLib provides g_convert() and g_locale_to_utf8() which are likely
328 * more convenient than the raw iconv wrappers.
330 * Return value: -1 on error, 0 on success
333 g_iconv_close (GIConv converter)
335 iconv_t cd = (iconv_t)converter;
337 return iconv_close (cd);
341 #ifdef NEED_ICONV_CACHE
343 #define ICONV_CACHE_SIZE (16)
345 struct _iconv_cache_bucket {
352 static GList *iconv_cache_list;
353 static GHashTable *iconv_cache;
354 static GHashTable *iconv_open_hash;
355 static guint iconv_cache_size = 0;
356 G_LOCK_DEFINE_STATIC (iconv_cache_lock);
358 /* caller *must* hold the iconv_cache_lock */
360 iconv_cache_init (void)
362 static gboolean initialized = FALSE;
367 iconv_cache_list = NULL;
368 iconv_cache = g_hash_table_new (g_str_hash, g_str_equal);
369 iconv_open_hash = g_hash_table_new (g_direct_hash, g_direct_equal);
376 * iconv_cache_bucket_new:
378 * @cd: iconv descriptor
380 * Creates a new cache bucket, inserts it into the cache and
381 * increments the cache size.
383 * This assumes ownership of @key.
385 * Returns a pointer to the newly allocated cache bucket.
387 static struct _iconv_cache_bucket *
388 iconv_cache_bucket_new (gchar *key, GIConv cd)
390 struct _iconv_cache_bucket *bucket;
392 bucket = g_new (struct _iconv_cache_bucket, 1);
394 bucket->refcount = 1;
398 g_hash_table_insert (iconv_cache, bucket->key, bucket);
400 /* FIXME: if we sorted the list so items with few refcounts were
401 first, then we could expire them faster in iconv_cache_expire_unused () */
402 iconv_cache_list = g_list_prepend (iconv_cache_list, bucket);
411 * iconv_cache_bucket_expire:
412 * @node: cache bucket's node
413 * @bucket: cache bucket
415 * Expires a single cache bucket @bucket. This should only ever be
416 * called on a bucket that currently has no used iconv descriptors
419 * @node is not a required argument. If @node is not supplied, we
420 * search for it ourselves.
423 iconv_cache_bucket_expire (GList *node, struct _iconv_cache_bucket *bucket)
425 g_hash_table_remove (iconv_cache, bucket->key);
428 node = g_list_find (iconv_cache_list, bucket);
430 g_assert (node != NULL);
434 node->prev->next = node->next;
436 node->next->prev = node->prev;
440 iconv_cache_list = node->next;
442 node->next->prev = NULL;
445 g_list_free_1 (node);
447 g_free (bucket->key);
448 g_iconv_close (bucket->cd);
456 * iconv_cache_expire_unused:
458 * Expires as many unused cache buckets as it needs to in order to get
459 * the total number of buckets < ICONV_CACHE_SIZE.
462 iconv_cache_expire_unused (void)
464 struct _iconv_cache_bucket *bucket;
467 node = iconv_cache_list;
468 while (node && iconv_cache_size >= ICONV_CACHE_SIZE)
473 if (bucket->refcount == 0)
474 iconv_cache_bucket_expire (node, bucket);
481 open_converter (const gchar *to_codeset,
482 const gchar *from_codeset,
485 struct _iconv_cache_bucket *bucket;
486 gchar *key, *dyn_key, auto_key[80];
488 gsize len_from_codeset, len_to_codeset;
491 len_from_codeset = strlen (from_codeset);
492 len_to_codeset = strlen (to_codeset);
493 if (len_from_codeset + len_to_codeset + 2 < sizeof (auto_key))
499 key = dyn_key = g_malloc (len_from_codeset + len_to_codeset + 2);
500 memcpy (key, from_codeset, len_from_codeset);
501 key[len_from_codeset] = ':';
502 strcpy (key + len_from_codeset + 1, to_codeset);
504 G_LOCK (iconv_cache_lock);
506 /* make sure the cache has been initialized */
509 bucket = g_hash_table_lookup (iconv_cache, key);
516 cd = g_iconv_open (to_codeset, from_codeset);
517 if (cd == (GIConv) -1)
522 /* Apparently iconv on Solaris <= 7 segfaults if you pass in
523 * NULL for anything but inbuf; work around that. (NULL outbuf
524 * or NULL *outbuf is allowed by Unix98.)
526 gsize inbytes_left = 0;
527 gchar *outbuf = NULL;
528 gsize outbytes_left = 0;
533 /* reset the descriptor */
534 g_iconv (cd, NULL, &inbytes_left, &outbuf, &outbytes_left);
541 cd = g_iconv_open (to_codeset, from_codeset);
542 if (cd == (GIConv) -1)
548 iconv_cache_expire_unused ();
550 bucket = iconv_cache_bucket_new (dyn_key ? dyn_key : g_strdup (key), cd);
553 g_hash_table_insert (iconv_open_hash, cd, bucket->key);
555 G_UNLOCK (iconv_cache_lock);
561 G_UNLOCK (iconv_cache_lock);
563 /* Something went wrong. */
567 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_CONVERSION,
568 _("Conversion from character set '%s' to '%s' is not supported"),
569 from_codeset, to_codeset);
571 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
572 _("Could not open converter from '%s' to '%s'"),
573 from_codeset, to_codeset);
580 close_converter (GIConv converter)
582 struct _iconv_cache_bucket *bucket;
588 if (cd == (GIConv) -1)
591 G_LOCK (iconv_cache_lock);
593 key = g_hash_table_lookup (iconv_open_hash, cd);
596 g_hash_table_remove (iconv_open_hash, cd);
598 bucket = g_hash_table_lookup (iconv_cache, key);
603 if (cd == bucket->cd)
604 bucket->used = FALSE;
608 if (!bucket->refcount && iconv_cache_size > ICONV_CACHE_SIZE)
610 /* expire this cache bucket */
611 iconv_cache_bucket_expire (NULL, bucket);
616 G_UNLOCK (iconv_cache_lock);
618 g_warning ("This iconv context wasn't opened using open_converter");
620 return g_iconv_close (converter);
623 G_UNLOCK (iconv_cache_lock);
628 #else /* !NEED_ICONV_CACHE */
631 open_converter (const gchar *to_codeset,
632 const gchar *from_codeset,
637 cd = g_iconv_open (to_codeset, from_codeset);
639 if (cd == (GIConv) -1)
641 /* Something went wrong. */
645 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_CONVERSION,
646 _("Conversion from character set '%s' to '%s' is not supported"),
647 from_codeset, to_codeset);
649 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
650 _("Could not open converter from '%s' to '%s'"),
651 from_codeset, to_codeset);
659 close_converter (GIConv cd)
661 if (cd == (GIConv) -1)
664 return g_iconv_close (cd);
667 #endif /* NEED_ICONV_CACHE */
670 * g_convert_with_iconv:
671 * @str: the string to convert
672 * @len: the length of the string, or -1 if the string is
673 * nul-terminated<footnoteref linkend="nul-unsafe"/>.
674 * @converter: conversion descriptor from g_iconv_open()
675 * @bytes_read: location to store the number of bytes in the
676 * input string that were successfully converted, or %NULL.
677 * Even if the conversion was successful, this may be
678 * less than @len if there were partial characters
679 * at the end of the input. If the error
680 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
681 * stored will the byte offset after the last valid
683 * @bytes_written: the number of bytes stored in the output buffer (not
684 * including the terminating nul).
685 * @error: location to store the error occurring, or %NULL to ignore
686 * errors. Any of the errors in #GConvertError may occur.
688 * Converts a string from one character set to another.
690 * Note that you should use g_iconv() for streaming
691 * conversions<footnote id="streaming-state">
693 * Despite the fact that @byes_read can return information about partial
694 * characters, the <literal>g_convert_...</literal> functions
695 * are not generally suitable for streaming. If the underlying converter
696 * being used maintains internal state, then this won't be preserved
697 * across successive calls to g_convert(), g_convert_with_iconv() or
698 * g_convert_with_fallback(). (An example of this is the GNU C converter
699 * for CP1255 which does not emit a base character until it knows that
700 * the next character is not a mark that could combine with the base
705 * Return value: If the conversion was successful, a newly allocated
706 * nul-terminated string, which must be freed with
707 * g_free(). Otherwise %NULL and @error will be set.
710 g_convert_with_iconv (const gchar *str,
714 gsize *bytes_written,
720 gsize inbytes_remaining;
721 gsize outbytes_remaining;
724 gboolean have_error = FALSE;
725 gboolean done = FALSE;
726 gboolean reset = FALSE;
728 g_return_val_if_fail (converter != (GIConv) -1, NULL);
734 inbytes_remaining = len;
735 outbuf_size = len + NUL_TERMINATOR_LENGTH;
737 outbytes_remaining = outbuf_size - NUL_TERMINATOR_LENGTH;
738 outp = dest = g_malloc (outbuf_size);
740 while (!done && !have_error)
743 err = g_iconv (converter, NULL, &inbytes_remaining, &outp, &outbytes_remaining);
745 err = g_iconv (converter, (char **)&p, &inbytes_remaining, &outp, &outbytes_remaining);
747 if (err == (gsize) -1)
752 /* Incomplete text, do not report an error */
757 gsize used = outp - dest;
760 dest = g_realloc (dest, outbuf_size);
763 outbytes_remaining = outbuf_size - used - NUL_TERMINATOR_LENGTH;
767 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
768 _("Invalid byte sequence in conversion input"));
775 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
776 _("Error during conversion: %s"),
787 /* call g_iconv with NULL inbuf to cleanup shift state */
789 inbytes_remaining = 0;
796 memset (outp, 0, NUL_TERMINATOR_LENGTH);
799 *bytes_read = p - str;
802 if ((p - str) != len)
806 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
807 _("Partial character sequence at end of input"));
814 *bytes_written = outp - dest; /* Doesn't include '\0' */
827 * @str: the string to convert
828 * @len: the length of the string, or -1 if the string is
829 * nul-terminated<footnote id="nul-unsafe">
831 Note that some encodings may allow nul bytes to
832 occur inside strings. In that case, using -1 for
833 the @len parameter is unsafe.
836 * @to_codeset: name of character set into which to convert @str
837 * @from_codeset: character set of @str.
838 * @bytes_read: (out): location to store the number of bytes in the
839 * input string that were successfully converted, or %NULL.
840 * Even if the conversion was successful, this may be
841 * less than @len if there were partial characters
842 * at the end of the input. If the error
843 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
844 * stored will the byte offset after the last valid
846 * @bytes_written: (out): the number of bytes stored in the output buffer (not
847 * including the terminating nul).
848 * @error: location to store the error occurring, or %NULL to ignore
849 * errors. Any of the errors in #GConvertError may occur.
851 * Converts a string from one character set to another.
853 * Note that you should use g_iconv() for streaming
854 * conversions<footnoteref linkend="streaming-state"/>.
856 * Return value: If the conversion was successful, a newly allocated
857 * nul-terminated string, which must be freed with
858 * g_free(). Otherwise %NULL and @error will be set.
861 g_convert (const gchar *str,
863 const gchar *to_codeset,
864 const gchar *from_codeset,
866 gsize *bytes_written,
872 g_return_val_if_fail (str != NULL, NULL);
873 g_return_val_if_fail (to_codeset != NULL, NULL);
874 g_return_val_if_fail (from_codeset != NULL, NULL);
876 cd = open_converter (to_codeset, from_codeset, error);
878 if (cd == (GIConv) -1)
889 res = g_convert_with_iconv (str, len, cd,
890 bytes_read, bytes_written,
893 close_converter (cd);
899 * g_convert_with_fallback:
900 * @str: the string to convert
901 * @len: the length of the string, or -1 if the string is
902 * nul-terminated<footnoteref linkend="nul-unsafe"/>.
903 * @to_codeset: name of character set into which to convert @str
904 * @from_codeset: character set of @str.
905 * @fallback: UTF-8 string to use in place of character not
906 * present in the target encoding. (The string must be
907 * representable in the target encoding).
908 If %NULL, characters not in the target encoding will
909 be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
910 * @bytes_read: location to store the number of bytes in the
911 * input string that were successfully converted, or %NULL.
912 * Even if the conversion was successful, this may be
913 * less than @len if there were partial characters
914 * at the end of the input.
915 * @bytes_written: the number of bytes stored in the output buffer (not
916 * including the terminating nul).
917 * @error: location to store the error occurring, or %NULL to ignore
918 * errors. Any of the errors in #GConvertError may occur.
920 * Converts a string from one character set to another, possibly
921 * including fallback sequences for characters not representable
922 * in the output. Note that it is not guaranteed that the specification
923 * for the fallback sequences in @fallback will be honored. Some
924 * systems may do an approximate conversion from @from_codeset
925 * to @to_codeset in their iconv() functions,
926 * in which case GLib will simply return that approximate conversion.
928 * Note that you should use g_iconv() for streaming
929 * conversions<footnoteref linkend="streaming-state"/>.
931 * Return value: If the conversion was successful, a newly allocated
932 * nul-terminated string, which must be freed with
933 * g_free(). Otherwise %NULL and @error will be set.
936 g_convert_with_fallback (const gchar *str,
938 const gchar *to_codeset,
939 const gchar *from_codeset,
940 const gchar *fallback,
942 gsize *bytes_written,
948 const gchar *insert_str = NULL;
950 gsize inbytes_remaining;
951 const gchar *save_p = NULL;
952 gsize save_inbytes = 0;
953 gsize outbytes_remaining;
957 gboolean have_error = FALSE;
958 gboolean done = FALSE;
960 GError *local_error = NULL;
962 g_return_val_if_fail (str != NULL, NULL);
963 g_return_val_if_fail (to_codeset != NULL, NULL);
964 g_return_val_if_fail (from_codeset != NULL, NULL);
969 /* Try an exact conversion; we only proceed if this fails
970 * due to an illegal sequence in the input string.
972 dest = g_convert (str, len, to_codeset, from_codeset,
973 bytes_read, bytes_written, &local_error);
977 if (!g_error_matches (local_error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE))
979 g_propagate_error (error, local_error);
983 g_error_free (local_error);
987 /* No go; to proceed, we need a converter from "UTF-8" to
988 * to_codeset, and the string as UTF-8.
990 cd = open_converter (to_codeset, "UTF-8", error);
991 if (cd == (GIConv) -1)
1002 utf8 = g_convert (str, len, "UTF-8", from_codeset,
1003 bytes_read, &inbytes_remaining, error);
1006 close_converter (cd);
1012 /* Now the heart of the code. We loop through the UTF-8 string, and
1013 * whenever we hit an offending character, we form fallback, convert
1014 * the fallback to the target codeset, and then go back to
1015 * converting the original string after finishing with the fallback.
1017 * The variables save_p and save_inbytes store the input state
1018 * for the original string while we are converting the fallback
1022 outbuf_size = len + NUL_TERMINATOR_LENGTH;
1023 outbytes_remaining = outbuf_size - NUL_TERMINATOR_LENGTH;
1024 outp = dest = g_malloc (outbuf_size);
1026 while (!done && !have_error)
1028 gsize inbytes_tmp = inbytes_remaining;
1029 err = g_iconv (cd, (char **)&p, &inbytes_tmp, &outp, &outbytes_remaining);
1030 inbytes_remaining = inbytes_tmp;
1032 if (err == (gsize) -1)
1037 g_assert_not_reached();
1041 gsize used = outp - dest;
1044 dest = g_realloc (dest, outbuf_size);
1047 outbytes_remaining = outbuf_size - used - NUL_TERMINATOR_LENGTH;
1054 /* Error converting fallback string - fatal
1056 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1057 _("Cannot convert fallback '%s' to codeset '%s'"),
1058 insert_str, to_codeset);
1066 gunichar ch = g_utf8_get_char (p);
1067 insert_str = g_strdup_printf (ch < 0x10000 ? "\\u%04x" : "\\U%08x",
1071 insert_str = fallback;
1073 save_p = g_utf8_next_char (p);
1074 save_inbytes = inbytes_remaining - (save_p - p);
1076 inbytes_remaining = strlen (p);
1079 /* fall thru if p is NULL */
1084 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_FAILED,
1085 _("Error during conversion: %s"),
1086 g_strerror (errsv));
1098 g_free ((gchar *)insert_str);
1100 inbytes_remaining = save_inbytes;
1105 /* call g_iconv with NULL inbuf to cleanup shift state */
1107 inbytes_remaining = 0;
1116 memset (outp, 0, NUL_TERMINATOR_LENGTH);
1118 close_converter (cd);
1121 *bytes_written = outp - dest; /* Doesn't include '\0' */
1127 if (save_p && !fallback)
1128 g_free ((gchar *)insert_str);
1143 strdup_len (const gchar *string,
1145 gsize *bytes_written,
1152 if (!g_utf8_validate (string, len, NULL))
1159 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1160 _("Invalid byte sequence in conversion input"));
1165 real_len = strlen (string);
1170 while (real_len < len && string[real_len])
1175 *bytes_read = real_len;
1177 *bytes_written = real_len;
1179 return g_strndup (string, real_len);
1184 * @opsysstring: a string in the encoding of the current locale. On Windows
1185 * this means the system codepage.
1186 * @len: the length of the string, or -1 if the string is
1187 * nul-terminated<footnoteref linkend="nul-unsafe"/>.
1188 * @bytes_read: location to store the number of bytes in the
1189 * input string that were successfully converted, or %NULL.
1190 * Even if the conversion was successful, this may be
1191 * less than @len if there were partial characters
1192 * at the end of the input. If the error
1193 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
1194 * stored will the byte offset after the last valid
1196 * @bytes_written: the number of bytes stored in the output buffer (not
1197 * including the terminating nul).
1198 * @error: location to store the error occurring, or %NULL to ignore
1199 * errors. Any of the errors in #GConvertError may occur.
1201 * Converts a string which is in the encoding used for strings by
1202 * the C runtime (usually the same as that used by the operating
1203 * system) in the <link linkend="setlocale">current locale</link> into a
1206 * Return value: The converted string, or %NULL on an error.
1209 g_locale_to_utf8 (const gchar *opsysstring,
1212 gsize *bytes_written,
1215 const char *charset;
1217 if (g_get_charset (&charset))
1218 return strdup_len (opsysstring, len, bytes_read, bytes_written, error);
1220 return g_convert (opsysstring, len,
1221 "UTF-8", charset, bytes_read, bytes_written, error);
1225 * g_locale_from_utf8:
1226 * @utf8string: a UTF-8 encoded string
1227 * @len: the length of the string, or -1 if the string is
1228 * nul-terminated<footnoteref linkend="nul-unsafe"/>.
1229 * @bytes_read: location to store the number of bytes in the
1230 * input string that were successfully converted, or %NULL.
1231 * Even if the conversion was successful, this may be
1232 * less than @len if there were partial characters
1233 * at the end of the input. If the error
1234 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
1235 * stored will the byte offset after the last valid
1237 * @bytes_written: the number of bytes stored in the output buffer (not
1238 * including the terminating nul).
1239 * @error: location to store the error occurring, or %NULL to ignore
1240 * errors. Any of the errors in #GConvertError may occur.
1242 * Converts a string from UTF-8 to the encoding used for strings by
1243 * the C runtime (usually the same as that used by the operating
1244 * system) in the <link linkend="setlocale">current locale</link>. On
1245 * Windows this means the system codepage.
1247 * Return value: The converted string, or %NULL on an error.
1250 g_locale_from_utf8 (const gchar *utf8string,
1253 gsize *bytes_written,
1256 const gchar *charset;
1258 if (g_get_charset (&charset))
1259 return strdup_len (utf8string, len, bytes_read, bytes_written, error);
1261 return g_convert (utf8string, len,
1262 charset, "UTF-8", bytes_read, bytes_written, error);
1265 #ifndef G_PLATFORM_WIN32
1267 typedef struct _GFilenameCharsetCache GFilenameCharsetCache;
1269 struct _GFilenameCharsetCache {
1272 gchar **filename_charsets;
1276 filename_charset_cache_free (gpointer data)
1278 GFilenameCharsetCache *cache = data;
1279 g_free (cache->charset);
1280 g_strfreev (cache->filename_charsets);
1285 * g_get_filename_charsets:
1286 * @charsets: return location for the %NULL-terminated list of encoding names
1288 * Determines the preferred character sets used for filenames.
1289 * The first character set from the @charsets is the filename encoding, the
1290 * subsequent character sets are used when trying to generate a displayable
1291 * representation of a filename, see g_filename_display_name().
1293 * On Unix, the character sets are determined by consulting the
1294 * environment variables <envar>G_FILENAME_ENCODING</envar> and
1295 * <envar>G_BROKEN_FILENAMES</envar>. On Windows, the character set
1296 * used in the GLib API is always UTF-8 and said environment variables
1299 * <envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list
1300 * of character set names. The special token "@locale" is taken to
1301 * mean the character set for the <link linkend="setlocale">current
1302 * locale</link>. If <envar>G_FILENAME_ENCODING</envar> is not set, but
1303 * <envar>G_BROKEN_FILENAMES</envar> is, the character set of the current
1304 * locale is taken as the filename encoding. If neither environment variable
1305 * is set, UTF-8 is taken as the filename encoding, but the character
1306 * set of the current locale is also put in the list of encodings.
1308 * The returned @charsets belong to GLib and must not be freed.
1310 * Note that on Unix, regardless of the locale character set or
1311 * <envar>G_FILENAME_ENCODING</envar> value, the actual file names present
1312 * on a system might be in any random encoding or just gibberish.
1314 * Return value: %TRUE if the filename encoding is UTF-8.
1319 g_get_filename_charsets (const gchar ***filename_charsets)
1321 static GPrivate cache_private = G_PRIVATE_INIT (filename_charset_cache_free);
1322 GFilenameCharsetCache *cache = g_private_get (&cache_private);
1323 const gchar *charset;
1327 cache = g_new0 (GFilenameCharsetCache, 1);
1328 g_private_set (&cache_private, cache);
1331 g_get_charset (&charset);
1333 if (!(cache->charset && strcmp (cache->charset, charset) == 0))
1335 const gchar *new_charset;
1339 g_free (cache->charset);
1340 g_strfreev (cache->filename_charsets);
1341 cache->charset = g_strdup (charset);
1343 p = getenv ("G_FILENAME_ENCODING");
1344 if (p != NULL && p[0] != '\0')
1346 cache->filename_charsets = g_strsplit (p, ",", 0);
1347 cache->is_utf8 = (strcmp (cache->filename_charsets[0], "UTF-8") == 0);
1349 for (i = 0; cache->filename_charsets[i]; i++)
1351 if (strcmp ("@locale", cache->filename_charsets[i]) == 0)
1353 g_get_charset (&new_charset);
1354 g_free (cache->filename_charsets[i]);
1355 cache->filename_charsets[i] = g_strdup (new_charset);
1359 else if (getenv ("G_BROKEN_FILENAMES") != NULL)
1361 cache->filename_charsets = g_new0 (gchar *, 2);
1362 cache->is_utf8 = g_get_charset (&new_charset);
1363 cache->filename_charsets[0] = g_strdup (new_charset);
1367 cache->filename_charsets = g_new0 (gchar *, 3);
1368 cache->is_utf8 = TRUE;
1369 cache->filename_charsets[0] = g_strdup ("UTF-8");
1370 if (!g_get_charset (&new_charset))
1371 cache->filename_charsets[1] = g_strdup (new_charset);
1375 if (filename_charsets)
1376 *filename_charsets = (const gchar **)cache->filename_charsets;
1378 return cache->is_utf8;
1381 #else /* G_PLATFORM_WIN32 */
1384 g_get_filename_charsets (const gchar ***filename_charsets)
1386 static const gchar *charsets[] = {
1392 /* On Windows GLib pretends that the filename charset is UTF-8 */
1393 if (filename_charsets)
1394 *filename_charsets = charsets;
1400 /* Cygwin works like before */
1401 result = g_get_charset (&(charsets[0]));
1403 if (filename_charsets)
1404 *filename_charsets = charsets;
1410 #endif /* G_PLATFORM_WIN32 */
1413 get_filename_charset (const gchar **filename_charset)
1415 const gchar **charsets;
1418 is_utf8 = g_get_filename_charsets (&charsets);
1420 if (filename_charset)
1421 *filename_charset = charsets[0];
1427 * g_filename_to_utf8:
1428 * @opsysstring: a string in the encoding for filenames
1429 * @len: the length of the string, or -1 if the string is
1430 * nul-terminated<footnoteref linkend="nul-unsafe"/>.
1431 * @bytes_read: location to store the number of bytes in the
1432 * input string that were successfully converted, or %NULL.
1433 * Even if the conversion was successful, this may be
1434 * less than @len if there were partial characters
1435 * at the end of the input. If the error
1436 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
1437 * stored will the byte offset after the last valid
1439 * @bytes_written: the number of bytes stored in the output buffer (not
1440 * including the terminating nul).
1441 * @error: location to store the error occurring, or %NULL to ignore
1442 * errors. Any of the errors in #GConvertError may occur.
1444 * Converts a string which is in the encoding used by GLib for
1445 * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
1446 * for filenames; on other platforms, this function indirectly depends on
1447 * the <link linkend="setlocale">current locale</link>.
1449 * Return value: The converted string, or %NULL on an error.
1452 g_filename_to_utf8 (const gchar *opsysstring,
1455 gsize *bytes_written,
1458 const gchar *charset;
1460 g_return_val_if_fail (opsysstring != NULL, NULL);
1462 if (get_filename_charset (&charset))
1463 return strdup_len (opsysstring, len, bytes_read, bytes_written, error);
1465 return g_convert (opsysstring, len,
1466 "UTF-8", charset, bytes_read, bytes_written, error);
1469 #if defined (G_OS_WIN32) && !defined (_WIN64)
1471 #undef g_filename_to_utf8
1473 /* Binary compatibility version. Not for newly compiled code. Also not needed for
1474 * 64-bit versions as there should be no old deployed binaries that would use
1479 g_filename_to_utf8 (const gchar *opsysstring,
1482 gsize *bytes_written,
1485 const gchar *charset;
1487 g_return_val_if_fail (opsysstring != NULL, NULL);
1489 if (g_get_charset (&charset))
1490 return strdup_len (opsysstring, len, bytes_read, bytes_written, error);
1492 return g_convert (opsysstring, len,
1493 "UTF-8", charset, bytes_read, bytes_written, error);
1499 * g_filename_from_utf8:
1500 * @utf8string: a UTF-8 encoded string.
1501 * @len: the length of the string, or -1 if the string is
1503 * @bytes_read: location to store the number of bytes in the
1504 * input string that were successfully converted, or %NULL.
1505 * Even if the conversion was successful, this may be
1506 * less than @len if there were partial characters
1507 * at the end of the input. If the error
1508 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
1509 * stored will the byte offset after the last valid
1511 * @bytes_written: the number of bytes stored in the output buffer (not
1512 * including the terminating nul).
1513 * @error: location to store the error occurring, or %NULL to ignore
1514 * errors. Any of the errors in #GConvertError may occur.
1516 * Converts a string from UTF-8 to the encoding GLib uses for
1517 * filenames. Note that on Windows GLib uses UTF-8 for filenames;
1518 * on other platforms, this function indirectly depends on the
1519 * <link linkend="setlocale">current locale</link>.
1521 * Return value: The converted string, or %NULL on an error.
1524 g_filename_from_utf8 (const gchar *utf8string,
1527 gsize *bytes_written,
1530 const gchar *charset;
1532 if (get_filename_charset (&charset))
1533 return strdup_len (utf8string, len, bytes_read, bytes_written, error);
1535 return g_convert (utf8string, len,
1536 charset, "UTF-8", bytes_read, bytes_written, error);
1539 #if defined (G_OS_WIN32) && !defined (_WIN64)
1541 #undef g_filename_from_utf8
1543 /* Binary compatibility version. Not for newly compiled code. */
1546 g_filename_from_utf8 (const gchar *utf8string,
1549 gsize *bytes_written,
1552 const gchar *charset;
1554 if (g_get_charset (&charset))
1555 return strdup_len (utf8string, len, bytes_read, bytes_written, error);
1557 return g_convert (utf8string, len,
1558 charset, "UTF-8", bytes_read, bytes_written, error);
1563 /* Test of haystack has the needle prefix, comparing case
1564 * insensitive. haystack may be UTF-8, but needle must
1565 * contain only ascii. */
1567 has_case_prefix (const gchar *haystack, const gchar *needle)
1571 /* Eat one character at a time. */
1576 g_ascii_tolower (*n) == g_ascii_tolower (*h))
1586 UNSAFE_ALL = 0x1, /* Escape all unsafe characters */
1587 UNSAFE_ALLOW_PLUS = 0x2, /* Allows '+' */
1588 UNSAFE_PATH = 0x8, /* Allows '/', '&', '=', ':', '@', '+', '$' and ',' */
1589 UNSAFE_HOST = 0x10, /* Allows '/' and ':' and '@' */
1590 UNSAFE_SLASHES = 0x20 /* Allows all characters except for '/' and '%' */
1591 } UnsafeCharacterSet;
1593 static const guchar acceptable[96] = {
1594 /* A table of the ASCII chars from space (32) to DEL (127) */
1595 /* ! " # $ % & ' ( ) * + , - . / */
1596 0x00,0x3F,0x20,0x20,0x28,0x00,0x2C,0x3F,0x3F,0x3F,0x3F,0x2A,0x28,0x3F,0x3F,0x1C,
1597 /* 0 1 2 3 4 5 6 7 8 9 : ; < = > ? */
1598 0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x38,0x20,0x20,0x2C,0x20,0x20,
1599 /* @ A B C D E F G H I J K L M N O */
1600 0x38,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,
1601 /* P Q R S T U V W X Y Z [ \ ] ^ _ */
1602 0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x20,0x20,0x20,0x20,0x3F,
1603 /* ` a b c d e f g h i j k l m n o */
1604 0x20,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,
1605 /* p q r s t u v w x y z { | } ~ DEL */
1606 0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x3F,0x20,0x20,0x20,0x3F,0x20
1609 static const gchar hex[16] = "0123456789ABCDEF";
1611 /* Note: This escape function works on file: URIs, but if you want to
1612 * escape something else, please read RFC-2396 */
1614 g_escape_uri_string (const gchar *string,
1615 UnsafeCharacterSet mask)
1617 #define ACCEPTABLE(a) ((a)>=32 && (a)<128 && (acceptable[(a)-32] & use_mask))
1624 UnsafeCharacterSet use_mask;
1626 g_return_val_if_fail (mask == UNSAFE_ALL
1627 || mask == UNSAFE_ALLOW_PLUS
1628 || mask == UNSAFE_PATH
1629 || mask == UNSAFE_HOST
1630 || mask == UNSAFE_SLASHES, NULL);
1634 for (p = string; *p != '\0'; p++)
1637 if (!ACCEPTABLE (c))
1641 result = g_malloc (p - string + unacceptable * 2 + 1);
1644 for (q = result, p = string; *p != '\0'; p++)
1648 if (!ACCEPTABLE (c))
1650 *q++ = '%'; /* means hex coming */
1665 g_escape_file_uri (const gchar *hostname,
1666 const gchar *pathname)
1668 char *escaped_hostname = NULL;
1673 char *p, *backslash;
1675 /* Turn backslashes into forward slashes. That's what Netscape
1676 * does, and they are actually more or less equivalent in Windows.
1679 pathname = g_strdup (pathname);
1680 p = (char *) pathname;
1682 while ((backslash = strchr (p, '\\')) != NULL)
1689 if (hostname && *hostname != '\0')
1691 escaped_hostname = g_escape_uri_string (hostname, UNSAFE_HOST);
1694 escaped_path = g_escape_uri_string (pathname, UNSAFE_PATH);
1696 res = g_strconcat ("file://",
1697 (escaped_hostname) ? escaped_hostname : "",
1698 (*escaped_path != '/') ? "/" : "",
1703 g_free ((char *) pathname);
1706 g_free (escaped_hostname);
1707 g_free (escaped_path);
1713 unescape_character (const char *scanner)
1718 first_digit = g_ascii_xdigit_value (scanner[0]);
1719 if (first_digit < 0)
1722 second_digit = g_ascii_xdigit_value (scanner[1]);
1723 if (second_digit < 0)
1726 return (first_digit << 4) | second_digit;
1730 g_unescape_uri_string (const char *escaped,
1732 const char *illegal_escaped_characters,
1733 gboolean ascii_must_not_be_escaped)
1735 const gchar *in, *in_end;
1736 gchar *out, *result;
1739 if (escaped == NULL)
1743 len = strlen (escaped);
1745 result = g_malloc (len + 1);
1748 for (in = escaped, in_end = escaped + len; in < in_end; in++)
1754 /* catch partial escape sequences past the end of the substring */
1755 if (in + 3 > in_end)
1758 c = unescape_character (in + 1);
1760 /* catch bad escape sequences and NUL characters */
1764 /* catch escaped ASCII */
1765 if (ascii_must_not_be_escaped && c <= 0x7F)
1768 /* catch other illegal escaped characters */
1769 if (strchr (illegal_escaped_characters, c) != NULL)
1778 g_assert (out - result <= len);
1791 is_asciialphanum (gunichar c)
1793 return c <= 0x7F && g_ascii_isalnum (c);
1797 is_asciialpha (gunichar c)
1799 return c <= 0x7F && g_ascii_isalpha (c);
1802 /* allows an empty string */
1804 hostname_validate (const char *hostname)
1807 gunichar c, first_char, last_char;
1814 /* read in a label */
1815 c = g_utf8_get_char (p);
1816 p = g_utf8_next_char (p);
1817 if (!is_asciialphanum (c))
1823 c = g_utf8_get_char (p);
1824 p = g_utf8_next_char (p);
1826 while (is_asciialphanum (c) || c == '-');
1827 if (last_char == '-')
1830 /* if that was the last label, check that it was a toplabel */
1831 if (c == '\0' || (c == '.' && *p == '\0'))
1832 return is_asciialpha (first_char);
1839 * g_filename_from_uri:
1840 * @uri: a uri describing a filename (escaped, encoded in ASCII).
1841 * @hostname: (allow-none): Location to store hostname for the URI, or %NULL.
1842 * If there is no hostname in the URI, %NULL will be
1843 * stored in this location.
1844 * @error: location to store the error occurring, or %NULL to ignore
1845 * errors. Any of the errors in #GConvertError may occur.
1847 * Converts an escaped ASCII-encoded URI to a local filename in the
1848 * encoding used for filenames.
1850 * Return value: a newly-allocated string holding the resulting
1851 * filename, or %NULL on an error.
1854 g_filename_from_uri (const gchar *uri,
1858 const char *path_part;
1859 const char *host_part;
1860 char *unescaped_hostname;
1871 if (!has_case_prefix (uri, "file:/"))
1873 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_BAD_URI,
1874 _("The URI '%s' is not an absolute URI using the \"file\" scheme"),
1879 path_part = uri + strlen ("file:");
1881 if (strchr (path_part, '#') != NULL)
1883 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_BAD_URI,
1884 _("The local file URI '%s' may not include a '#'"),
1889 if (has_case_prefix (path_part, "///"))
1891 else if (has_case_prefix (path_part, "//"))
1894 host_part = path_part;
1896 path_part = strchr (path_part, '/');
1898 if (path_part == NULL)
1900 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_BAD_URI,
1901 _("The URI '%s' is invalid"),
1906 unescaped_hostname = g_unescape_uri_string (host_part, path_part - host_part, "", TRUE);
1908 if (unescaped_hostname == NULL ||
1909 !hostname_validate (unescaped_hostname))
1911 g_free (unescaped_hostname);
1912 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_BAD_URI,
1913 _("The hostname of the URI '%s' is invalid"),
1919 *hostname = unescaped_hostname;
1921 g_free (unescaped_hostname);
1924 filename = g_unescape_uri_string (path_part, -1, "/", FALSE);
1926 if (filename == NULL)
1928 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_BAD_URI,
1929 _("The URI '%s' contains invalidly escaped characters"),
1936 /* Drop localhost */
1937 if (hostname && *hostname != NULL &&
1938 g_ascii_strcasecmp (*hostname, "localhost") == 0)
1944 /* Turn slashes into backslashes, because that's the canonical spelling */
1946 while ((slash = strchr (p, '/')) != NULL)
1952 /* Windows URIs with a drive letter can be like "file://host/c:/foo"
1953 * or "file://host/c|/foo" (some Netscape versions). In those cases, start
1954 * the filename from the drive letter.
1956 if (g_ascii_isalpha (filename[1]))
1958 if (filename[2] == ':')
1960 else if (filename[2] == '|')
1968 result = g_strdup (filename + offs);
1974 #if defined (G_OS_WIN32) && !defined (_WIN64)
1976 #undef g_filename_from_uri
1979 g_filename_from_uri (const gchar *uri,
1983 gchar *utf8_filename;
1984 gchar *retval = NULL;
1986 utf8_filename = g_filename_from_uri_utf8 (uri, hostname, error);
1989 retval = g_locale_from_utf8 (utf8_filename, -1, NULL, NULL, error);
1990 g_free (utf8_filename);
1998 * g_filename_to_uri:
1999 * @filename: an absolute filename specified in the GLib file name encoding,
2000 * which is the on-disk file name bytes on Unix, and UTF-8 on
2002 * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none.
2003 * @error: location to store the error occurring, or %NULL to ignore
2004 * errors. Any of the errors in #GConvertError may occur.
2006 * Converts an absolute filename to an escaped ASCII-encoded URI, with the path
2007 * component following Section 3.3. of RFC 2396.
2009 * Return value: a newly-allocated string holding the resulting
2010 * URI, or %NULL on an error.
2013 g_filename_to_uri (const gchar *filename,
2014 const gchar *hostname,
2019 g_return_val_if_fail (filename != NULL, NULL);
2021 if (!g_path_is_absolute (filename))
2023 g_set_error (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NOT_ABSOLUTE_PATH,
2024 _("The pathname '%s' is not an absolute path"),
2030 !(g_utf8_validate (hostname, -1, NULL)
2031 && hostname_validate (hostname)))
2033 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
2034 _("Invalid hostname"));
2039 /* Don't use localhost unnecessarily */
2040 if (hostname && g_ascii_strcasecmp (hostname, "localhost") == 0)
2044 escaped_uri = g_escape_file_uri (hostname, filename);
2049 #if defined (G_OS_WIN32) && !defined (_WIN64)
2051 #undef g_filename_to_uri
2054 g_filename_to_uri (const gchar *filename,
2055 const gchar *hostname,
2058 gchar *utf8_filename;
2059 gchar *retval = NULL;
2061 utf8_filename = g_locale_to_utf8 (filename, -1, NULL, NULL, error);
2065 retval = g_filename_to_uri_utf8 (utf8_filename, hostname, error);
2066 g_free (utf8_filename);
2075 * g_uri_list_extract_uris:
2076 * @uri_list: an URI list
2078 * Splits an URI list conforming to the text/uri-list
2079 * mime type defined in RFC 2483 into individual URIs,
2080 * discarding any comments. The URIs are not validated.
2082 * Returns: (transfer full): a newly allocated %NULL-terminated list
2083 * of strings holding the individual URIs. The array should be freed
2084 * with g_strfreev().
2089 g_uri_list_extract_uris (const gchar *uri_list)
2100 /* We don't actually try to validate the URI according to RFC
2101 * 2396, or even check for allowed characters - we just ignore
2102 * comments and trim whitespace off the ends. We also
2103 * allow LF delimination as well as the specified CRLF.
2105 * We do allow comments like specified in RFC 2483.
2111 while (g_ascii_isspace (*p))
2115 while (*q && (*q != '\n') && (*q != '\r'))
2121 while (q > p && g_ascii_isspace (*q))
2126 uris = g_slist_prepend (uris, g_strndup (p, q - p + 1));
2131 p = strchr (p, '\n');
2136 result = g_new (gchar *, n_uris + 1);
2138 result[n_uris--] = NULL;
2139 for (u = uris; u; u = u->next)
2140 result[n_uris--] = u->data;
2142 g_slist_free (uris);
2148 * g_filename_display_basename:
2149 * @filename: an absolute pathname in the GLib file name encoding
2151 * Returns the display basename for the particular filename, guaranteed
2152 * to be valid UTF-8. The display name might not be identical to the filename,
2153 * for instance there might be problems converting it to UTF-8, and some files
2154 * can be translated in the display.
2156 * If GLib cannot make sense of the encoding of @filename, as a last resort it
2157 * replaces unknown characters with U+FFFD, the Unicode replacement character.
2158 * You can search the result for the UTF-8 encoding of this character (which is
2159 * "\357\277\275" in octal notation) to find out if @filename was in an invalid
2162 * You must pass the whole absolute pathname to this functions so that
2163 * translation of well known locations can be done.
2165 * This function is preferred over g_filename_display_name() if you know the
2166 * whole path, as it allows translation.
2168 * Return value: a newly allocated string containing
2169 * a rendition of the basename of the filename in valid UTF-8
2174 g_filename_display_basename (const gchar *filename)
2179 g_return_val_if_fail (filename != NULL, NULL);
2181 basename = g_path_get_basename (filename);
2182 display_name = g_filename_display_name (basename);
2184 return display_name;
2188 * g_filename_display_name:
2189 * @filename: a pathname hopefully in the GLib file name encoding
2191 * Converts a filename into a valid UTF-8 string. The conversion is
2192 * not necessarily reversible, so you should keep the original around
2193 * and use the return value of this function only for display purposes.
2194 * Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL
2195 * even if the filename actually isn't in the GLib file name encoding.
2197 * If GLib cannot make sense of the encoding of @filename, as a last resort it
2198 * replaces unknown characters with U+FFFD, the Unicode replacement character.
2199 * You can search the result for the UTF-8 encoding of this character (which is
2200 * "\357\277\275" in octal notation) to find out if @filename was in an invalid
2203 * If you know the whole pathname of the file you should use
2204 * g_filename_display_basename(), since that allows location-based
2205 * translation of filenames.
2207 * Return value: a newly allocated string containing
2208 * a rendition of the filename in valid UTF-8
2213 g_filename_display_name (const gchar *filename)
2216 const gchar **charsets;
2217 gchar *display_name = NULL;
2220 is_utf8 = g_get_filename_charsets (&charsets);
2224 if (g_utf8_validate (filename, -1, NULL))
2225 display_name = g_strdup (filename);
2230 /* Try to convert from the filename charsets to UTF-8.
2231 * Skip the first charset if it is UTF-8.
2233 for (i = is_utf8 ? 1 : 0; charsets[i]; i++)
2235 display_name = g_convert (filename, -1, "UTF-8", charsets[i],
2243 /* if all conversions failed, we replace invalid UTF-8
2244 * by a question mark
2247 display_name = _g_utf8_make_valid (filename);
2249 return display_name;