From 00334bdf09071e65e340eeeb6f3900c79a262649 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Wed, 20 Mar 2013 19:49:09 -0500 Subject: [PATCH 1/1] Update docs --- NEWS | 2 ++ doc/imagex.1.in | 15 +++++++++++++++ programs/imagex.c | 3 +++ src/encoding.c | 2 +- src/wim.c | 5 ++--- src/wimlib.h | 30 +++++++++++++++--------------- src/wimlib_internal.h | 2 +- 7 files changed, 39 insertions(+), 20 deletions(-) diff --git a/NEWS b/NEWS index 5c657558..ad68f6ac 100644 --- 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. diff --git a/doc/imagex.1.in b/doc/imagex.1.in index 9e01c800..c694dd33 100644 --- a/doc/imagex.1.in +++ b/doc/imagex.1.in @@ -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 diff --git a/programs/imagex.c b/programs/imagex.c index 580e65ac..c8fa94af 100644 --- a/programs/imagex.c +++ b/programs/imagex.c @@ -38,6 +38,7 @@ #include #include #include +#include #ifdef HAVE_ALLOCA_H #include @@ -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(); diff --git a/src/encoding.c b/src/encoding.c index e8bc4027..aa8f9281 100644 --- a/src/encoding.c +++ b/src/encoding.c @@ -32,7 +32,7 @@ #include #include -bool wimlib_mbs_is_utf8 = false; +bool wimlib_mbs_is_utf8 = true; struct iconv_list_head { const char *from_encoding; diff --git a/src/wim.c b/src/wim.c index 6262a1b7..667d076b 100644 --- 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 diff --git a/src/wimlib.h b/src/wimlib.h index f875afb9..1fe08ef5 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -181,11 +181,20 @@ * wimlib also comes with the mkwinpeimg 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(); diff --git a/src/wimlib_internal.h b/src/wimlib_internal.h index be06dafd..43331e2b 100644 --- a/src/wimlib_internal.h +++ b/src/wimlib_internal.h @@ -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. * -- 2.43.0