/**
* @mainpage
*
- * @section sec_intro Introduction
- *
* This is the documentation for the library interface of wimlib 1.7.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 README file or manual pages.
+ * program, please see the manual pages and also the <a
+ * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/README">README
+ * file</a>.
*
- * @section sec_installing_and_compiling Installing and Compiling
+ * @section sec_installing Installing
*
- * wimlib uses the GNU autotools, so, on UNIX-like systems, it should be easy to
- * install with <code>configure && make && sudo make install</code>; however,
- * please see the README for more information about installing it.
+ * @subsection UNIX
*
- * To use wimlib in your program after installing it, include wimlib.h and link
- * your program with @c -lwim.
+ * Download the source code from <a
+ * href="http://sourceforge.net/projects/wimlib/files">http://sourceforge.net/projects/wimlib/files</a>.
+ * Install the library by running <c>configure && make && sudo make install</c>.
+ * See the README for information about configuration options. To use wimlib in
+ * your program after installing it, include wimlib.h and link your program with
+ * <c>-lwim</c>.
*
- * As of wimlib 1.5.0, wimlib.h is also compatible with C++.
+ * @subsection Windows
*
- * Note: before calling any other function declared in wimlib.h,
- * wimlib_global_init() can (and in some cases, must) be called. See its
- * documentation for more details.
+ * Download the Windows binary distribution with the appropriate architecture
+ * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from <a
+ * href="http://sourceforge.net/projects/wimlib/files">http://sourceforge.net/projects/wimlib/files</a>.
+ * 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".
+ *
+ * @section sec_examples Examples
+ *
+ * Several examples are located in the <a
+ * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/examples">examples</a>
+ * directory of the source distribution.
+ *
+ * There is also the <a
+ * href="http://sourceforge.net/p/wimlib/code/ci/master/tree/programs/imagex.c">
+ * source code of <b>wimlib-imagex</b></a>, which is complicated but uses most
+ * capabilities of wimlib.
*
* @section sec_basic_wim_handling_concepts Basic WIM handling concepts
*
* you can make multiple changes to a WIM and commit them all to the underlying
* file in only one overwrite operation, which is more efficient.
*
+ * Note: before calling any other function declared in wimlib.h,
+ * wimlib_global_init() can (and in some cases, must) be called. See its
+ * documentation for more details.
+ *
* @section sec_cleaning_up Cleaning up
*
* After you are done with any ::WIMStruct, you can call wimlib_free() to free
* @brief Write and overwrite on-disk WIM files.
*
* As described in @ref sec_basic_wim_handling_concepts, these functions are
- * critical to the design of the library as they allow new or modified WIMs to
- * actually be written to on-disk files. Generally, wimlib_write() is the
- * function you need to call to write a new WIM file, and wimlib_overwrite() is
- * the function you need to call to persistently update an existing WIM file.
+ * fundamental to the design of the library as they allow new or modified
+ * ::WIMStruct's to actually be written to on-disk files. Call wimlib_write()
+ * to write a new WIM file, or wimlib_overwrite() to persistently update an
+ * existing WIM file.
*/
/** @defgroup G_nonstandalone_wims Creating and handling non-standalone WIMs
*
* @brief Create and handle non-standalone WIMs, such as split and delta WIMs.
*
- * Normally, ::WIMStruct represents a WIM file, but there's a bit more to it
+ * Normally, a ::WIMStruct represents a WIM file, but there's a bit more to it
* than that. Normally, WIM files are "standalone". However, WIM files can
* also be arranged in non-standalone ways, such as a set of on-disk files that
* together form a single "split WIM" or "delta WIM". Such arrangements are
#include <inttypes.h>
#include <time.h>
-/** @ingroup G_general
+#ifdef __GNUC__
+# define _wimlib_deprecated __attribute__((deprecated))
+#else
+# define _wimlib_deprecated
+#endif
+
+/** @addtogroup G_general
* @{ */
/** Major version of the library (for example, the 1 in 1.2.5). */
extern "C" {
#endif
-/** @} */
-/** @ingroup G_general
- * @{ */
-
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
* and need not correspond to a specific on-disk file. However, a ::WIMStruct
#endif
#ifdef __WIN32__
-/** Path separator for WIM paths passed back to progress callbacks. */
+/** 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 '\\'
# define WIMLIB_WIM_PATH_SEPARATOR_STRING L"\\"
#else
-/** Path separator for WIM paths passed back to progress callbacks. */
+/** 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 '/'
# define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
#endif
((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \
(path)[1] == 0)
-#ifdef __GNUC__
-# define _wimlib_deprecated __attribute__((deprecated))
-#else
-# define _wimlib_deprecated
-#endif
-
+/** Length of a Globally Unique Identifier (GUID) */
#define WIMLIB_GUID_LEN 16
/**
- * Specifies the compression type of a WIM file.
+ * Specifies a compression format. Pass one of these values to
+ * wimlib_create_new_wim(), wimlib_create_compressor(), or
+ * wimlib_create_decompressor().
+ *
+ * A WIM file has one default compression type and chunk size. Normally, each
+ * resource is compressed with this compression type. However, resources may be
+ * stored as uncompressed. In addition, a WIM with the new version number of
+ * 3584, or "ESD file", might contain solid blocks with different compression
+ * types.
*/
enum wimlib_compression_type {
- /** An invalid compression type. */
- WIMLIB_COMPRESSION_TYPE_INVALID = -1,
-
- /** The WIM does not include any compressed resources. */
+ /** No compression. */
WIMLIB_COMPRESSION_TYPE_NONE = 0,
- /** Compressed resources in the WIM use XPRESS compression. */
+ /** The XPRESS compression format. This format combines Lempel-Ziv
+ * factorization with Huffman encoding. Compression and decompression
+ * are both fast. This format supports chunk sizes that are powers of 2
+ * between <c>2^12</c> and <c>2^26</c>, inclusively. */
WIMLIB_COMPRESSION_TYPE_XPRESS = 1,
- /** Compressed resources in the WIM use LZX compression. */
+ /** The LZX compression format. This format combines Lempel-Ziv
+ * factorization with Huffman encoding, but with more features and
+ * complexity than XPRESS. Compression is slow to somewhat fast,
+ * depending on the settings. Decompression is fast but slower than
+ * XPRESS. This format supports chunk sizes that are powers of 2
+ * between <c>2^15</c> and <c>2^21</c>, inclusively. Note: chunk sizes
+ * other than <c>2^15</c> are not compatible with the Microsoft
+ * implementation. */
WIMLIB_COMPRESSION_TYPE_LZX = 2,
- /** Compressed resources in the WIM use LZMS compression. Note: LZMS
- * compression is only compatible with wimlib v1.6.0 and later and with
- * WIMGAPI Windows 8 and later (and some restrictions apply on the
- * latter). */
+ /** The LZMS compression format. This format combines Lempel-Ziv
+ * factorization with adaptive Huffman encoding and range coding.
+ * Compression and decompression are both fairly slow. This format
+ * supports chunk sizes that are powers of 2 between <c>2^15</c> and
+ * <c>2^30</c>, inclusively. This format is best used for large chunk
+ * sizes. Note: LZMS compression is only compatible with wimlib v1.6.0
+ * and later, WIMGAPI Windows 8 and later, and DISM Windows 8.1 and
+ * later. Also, chunk sizes larger than <c>2^26</c> are not compatible
+ * with the Microsoft implementation. */
WIMLIB_COMPRESSION_TYPE_LZMS = 3,
};
/** @} */
-/** @ingroup G_progress
+/** @addtogroup G_progress
* @{ */
/** Possible values of the first parameter to the user-supplied
/** A WIM image is being applied with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and
* a file is being extracted normally (not as a WIMBoot "pointer file")
* due to it matching a pattern in the [PrepopulateList] section of the
- * configuration file \Windows\System32\WimBootCompress.ini in the WIM
- * image. @info will point to ::wimlib_progress_info.wimboot_exclude.
+ * configuration file @c \\Windows\\System32\\WimBootCompress.ini in the
+ * WIM image. @p info will point to
+ * ::wimlib_progress_info.wimboot_exclude.
*/
WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE = 24,
+
+ /** Starting to unmount a WIM image. @p info will point to
+ * ::wimlib_progress_info.unmount. */
+ WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25,
};
/** Valid return values from user-provided progress functions
WIMLIB_PROGRESS_STATUS_ABORT = 1,
};
-/** A pointer to this union is passed to the user-supplied
+/**
+ * A pointer to this union is passed to the user-supplied
* ::wimlib_progress_func_t progress function. One (or none) of the structures
* contained in this union will be applicable for the operation
* (::wimlib_progress_msg) indicated in the first argument to the progress
WIMLIB_SCAN_DENTRY_UNSUPPORTED,
/** The file is an absolute symbolic link or junction
- * point and it is being excluded from capture because
- * it points outside of the capture directory and
- * reparse-point fixups are enabled. (Reparse point
- * fixups can be disabled by using the flag
- * ::WIMLIB_ADD_FLAG_NORPFIX.) */
- WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK,
+ * that points into the capture directory, and
+ * reparse-point fixups are enabled, so its target is
+ * being adjusted. (Reparse point fixups can be
+ * disabled with the flag ::WIMLIB_ADD_FLAG_NORPFIX.)
+ */
+ WIMLIB_SCAN_DENTRY_FIXED_SYMLINK,
+
+ /** Reparse-point fixups are enabled, but the file is an
+ * absolute symbolic link or junction that does
+ * <b>not</b> point into the capture directory, so its
+ * target is <b>not</b> being adjusted. */
+ WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK,
} status;
union {
const wimlib_tchar *wim_target_path;
/** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
- * of @p WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is
- * the target of the absolute symbolic link or junction
- * point. */
+ * of @p WIMLIB_SCAN_DENTRY_FIXED_SYMLINK or @p
+ * WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK, this is the
+ * target of the absolute symbolic link or junction. */
const wimlib_tchar *symlink_target;
};
/** Path to which the file is being extracted */
const wimlib_tchar *extraction_path;
} wimboot_exclude;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN. */
+ struct wimlib_progress_info_unmount {
+ /** Path to directory being unmounted */
+ const wimlib_tchar *mountpoint;
+
+ /** Path to WIM file being unmounted */
+ const wimlib_tchar *mounted_wim;
+
+ /** 1-based index of image being unmounted. */
+ uint32_t mounted_image;
+
+ /** Flags that were passed to wimlib_mount_image() when the
+ * mountpoint was set up. */
+ uint32_t mount_flags;
+
+ /** Flags passed to wimlib_unmount_image(). */
+ uint32_t unmount_flags;
+ } unmount;
};
/**
void *progctx);
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** An array of these structures is passed to wimlib_add_image_multisource() to
#define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008
/** @} */
-/** @ingroup G_wim_information
- * @{ */
+
+/** @addtogroup G_wim_information
+ * { */
+
+/** @{ */
/** General information about a WIM file. */
struct wimlib_wim_info {
uint64_t reserved[2];
};
-/** A stream of a file in the WIM. */
+/** Information about a stream of a particular file in the WIM. */
struct wimlib_stream_entry {
/** Name of the stream, or NULL if the stream is unnamed. */
const wimlib_tchar *stream_name;
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** Directly capture an NTFS volume rather than a generic directory. This flag
/** Reparse-point fixups: Modify absolute symbolic links (or junction points,
* in the case of Windows) that point inside the directory being captured to
* instead be absolute relative to the directory being captured, rather than the
- * current root; also exclude absolute symbolic links that point outside the
- * directory tree being captured.
+ * current root.
*
* Without this flag, the default is to do this if WIM_HDR_FLAG_RP_FIX is set in
* the WIM header or if this is the first image being added.
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** Do not issue an error if the path to delete does not exist. */
#define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/**
* Mark each exported image as WIMBoot-compatible.
*
* Note: by itself, this does change the destination WIM's compression type, nor
- * does it add the file \Windows\System32\WimBootCompress.ini in the WIM image.
- * Before writing the destination WIM, it's recommended to do something like:
+ * does it add the file @c \\Windows\\System32\\WimBootCompress.ini in the WIM
+ * image. Before writing the destination WIM, it's recommended to do something
+ * like:
*
* \code
* wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS);
#define WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010
/** @} */
-/** @ingroup G_extracting_wims
+/** @addtogroup G_extracting_wims
* @{ */
/** Extract the image directly to an NTFS volume rather than a generic directory.
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
/** @} */
-/** @ingroup G_mounting_wim_images
+/** @addtogroup G_mounting_wim_images
* @{ */
/** Mount the WIM image read-write rather than the default of read-only. */
/** Enable FUSE debugging by passing the @c -d flag to @c fuse_main().*/
#define WIMLIB_MOUNT_FLAG_DEBUG 0x00000002
-/** Do not allow accessing alternate data streams in the mounted WIM image. */
+/** Do not allow accessing named data streams in the mounted WIM image. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE 0x00000004
-/** Access alternate data streams in the mounted WIM image through extended file
- * attributes. This is the default mode. */
+/** Access named data streams in the mounted WIM image through extended file
+ * attributes named "user.X", where X is the name of a data stream. This is the
+ * default mode. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR 0x00000008
-/** Access alternate data streams in the mounted WIM image by specifying the
- * file name, a colon, then the alternate file stream name. */
+/** Access named data streams in the mounted WIM image by specifying the file
+ * name, a colon, then the name of the data stream. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010
-/** Use UNIX file owners, groups, and modes if available in the WIM (see
- * ::WIMLIB_ADD_FLAG_UNIX_DATA). */
+/** Use UNIX metadata if available in the WIM image. See
+ * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
#define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020
-/** Allow other users to see the mounted filesystem. (this passes the @c
- * allow_other option to FUSE mount) */
+/** Allow other users to see the mounted filesystem. This passes the @c
+ * allow_other option to the FUSE mount. */
#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040
/** @} */
-/** @ingroup G_creating_and_opening_wims
+/** @addtogroup G_creating_and_opening_wims
* @{ */
/** Verify the WIM contents against the WIM's integrity table, if present. This
* causes the raw data of the WIM file, divided into 10 MB chunks, to be
* checksummed and checked against the SHA1 message digests specified in the
- * integrity table. ::WIMLIB_ERR_INTEGRITY is returned if there are any
- * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the
- * integrity table is invalid). */
+ * integrity table. If there are any mismatches, ::WIMLIB_ERR_INTEGRITY is
+ * issued. If the WIM file does not contain an integrity table, this flag has
+ * no effect. */
#define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001
-/** Issue an error if the WIM is part of a split WIM. Software can provide
- * this flag for convenience if it explicitly does not want to support split
- * WIMs. */
+/** Issue an error (::WIMLIB_ERR_IS_SPLIT_WIM) if the WIM is part of a split
+ * WIM. Software can provide this flag for convenience if it explicitly does
+ * not want to support split WIMs. */
#define WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT 0x00000002
-/** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it
- * is not. A WIM is considered writable only if it is writable at the
- * filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its
- * header, and is not part of a spanned set. It is not required to provide this
- * flag before attempting to make changes to the WIM, but with this flag you get
- * an error sooner rather than later. */
+/** Check if the WIM is writable and issue an error
+ * (::WIMLIB_ERR_WIM_IS_READONLY) if it is not. A WIM is considered writable
+ * only if it is writable at the filesystem level, does not have the
+ * WIM_HDR_FLAG_READONLY flag set in its header, and is not part of a spanned
+ * set. It is not required to provide this flag before attempting to make
+ * changes to the WIM, but with this flag you get an error sooner rather than
+ * later. */
#define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004
/** @} */
-/** @ingroup G_mounting_wim_images
+/** @addtogroup G_mounting_wim_images
* @{ */
-/** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */
+/** Provide ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image.
+ * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */
#define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001
-/** Unless this flag is given, changes to a read-write mounted WIM are
- * discarded. Ignored for read-only mounts. */
+/** Commit changes to the read-write mounted WIM image.
+ * If this flag is not specified, changes will be discarded. */
#define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002
-/** See ::WIMLIB_WRITE_FLAG_REBUILD. */
+/** Provide ::WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image.
+ * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */
#define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004
-/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */
+/** Provide ::WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image.
+ * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */
#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008
-/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */
-#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010
+/**
+ * In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM
+ * image, forces all file descriptors to the open WIM image to be closed before
+ * committing it.
+ *
+ * Without ::WIMLIB_UNMOUNT_FLAG_COMMIT or with a read-only mounted WIM image,
+ * this flag has no effect.
+ */
+#define WIMLIB_UNMOUNT_FLAG_FORCE 0x00000010
/** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted
- * image, causes the modified image to be committed as a new, unnamed image
- * appended to the archive. The original image will be unmodified. */
+ * WIM image, causes the modified image to be committed to the WIM file as a
+ * new, unnamed image appended to the archive. The original image in the WIM
+ * file will be unmodified. */
#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and
#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001
/** @} */
-/** @ingroup G_writing_and_overwriting_wims
+/** @addtogroup G_writing_and_overwriting_wims
* @{ */
/**
/**
* Write the WIM as "pipable". After writing a WIM with this flag specified,
* images from it can be applied directly from a pipe using
- * wimlib_extract_image_from_pipe(). See the documentation for the --pipable
- * flag of `wimlib-imagex capture' for more information. Beware: WIMs written
- * with this flag will not be compatible with Microsoft's software.
+ * wimlib_extract_image_from_pipe(). See the documentation for the
+ * <b>--pipable</b> option of <b>wimlib-imagex capture</b> for more information.
+ * Beware: WIMs written with this flag will not be compatible with Microsoft's
+ * software.
*
* For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to
* write the WIM as pipable if and only if it was pipable before. For
* compression ratio for the same compression type and chunk size. wimlib's LZX
* compressor currently can be given different parameters in order to achieve
* different balances between compression ratio and time. In its default mode
- * as of v1.5.3, it usually compresses slightly better than the competing
- * Microsoft implementation.
+ * as of v1.7.0, it usually compresses slightly better than the competing
+ * Microsoft implementation and is almost as fast.
*
* ::WIMLIB_WRITE_FLAG_RECOMPRESS can also be used in combination with
* ::WIMLIB_WRITE_FLAG_PACK_STREAMS to prevent any solid blocks from being
/**
* For wimlib_overwrite(), rebuild the entire WIM file, even if it otherwise
- * could be updated merely be appending to it.
+ * could be updated merely by appending to it.
*
* When rebuilding the WIM file, stream reference counts will be recomputed, and
* any streams with 0 reference count (e.g. from deleted files or images) will
* all streams recompressed in solid mode.
*
* Currently, new solid blocks will, by default, be written using LZMS
- * compression with 32 MiB (33554432 byte) chunks. Use
+ * compression with 64 MiB (67108864 byte) chunks. Use
* wimlib_set_output_pack_compression_type() and/or
* wimlib_set_output_pack_chunk_size() to change this. This is independent of
* the WIM's main compression type and chunk size; you can have a WIM that
#define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000
/** @} */
-/** @ingroup G_general
+/** @addtogroup G_general
* @{ */
/** Assume that strings are represented in UTF-8, even if this is not the
#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020
/** @} */
-/** @ingroup G_nonstandalone_wims
+/** @addtogroup G_nonstandalone_wims
* @{ */
/** For wimlib_reference_resource_files(), enable shell-style filename globbing.
#define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** The specific type of update to perform. */
};
/** @} */
-/** @ingroup G_general
+/** @addtogroup G_general
* @{ */
/**
* codes can be returned by a given function, and what they mean.
*/
enum wimlib_error_code {
- WIMLIB_ERR_SUCCESS = 0,
- WIMLIB_ERR_ALREADY_LOCKED,
- WIMLIB_ERR_DECOMPRESSION,
- WIMLIB_ERR_DELETE_STAGING_DIR,
- WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED,
- WIMLIB_ERR_FORK,
- WIMLIB_ERR_FUSE,
- WIMLIB_ERR_FUSERMOUNT,
- WIMLIB_ERR_GLOB_HAD_NO_MATCHES,
- WIMLIB_ERR_ICONV_NOT_AVAILABLE,
- WIMLIB_ERR_IMAGE_COUNT,
- WIMLIB_ERR_IMAGE_NAME_COLLISION,
- WIMLIB_ERR_INSUFFICIENT_PRIVILEGES,
- WIMLIB_ERR_INTEGRITY,
- WIMLIB_ERR_INVALID_CAPTURE_CONFIG,
- WIMLIB_ERR_INVALID_CHUNK_SIZE,
- WIMLIB_ERR_INVALID_COMPRESSION_TYPE,
- WIMLIB_ERR_INVALID_HEADER,
- WIMLIB_ERR_INVALID_IMAGE,
- WIMLIB_ERR_INVALID_INTEGRITY_TABLE,
- WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY,
- WIMLIB_ERR_INVALID_METADATA_RESOURCE,
- WIMLIB_ERR_INVALID_MULTIBYTE_STRING,
- WIMLIB_ERR_INVALID_OVERLAY,
- WIMLIB_ERR_INVALID_PARAM,
- WIMLIB_ERR_INVALID_PART_NUMBER,
- WIMLIB_ERR_INVALID_PIPABLE_WIM,
- WIMLIB_ERR_INVALID_REPARSE_DATA,
- WIMLIB_ERR_INVALID_RESOURCE_HASH,
- WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
- WIMLIB_ERR_INVALID_UTF16_STRING,
- WIMLIB_ERR_INVALID_UTF8_STRING,
- WIMLIB_ERR_IS_DIRECTORY,
- WIMLIB_ERR_IS_SPLIT_WIM,
- WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE,
- WIMLIB_ERR_LINK,
- WIMLIB_ERR_METADATA_NOT_FOUND,
- WIMLIB_ERR_MKDIR,
- WIMLIB_ERR_MQUEUE,
- WIMLIB_ERR_NOMEM,
- WIMLIB_ERR_NOTDIR,
- WIMLIB_ERR_NOTEMPTY,
- WIMLIB_ERR_NOT_A_REGULAR_FILE,
- WIMLIB_ERR_NOT_A_WIM_FILE,
- WIMLIB_ERR_NOT_PIPABLE,
- WIMLIB_ERR_NO_FILENAME,
- WIMLIB_ERR_NTFS_3G,
- WIMLIB_ERR_OPEN,
- WIMLIB_ERR_OPENDIR,
- WIMLIB_ERR_PATH_DOES_NOT_EXIST,
- WIMLIB_ERR_READ,
- WIMLIB_ERR_READLINK,
- WIMLIB_ERR_RENAME,
- WIMLIB_ERR_REOPEN,
- WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED,
- WIMLIB_ERR_RESOURCE_NOT_FOUND,
- WIMLIB_ERR_RESOURCE_ORDER,
- WIMLIB_ERR_SET_ATTRIBUTES,
- WIMLIB_ERR_SET_REPARSE_DATA,
- WIMLIB_ERR_SET_SECURITY,
- WIMLIB_ERR_SET_SHORT_NAME,
- WIMLIB_ERR_SET_TIMESTAMPS,
- WIMLIB_ERR_SPLIT_INVALID,
- WIMLIB_ERR_STAT,
- WIMLIB_ERR_TIMEOUT,
- WIMLIB_ERR_UNEXPECTED_END_OF_FILE,
- WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE,
- WIMLIB_ERR_UNKNOWN_VERSION,
- WIMLIB_ERR_UNSUPPORTED,
- WIMLIB_ERR_UNSUPPORTED_FILE,
- WIMLIB_ERR_VOLUME_LACKS_FEATURES,
- WIMLIB_ERR_WIM_IS_READONLY,
- WIMLIB_ERR_WRITE,
- WIMLIB_ERR_XML,
- WIMLIB_ERR_WIM_IS_ENCRYPTED,
- WIMLIB_ERR_WIMBOOT,
- WIMLIB_ERR_ABORTED_BY_PROGRESS,
- WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS,
- WIMLIB_ERR_MKNOD,
+ WIMLIB_ERR_SUCCESS = 0,
+ WIMLIB_ERR_ALREADY_LOCKED = 1,
+ 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,
+ WIMLIB_ERR_INTEGRITY = 13,
+ WIMLIB_ERR_INVALID_CAPTURE_CONFIG = 14,
+ WIMLIB_ERR_INVALID_CHUNK_SIZE = 15,
+ WIMLIB_ERR_INVALID_COMPRESSION_TYPE = 16,
+ WIMLIB_ERR_INVALID_HEADER = 17,
+ WIMLIB_ERR_INVALID_IMAGE = 18,
+ 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,
+ WIMLIB_ERR_INVALID_PIPABLE_WIM = 26,
+ WIMLIB_ERR_INVALID_REPARSE_DATA = 27,
+ WIMLIB_ERR_INVALID_RESOURCE_HASH = 28,
+ WIMLIB_ERR_INVALID_UTF16_STRING = 30,
+ WIMLIB_ERR_INVALID_UTF8_STRING = 31,
+ WIMLIB_ERR_IS_DIRECTORY = 32,
+ WIMLIB_ERR_IS_SPLIT_WIM = 33,
+ WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE = 34,
+ WIMLIB_ERR_LINK = 35,
+ WIMLIB_ERR_METADATA_NOT_FOUND = 36,
+ WIMLIB_ERR_MKDIR = 37,
+ WIMLIB_ERR_MQUEUE = 38,
+ WIMLIB_ERR_NOMEM = 39,
+ WIMLIB_ERR_NOTDIR = 40,
+ WIMLIB_ERR_NOTEMPTY = 41,
+ WIMLIB_ERR_NOT_A_REGULAR_FILE = 42,
+ WIMLIB_ERR_NOT_A_WIM_FILE = 43,
+ WIMLIB_ERR_NOT_PIPABLE = 44,
+ WIMLIB_ERR_NO_FILENAME = 45,
+ WIMLIB_ERR_NTFS_3G = 46,
+ WIMLIB_ERR_OPEN = 47,
+ WIMLIB_ERR_OPENDIR = 48,
+ WIMLIB_ERR_PATH_DOES_NOT_EXIST = 49,
+ WIMLIB_ERR_READ = 50,
+ WIMLIB_ERR_READLINK = 51,
+ WIMLIB_ERR_RENAME = 52,
+ WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED = 54,
+ WIMLIB_ERR_RESOURCE_NOT_FOUND = 55,
+ WIMLIB_ERR_RESOURCE_ORDER = 56,
+ WIMLIB_ERR_SET_ATTRIBUTES = 57,
+ WIMLIB_ERR_SET_REPARSE_DATA = 58,
+ WIMLIB_ERR_SET_SECURITY = 59,
+ WIMLIB_ERR_SET_SHORT_NAME = 60,
+ WIMLIB_ERR_SET_TIMESTAMPS = 61,
+ WIMLIB_ERR_SPLIT_INVALID = 62,
+ WIMLIB_ERR_STAT = 63,
+ WIMLIB_ERR_UNEXPECTED_END_OF_FILE = 65,
+ WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE = 66,
+ WIMLIB_ERR_UNKNOWN_VERSION = 67,
+ WIMLIB_ERR_UNSUPPORTED = 68,
+ WIMLIB_ERR_UNSUPPORTED_FILE = 69,
+ WIMLIB_ERR_WIM_IS_READONLY = 71,
+ WIMLIB_ERR_WRITE = 72,
+ WIMLIB_ERR_XML = 73,
+ WIMLIB_ERR_WIM_IS_ENCRYPTED = 74,
+ WIMLIB_ERR_WIMBOOT = 75,
+ WIMLIB_ERR_ABORTED_BY_PROGRESS = 76,
+ WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS = 77,
+ WIMLIB_ERR_MKNOD = 78,
+ WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79,
+ WIMLIB_ERR_NOT_A_MOUNTPOINT = 80,
+ WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81,
};
* any) until wimlib_write() or wimlib_overwrite() is called.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file to which the image will be
- * added.
+ * Pointer to the ::WIMStruct to which to add the image.
* @param source
* A path to a directory or unmounted NTFS volume that will be captured as
* a WIM image.
* ::wimlib_compression_type constants.
* @param wim_ret
* On success, a pointer to an opaque ::WIMStruct for the new WIM file is
- * written to the memory location pointed to by this paramater. The
+ * written to the memory location pointed to by this parameter. The
* ::WIMStruct must be freed using using wimlib_free() when finished with
* it.
* @return 0 on success; nonzero on error.
*
* The destination image is made to share the same dentry tree and security data
* structure as the source image. This places some restrictions on additional
- * functions that may be called. wimlib_mount_image() may not be called on
- * either the source image or the destination image without an intervening call
- * to a function that un-shares the images, such as wimlib_free() on @p
- * dest_wim, or wimlib_delete_image() on either the source or destination image.
- * Furthermore, you may not call wimlib_free() on @p src_wim before calling
- * wimlib_write() or wimlib_overwrite() on @p dest_wim because @p dest_wim will
- * have references back to @p src_wim.
+ * functions that may be called. For example, you may not call wimlib_free() on
+ * @p src_wim before calling wimlib_write() or wimlib_overwrite() on @p dest_wim
+ * because @p dest_wim will have references back to @p src_wim.
*
* If this function fails, all changes to @p dest_wim are rolled back.
*
* @ingroup G_extracting_wims
*
* Since wimlib v1.6.0: Similar to wimlib_extract_paths(), but the paths to
- * extract from the WIM image are specified in the UTF-8 text file named by @p
- * path_list_file which itself contains the list of paths to use, one per line.
- * Leading and trailing whitespace, and otherwise empty lines and lines
- * beginning with the ';' character are ignored. No quotes are needed as paths
- * are otherwise delimited by the newline character.
+ * extract from the WIM image are specified in the ASCII, UTF-8, or UTF-16LE
+ * text file named by @p path_list_file which itself contains the list of paths
+ * to use, one per line. Leading and trailing whitespace, and otherwise empty
+ * lines and lines beginning with the ';' character are ignored. No quotes are
+ * needed as paths are otherwise delimited by the newline character.
*
* 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 (::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT,
- * ::WIMLIB_ERR_READ, ::WIMLIB_ERR_NOMEM, or ::WIMLIB_ERR_INVALID_UTF8_STRING).
+ * cannot read the path list file (e.g. ::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT,
+ * ::WIMLIB_ERR_READ).
*/
extern int
wimlib_extract_pathlist(WIMStruct *wim, int image,
* See wimlib_get_xml_data() to read the XML data into memory instead.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file, which does not necessarily
- * have to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param fp
* @c stdout, or a FILE* opened for writing, to extract the data to.
*
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p wim is not a ::WIMStruct that was created by wimlib_open_wim().
* @retval ::WIMLIB_ERR_NOMEM
+ * Failed to allocate needed memory.
* @retval ::WIMLIB_ERR_READ
+ * Error reading the XML data from the WIM file.
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
- * Failed to read the XML data from the WIM.
+ * Error reading the XML data from the WIM file.
* @retval ::WIMLIB_ERR_WRITE
* Failed to completely write the XML data to @p fp.
*/
* with it.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file.
+ * Pointer to the ::WIMStruct to free.
*
* @return This function has no return value.
*/
* Returns the description of the specified image.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param image
* The number of the image, numbered starting at 1.
*
* Returns the name of the specified image.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param image
* The number of the image, numbered starting at 1.
*
* Get basic information about a WIM file.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param info
* A ::wimlib_wim_info structure that will be filled in with information
* about the WIM file.
* instead.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file, which does not necessarily
- * have to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param buf_ret
* On success, a pointer to an allocated buffer containing the raw UTF16-LE
* XML data is written to this location.
* Determines if an image name is already used by some image in the WIM.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file.
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param name
* The name to check.
*
* explicitly referenced.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
*
* @param flags
* Reserved; set to 0.
/**
* @ingroup G_mounting_wim_images
*
- * Mounts an image in a WIM file on a directory read-only or read-write.
- *
- * As this is implemented using FUSE (Filesystme in UserSpacE), this is not
- * supported if wimlib was configured with @c --without-fuse. This includes
- * Windows builds of wimlib; ::WIMLIB_ERR_UNSUPPORTED will be returned in such
- * cases.
- *
- * Calling this function daemonizes the process, unless
- * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early occur occurs. If the
- * mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), modifications
- * to the WIM are staged in a temporary directory.
- *
- * It is safe to mount multiple images from the same underlying WIM file
- * read-only at the same time, but only if different ::WIMStruct's are used. It
- * is @b not safe to mount multiple images from the same WIM file read-write at
- * the same time.
- *
- * wimlib_mount_image() cannot be used on an image that was exported with
- * wimlib_export_image() while the dentry trees for both images are still in
- * memory. In addition, wimlib_mount_image() may not be used to mount an image
- * that already has modifications pending (e.g. an image added with
- * wimlib_add_image()).
+ * Mounts an image from a WIM file on a directory read-only or read-write.
*
* @param wim
* Pointer to the ::WIMStruct containing the image to be mounted.
* @param image
- * The number of the image to mount, indexed starting from it. It must be
- * an existing, single image.
+ * The 1-based index of the image to mount.
* @param dir
- * The path to an existing empty directory to mount the image on.
+ * The path to an existing empty directory on which to mount the WIM image.
* @param mount_flags
- * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG.
+ * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. Use
+ * ::WIMLIB_MOUNT_FLAG_READWRITE to request a read-write mount instead of a
+ * read-only mount.
* @param staging_dir
- * If non-NULL, the name of a directory in which the staging directory will
- * be created. Ignored if ::WIMLIB_MOUNT_FLAG_READWRITE is not specified
- * in @p mount_flags. If left @c NULL, the staging directory is created in
- * the same directory as the WIM file that @p wim was originally read from.
+ * If non-NULL, the name of a directory in which a temporary directory for
+ * storing modified or added files will be created. Ignored if
+ * ::WIMLIB_MOUNT_FLAG_READWRITE is not specified in @p mount_flags. If
+ * left @c NULL, the staging directory is created in the same directory as
+ * the WIM file that @p wim was originally read from. The staging
+ * directory is deleted when the image is unmounted.
*
- * @return 0 on success; nonzero on error.
+ * @return 0 on success; nonzero on error. The possible error codes include:
*
* @retval ::WIMLIB_ERR_ALREADY_LOCKED
- * A read-write mount was requested, but an exclusive advisory lock on
- * the on-disk WIM file could not be acquired because another thread or
- * process has mounted an image from the WIM read-write or is currently
- * modifying the WIM in-place.
+ * An image from the WIM file is already mounted read-write, or another
+ * process is currently appending data to the WIM file.
* @retval ::WIMLIB_ERR_FUSE
- * A non-zero status was returned by @c fuse_main().
+ * A non-zero status code was returned by @c fuse_main().
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not specify an existing, single image in @p wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * @p image is shared among multiple ::WIMStruct's as a result of a call to
- * wimlib_export_image(), or @p image has been added with
- * wimlib_add_image().
+ * @p wim was @c NULL; or @p dir was NULL or the empty string; or an
+ * unrecognized flag was specified in @p mount_flags; or the WIM image has
+ * already been modified in memory (e.g. by wimlib_update_image()).
* @retval ::WIMLIB_ERR_MKDIR
* ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the
* staging directory could not be created.
- * @retval ::WIMLIB_ERR_NOTDIR
- * Could not determine the current working directory.
- * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
- * One of the dentries in the image referenced a stream not present in the
- * WIM's lookup table (or in any of the lookup tables of the split WIM
- * parts).
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but @p
- * wim is considered read-only because of any of the reasons mentioned in
- * the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
+ * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the
+ * WIM file is considered read-only because of any of the reasons mentioned
+ * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* Mounting is not supported, either because the platform is Windows, or
- * because the platform is UNIX-like and wimlib was compiled with @c
- * --without-fuse.
+ * because the platform is UNIX-like and wimlib was compiled using
+ * <code>--without-fuse</code>.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
* ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or
* ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for
* different reasons) to read the metadata resource for the image to mount.
+ *
+ * The ability to mount WIM image is implemented using FUSE (Filesystem in
+ * UserSpacE). Depending on how FUSE is set up on your system, this function
+ * may work as normal users in addition to the root user.
+ *
+ * Mounting WIM images is not supported if wimlib was configured
+ * <code>--without-fuse</code>. This includes Windows builds of wimlib;
+ * ::WIMLIB_ERR_UNSUPPORTED will be returned in such cases.
+ *
+ * Calling this function daemonizes the process, unless
+ * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early error occurs.
+ *
+ * It is safe to mount multiple images from the same underlying WIM file
+ * read-only at the same time, but only if different ::WIMStruct's are used. It
+ * is @b not safe to mount multiple images from the same WIM file read-write at
+ * the same time.
+ *
+ * To unmount the image, call wimlib_unmount_image(). This may be done in a
+ * different process.
*/
extern int
wimlib_mount_image(WIMStruct *wim,
* @param wim_ret
* On success, a pointer to an opaque ::WIMStruct for the opened WIM file
* is written to the memory location pointed to by this parameter. The
- * ::WIMStruct can be freed using using wimlib_free() when finished with
+ * ::WIMStruct must be freed using using wimlib_free() when finished with
* it.
*
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_IMAGE_COUNT
- * The WIM is not the non-first part of a split WIM, and the number of
- * metadata resources found in the WIM did not match the image count given
- * in the WIM header, or the number of <IMAGE> elements in the XML
- * data for the WIM did not match the image count given in the WIM header.
+ * The number of metadata resources found in the WIM did not match the
+ * image count specified in the WIM header, or the number of <IMAGE>
+ * elements in the XML data of the WIM did not match the image count
+ * specified in the WIM header.
* @retval ::WIMLIB_ERR_INTEGRITY
- * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and @p
- * wim_file contains an integrity table, but the SHA1 message digest for a
- * chunk of the WIM does not match the corresponding message digest given
- * in the integrity table.
+ * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and
+ * the WIM contained an integrity table, but the SHA1 message digest for a
+ * chunk of the WIM did not match the corresponding value in the integrity
+ * table.
* @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE
- * Resources in @p wim_file are compressed, but the chunk size was invalid
- * for the WIM's compression type.
+ * The library did not recognize the compression chunk size of the WIM as
+ * valid for its compression type.
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
- * The header of @p wim_file says that resources in the WIM are compressed,
- * but the header flag for a recognized compression type is not set.
+ * The library did not recognize the compression type of the WIM.
* @retval ::WIMLIB_ERR_INVALID_HEADER
- * The header of @p wim_file was otherwise invalid.
+ * The header of the WIM was otherwise invalid.
* @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE
- * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and @p
- * wim_file contains an integrity table, but the integrity table is
+ * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and
+ * the WIM contained an integrity table, but the integrity table was
* invalid.
* @retval ::WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY
- * The lookup table for the WIM was invalid.
+ * The lookup table of the WIM was invalid.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p wim_ret was @c NULL.
* @retval ::WIMLIB_ERR_IS_SPLIT_WIM
- * @p wim_file is a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was
+ * The WIM was a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was
* specified in @p open_flags.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocated needed memory.
* @retval ::WIMLIB_ERR_NOT_A_WIM_FILE
- * @p wim_file does not begin with the expected magic characters.
+ * The file did not begin with the magic characters that identify a WIM
+ * file.
* @retval ::WIMLIB_ERR_OPEN
- * Failed to open the file @p wim_file for reading.
+ * Failed to open the file for reading.
* @retval ::WIMLIB_ERR_READ
- * Failed to read data from @p wim_file.
+ * Failed to read data from the file.
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
- * Unexpected end-of-file while reading data from @p wim_file.
+ * Unexpected end-of-file while reading data from the file.
* @retval ::WIMLIB_ERR_UNKNOWN_VERSION
* The WIM version number was not recognized. (May be a pre-Vista WIM.)
* @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED
* The WIM cannot be opened because it contains encrypted segments. (It
- * may be a Windows 8 "ESD" file).
+ * may be a Windows 8 "ESD" file.)
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
* considered read-only because of any of the reasons mentioned in the
* documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
* @retval ::WIMLIB_ERR_XML
- * The XML data for @p wim_file is invalid.
+ * The XML data of the WIM was invalid.
*/
extern int
wimlib_open_wim(const wimlib_tchar *wim_file,
*
* Same as wimlib_open_wim(), but allows specifying a progress function and
* progress context. If successful, the progress function will be registered in
- * the newly open ::WIMStruct. In addition, if
+ * the newly open ::WIMStruct, as if by an automatic call to
+ * wimlib_register_progress_function(). In addition, if
* ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p open_flags, the
* progress function will receive ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY
* messages while checking the WIM's integrity.
* rebuild. In this mode, the new WIM is written to a temporary file and then
* renamed to the original file after it is has been completely written. The
* temporary file is made in the same directory as the original WIM file. A
- * full rebuild may take a while, but can be used even if images have been
- * modified or deleted, will produce a WIM with no holes, and has little chance
- * of unintentional data loss because the temporary WIM is fsync()ed before
- * being renamed to the original WIM.
+ * full rebuild may take a while, but it will save space by producing a WIM with
+ * no "holes".
*
* The second way to overwrite a WIM is by appending to the end of it and
* overwriting the header. This can be much faster than a full rebuild, but the
* ::WIMLIB_WRITE_FLAG_SOFT_DELETE to request the in-place overwrite even if
* images have been deleted from the WIM.
*
- * In the temporary-file overwrite mode, no changes are made to the WIM on
- * failure, and the temporary file is deleted if possible. Abnormal termination
- * of the program will result in the temporary file being orphaned. In the
- * direct append mode, the WIM is truncated to the original length on failure;
- * and while abnormal termination of the program will result in extra data
- * appended to the original WIM, it should still be a valid WIM.
- *
* If this function completes successfully, no more functions should be called
* on @p wim other than wimlib_free(). You must use wimlib_open_wim() to read
* the WIM file anew.
* because another thread or process has mounted an image from the WIM
* read-write or is currently modifying the WIM in-place.
* @retval ::WIMLIB_ERR_NO_FILENAME
- * @p wim corresponds to a WIM created with wimlib_create_new_wim() rather
- * than a WIM read with wimlib_open_wim().
+ * @p wim corresponds to a ::WIMStruct created with wimlib_create_new_wim()
+ * rather than a WIM read with wimlib_open_wim().
* @retval ::WIMLIB_ERR_RENAME
* The temporary file that the WIM was written to could not be renamed to
* the original filename of @p wim.
* Prints information about one image, or all images, contained in a WIM.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file.
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param image
* The image about which to print information. Can be the number of an
* image, or ::WIMLIB_ALL_IMAGES to print information about all images in the
* Set the compression chunk size of a WIM to use in subsequent calls to
* wimlib_write() or wimlib_overwrite().
*
- * For compatibility reasons, using this function is not generally recommended.
- * See the documentation for the @c --chunk-size option of <b>wimlib-imagex
- * capture</b> for more information.
- *
* A larger compression chunk size will likely result in a better compression
* ratio, but the speed of random access to the WIM will be reduced.
* Furthermore, the effect of a larger compression chunk size is limited by the
* ::WIMStruct for a WIM.
* @param chunk_size
* The chunk size (in bytes) to set. The valid chunk sizes are dependent
- * on the compression format; see the documentation for the @c --chunk-size
- * option of <b>wimlib-imagex capture</b> for more information. As a
- * special case, if @p chunk_size is specified as 0, the chunk size is set
- * to the default for the currently selected output compression type.
+ * on the compression format. See the documentation for each
+ * ::wimlib_compression_type constant for more information. As a special
+ * case, if @p chunk_size is specified as 0, the chunk size is set to the
+ * default for the currently selected output compression type.
*
* @return 0 on success; nonzero on error.
*
* library.
*
* Please note that some external functions, such as those in @c libntfs-3g, may
- * use the standard memory allocation functions.
+ * use the standard memory allocation functions regardless of this setting.
*
* @param malloc_func
* A function equivalent to @c malloc() that wimlib will use to allocate
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p swm_name was not a nonempty string, or @p part_size was 0.
*
- * Note: the WIM's uncompressed and compressed resources are not checksummed
- * when they are copied from the joined WIM to the split WIM parts, nor are
- * compressed resources re-compressed (unless explicitly requested with
- * ::WIMLIB_WRITE_FLAG_RECOMPRESS).
- *
* If a progress function is registered with @p wim, for each split WIM part
* that is written it will receive the messages
* ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and
*
* Unmounts a WIM image that was mounted using wimlib_mount_image().
*
- * The image to unmount is specified by the path to the mountpoint, not the
- * original ::WIMStruct passed to wimlib_mount_image(), which should not be
- * touched and also may have been allocated in a different process.
- *
- * To unmount the image, the process calling this function communicates with the
- * process that is managing the mounted WIM image. This function blocks until it
- * is known whether the unmount succeeded or failed. In the case of a
- * read-write mounted WIM, the unmount is not considered to have succeeded until
- * all changes have been saved to the underlying WIM file.
+ * When unmounting a read-write mounted image, the default behavior is to
+ * discard changes to the image. Use ::WIMLIB_UNMOUNT_FLAG_COMMIT to cause the
+ * WIM image to be committed.
*
* @param dir
- * The directory that the WIM image was mounted on.
+ * The directory the WIM image was mounted on.
* @param unmount_flags
- * Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY,
- * ::WIMLIB_UNMOUNT_FLAG_COMMIT, ::WIMLIB_UNMOUNT_FLAG_REBUILD, and/or
- * ::WIMLIB_UNMOUNT_FLAG_RECOMPRESS. None of these flags affect read-only
- * mounts.
+ * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG.
*
- * @return 0 on success; nonzero on error.
+ * @return 0 on success; nonzero on error. The possible error codes include:
*
- * @retval ::WIMLIB_ERR_DELETE_STAGING_DIR
- * The filesystem daemon was unable to remove the staging directory and the
- * temporary files that it contains.
- * @retval ::WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED
- * The filesystem daemon appears to have terminated before sending an exit
- * status.
- * @retval ::WIMLIB_ERR_FORK
- * Could not @c fork() the process.
- * @retval ::WIMLIB_ERR_FUSERMOUNT
- * The @b fusermount program could not be executed or exited with a failure
- * status.
+ * @retval ::WIMLIB_ERR_NOT_A_MOUNTPOINT
+ * There is no WIM image mounted on the specified directory.
+ * @retval ::WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY
+ * The read-write mounted WIM image cannot be committed because there are
+ * file descriptors open to it, and ::WIMLIB_UNMOUNT_FLAG_FORCE was not
+ * specified.
* @retval ::WIMLIB_ERR_MQUEUE
- * Could not open a POSIX message queue to communicate with the filesystem
- * daemon servicing the mounted filesystem, could not send a message
- * through the queue, or could not receive a message through the queue.
- * @retval ::WIMLIB_ERR_NOMEM
- * Failed to allocate needed memory.
- * @retval ::WIMLIB_ERR_OPEN
- * The filesystem daemon could not open a temporary file for writing the
- * new WIM.
- * @retval ::WIMLIB_ERR_READ
- * A read error occurred when the filesystem daemon tried to a file from
- * the staging directory
- * @retval ::WIMLIB_ERR_RENAME
- * The filesystem daemon failed to rename the newly written WIM file to the
- * original WIM file.
+ * Could not create a POSIX message queue.
+ * @retval ::WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT
+ * The WIM image was mounted by a different user.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* Mounting is not supported, either because the platform is Windows, or
- * because the platform is UNIX-like and wimlib was compiled with @c
+ * because the platform is UNIX-like and wimlib was compiled using @c
* --without-fuse.
- * @retval ::WIMLIB_ERR_WRITE
- * A write error occurred when the filesystem daemon was writing to the new
- * WIM file, or the filesystem daemon was unable to flush changes that had
- * been made to files in the staging directory.
+ *
+ * Note: you can also unmount the image by using the @c umount() system call, or
+ * by using the @c umount or @c fusermount programs. However, you need to call
+ * this function if you want changes to be committed.
*/
extern int
-wimlib_unmount_image(const wimlib_tchar *dir,
- int unmount_flags);
+wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags);
/**
* @ingroup G_mounting_wim_images
struct wimlib_compressor_params_header hdr;
/** Relatively fast LZX compression algorithm with a decent compression
- * ratio; the suggested default. */
+ * ratio. */
#define WIMLIB_LZX_ALGORITHM_FAST 0
/** Slower LZX compression algorithm that provides a better compression
- * ratio. */
+ * ratio. This is the default. */
#define WIMLIB_LZX_ALGORITHM_SLOW 1
/** Algorithm to use to perform the compression: either
uint32_t fast_reserved1[10];
} fast;
- /** Parameters for the slow algorithm. */
+ /** Parameters for the "slow" algorithm. */
struct wimlib_lzx_slow_params {
/** If set to 1, the compressor can output length 2
- * matches. If set 0, the compressor only outputs
+ * matches. If set 0, the compressor can only output
* matches of length 3 or greater. Suggested value: 1
*/
uint32_t use_len2_matches : 1;
* position. Suggested value: 50. */
uint32_t max_search_depth;
- /** Maximum number of potentially good matches to
- * consider for each position. Suggested value: 3. */
- uint32_t max_matches_per_pos;
+ /* Note: max_matches_per_pos has been removed and no
+ * longer has any effect. */
- uint32_t slow_reserved2[2];
+ uint32_t slow_reserved2[3];
/** Assumed cost of a main symbol with zero frequency.
* Must be at least 1 and no more than 16. Suggested
* value: 50. */
uint32_t max_search_depth;
- /** Maximum number of potentially good matches to consider at each
- * position. Suggested value: 3. */
- uint32_t max_matches_per_pos;
+ /* Note: max_matches_per_pos has been removed and no longer has any
+ * effect. */
+
+ uint32_t reserved1;
/** Length of the array for the near-optimal LZ parsing algorithm. This
* must be at least 1. Suggested value: 1024. */
/**
* Set the default compression parameters for the specified compression type.
- * This will affect both explicit and wimlib-internal calls to
+ * This will affect both explicit and library-internal calls to
* wimlib_create_compressor().
*
* @param ctype
/**
* Allocate a compressor for the specified compression type using the specified
- * parameters.
+ * parameters. This function is part of wimlib's compression API; it is not
+ * necessary to call this to process a WIM file.
*
* @param ctype
* Compression type for which to create the compressor.
* @param extra_params
* An optional pointer to extra compressor parameters for the specified
* compression type. For LZX, a pointer to ::wimlib_lzx_compressor_params
- * may be specified here. If left @c NULL, the default parameters are
- * used.
+ * may be specified here. For LZMS, a pointer to
+ * ::wimlib_lzms_compressor_params may be specified here. If left @c NULL,
+ * the default parameters are used.
* @param compressor_ret
* A location into which to return the pointer to the allocated compressor,
* which can be used for any number of calls to wimlib_compress() before
/**
* Set the default decompression parameters for the specified compression type.
- * This will affect both explicit and wimlib-internal calls to
+ * This will affect both explicit and library-internal calls to
* wimlib_create_decompressor().
*
* @param ctype
/**
* Allocate a decompressor for the specified compression type using the
- * specified parameters.
+ * specified parameters. This function is part of wimlib's compression API; it
+ * is not necessary to call this to process a WIM file.
*
* @param ctype
* Compression type for which to create the decompressor.
git://wimlib.net / wimlib / blobdiff