X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=43c38526349f9ae456c819e6d5582d3c7d189443;hb=bd926816f3b9d5982d1c497840c56724520c62dc;hp=02b1ce9f08688c0fe22aa69d784bffb00cdc7cef;hpb=dcc5063d306e7c82e38968548db370960a4efbce;p=wimlib
diff --git a/include/wimlib.h b/include/wimlib.h
index 02b1ce9f..43c38526 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -11,13 +11,12 @@
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.9.0, a C
+ * This is the documentation for the library interface of wimlib 1.13.0, a C
* library for creating, modifying, extracting, and mounting files in the
- * Windows Imaging Format. This documentation is intended for developers only.
- * If you have installed wimlib and want to know how to use the @b wimlib-imagex
- * program, please see the manual pages and also the README
- * file.
+ * Windows Imaging (WIM) format. This documentation is intended for developers
+ * only. If you have installed wimlib and want to know how to use the @b
+ * wimlib-imagex program, please see the manual pages and also the README file.
*
* @section sec_installing Installing
*
@@ -32,13 +31,16 @@
*
* Download the Windows binary distribution with the appropriate architecture
* (i686 or x86_64 --- also called "x86" and "amd64" respectively) from
- * https://wimlib.net. Link your program with the libwim-15.dll file. Make
- * sure to also download the source code so you can get wimlib.h, as it is not
- * included in the binary distribution. If you need to access the DLL from
- * other programming languages, note that the calling convention is "cdecl".
+ * https://wimlib.net. Link your program with libwim-15.dll. If needed by your
+ * programming language or development environment, the import library
+ * libwim.lib and C/C++ header wimlib.h can be found in the directory "devel" in
+ * the ZIP file.
*
- * Note that wimlib is developed using MinGW-w64, and there may be a little work
- * required if you plan to use the header and DLL with Visual Studio.
+ * If you need to access the DLL from non-C/C++ programming languages, note that
+ * the calling convention is "cdecl".
+ *
+ * If you want to build wimlib from source on Windows, see README.WINDOWS. This
+ * is only needed if you are making modifications to wimlib.
*
* @section sec_examples Examples
*
@@ -46,7 +48,7 @@
* distribution. Also see @ref sec_basic_wim_handling_concepts below.
*
* There is also the
+ * href="https://wimlib.net/git/?p=wimlib;a=blob;f=programs/imagex.c">
* source code of wimlib-imagex, which is complicated but uses most
* capabilities of wimlib.
*
@@ -142,20 +144,21 @@
* messages and strings (as well as all documentation, for that matter) are only
* available in English.
*
- * @section sec_encodings Locales and character encodings
+ * @section sec_encodings Character encoding
*
* To support Windows as well as UNIX-like systems, wimlib's API typically takes
- * and returns strings of ::wimlib_tchar, which are in a platform-dependent
- * encoding.
+ * and returns strings of ::wimlib_tchar which have a platform-dependent type
+ * and encoding.
*
- * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t",
- * and the encoding is UTF-16LE.
+ * On Windows, each ::wimlib_tchar is a 2-byte wchar_t. The encoding
+ * is meant to be UTF-16LE. However, unpaired surrogates are permitted because
+ * neither Windows nor the NTFS filesystem forbids them in filenames.
*
- * On UNIX-like systems, 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.
+ * On UNIX-like systems, each ::wimlib_tchar is a 1 byte char. The
+ * encoding is meant to be UTF-8. However, for compatibility with Windows-style
+ * filenames that are not valid UTF-16LE, surrogate codepoints are permitted.
+ * Other multibyte encodings (e.g. ISO-8859-1) or garbage sequences of bytes are
+ * not permitted.
*
* @section sec_advanced Additional information and features
*
@@ -346,10 +349,10 @@
* such as wimlib_join(), also take the progress function directly using an
* extended version of the function, such as wimlib_join_with_progress().
*
- * In wimlib v1.7.0 and later, progress functions are no longer just
- * unidirectional. You can now return ::WIMLIB_PROGRESS_STATUS_ABORT to cause
- * the current operation to be aborted. wimlib v1.7.0 also added the third
- * argument to ::wimlib_progress_func_t, which is a user-supplied context.
+ * Since wimlib v1.7.0, progress functions are no longer just unidirectional.
+ * You can now return ::WIMLIB_PROGRESS_STATUS_ABORT to cause the current
+ * operation to be aborted. wimlib v1.7.0 also added the third argument to
+ * ::wimlib_progress_func_t, which is a user-supplied context.
*/
/** @defgroup G_writing_and_overwriting_wims Writing and Overwriting WIMs
@@ -388,8 +391,14 @@
#include
#include
-#include
-#include
+#ifndef __cplusplus
+# if defined(_MSC_VER) && _MSC_VER < 1800 /* VS pre-2013? */
+ typedef unsigned char bool;
+# else
+# include
+# endif
+#endif
+#include
#include
/** @addtogroup G_general
@@ -399,7 +408,7 @@
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 9
+#define WIMLIB_MINOR_VERSION 13
/** Patch version of the library (for example, the 5 in 1.2.5). */
#define WIMLIB_PATCH_VERSION 0
@@ -408,6 +417,32 @@
extern "C" {
#endif
+/*
+ * To represent file timestamps, wimlib's API originally used the POSIX 'struct
+ * timespec'. This was a mistake because when building wimlib for 32-bit
+ * Windows with MinGW we ended up originally using 32-bit time_t which isn't
+ * year 2038-safe, and therefore we had to later add fields like
+ * 'creation_time_high' to hold the high 32 bits of each timestamp. Moreover,
+ * old Visual Studio versions did not define struct timespec, while newer ones
+ * define it but with 64-bit tv_sec. So to at least avoid a missing or
+ * incompatible 'struct timespec' definition, define the correct struct
+ * ourselves when this header is included on Windows.
+ */
+#ifdef _WIN32
+struct wimlib_timespec {
+ /* Seconds since start of UNIX epoch (January 1, 1970) */
+#ifdef _WIN64
+ int64_t tv_sec;
+#else
+ int32_t tv_sec;
+#endif
+ /* Nanoseconds (0-999999999) */
+ int32_t tv_nsec;
+};
+#else
+# define wimlib_timespec timespec /* standard definition */
+#endif
+
/**
* Opaque structure that represents a WIM, possibly backed by an on-disk file.
* See @ref sec_basic_wim_handling_concepts for more information.
@@ -417,14 +452,14 @@ typedef struct WIMStruct WIMStruct;
#define WIMLIB_WIMSTRUCT_DECLARED
#endif
-#ifdef __WIN32__
+#ifdef _WIN32
typedef wchar_t wimlib_tchar;
#else
/** See @ref sec_encodings */
typedef char wimlib_tchar;
#endif
-#ifdef __WIN32__
+#ifdef _WIN32
/** Path separator for WIM paths passed back to progress callbacks.
* This is forward slash on UNIX and backslash on Windows. */
# define WIMLIB_WIM_PATH_SEPARATOR '\\'
@@ -1063,8 +1098,8 @@ union wimlib_progress_info {
/** Name of the split WIM part that is about to be started
* (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been
- * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART).
- * As of wimlib v1.7.0, the library user may change this when
+ * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). Since
+ * wimlib v1.7.0, the library user may change this when
* receiving ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART in order to
* cause the next split WIM part to be written to a different
* location. */
@@ -1461,8 +1496,8 @@ struct wimlib_stream_entry {
};
/**
- * An object ID, which is an extra piece of metadata that may be associated with
- * a file on NTFS filesystems. See:
+ * Since wimlib v1.9.1: an object ID, which is an extra piece of metadata that
+ * may be associated with a file on NTFS filesystems. See:
* https://msdn.microsoft.com/en-us/library/windows/desktop/aa363997(v=vs.85).aspx
*/
struct wimlib_object_id {
@@ -1559,13 +1594,13 @@ struct wimlib_dir_entry {
uint64_t hard_link_group_id;
/** Time this file was created. */
- struct timespec creation_time;
+ struct wimlib_timespec creation_time;
/** Time this file was last written to. */
- struct timespec last_write_time;
+ struct wimlib_timespec last_write_time;
/** Time this file was last accessed. */
- struct timespec last_access_time;
+ struct wimlib_timespec last_access_time;
/** The UNIX user ID of this file. This is a wimlib extension.
*
@@ -1594,7 +1629,21 @@ struct wimlib_dir_entry {
* object_id.object_id is not all zeroes. */
struct wimlib_object_id object_id;
- uint64_t reserved[6];
+ /** High 32 bits of the seconds portion of the creation timestamp,
+ * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */
+ int32_t creation_time_high;
+
+ /** High 32 bits of the seconds portion of the last write timestamp,
+ * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */
+ int32_t last_write_time_high;
+
+ /** High 32 bits of the seconds portion of the last access timestamp,
+ * filled in if @p wimlib_timespec.tv_sec is only 32-bit. */
+ int32_t last_access_time_high;
+
+ int32_t reserved2;
+
+ uint64_t reserved[4];
/**
* Variable-length array of streams that make up this file.
@@ -1679,8 +1728,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID
* (major and minor number) of each file. In addition, capture special files
- * such as device nodes and FIFOs. See the documentation for the
- * --unix-data option to wimcapture for more information. */
+ * such as device nodes and FIFOs. Since wimlib v1.11.0, on Linux also capture
+ * extended attributes. See the documentation for the --unix-data option
+ * to wimcapture for more information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS-3G capture
@@ -1872,9 +1922,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* wimlib_extract_paths() when passed multiple paths. */
#define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001
-/** UNIX-like systems only: Extract special UNIX data captured with
- * ::WIMLIB_ADD_FLAG_UNIX_DATA. This flag cannot be combined with
- * ::WIMLIB_EXTRACT_FLAG_NTFS. */
+/** UNIX-like systems only: Extract UNIX-specific metadata captured with
+ * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020
/** Do not extract security descriptors. This flag cannot be combined with
@@ -2034,8 +2083,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* name, a colon, then the name of the data stream. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010
-/** Use UNIX metadata if available in the WIM image. See
- * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
+/** Support UNIX owners, groups, modes, and special files. */
#define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020
/** Allow other users to see the mounted filesystem. This passes the @c
@@ -2324,9 +2372,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** @addtogroup G_general
* @{ */
-/** Assume that strings are represented in UTF-8, even if this is not the
- * locale's character encoding. This flag is ignored on Windows, where wimlib
- * always uses UTF-16LE. */
+/** Deprecated; no longer has any effect. */
#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
/** Windows-only: do not attempt to acquire additional privileges (currently
@@ -2463,7 +2509,6 @@ enum wimlib_error_code {
WIMLIB_ERR_DECOMPRESSION = 2,
WIMLIB_ERR_FUSE = 6,
WIMLIB_ERR_GLOB_HAD_NO_MATCHES = 8,
- WIMLIB_ERR_ICONV_NOT_AVAILABLE = 9,
WIMLIB_ERR_IMAGE_COUNT = 10,
WIMLIB_ERR_IMAGE_NAME_COLLISION = 11,
WIMLIB_ERR_INSUFFICIENT_PRIVILEGES = 12,
@@ -2476,7 +2521,6 @@ enum wimlib_error_code {
WIMLIB_ERR_INVALID_INTEGRITY_TABLE = 19,
WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY = 20,
WIMLIB_ERR_INVALID_METADATA_RESOURCE = 21,
- WIMLIB_ERR_INVALID_MULTIBYTE_STRING = 22,
WIMLIB_ERR_INVALID_OVERLAY = 23,
WIMLIB_ERR_INVALID_PARAM = 24,
WIMLIB_ERR_INVALID_PART_NUMBER = 25,
@@ -2539,6 +2583,8 @@ enum wimlib_error_code {
WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87,
WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88,
WIMLIB_ERR_SNAPSHOT_FAILURE = 89,
+ WIMLIB_ERR_INVALID_XATTR = 90,
+ WIMLIB_ERR_SET_XATTR = 91,
};
@@ -3009,6 +3055,9 @@ wimlib_extract_image_from_pipe_with_progress(int pipe_fd,
* are otherwise delimited by the newline character. However, quotes will be
* stripped if present.
*
+ * If @p path_list_file is @c NULL, then the pathlist file is read from standard
+ * input.
+ *
* The error codes are the same as those returned by wimlib_extract_paths(),
* except that wimlib_extract_pathlist() returns an appropriate error code if it
* cannot read the path list file (e.g. ::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT,
@@ -3044,7 +3093,7 @@ wimlib_extract_pathlist(WIMStruct *wim, int image,
* to match no files, and there is a flag (::WIMLIB_EXTRACT_FLAG_STRICT_GLOB) to
* enable the strict behavior if desired.
*
- * Symbolic are not be dereferenced when paths in the image are interpreted.
+ * Symbolic links are not dereferenced when paths in the image are interpreted.
*
* @param wim
* WIM from which to extract the paths, specified as a pointer to the
@@ -3227,6 +3276,16 @@ wimlib_get_image_property(const WIMStruct *wim, int image,
extern uint32_t
wimlib_get_version(void);
+/**
+ * @ingroup G_general
+ *
+ * Since wimlib v1.13.0: like wimlib_get_version(), but returns the full
+ * PACKAGE_VERSION string that was set at build time. (This allows a beta
+ * release to be distinguished from an official release.)
+ */
+extern const wimlib_tchar *
+wimlib_get_version_string(void);
+
/**
* @ingroup G_wim_information
*
@@ -3279,9 +3338,8 @@ wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret);
*
* Initialization function for wimlib. Call before using any other wimlib
* function (except possibly wimlib_set_print_errors()). If not done manually,
- * this function will be called automatically with @p init_flags set to
- * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. This function does nothing if called again
- * after it has already successfully run.
+ * this function will be called automatically with a flags argument of 0. This
+ * function does nothing if called again after it has already successfully run.
*
* @param init_flags
* Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG.
@@ -4335,8 +4393,9 @@ wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags);
* @ingroup G_mounting_wim_images
*
* Same as wimlib_unmount_image(), but allows specifying a progress function.
- * If changes are committed from a read-write mount, the progress function will
- * receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages.
+ * The progress function will receive a ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN
+ * message. In addition, if changes are committed from a read-write mount, the
+ * progress function will receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages.
*/
extern int
wimlib_unmount_image_with_progress(const wimlib_tchar *dir,