X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=d1ee1221a3a3790b85fadb9d4920e83ee94a6b76;hp=6044f245b0245d2e28ca62e23f5e87c5269ab8d6;hb=8eaff5673d8e133e72e20cf4409ab4c901831424;hpb=cf97788e31c037aa36db9c62fcf44c36f806362e

diff --git a/src/wimlib.h b/src/wimlib.h
index 6044f245..d1ee1221 100644
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -31,7 +31,7 @@
  *
  * \section intro Introduction
  *
- * This is the documentation for the library interface of wimlib 1.2.3.  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.
  *
@@ -117,8 +117,14 @@
  * 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().
  *
@@ -215,9 +221,14 @@
 #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 3
+
+/** 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
@@ -546,7 +557,9 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * 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
@@ -561,6 +574,14 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 /** 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_* *
  ******************************/
@@ -593,6 +614,10 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 /** 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_*        *
  ******************************/
@@ -614,6 +639,14 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * 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_*         *
  ******************************/
@@ -678,6 +711,9 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * 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,
@@ -1089,11 +1125,13 @@ extern int wimlib_export_image(WIMStruct *src_wim, int src_image,
  * 	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.
@@ -1282,6 +1320,34 @@ extern int wimlib_get_num_images(const WIMStruct *wim);
  */
 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.
  *
@@ -1356,9 +1422,8 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
 /**
  * Mounts an image in a WIM file on a directory read-only or read-write.
  *
- * The calling thread will be daemonized to 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.
@@ -1428,7 +1493,7 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
  * @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
@@ -1841,7 +1906,7 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const char *flags);
  * @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
@@ -1934,7 +1999,7 @@ extern int wimlib_set_print_errors(bool show_messages);
  * @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.
@@ -2048,9 +2113,9 @@ extern int wimlib_unmount_image(const char *dir, int unmount_flags,
  * 	@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