*
* \section intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.2.0. If you
+ * This is the documentation for the library interface of wimlib 1.2.6. If you
* have installed wimlib and want to know how to use the @c imagex program,
* please see the man pages instead.
*
* message being printed.
*
* wimlib is thread-safe as long as different ::WIMStruct's are used, except for
- * the fact that wimlib_set_print_errors() and wimlib_set_memory_allocator()
- * both apply globally.
+ * the following exceptions:
+ * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally.
+ * - You also must call wimlib_global_init() in the main thread to avoid any
+ * race conditions with one-time allocations of memory.
+ * - wimlib_mount_image(), while it can be used to mount multiple WIMs
+ * concurrently in the same process, will daemonize the entire process when it
+ * does so for the first time. This includes changing the working directory
+ * to the root directory.
*
* To open an existing WIM, use wimlib_open_wim().
*
#include <stdbool.h>
#include <inttypes.h>
+/** Major version of the library (for example, the 1 in 1.2.5). */
#define WIMLIB_MAJOR_VERSION 1
+
+/** Minor version of the library (for example, the 2 in 1.2.5). */
#define WIMLIB_MINOR_VERSION 2
-#define WIMLIB_PATCH_VERSION 0
+
+/** Patch version of the library (for example, the 5 in 1.2.5). */
+#define WIMLIB_PATCH_VERSION 6
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
* WIMLIB_ADD_IMAGE_FLAG_* *
*****************************/
-/** Directly capture a NTFS volume rather than a generic directory */
+/** Directly capture a NTFS volume rather than a generic directory. This flag
+ * cannot be combined with ::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE or
+ * ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA. */
#define WIMLIB_ADD_IMAGE_FLAG_NTFS 0x00000001
/** Follow symlinks; archive and dump the files they point to. Cannot be used
/** Mark the image being added as the bootable image of the WIM. */
#define WIMLIB_ADD_IMAGE_FLAG_BOOT 0x00000008
+/** Store the UNIX owner, group, and mode. This is done by adding a special
+ * alternate data stream to each regular file, symbolic link, and directory to
+ * contain this information. Please note that this flag is for convenience
+ * only; Microsoft's version of imagex.exe will not understand this special
+ * information. This flag cannot be combined with ::WIMLIB_ADD_IMAGE_FLAG_NTFS.
+ * */
+#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA 0x00000010
+
/******************************
* WIMLIB_EXPORT_FLAG_* *
******************************/
/** Read the WIM file sequentially while extracting the image. */
#define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010
+/** Extract special UNIX data captured with ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA.
+ * Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */
+#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020
+
/******************************
* WIMLIB_MOUNT_FLAG_* *
******************************/
* file name, a colon, then the alternate file stream name. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010
+/** Use UNIX file owners, groups, and modes if available in the WIM (see
+ * ::WIMLIB_ADD_IMAGE_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) */
+#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040
+
/******************************
* WIMLIB_OPEN_FLAG_* *
******************************/
* See the documentation for each wimlib function to see specifically what error
* codes can be returned by a given function, and what they mean.
*/
+/* Note: these are currently in alphabetic order, but new error codes should be
+ * added at the end to maintain a compatible ABI, except when it's being broken
+ * anyway. */
enum wimlib_error_code {
WIMLIB_ERR_SUCCESS = 0,
WIMLIB_ERR_ALREADY_LOCKED,
- WIMLIB_ERR_CHAR_CONVERSION,
WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
WIMLIB_ERR_DECOMPRESSION,
WIMLIB_ERR_DELETE_STAGING_DIR,
WIMLIB_ERR_FORK,
WIMLIB_ERR_FUSE,
WIMLIB_ERR_FUSERMOUNT,
+ WIMLIB_ERR_ICONV_NOT_AVAILABLE,
WIMLIB_ERR_IMAGE_COUNT,
WIMLIB_ERR_IMAGE_NAME_COLLISION,
WIMLIB_ERR_INTEGRITY,
WIMLIB_ERR_INVALID_RESOURCE_SIZE,
WIMLIB_ERR_INVALID_SECURITY_DATA,
WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
+ WIMLIB_ERR_INVALID_UTF8_STRING,
+ WIMLIB_ERR_INVALID_UTF16_STRING,
+ WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE,
WIMLIB_ERR_LINK,
WIMLIB_ERR_MKDIR,
WIMLIB_ERR_MQUEUE,
/**
* Adds an image to a WIM file from an on-disk directory tree or NTFS volume.
*
- * The directory tree is read immediately for the purpose of constructing a
- * directory entry tree in-memory. Also, all files are read to calculate their
- * SHA1 message digests. However, because the directory tree may contain a very
- * large amount of data, the files themselves are not read into memory
- * permanently, and instead references to their paths saved. The files are then
- * read on-demand if wimlib_write() or wimlib_overwrite() is called.
+ * The directory tree of NTFS volume is read immediately for the purpose of
+ * constructing a directory entry tree in-memory. Also, all files are read to
+ * calculate their SHA1 message digests. However, because the directory tree
+ * may contain a very large amount of data, the files themselves are not read
+ * into memory permanently, and instead references to their paths saved. The
+ * files are then read on-demand if wimlib_write() or wimlib_overwrite() is
+ * called.
*
- * Please note that @b no changes are committed to the underlying WIM file (if
+ * See the manual page for the @c imagex program for more information about the
+ * "normal" capture mode versus the NTFS capture mode (entered by providing the
+ * flag ::WIMLIB_ADD_IMAGE_FLAG_NTFS).
+ *
+ * Note that @b no changes are committed to the underlying WIM file (if
* any) until wimlib_write() or wimlib_overwrite() is called.
*
* @param wim
* @param config_len
* Length of the string @a config in bytes. Ignored if @a config is @c
* NULL.
- *
* @param add_image_flags
- * Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG. If
- * ::WIMLIB_ADD_IMAGE_FLAG_BOOT is specified, the image in @a wim that is
- * marked as bootable is changed to the one being added. If
- * ::WIMLIB_ADD_IMAGE_FLAG_VERBOSE is specified, the name of each file is
- * printed as it is scanned or captured. If
- * ::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE is specified, the files or
- * directories pointed to by symbolic links are archived rather than the
- * symbolic links themselves.
- *
+ * Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.
* @param progress_func
* If non-NULL, a function that will be called periodically with the
* progress of the current operation.
* @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
* @a wim is part of a split WIM. Adding an image to a split WIM is
* unsupported.
- * @retval ::WIMLIB_ERR_UNSUPPORTED:
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
* ::WIMLIB_ADD_IMAGE_FLAG_NTFS was specified in @a add_image_flags, but
* wimlib was configured with the @c --without-ntfs-3g flag.
*/
* invalid.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @a target was @c NULL, or both ::WIMLIB_EXTRACT_FLAG_HARDLINK and
- * ::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags, or
+ * ::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags; or
* both ::WIMLIB_EXTRACT_FLAG_NTFS and either
* ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK were
- * specified in @a extract_flags, or ::WIMLIB_EXTRACT_FLAG_NTFS was
- * specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES.
+ * specified in @a extract_flags; or ::WIMLIB_EXTRACT_FLAG_NTFS was
+ * specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES; or
+ * both ::WIMLIB_EXTRACT_FLAG_NTFS and ::WIMLIB_EXTRACT_FLAG_UNIX_DATA were
+ * specified in @a extract_flag.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
* The SHA1 message digest of an extracted stream did not match the SHA1
* message digest given in the WIM file.
*/
extern int 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.
+ *
+ * @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.
+ */
+extern int wimlib_global_init();
+
+/**
+ * Since wimlib 1.2.6: Cleanup function for wimlib. This is not re-entrant.
+ * You are not required to call this function, but it will release any global
+ * memory allocated by the library.
+ */
+extern void wimlib_global_cleanup();
+
/**
* Returns true if the WIM has an integrity table.
*
/**
* Mounts an image in a WIM file on a directory read-only or read-write.
*
- * The calling thread will be daemonized service the filesystem, and this
- * function will not return until the image is unmounted, unless an error occurs
- * before the filesystem is successfully mounted.
+ * Unless ::WIMLIB_MOUNT_FLAG_DEBUG is specified or an early error occurs, the
+ * process shall be daemonized.
*
* If the mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified),
* modifications to the WIM are staged in a temporary directory.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @a image is shared among multiple ::WIMStruct's as a result of a call to
* wimlib_export_image(), or @a image has been added with
- * wimlib_add_image() or wimlib_add_image_from_ntfs_volume().
+ * wimlib_add_image().
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
* The metadata resource for @a image in @a wim is invalid.
* @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
* @param image
* The number of the image for which to change the name.
* @param name
- * The new name to give the image. It must not a nonempty string.
+ * The new name to give the image. It must be a nonempty string.
*
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
* @return 0 on success; nonzero on error. This function may return any value
* returned by wimlib_write() as well as the following error codes:
*
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED:
+ * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
* @a wim is not part 1 of a stand-alone WIM.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @a swm_name was @c NULL, or @a part_size was 0.
* @param dir
* The directory that the WIM image was mounted on.
* @param unmount_flags
- * Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY and/or
- * ::WIMLIB_UNMOUNT_FLAG_COMMIT. Neither of these flags affect read-only
+ * 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.
* @param progress_func
- * Currently ignored, but may be used for a progress callback in the
- * future. Set to @c NULL.
+ * If non-NULL, a function that will be called periodically with the
+ * progress of the current operation.
*
* @return 0 on success; nonzero on error.
*
* @a image does not specify a single existing image in @a wim, and is not
* ::WIMLIB_ALL_IMAGES.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
- * A file that had previously been scanned for inclusion in the WIM by the
- * wimlib_add_image() or wimlib_add_image_from_ntfs_volume() functions was
- * concurrently modified, so it failed the SHA1 message digest check.
+ * A file that had previously been scanned for inclusion in the WIM by
+ * wimlib_add_image() was concurrently modified, so it failed the SHA1
+ * message digest check.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @a path was @c NULL.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
git://wimlib.net / wimlib / blobdiff