Miscellaneous fixes and cleanups

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index 8c293c8a81d42dbbd867f0b5e6b3878959843737..a7e068aee74f09149bbf3d58d15d062ec42ea260 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -1207,9 +1207,18 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  ******************************/
 
 /** Assume that strings are represented in UTF-8, even if this is not the
- * locale's character encoding. */
+ * locale's character encoding.  Not used on Windows.  */
 #define WIMLIB_INIT_FLAG_ASSUME_UTF8                   0x00000001
 
+/** Windows-only: do not attempt to acquire additional privileges (currently
+ * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and
+ * SeTakeOwnershipPrivilege) when initializing the library.  This is intended
+ * for the case where the calling program manages these privileges itself.
+ * Note: no error is issued if privileges cannot be acquired, although related
+ * errors may be reported later, depending on if the operations performed
+ * actually require additional privileges or not.  */
+#define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES       0x00000002
+
 /** Specification of an update to perform on a WIM image. */
 struct wimlib_update_command {
 
@@ -1847,10 +1856,9 @@ wimlib_extract_files(WIMStruct *wim,
  *     Failed to set security descriptor on a file
  *     (only if ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS) specified in @p
  *     extract_flags.
- * @retval ::WIMLIB_ERR_SET_SECURITY
- *     Failed to set security descriptor on a file
- *     (only if ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS) specified in @p
- *     extract_flags.
+ * @retval ::WIMLIB_ERR_SET_TIMESTAMPS
+ *     Failed to set timestamps on a file (only if
+ *     ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS) specified in @p extract_flags.
  * @retval ::WIMLIB_ERR_SPLIT_INVALID
  *     The WIM is a split WIM, but the parts specified do not form a complete
  *     split WIM because they do not include all the parts of the original WIM,
@@ -1872,7 +1880,8 @@ wimlib_extract_image(WIMStruct *wim, int image,
                     wimlib_progress_func_t progress_func);
 
 /**
- * Extract one or more images from a pipe on which a pipable WIM is being sent.
+ * Since wimlib v1.5.0:  Extract one or more images from a pipe on which a
+ * pipable WIM is being sent.
  *
  * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information
  * about pipable WIMs.
@@ -2061,14 +2070,13 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info);
 
 /**
  * Initialization function for wimlib.  Call before using any other wimlib
- * function.
+ * function except wimlib_set_print_errors().  (However, currently this is not
+ * strictly necessary and it will be called automatically if not done manually,
+ * but you should not rely on this behavior.)
  *
  * @param init_flags
- *     On UNIX, specify ::WIMLIB_INIT_FLAG_ASSUME_UTF8 if wimlib should assume
- *     that all input data, including filenames, are in UTF-8 rather than the
- *     locale-dependent character encoding which may or may not be UTF-8, and
- *     that UTF-8 data can be directly printed to the console.  On Windows, use
- *     0 for this parameter.
+ *     Bitwise OR of ::WIMLIB_INIT_FLAG_ASSUME_UTF8 and/or
+ *     ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES.
  *
  * @return 0; other error codes may be returned in future releases.
  */
@@ -2078,7 +2086,7 @@ wimlib_global_init(int init_flags);
 /**
  * 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.
+ * resources allocated by the library.
  */
 extern void
 wimlib_global_cleanup(void);
@@ -2784,6 +2792,8 @@ wimlib_set_memory_allocator(void *(*malloc_func)(size_t),
  *
  * By default, error messages are not printed.
  *
+ * This can be called before wimlib_global_init().
+ *
  * @param show_messages
  *     @c true if error messages are to be printed; @c false if error messages
  *     are not to be printed.
@@ -3089,12 +3099,15 @@ wimlib_write(WIMStruct *wim,
             wimlib_progress_func_t progress_func);
 
 /**
- * Same as wimlib_write(), but write the WIM directly to a file descriptor,
- * which need not be seekable if the write is done in a special pipable WIM
- * format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p write_flags.  This can,
- * for example, allow capturing a WIM image and streaming it over the network.
- * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information
- * about pipable WIMs.
+ * Since wimlib v1.5.0:  Same as wimlib_write(), but write the WIM directly to a
+ * file descriptor, which need not be seekable if the write is done in a special
+ * pipable WIM format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p
+ * write_flags.  This can, for example, allow capturing a WIM image and
+ * streaming it over the network.  See the documentation for
+ * ::WIMLIB_WRITE_FLAG_PIPABLE for more information about pipable WIMs.
+ *
+ * The file descriptor @p fd will not be closed when the write is complete; the
+ * calling code is responsible for this.
  *
  * Return values are mostly the same as wimlib_write(), but also:
  *