wimlib.net Git - wimlib/blob - doc/html/index.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
   6 <title>wimlib: Main Page</title>
   7
   8 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   9 <link href="doxygen.css" rel="stylesheet" type="text/css" />
  10
  11 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  12 <script type="text/javascript" src="jquery.js"></script>
  13 <script type="text/javascript" src="search/search.js"></script>
  14 <script type="text/javascript">
  15   $(document).ready(function() { searchBox.OnSelectItem(0); });
  16 </script>
  17
  18 </head>
  19 <body>
  20 <div id="top"><!-- do not remove this div! -->
  21
  22
  23 <div id="titlearea">
  24 <table cellspacing="0" cellpadding="0">
  25  <tbody>
  26  <tr style="height: 56px;">
  27
  28
  29   <td style="padding-left: 0.5em;">
  30    <div id="projectname">wimlib
  31
  32    </div>
  33
  34   </td>
  35
  36
  37
  38  </tr>
  39  </tbody>
  40 </table>
  41 </div>
  42
  43 <!-- Generated by Doxygen 1.8.0 -->
  44 <script type="text/javascript">
  45 var searchBox = new SearchBox("searchBox", "search",false,'Search');
  46 </script>
  47   <div id="navrow1" class="tabs">
  48     <ul class="tablist">
  49       <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
  50       <li><a href="files.html"><span>Files</span></a></li>
  51       <li>
  52         <div id="MSearchBox" class="MSearchBoxInactive">
  53         <span class="left">
  54           <img id="MSearchSelect" src="search/mag_sel.png"
  55                onmouseover="return searchBox.OnSearchSelectShow()"
  56                onmouseout="return searchBox.OnSearchSelectHide()"
  57                alt=""/>
  58           <input type="text" id="MSearchField" value="Search" accesskey="S"
  59                onfocus="searchBox.OnSearchFieldFocus(true)"
  60                onblur="searchBox.OnSearchFieldFocus(false)"
  61                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  62           </span><span class="right">
  63             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
  64           </span>
  65         </div>
  66       </li>
  67     </ul>
  68   </div>
  69 </div>
  70 <!-- window showing the filter options -->
  71 <div id="MSearchSelectWindow"
  72      onmouseover="return searchBox.OnSearchSelectShow()"
  73      onmouseout="return searchBox.OnSearchSelectHide()"
  74      onkeydown="return searchBox.OnSearchSelectKey(event)">
  75 <a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Defines</a></div>
  76
  77 <!-- iframe showing the search results (closed by default) -->
  78 <div id="MSearchResultsWindow">
  79 <iframe src="javascript:void(0)" frameborder="0"
  80         name="MSearchResults" id="MSearchResults">
  81 </iframe>
  82 </div>
  83
  84 <div class="header">
  85   <div class="headertitle">
  86 <div class="title">wimlib Documentation</div>  </div>
  87 </div><!--header-->
  88 <div class="contents">
  89 <div class="textblock"><h2><a class="anchor" id="intro"></a>
  90 Introduction</h2>
  91 <p>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 <code>imagex.exe</code> utility on Windows, but this library provides a free implementetion of <code>imagex</code> for UNIX-based systems and an API to allow other programs to read, write, and mount WIM files. wimlib is comparable to Microsoft's WIMGAPI, but was designed independently and is not a clone of it.</p>
  92 <p>The main intended use of wimlib is to create customized images of Windows PE, the Windows Preinstallation Environment, without having to rely on Windows. Windows PE, which is the operating system that runs when you boot from the Windows Vista or Windows 7 DVD, is a lightweight version of Windows that can run entirely from memory. It can be used to install Windows from local media or a network drive or perform maintenance.</p>
  93 <p>You can find Windows PE on the installation media for Windows Vista, Windows 7, and Windows 8. The Windows PE image itself is a WIM file, <code>sources/boot.wim</code>, on the ISO filesystem. Windows PE can also be found in the Windows Automated Installation Kit (WAIK) inside the <code>WinPE.cab</code> file, which you can extract if you install the <code>cabextract</code> program.</p>
  94 <h2><a class="anchor" id="format"></a>
  95 WIM files</h2>
  96 <p>A <b>Windows Imaging (WIM)</b> file is an archive. Like some other archive formats such as ZIP, files in WIM archives may be compressed. WIM archives support two Microsoft-specific compression formats: <b>LZX</b> and <b>XPRESS</b>. Both are based on LZ77 and Huffman encoding, and both are supported by wimlib.</p>
  97 <p>Unlike ZIP files, WIM files can contain multiple independent toplevel directory trees known as <em>images</em>. While each image has its own metadata, files are not duplicated for each image; instead, each file is included only once in the entire WIM. Microsoft did this so that in one WIM file, they could do things like have 5 different versions of Windows that are almost exactly the same.</p>
  98 <p>WIM files may contain a integrity table. The integrity table, if it exists, is located at the end of the WIM file and contains SHA1 message digests of 10MB chunks of the WIM.</p>
  99 <p>Microsoft provides documentation for the WIM file format, XPRESS compression format, and LZX compression format. However, there are errors and omissions in some places in their documentation.</p>
 100 <h2><a class="anchor" id="starting"></a>
 101 Getting Started</h2>
 102 <p>wimlib uses the GNU autotools, so it should be easy to install with <code>configure &amp;&amp; make &amp;&amp; sudo make install</code>, provided that you have <code>libxml2</code> and <code>libfuse</code> installed. To use wimlib in a program after installing it, include <code><a class="el" href="wimlib_8h.html">wimlib.h</a></code> and link your program with <code>-lwim</code>.</p>
 103 <p>wimlib wraps up a WIM file in an opaque <a class="el" href="wimlib_8h.html#a8d4f2d1c1110b4519054e55d26b73775" title="Opaque structure that represents a WIM file.">WIMStruct</a> structure.</p>
 104 <p>All functions in wimlib's public API are prefixed with <code>wimlib</code>. Most return an integer error code on failure. Use <a class="el" href="wimlib_8h.html#a4cad466851acb2f24ba4af35b27003b7" title="Converts an error code into a string describing it.">wimlib_get_error_string()</a> to get a string that describes an error code. wimlib also can print error messages itself when an error happens, and these may be more informative than the error code; to enable this, call <a class="el" href="wimlib_8h.html#a49c39d3c9aa74ac63e1f97da97c20959" title="Sets whether wimlib is to print error messages to stderr when a function fails or not...">wimlib_set_print_errors()</a>.</p>
 105 <p>wimlib is thread-safe as long as different <a class="el" href="wimlib_8h.html#a8d4f2d1c1110b4519054e55d26b73775" title="Opaque structure that represents a WIM file.">WIMStruct</a>'s are used, with the following exceptions: <a class="el" href="wimlib_8h.html#a49c39d3c9aa74ac63e1f97da97c20959" title="Sets whether wimlib is to print error messages to stderr when a function fails or not...">wimlib_set_print_errors()</a> and <a class="el" href="wimlib_8h.html#a956a20eabacceda5230e346ee5cd387f" title="Set the functions that wimlib uses to allocate and free memory.">wimlib_set_memory_allocator()</a> apply globally, and <a class="el" href="wimlib_8h.html#aa6c0a2c2b896530718bd23e433b07e46" title="Mounts an image in a WIM file on a directory read-only or read-write.">wimlib_mount()</a> can only be used by one <a class="el" href="wimlib_8h.html#a8d4f2d1c1110b4519054e55d26b73775" title="Opaque structure that represents a WIM file.">WIMStruct</a> at a time.</p>
 106 <p>To open an existing WIM, use <a class="el" href="wimlib_8h.html#a16e1b87c7ab9eeadc0523a2477bfb0f6" title="Opens a WIM file and creates a WIMStruct for it.">wimlib_open_wim()</a>.</p>
 107 <p>To create a new WIM that initially contains no images, use <a class="el" href="wimlib_8h.html#a75acbea33e2faf398d58865fb764b91e" title="Creates a WIMStruct for a new WIM file.">wimlib_create_new_wim()</a>.</p>
 108 <p>To add an image to a WIM file from a directory tree on your filesystem, call <a class="el" href="wimlib_8h.html#a27ff93a6c6e9df370a6aa1eff753bb43" title="Adds an image to a WIM file from a directory tree on disk.">wimlib_add_image()</a>. This can be done with a <a class="el" href="wimlib_8h.html#a8d4f2d1c1110b4519054e55d26b73775" title="Opaque structure that represents a WIM file.">WIMStruct</a> gotten from <a class="el" href="wimlib_8h.html#a16e1b87c7ab9eeadc0523a2477bfb0f6" title="Opens a WIM file and creates a WIMStruct for it.">wimlib_open_wim()</a> or from <a class="el" href="wimlib_8h.html#a75acbea33e2faf398d58865fb764b91e" title="Creates a WIMStruct for a new WIM file.">wimlib_create_new_wim()</a>.</p>
 109 <p>To extract an image from a WIM file, call <a class="el" href="wimlib_8h.html#ab2a5fd17df52da1517835a05ee9b4965" title="Sets and creates the directory to which files are to be extracted when extracting files from the WIM...">wimlib_set_output_dir()</a> to set the output directory, then call <a class="el" href="wimlib_8h.html#a6a681ff211ec60f05a6ac5f743b17f65" title="Extracts an image, or all images, from a WIM file.">wimlib_extract_image()</a>.</p>
 110 <p>wimlib supports mounting WIM files either read-only or read-write. Mounting is done using <a class="el" href="wimlib_8h.html#aa6c0a2c2b896530718bd23e433b07e46" title="Mounts an image in a WIM file on a directory read-only or read-write.">wimlib_mount()</a> and unmounting is done using <a class="el" href="wimlib_8h.html#a2e0ba93652ac9372b56f9a67e3dbf1a1" title="Unmounts a WIM image that was mounted using wimlib_mount().">wimlib_unmount()</a>. Mounting can be done without root privileges because it is implemented using FUSE (Filesystem in Userspace). If wimlib is compiled with the <code>--without-fuse</code> flag, these functions will be available but will fail.</p>
 111 <p>After creating or modifying a WIM file, you can write it to a file using <a class="el" href="wimlib_8h.html#a968b46d4decee0ff73504ad9b212734e" title="Writes the WIM to a file.">wimlib_write()</a>. Alternatively, if the WIM was originally read from a file, you can use <a class="el" href="wimlib_8h.html#ab8648f8386379f2b2930b877e4efd6ca" title="Overwrites the file that the WIM was originally read from, with changes made.">wimlib_overwrite()</a> to overwrite the original file. In some cases, <a class="el" href="wimlib_8h.html#aec658496a01b1ca9dfd97eb9b9a92bb8" title="Updates the header and XML data of the WIM file, without the need to write out the entire WIM to a te...">wimlib_overwrite_xml_and_header()</a> can be used instead.</p>
 112 <p>After you are done with the WIM file, use <a class="el" href="wimlib_8h.html#a36a722a1651ff46b2f5a11a445c6fd73" title="Frees all memory allocated for a WIMStruct and closes all files associated with it.">wimlib_free()</a> to free all memory associated with a <a class="el" href="wimlib_8h.html#a8d4f2d1c1110b4519054e55d26b73775" title="Opaque structure that represents a WIM file.">WIMStruct</a> and close all files associated with it.</p>
 113 <p>To see an example of how to use wimlib, see the file <code>programs/imagex.c</code> in wimlib's source tree.</p>
 114 <p>wimlib supports custom memory allocators; use <a class="el" href="wimlib_8h.html#a956a20eabacceda5230e346ee5cd387f" title="Set the functions that wimlib uses to allocate and free memory.">wimlib_set_memory_allocator()</a> for this.</p>
 115 <h2><a class="anchor" id="imagex"></a>
 116 imagex</h2>
 117 <p>wimlib comes with the <b>imagex</b> program, which is documented in man pages.</p>
 118 <h2><a class="anchor" id="mkwinpeimg"></a>
 119 mkwinpeimg</h2>
 120 <p>wimlib comes with the <b>mkwinpeimg</b> script, which is documented in a man page.</p>
 121 <h2><a class="anchor" id="Limitations"></a>
 122 Limitations</h2>
 123 <p>While wimlib supports the main features of WIM files, wimlib currently has the following limitations:</p>
 124 <ul>
 125 <li>wimlib does not support "security data", which describes the access rights of the files in the WIM. This data is very Windows-specific, and it would be difficult to do anything with it. Microsoft's software can still read a WIM without security data, including a boot.wim for Windows PE, but <b>do not expect to be able to use wimlib to image a Windows installation and preserve file attributes</b>.</li>
 126 <li>There is no support for split WIMs, which have an image divided up between multiple WIM files.</li>
 127 <li>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 file going missing.</li>
 128 <li>Alternate stream entries for directory entries are ignored. I'm not sure if these are ever used for anything important.</li>
 129 <li>Different versions of the WIM file format, if they even exist, are unsupported. Let me know if you notice WIM files with a different version.</li>
 130 <li>Chunk sizes other than 32768 are unsupported (except for uncompressed WIMs, for which the chunk size field is ignored). As far as I can tell, other chunk sizes are not used in compressed WIMs. Let me know if you find a WIM file with a different chunk size.</li>
 131 <li>wimlib does not provide a clone of the <b>PEImg</b> tool that allows you to make certain Windows-specific modifications to a Windows PE image, such as adding a driver or Windows component. Such a tool could conceivably be implemented on top of wimlib, although it likely would be hard to implement because it would have to do very Windows-specific things such as manipulating the driver store. wimlib does provide the <b>mkwinpeimg</b> script for a similar purpose, however. With regards to adding drivers to Windows PE, you have the option of putting them anywhere in the Windows PE image, then loading them after boot using <b>drvload.exe</b>.</li>
 132 <li>There is not yet a way to extract specific files or directories from a WIM file without mounting it, or to add, remove, or modify files in a WIM without mounting it, other than by adding or removing an entire image. I can implement this if requested, but I intend the FUSE mount feature to be used for this purpose, as it is easy to do these things in whatever way you want after the image is mounted.</li>
 133 </ul>
 134 <p>Currently, Microsoft's <em>image.exe</em> can create slightly smaller WIM files than wimlib when using maximum (LZX) compression because it knows how to split up LZX compressed blocks, which is not yet implemented in wimlib.</p>
 135 <p>wimlib is experimental and likely contains bugs; use Microsoft's <em>imagex.exe</em> if you want to make sure your WIM files are made correctly.</p>
 136 <h2><a class="anchor" id="legal"></a>
 137 License</h2>
 138 <p>The wimlib library is licensed under the GNU Lesser General Public License version 2.1 or later.</p>
 139 <p><b>imagex</b> and <b>mkwinpeiso</b> are licensed under the GNU General Public License version 3 or later. </p>
 140 </div></div><!-- contents -->
 141
 142
 143 <hr class="footer"/><address class="footer"><small>
 144 Generated by &#160;<a href="http://www.doxygen.org/index.html">
 145 <img class="footer" src="doxygen.png" alt="doxygen"/>
 146 </a> 1.8.0
 147 </small></address>
 148
 149 </body>
 150 </html>