X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=src%2Fwimlib.h;h=ad8db22556cdd48dab17b6a698a8bdf90cc6685b;hb=e0beab67ce67493da928a9fe5957c1f258073b9a;hp=648345a5236bdd1655af4c16897485b1bc2776da;hpb=5ab1d0645f63d09334d1b2573e36c033d078f4f2;p=wimlib diff --git a/src/wimlib.h b/src/wimlib.h index 648345a5..ad8db225 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -388,7 +388,8 @@ enum wimlib_error_code { * NULL, a default string is used. Please see the manual page for * imagex capture for more information. * @param config_len - * Length of the string @a config in bytes. + * Length of the string @a config in bytes. Ignored if @a config is @c + * NULL. * * @param flags * Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG. If @@ -417,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. @@ -479,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) @@ -488,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 @@ -501,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 @@ -511,7 +521,28 @@ extern int wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); extern int wimlib_delete_image(WIMStruct *wim, int image); /** - * Copies an image, or all the images, from a WIM file, into another WIM file. + * Exports an image, or all the images, from a WIM file, into another WIM file. + * + * The destination image is made to share the same dentry tree and security data + * structure as the source image. This places some restrictions on additional + * functions that may be called. wimlib_mount() may not be called on either the + * source image or the destination image without an intervening call to a + * function that un-shares the images, such as wimlib_free() on @a dest_wim, or + * wimlib_delete_image() on either the source or destination image. + * Furthermore, you may not call wimlib_free() or wimlib_overwrite() on @a + * src_wim before any calls to functions such as wimlib_write() on @a dest_wim + * because @a dest_wim will have references back to @a src_wim. + * + * Previous versions of this function left @a dest_wim in an indeterminate state + * on failure. This is no longer the case; all changes to @a dest_wim made by + * this function are rolled back on failure. + * + * Previous versions of this function did not allow exporting an image that had + * been added by wimlib_add_image(). This is no longer the case; you may now + * export an image regardless of how it was added. + * + * Regardless of whether this function succeeds or fails, no user-visible + * changes are made to @a src_wim. * * @param src_wim * Pointer to the ::WIMStruct for a stand-alone WIM or part 1 of a split @@ -552,8 +583,7 @@ extern int wimlib_delete_image(WIMStruct *wim, int image); * This number should be one less than the total number of parts in the * split WIM. Set to 0 if the WIM is a standalone WIM. * - * @return 0 on success; nonzero on error. On error, @a dest_wim is left in an - * indeterminate state and should be freed with wimlib_free(). + * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_DECOMPRESSION * Could not decompress the metadata resource for @a src_image * in @a src_wim @@ -757,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); @@ -772,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); @@ -823,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); @@ -869,9 +906,10 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * directory. * * wimlib_mount() currently cannot be used with multiple ::WIMStruct's without - * intervening wimlib_unmount()s. If there was a way to have libfuse pass a - * pointer to user data to each FUSE callback, then this would be possible, but - * there doesn't seem to be a way to do this currently. + * intervening wimlib_unmount()s. + * + * wimlib_mount() cannot be used on an image that was exported with + * wimlib_export() while the dentry trees for both images are still in memory. * * @param wim * Pointer to the ::WIMStruct for the WIM file to be mounted. @@ -909,6 +947,9 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @a image does not specify an existing, single image in @a wim. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @a image is shared among multiple ::WIMStruct's as a result of a call to + * wimlib_export(). * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE * The metadata resource for @a image in @a wim is invalid. * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA @@ -1216,8 +1257,8 @@ extern void wimlib_print_wim_information(const WIMStruct *wim); * A string specifying which image. If it begins with a number, it is * taken to be a string specifying the image number. Otherwise, it is * taken to be the name of an image, as specified in the XML data for the - * WIM file. It also may be the keyword "all", which will resolve to - * ::WIM_ALL_IMAGES. + * WIM file. It also may be the keyword "all" or the string "*", both of + * which will resolve to ::WIM_ALL_IMAGES. * * @return * If the string resolved to a single existing image, the number of that