Update docs
authorEric Biggers <ebiggers3@gmail.com>
Thu, 21 Mar 2013 00:49:09 +0000 (19:49 -0500)
committerEric Biggers <ebiggers3@gmail.com>
Thu, 21 Mar 2013 00:49:09 +0000 (19:49 -0500)
NEWS
doc/imagex.1.in
programs/imagex.c
src/encoding.c
src/wim.c
src/wimlib.h
src/wimlib_internal.h

diff --git a/NEWS b/NEWS
index 5c65755..ad68f6a 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -5,6 +5,8 @@ Version 1.3.0:
 
        --source-list option added to `imagex capture' and `imagex append'.
 
+       Better support for different character encodings.
+
 Version 1.2.6:
        Storing UNIX file owners, groups, and modes in WIM images is now
        possible using `imagex capture' with the --unix-data flag.
index 9e01c80..c694dd3 100644 (file)
@@ -149,6 +149,21 @@ wimlib's \fBimagex mount\fR supports mounting an image from a split WIM, but
 Microsoft's software does not.  (Note: this functionality is only available on
 UNIX builds.)
 
+.SH LOCALES AND CHARACTER ENCODINGS
+
+wimlib 1.3.0 has improved support for alternate character encodings.
+However, not everything has been well tested, and on UNIX you are strongly
+encouraged to use a UTF-8 locale so that you do not run into any problems.
+In particular, if your locale uses a character encoding that is
+not UTF-8, then you will not be able to open or capture WIM files containing
+files with paths not representable in the current locale's character encoding.
+
+Similar restrictions apply to the Windows-native build of wimlib, but
+unfortunately Windows does not support UTF-8 locales.  So you will not be able
+to apply a WIM image containing files with names not representable in the
+current Windows code page, nor will you be able to capture a directory tree
+containing files with names not representable in the current Windows code page.
+
 .SH WARNING
 
 Note: \fBwimlib\fR and \fBimagex\fR are experimental.  Use Microsoft's
index 580e65a..c8fa94a 100644 (file)
@@ -38,6 +38,7 @@
 #include <string.h>
 #include <sys/stat.h>
 #include <unistd.h>
+#include <locale.h>
 
 #ifdef HAVE_ALLOCA_H
 #include <alloca.h>
@@ -2120,6 +2121,8 @@ int main(int argc, char **argv)
        const struct imagex_command *cmd;
        int ret;
 
+       setlocale(LC_ALL, "");
+
        if (argc < 2) {
                imagex_error("No command specified");
                usage_all();
index e8bc402..aa8f928 100644 (file)
@@ -32,7 +32,7 @@
 #include <stdlib.h>
 #include <errno.h>
 
-bool wimlib_mbs_is_utf8 = false;
+bool wimlib_mbs_is_utf8 = true;
 
 struct iconv_list_head {
        const char *from_encoding;
index 6262a1b..667d076 100644 (file)
--- a/src/wim.c
+++ b/src/wim.c
@@ -670,7 +670,8 @@ wimlib_free(WIMStruct *w)
        DEBUG("Freed WIMStruct");
 }
 
-static bool test_locale_ctype_utf8()
+static bool
+test_locale_ctype_utf8()
 {
        char *ctype = nl_langinfo(CODESET);
 
@@ -680,8 +681,6 @@ static bool test_locale_ctype_utf8()
                strstr(ctype, "utf-8") == 0);
 }
 
-bool wimlib_mbs_is_utf8;
-
 /* Get global memory allocations out of the way.  Not strictly necessary in
  * single-threaded programs like 'imagex'. */
 WIMLIBAPI int
index f875afb..1fe08ef 100644 (file)
  * wimlib also comes with the <b>mkwinpeimg</b> script, which is documented in a
  * man page.
  *
+ * \section Locales and character encodings
+ *
+ * wimlib 1.3.0 is able to better handle alternate character encodings than
+ * previous versions.  Functions are explictly noted as taking ::wimlib_mbchar
+ * strings, which are encoded in the locale-dependent multibyte encoding (e.g.
+ * ASCII, ISO-8859-1, or UTF-8), or ::wimlib_utf8char strings, which are
+ * encoded in UTF-8.  Generally, filenames and paths are in the locale-dependent
+ * multibyte encoding, while other types of data must be provided in UTF-8.
+ * Please see the  man page for 'imagex' for more information.
+ *
  * \section Limitations
  *
  * While wimlib supports the main features of WIM files, wimlib currently has
  * the following limitations:
- * - wimlib cannot be used on MS-Windows.
  * - There is no way to add, remove, modify, or extract specific files in a WIM
  *   without mounting it, other than by adding, removing, or extracting an
  *   entire image.  The FUSE mount feature should be used for this purpose.
@@ -1403,21 +1412,12 @@ wimlib_get_part_number(const WIMStruct *wim, int *total_parts_ret);
 /**
  * Since wimlib 1.2.6:  Initialization function for wimlib.  This is not
  * re-entrant.  If you are calling wimlib functions concurrently in different
- * threads, then you must call this function serially first.  Otherwise, calling
- * this function is not required.
+ * threads, then you must call this function serially first.  Also, since wimlib
+ * 1.3.0, you must call this function if the character encoding of the current
+ * locale is not UTF-8.  Otherwise, calling this function this function is not
+ * required.
  *
- * @return 0 on success; nonzero on error.
- * @retval ::WIMLIB_ERR_NOMEM
- *     Could not allocate memory.
- * @retval ::WIMLIB_ERR_ICONV_NOT_AVAILABLE
- *     wimlib was configured @c --without-libntfs-3g at compilation time, and
- *     at runtime the @c iconv() set of functions did not seem to be available,
- *     perhaps due to missing files in the C library installation.
- *
- * If this function is not called or returns nonzero, then it will not be safe
- * to use wimlib in multiple threads.  Furthermore, a nonzero return value here
- * indicates that further calls into wimlib will probably fail when they try to
- * repeat the same initializations.
+ * This function always returns 0.
  */
 extern int
 wimlib_global_init();
index be06daf..43331e2 100644 (file)
@@ -5,7 +5,7 @@
  */
 
 /*
- * Copyright (C) 2012 Eric Biggers
+ * Copyright (C) 2012, 2013 Eric Biggers
  *
  * This file is part of wimlib, a library for working with WIM files.
  *