Refactor error functions; make re-entrant

[wimlib] / src / wimlib.h

diff --git a/src/wimlib.h b/src/wimlib.h
index 6044f245b0245d2e28ca62e23f5e87c5269ab8d6..55289fe91dda2e2073f31403e306b7e9b91f9552 100644 (file)
--- 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.5.  If you
  * have installed wimlib and want to know how to use the @c imagex program,
  * please see the man pages instead.
  *
@@ -118,7 +118,8 @@
  *
  * 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.
+ * both apply globally, and you also must call wimlib_global_init() in the main
+ * thread to avoid any race conditions with one-time allocations of memory.
  *
  * To open an existing WIM, use wimlib_open_wim().
  *
@@ -217,7 +218,7 @@
 
 #define WIMLIB_MAJOR_VERSION 1
 #define WIMLIB_MINOR_VERSION 2
-#define WIMLIB_PATCH_VERSION 3
+#define WIMLIB_PATCH_VERSION 5
 
 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
@@ -1282,6 +1283,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 --without-libntfs-3g at compilation time, and at
+ *     runtime the 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.
  *
@@ -1841,7 +1870,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 +1963,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.