From: Eric Biggers Date: Sat, 19 May 2012 18:30:58 +0000 (-0500) Subject: Documentation fixes/additions X-Git-Tag: v0.7.0~1 X-Git-Url: https://wimlib.net/git/?p=wimlib;a=commitdiff_plain;h=bec7f491bd14b1da3aae7054edd72575dcf77a4f Documentation fixes/additions --- diff --git a/doc/imagex-append.1.in b/doc/imagex-append.1.in index 2a7b2abe..d5fa11ec 100644 --- a/doc/imagex-append.1.in +++ b/doc/imagex-append.1.in @@ -36,6 +36,15 @@ Specify a string to use in the element of the XML data for the image. .TP \fB--verify\fR This option is currently unsupported. + +.SH EXAMPLES +.IP +image append boot.wim winpe/ "Microsoft Windows PE" +.LP +Add a new image to the existing WIM file boot.wim. The files in the directory 'winpe' +are added recursively to the image. The image is given the name "Microsoft +Windows PE" and no description. + .SH SEE ALSO .BR imagex (1) diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index d66034ef..7e09a949 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -42,6 +42,14 @@ Print the path to of each file or directory within the WIM image as it is extrac .TP \fB--verify\fR This option is currently unsupported. + +.SH EXAMPLES +.IP +image apply boot.wim all boot --hardlink +.LP +Extract all images in the WIM 'boot.wim' to the directory 'boot', and hard link +all identical files. + .SH SEE ALSO .BR imagex (1) diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in index 02d47650..3c51ab77 100644 --- a/doc/imagex-capture.1.in +++ b/doc/imagex-capture.1.in @@ -46,6 +46,14 @@ This option is currently unsupported. .TP \fB--verbose\fR Print the names of files and directories as they are captured. + +.SH EXAMPLES +.IP +image capture boot boot.wim --compress=maximum --check +.LP +Create a new WIM 'boot.wim' from the directory 'boot', using LZX compression and +including an integrity table. + .SH SEE ALSO .BR imagex (1) diff --git a/doc/imagex-delete.1.in b/doc/imagex-delete.1.in index a2bea232..ef8b3f61 100644 --- a/doc/imagex-delete.1.in +++ b/doc/imagex-delete.1.in @@ -29,6 +29,13 @@ When reading \fIWIMFILE\fR, verify its integrity if the integrity table is present; additionally, when rewriting \fIWIMFILE\fR after the specified image was deleted, write an integrity table. If this option is not specified, no integrity table is included in the new WIM file, even if there was one before. + +.SH EXAMPLES +.IP +image delete boot.wim 1 +.LP +Delete the first image from 'boot.wim'. + .SH SEE ALSO .BR imagex (1) diff --git a/doc/imagex-dir.1.in b/doc/imagex-dir.1.in index fd264675..34dbe540 100644 --- a/doc/imagex-dir.1.in +++ b/doc/imagex-dir.1.in @@ -15,6 +15,12 @@ an index of an image in the WIM file, starting at 1. Alternatively, it may be the name of an image in the WIM file. It also may be the keyword "all", which specifies all images. +.SH EXAMPLES +.IP +image dir boot.wim 1 +.LP +Show all files in the first image of 'boot.wim' + .SH SEE ALSO .BR imagex (1) diff --git a/doc/imagex-export.1.in b/doc/imagex-export.1.in index aa8030eb..6ec57160 100644 --- a/doc/imagex-export.1.in +++ b/doc/imagex-export.1.in @@ -54,6 +54,13 @@ Specifies the compression type for \fIDEST_WIMFILE\fR. This is only valid if is specified but \fITYPE\fR is not, the compression type is taken to be "maximum", which is LZX compression. "fast" compression is XPRESS compression. +.SH EXAMPLES +.IP +image export boot.wim 2 image2.wim --compress=maximum +.LP +Export the second image of 'boot.wim' to the new WIM file 'image2.wim', and +change the compression type to maximum, if it wasn't maximum already. + .SH SEE ALSO .BR imagex (1) diff --git a/doc/imagex-join.1.in b/doc/imagex-join.1.in index db149fa5..5b65238c 100644 --- a/doc/imagex-join.1.in +++ b/doc/imagex-join.1.in @@ -12,14 +12,6 @@ Joins the \fISPLIT_WIMs\fR into a standalone one-part WIM \fIOUT_WIMFILE\fR. All parts of the split WIM must be specified. You probably want to do so using a shell wildcard. -.SH EXAMPLES - -.IP -imagex join windows.wim windows*.swm -.LP -Join a split WIM, with the parts named `windows*.swm' where the * is anything -(usually the number of the part, except for the first part which may have no -number), and write the joined with to the file `windows.wim'. .SH OPTIONS .TP 6 @@ -28,6 +20,14 @@ When reading each \fISPLIT_WIM\fR, verify its integrity if the integrity table i present; additionally, when writing \fIOUT_WIMFILE\fR, write an integrity table. If this option is not specified, no integrity table is included in the new WIM file, even if there was one before. -.TP + +.SH EXAMPLES +.IP +imagex join windows.wim windows*.swm +.LP +Join a split WIM, with the parts named `windows*.swm' where the * is anything +(usually the number of the part, except for the first part which may have no +number), and write the joined with to the file `windows.wim'. + .SH SEE ALSO .BR imagex (1) diff --git a/doc/imagex.1.in b/doc/imagex.1.in index 0a24ca4d..c65cd2d8 100644 --- a/doc/imagex.1.in +++ b/doc/imagex.1.in @@ -69,7 +69,7 @@ Change the name or description of an image in the WIM (\fBimagex info\fR) .IP \[bu] 2 Change which image in a WIM is bootable (\fBimagex info\fR) .IP \[bu] 2 -Combining split WIMs into one WIM (\fB image join\fR) +Combining split WIMs into one WIM (\fBimage join\fR) .SH UNSUPPORTED FEATURES The following features are currently unsupported: @@ -82,7 +82,8 @@ be applied with the correct file permissions. .IP \[bu] 2 Split WIMs are not fully supported. These can be used to split up a WIM to fit on multiple CDs, if you can't use a DVD for some reason. You can use -\fBimagex join\fR to combine split WIMs, but you cannot yet create split WIMs. +\fBimagex join\fR to combine split WIMs, but you cannot yet create split WIMs or +mount them directly. .IP \[bu] 2 The \fB--verify\fR option, for all commands that use it. Without this option, there theoretically could be a SHA1 hash collision between two files, although diff --git a/programs/imagex.c b/programs/imagex.c index 6dcc62d3..66772ae4 100644 --- a/programs/imagex.c +++ b/programs/imagex.c @@ -93,7 +93,7 @@ static const char *usage_strings[] = { " [NEW_DESC] [--boot] [--check] [--header] [--lookup-table]\n" " [--xml] [--extract-xml FILE] [--metadata]\n", [JOIN] = -" imagex join [--check] --output WIMFILE SPLIT_WIM...\n", +" imagex join [--check] WIMFILE SPLIT_WIM...\n", [MOUNT] = " imagex mount WIMFILE (IMAGE_NUM | IMAGE_NAME) DIRECTORY\n" " [--check] [--debug]\n", @@ -1004,16 +1004,13 @@ static int imagex_join(int argc, const char **argv) int flags = WIMLIB_OPEN_FLAG_SPLIT_OK | WIMLIB_OPEN_FLAG_SHOW_PROGRESS; int image; int ret; - const char *output_path = NULL; + const char *output_path; for_opt(c, join_options) { switch (c) { case 'c': flags |= WIMLIB_OPEN_FLAG_CHECK_INTEGRITY; break; - case 'o': - output_path = optarg; - break; default: goto err; } @@ -1021,16 +1018,13 @@ static int imagex_join(int argc, const char **argv) argc -= optind; argv += optind; - if (argc < 2) { + if (argc < 3) { imagex_error("Must specify at least two split WIM " "(.swm) parts to join!\n"); goto err; } - if (!output_path) { - imagex_error("Must specify output_path!\n"); - goto err; - } - return wimlib_join(argv, argc, output_path, flags); + output_path = argv[0]; + return wimlib_join(++argv, --argc, output_path, flags); err: usage(JOIN); return -1; diff --git a/src/wimlib.h b/src/wimlib.h index c284dbc3..1bc23970 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -140,8 +140,7 @@ * WIM without security data, including a boot.wim for Windows PE, but do * not expect to be able to use wimlib to image a Windows installation and * preserve file attributes. - * - There is no support for split WIMs, which have an image divided up between - * multiple WIM files. + * - There is no way to create split WIMs. * - There is not yet any code to verify that there are no collisions between * different files that happen to have the same SHA1 message digest. * This is extremely unlikely, but could result in something bad such as a @@ -265,9 +264,7 @@ enum wim_compression_type { #define WIMLIB_OPEN_FLAG_SHOW_PROGRESS 0x2 /** If this flag is not given, an error is issued if the WIM is part of a split - * WIM. Giving this flag makes the function allows split WIMS to be opened, but - * beware: wimlib has little support for split WIMs and only certain functions - * will work on them. */ + * WIM. */ #define WIMLIB_OPEN_FLAG_SPLIT_OK 0x4 /** @@ -699,7 +696,20 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name); * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY to check the split WIMs' integrity * tables (if present) when opening them, and include an integrity table in * the output WIM. - * @return 0 on success; nonzero on error. + * + * @return 0 on success; nonzero on error. This function may return any value + * returned by wimlib_open_wim() except ::WIMLIB_ERR_SPLIT_UNSUPPORTED, as well + * as the following error codes: + * + * @retval ::WIMLIB_ERR_SPLIT_INVALID + * The split WIMs do not form a valid WIM because they do not include all + * the parts of the original WIM, there are duplicate parts, or not all the + * parts have the same GUID and compression type. + * @retval ::WIMLIB_ERR_WRITE + * An error occurred when trying to write data to to the new WIM at @a output_path. + * + * Note that this function merely copies the resources, so it will not check to + * see if the resources, including the metadata resource, are valid or not. */ extern int wimlib_join(const char **swms, int num_swms, const char *output_path, int flags); @@ -771,7 +781,10 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags); * If ::WIMLIB_OPEN_FLAG_SHOW_PROGRESS is given, progress information will * be shown if the integrity of the WIM is checked. * If ::WIMLIB_OPEN_FLAG_SPLIT_OK is given, no error will be issued if the - * WIM is part of a split WIM. + * WIM is part of a split WIM. However, wimlib does not fully support + * split WIMs, so not all functions will work correctly after opening a + * split WIM. For example, you cannot use wimlib_mount() or + * wimlib_extract_image() on a split WIM. * * @param wim_ret * On success, a pointer to an opaque ::WIMStruct for the opened WIM file @@ -785,10 +798,10 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags); * added to wimlib if needed, but it appears to be the case that the lookup * table is never compressed. * @retval ::WIMLIB_ERR_IMAGE_COUNT - * The number of metadata resources found in the WIM did not match the - * image count given in the WIM header, or the number of <IMAGE> - * elements in the XML data for the WIM did not match the image count given - * in the WIM header. + * The WIM is not the non-first part of a split WIM, and the number of + * metadata resources found in the WIM did not match the image count given + * in the WIM header, or the number of <IMAGE> elements in the XML + * data for the WIM did not match the image count given in the WIM header. * @retval ::WIMLIB_ERR_INTEGRITY * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @a flags and @a * wim_file contains an integrity table, but the SHA1 message digest for a @@ -814,7 +827,7 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags); * @retval ::WIMLIB_ERR_READ * An unexpected end-of-file or read error occurred when trying to read * data from @a wim_file. - * @retval ::WIMLIB_ERR_SPLIT + * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED * @a wim_file is a split WIM, but ::WIMLIB_OPEN_FLAG_SPLIT_OK was not * givin in @a flags. * @retval ::WIMLIB_ERR_UNKNOWN_VERSION @@ -1292,6 +1305,9 @@ extern int wimlib_unmount(const char *dir, int flags); * with @a wim, or some file resources in @a wim refer to files in the * outside filesystem, and a read error occurred when reading one of these * files. + * @retval ::WIMLIB_ERR_WRITE + * An error occurred when trying to write data to the new WIM file at @a + * path. */ extern int wimlib_write(WIMStruct *wim, const char *path, int image, int flags);