*
* \section intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.3.1. If you
+ * This is the documentation for the library interface of wimlib 1.3.2. If you
* have installed wimlib and want to know how to use the @b wimlib-imagex
* program, please see the man pages instead. Also: the actual project page
* where you can download the source code for the library is at <a
*
* \section encodings Locales and character encodings
*
- * wimlib 1.3.0 has improved handling of different character encodings compared
- * to 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 @b wimlib-imagex for more
- * information. However, I strongly recommend that you use UTF-8 for your
- * locale's encoding so that ::wimlib_mbchar strings will be encoded the same
- * way as ::wimlib_utf8char strings.
+ * To support Windows as well as UNIX, wimlib's API typically takes and returns
+ * strings of ::wimlib_tchar, which are in a platform-dependent encoding.
+ *
+ * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t",
+ * and the encoding is UTF-16LE.
+ *
+ * On UNIX, each ::wimlib_tchar is 1 byte and is simply a "char", and the
+* encoding is the locale-dependent multibyte encoding. I recommend you set your
+* locale to a UTF-8 capable locale to avoid any issues. Also, by default,
+ * wimlib on UNIX will assume the locale is UTF-8 capable unless you call
+* wimlib_global_init() after having set your desired locale.
*
* \section Limitations
*
* without mounting it, other than by adding, removing, or extracting an
* entire image. The FUSE mount feature should be used for this purpose.
* - Currently, Microsoft's @a image.exe can create slightly smaller WIM files
- * than wimlib when using maximum (LZX) compression because it knows how to
- * split up LZX compressed blocks, which is not yet implemented in wimlib.
+ * than wimlib (~2% or 3% smaller) when using maximum (LZX) compression.
* - wimlib is experimental and likely contains bugs; use Microsoft's @a
* imagex.exe if you want to make sure your WIM files are made "correctly".
* - The old WIM format from Vista pre-releases is not supported.
#define WIMLIB_MINOR_VERSION 3
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 2
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
#ifdef __WIN32__
typedef wchar_t wimlib_tchar;
#else
+/** See \ref encodings */
typedef char wimlib_tchar;
#endif
* mode, or in Win32 native builds. */
#define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS 0x00000020
+/** Fail immediately if the full security descriptor of any file or directory
+ * cannot be accessed. Only has an effect in Win32 native builds. The default
+ * behavior without this flag is to first try omitting the SACL from the
+ * security descriptor, then to try omitting the security descriptor entirely.
+ * */
+#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS 0x00000040
+
/******************************
* WIMLIB_EXPORT_FLAG_* *
******************************/
/** Do not extract security descriptors. Only has an effect in NTFS apply mode,
* or in Win32 native builds. */
-#define WIMLIB_EXTRACT_FLAG_NOACLS 0x00000040
+#define WIMLIB_EXTRACT_FLAG_NO_ACLS 0x00000040
+
+/** Fail immediately if the full security descriptor of any file or directory
+ * cannot be set exactly as specified in the WIM file. The default behavior
+ * without this flag is to fall back to setting the security descriptor with the
+ * SACL omitted, then only the default inherited security descriptor, if we do
+ * not have permission to set the desired one. */
+#define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080
/******************************
* WIMLIB_MOUNT_FLAG_* *
/**
* 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. 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.
+ * threads, then you must call this function serially first.
+ *
+ * Since wimlib 1.3.0, you must call this function if the character encoding of
+ * the current locale is not UTF-8.
+ *
+ * Since wimlib 1.3.2, you must call this function if using the Windows-native
+ * build of the library so that certain functions can be dynamically loaded from
+ * system DLLs.
*
- * This function always returns 0.
+ * This function currently always returns 0, but it may return other error codes
+ * in future releases.
*/
extern int
wimlib_global_init();
git://wimlib.net / wimlib / blobdiff