X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=a547d3a824e1588a3e4b450e663450c8d1926c5f;hp=0b0f04bf6b045acea1a988f154cfbecf072ee144;hb=3ad1560f7040accb19afb4b31730d0820076b80b;hpb=7c83ef53090441de11cc78d8d26dc337cd7ac475 diff --git a/src/wimlib.h b/src/wimlib.h index 0b0f04bf..a547d3a8 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -31,6 +31,10 @@ * * \section intro Introduction * + * This is the documentation for the library interface of wimlib 1.2.0. If you + * have installed wimlib and want to know how to use the @c imagex program, + * please see the man pages instead. + * * wimlib is a C library to read, write, and mount archive files in the Windows * Imaging Format (WIM files). These files are normally created using the @c * imagex.exe utility on Windows, but this library provides a free @@ -297,17 +301,17 @@ enum wimlib_progress_msg { * ::wimlib_progress_info.scan. */ WIMLIB_PROGRESS_MSG_SCAN_END, - /** + /** * File resources are currently being written to the WIM. * @a info will point to ::wimlib_progress_info.write_streams. */ WIMLIB_PROGRESS_MSG_WRITE_STREAMS, - /** + /** * The metadata resource for each image is about to be written to the * WIM. @a info will not be valid. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, - /** + /** * The metadata resource for each image has successfully been writen to * the WIM. @a info will not be valid. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_END, @@ -410,6 +414,12 @@ union wimlib_progress_info { /** Number of the image being extracted (1-based). */ int image; + /** Flags passed to to wimlib_extract_image() */ + int extract_flags; + + /** Full path to the WIM file being extracted. */ + const char *wimfile_name; + /** Name of the image being extracted. */ const char *image_name; @@ -1341,27 +1351,21 @@ 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. * - * A daemon will be forked to service the filesystem, unless - * ::WIMLIB_MOUNT_FLAG_DEBUG is specified in @a mount_flags. In other words, - * this function returns @b before the image is unmounted, and filesystem - * requests are handled by a new thread. This also means that no functions may - * be safely called on @a wim after wimlib_mount_image() has been called on any - * images from it. (@a wim will be freed by the filesystem thread after the - * filesystem is unmounted.) + * The calling thread will be daemonized service the filesystem, and this + * function will not return until the image is unmounted, unless an error occurs + * before the filesystem is successfully mounted. * * If the mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), - * modifications to the WIM are staged in a temporary directory created in the - * process's working directory when this function is called. + * modifications to the WIM are staged in a temporary directory. * * It is safe to mount multiple images from the same WIM file read-only at the - * same time (but different ::WIMStruct's should be used). However, it is @b - * not safe to mount multiple images from the same WIM file read-write at the - * same time. + * same time, but only if different ::WIMStruct's are used. It is @b not safe + * to mount multiple images from the same WIM file read-write at the same time. * * wimlib_mount_image() cannot be used on an image that was exported with * wimlib_export_image() while the dentry trees for both images are still in * memory. In addition, wimlib_mount_image() may not be used to mount an image - * that has just been added with wimlib_add_image(), or unless the WIM has been + * that has just been added with wimlib_add_image(), unless the WIM has been * written and read into a new ::WIMStruct. * * @param wim @@ -1395,10 +1399,17 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * 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. * @param staging_dir - * Currently ignored, but may provide a way to specify the staging - * directory in the future. Set to @c NULL. + * If non-NULL, the name of a directory in which the staging directory will + * be created. Ignored if ::WIMLIB_MOUNT_FLAG_READWRITE is not specified + * in @a mount_flags. If left @c NULL, the staging directory is created in + * the same directory as the WIM file that @a wim was originally read from. * * @return 0 on success; nonzero on error. + * @retval ::WIMLIB_ERR_ALREADY_LOCKED + * A read-write mount was requested, but an an exclusive advisory lock on + * the on-disk WIM file could not be acquired because another thread or + * process has mounted an image from the WIM read-write or is currently + * modifying the WIM in-place. * @retval ::WIMLIB_ERR_DECOMPRESSION * Could not decompress the metadata resource for @a image in @a wim. * @retval ::WIMLIB_ERR_FUSE @@ -1577,10 +1588,10 @@ extern int wimlib_open_wim(const char *wim_file, int open_flags, * @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_ALREADY_LOCKED - * The append-only overwrite mode was going to be used, but an exclusive - * advisory lock on the on-disk WIM file could not be acquired, probably - * because another thread or process was calling wimlib_overwrite() on the - * same underlying on-disk file at the same time. + * The WIM was going to be modifien in-place (with no temporary file), but + * an exclusive advisory lock on the on-disk WIM file could not be acquired + * because another thread or process has mounted an image from the WIM + * read-write or is currently modifying the WIM in-place. * @retval ::WIMLIB_ERR_NO_FILENAME * @a wim corresponds to a WIM created with wimlib_create_new_wim() rather * than a WIM read with wimlib_open_wim().