build_dentry_tree() fix error paths

[wimlib] / src / wimlib.h

diff --git a/src/wimlib.h b/src/wimlib.h
index 98651debd9eea4f2171c95c3a3f1ea1fb3c4c42b..ad8db22556cdd48dab17b6a698a8bdf90cc6685b 100644 (file)
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -418,6 +418,9 @@ enum wimlib_error_code {
  *     dir.
  * @retval ::WIMLIB_ERR_READ
  *     Failed to read a file in the directory tree rooted at @a dir.
+ * @retval ::WIMLIB_ERR_SPECIAL_FILE
+ *     The directory tree rooted at @dir contains a special file that is not a
+ *     directory, regular file, or symbolic link.
  * @retval ::WIMLIB_ERR_STAT
  *     Failed obtain the metadata for a file or directory in the directory tree
  *     rooted at @a dir.
@@ -480,8 +483,9 @@ extern int wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
 /**
  * Deletes an image, or all images, from a WIM file.
  *
- * All file resources referenced by the image(s) being deleted are removed from
- * the WIM if they are not referenced by any other images in the WIM.
+ * All streams referenced by the image(s) being deleted are removed from the
+ * lookup table of the WIM if they are not referenced by any other images in the
+ * WIM.
  *
  * @param wim
  *     Pointer to the ::WIMStruct for the WIM file that contains the image(s)
@@ -489,8 +493,12 @@ extern int wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
  * @param image
  *     The number of the image to delete, or ::WIM_ALL_IMAGES to delete all
  *     images.
- * @return 0 on success; nonzero on error.  On error, @a wim is left in an
- * indeterminate state and should be freed with wimlib_free().
+ * @return 0 on success; nonzero on failure.  On failure, @a wim is guaranteed
+ * to be left unmodified only if @a image specified a single image.  If instead
+ * @a image was ::WIM_ALL_IMAGES and @a wim contained more than one image, it's
+ * possible for some but not all of the images to have been deleted when a
+ * failure status is returned.
+ *
  * @retval ::WIMLIB_ERR_DECOMPRESSION
  *     Could not decompress the metadata resource for @a image.
  * @retval ::WIMLIB_ERR_INVALID_DENTRY
@@ -502,7 +510,8 @@ extern int wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
  *     The metadata resource for @a image in the WIM is invalid.       
  * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
  *     The security data for @a image in the WIM is invalid.   
- * @retval ::WIMLIB_ERR_NOMEM Failed to allocate needed memory.
+ * @retval ::WIMLIB_ERR_NOMEM
+ *     Failed to allocate needed memory.
  * @retval ::WIMLIB_ERR_READ
  *     Could not read the metadata resource for @a image from the WIM.
  * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
@@ -778,8 +787,11 @@ extern const char *wimlib_get_error_string(enum wimlib_error_code code);
  *     The number of the image, numbered starting at 1.
  *
  * @return
- *     The description of the image, or @c NULL if there is no such image, or @c NULL
- *     if the specified image has no description.
+ *     The description of the image, or @c NULL if there is no such image, or
+ *     @c NULL if the specified image has no description.  The description
+ *     string is in library-internal memory and may not be modified or freed;
+ *     in addition, the string will become invalid if the description of the
+ *     image is changed, the image is deleted, or the ::WIMStruct is destroyed.
  */
 extern const char *wimlib_get_image_description(const WIMStruct *wim, int image);
 
@@ -793,7 +805,10 @@ extern const char *wimlib_get_image_description(const WIMStruct *wim, int image)
  *     The number of the image, numbered starting at 1.
  *
  * @return
- *     The name of the image, or @c NULL if there is no such image.
+ *     The name of the image, or @c NULL if there is no such image.  The name
+ *     string is in library-internal memory and may not be modified or freed;
+ *     in addition, the string will become invalid if the name of the image is
+ *     changed, the image is deleted, or the ::WIMStruct is destroyed.
  */
 extern const char *wimlib_get_image_name(const WIMStruct *wim, int image);
 
@@ -844,8 +859,9 @@ extern bool wimlib_has_integrity_table(const WIMStruct *wim);
  *     The name to check.
  *
  * @return
- *     @c true if there is already an image in @a wim named @a name; @c
- *     false if there is no image named @a name in @a wim.
+ *     @c true if there is already an image in @a wim named @a name; @c false
+ *     if there is no image named @a name in @a wim.  (If @a name is @c NULL,
+ *     @c false is returned.)
  */
 extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name);