*
* \section intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.4.1, a C
+ * This is the documentation for the library interface of wimlib 1.5.0, a C
* library for creating, modifying, extracting, and mounting files in the
* Windows Imaging Format. This documentation is intended for developers only.
* If you have installed wimlib and want to know how to use the @b wimlib-imagex
* After creating or modifying a WIM file, you can write it to a file using
* wimlib_write(). Alternatively, if the WIM was originally read from a file
* (using wimlib_open_wim() rather than wimlib_create_new_wim()), you can use
- * wimlib_overwrite() to overwrite the original file.
+ * wimlib_overwrite() to overwrite the original file. Still alternatively, you
+ * can write a WIM directly to a file descriptor by calling wimlib_write_to_fd()
+ * instead.
+ *
+ * wimlib supports a special "pipable" WIM format (which unfortunately is @b not
+ * compatible with Microsoft's software). To create a pipable WIM, call
+ * wimlib_write(), wimlib_write_to_fd(), or wimlib_overwrite() with
+ * ::WIMLIB_WRITE_FLAG_PIPABLE specified. Pipable WIMs are pipable in both
+ * directions, so wimlib_write_to_fd() can be used to write a pipable WIM to a
+ * pipe, and wimlib_extract_image_from_pipe() can be used to apply an image from
+ * a pipable WIM.
*
* Please note: merely by calling wimlib_add_image() or many of the other
* functions in this library that operate on ::WIMStruct's, you are @b not
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 4
+#define WIMLIB_MINOR_VERSION 5
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 0
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
* info will point to ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
- /** A file or directory is being extracted. @a info will point to
- * ::wimlib_progress_info.extract, and the @a cur_path member will be
- * valid. */
- WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY,
+ /** Reserved. */
+ WIMLIB_PROGRESS_MSG_EXTRACT_RESERVED,
/** All the WIM files and directories have been extracted, and
* timestamps are about to be applied. @a info will point to
* ::wimlib_progress_info.integrity. */
WIMLIB_PROGRESS_MSG_CALC_INTEGRITY,
- /** A wimlib_join() operation is in progress. @a info will point to
- * ::wimlib_progress_info.join. */
- WIMLIB_PROGRESS_MSG_JOIN_STREAMS,
+ /** Reserved. (Previously used for WIMLIB_PROGRESS_MSG_JOIN_STREAMS,
+ * but in wimlib v1.5.0 this was removed to simplify the code and now
+ * you'll get ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages instead.) */
+ WIMLIB_PROGRESS_MSG_RESERVED,
/** A wimlib_split() operation is in progress, and a new split part is
* about to be started. @a info will point to
* (The actual number of bytes will be less if the data is being
* written compressed.) */
uint64_t total_bytes;
+
/** Number of streams that are going to be written. */
uint64_t total_streams;
uint64_t completed_streams;
/** Number of threads that are being used to compress resources
- * (if applicable). */
+ * (if applicable). */
unsigned num_threads;
/** The compression type being used to write the streams; either
* ::WIMLIB_COMPRESSION_TYPE_LZX. */
int compression_type;
- /** Library internal use only. */
- uint64_t _private;
+ /** Number of split WIM parts from which streams are being
+ * written (may be 0 if irrelevant). */
+ unsigned total_parts;
+
+ /** Number of split WIM parts from which streams have been
+ * written (may be 0 if irrelevant). */
+ unsigned completed_parts;
} write_streams;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
* extracted. */
const wimlib_tchar *target;
- /** Current dentry being extracted. (Valid only if message is
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY.) */
+ /** Reserved. */
const wimlib_tchar *cur_path;
/** Number of bytes of uncompressed data that will be extracted.
* Takes into account hard links (they are not counted for each
- * link.)
- * */
+ * link.) */
uint64_t total_bytes;
/** Number of bytes that have been written so far. Will be 0
const wimlib_tchar *filename;
} integrity;
- /** Valid on messages ::WIMLIB_PROGRESS_MSG_JOIN_STREAMS. */
- struct wimlib_progress_info_join {
- /** Total number of bytes of compressed data contained in all
- * the split WIM part's file and metadata resources. */
- uint64_t total_bytes;
-
- /** Number of bytes that have been copied to the joined WIM so
- * far. Will be 0 initially, and equal to @a total_bytes at the
- * end. */
- uint64_t completed_bytes;
-
- /** Number of split WIM parts that have had all their file and
- * metadata resources copied over to the joined WIM so far. */
- unsigned completed_parts;
-
- /** Number of split WIM parts. */
- unsigned total_parts;
- } join;
-
/** Valid on messages ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and
* ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART. */
struct wimlib_progress_info_split {
* finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */
unsigned cur_part_number;
+ /** Total number of split WIM parts that are being written. */
+ unsigned total_parts;
+
/** Name of the split WIM part that is about to be started
* (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been
* finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */
struct wimlib_pattern_list reserved2;
/** Library internal use only. */
- const wimlib_tchar *_prefix;
+ wimlib_tchar *_prefix;
/** Library internal use only. */
size_t _prefix_num_tchars;
uint32_t write_in_progress : 1;
uint32_t metadata_only : 1;
uint32_t resource_only : 1;
- uint32_t reserved_flags : 23;
+
+ /** 1 if the WIM is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */
+ uint32_t pipable : 1;
+ uint32_t reserved_flags : 22;
uint32_t reserved[9];
};
* together. Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */
#define WIMLIB_EXTRACT_FLAG_SYMLINK 0x00000004
-/** Call the progress function with the argument
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY each time a file or directory is
- * extracted. Note: these calls will be interspersed with calls for the message
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. */
+/** This flag no longer does anything but is reserved for future use. */
#define WIMLIB_EXTRACT_FLAG_VERBOSE 0x00000008
/** Read the WIM file sequentially while extracting the image. */
* one. */
#define WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS 0x00001000
+/** Do not ignore failure to set timestamps on extracted files. */
+#define WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS 0x00002000
+
+/** Do not ignore failure to set short names on extracted files. */
+#define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000
+
+/** Do not ignore failure to extract symbolic links (and junction points, on
+ * Windows) due to permissions problems. By default, such failures are ignored
+ * since the default configuration of Windows only allows the Administrator to
+ * create symbolic links. */
+#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000
+
+/** TODO */
+#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000
+
+
/******************************
* WIMLIB_MOUNT_FLAG_*
******************************/
* WIMLIB_WRITE_FLAG_*
******************************/
-/** Include an integrity table in the new WIM file. */
+/** Include an integrity table in the WIM.
+ *
+ * For WIMs created with wimlib_open_wim(), the default behavior is to include
+ * an integrity table if and only if one was present before. For WIMs created
+ * with wimlib_create_new_wim(), the default behavior is to not include an
+ * integrity table. */
#define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY 0x00000001
-/** Re-build the entire WIM file rather than appending data to it, if possible.
- * (Applies to wimlib_overwrite(), not wimlib_write()). */
-#define WIMLIB_WRITE_FLAG_REBUILD 0x00000002
-
-/** Recompress all resources, even if they could otherwise be copied from a
- * different WIM with the same compression type (in the case of
- * wimlib_export_image() being called previously). */
-#define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000004
-
-/** Call fsync() when the WIM file is closed */
-#define WIMLIB_WRITE_FLAG_FSYNC 0x00000008
+/** Do not include an integrity table in the new WIM file. This is the default
+ * behavior, unless the WIM already included an integrity table. */
+#define WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY 0x00000002
-/* Specifying this flag overrides the default behavior of wimlib_overwrite()
- * after one or more calls to wimlib_delete_image(), which is to rebuild the
- * entire WIM.
+/** Write the WIM as "pipable". After writing a WIM with this flag specified,
+ * images from it can be applied directly from a pipe using
+ * wimlib_extract_image_from_pipe(). See the documentation for the --pipable
+ * flag of `wimlib-imagex capture' for more information. Beware: WIMs written
+ * with this flag will not be compatible with Microsoft's software.
*
- * If you specifiy this flag to wimlib_overwrite(), only minimal changes to
- * correctly remove the image from the WIM will be taken. In particular, all
- * streams will be left alone, even if they are no longer referenced. This is
- * probably not what you want, because almost no space will be spaced by
- * deleting an image in this way. */
-#define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000010
+ * For WIMs created with wimlib_open_wim(), the default behavior is to write the
+ * WIM as pipable if and only if it was pipable before. For WIMs created with
+ * wimlib_create_new_wim(), the default behavior is to write the WIM as
+ * non-pipable. */
+#define WIMLIB_WRITE_FLAG_PIPABLE 0x00000004
-/** With wimlib_overwrite(), allow overwriting the WIM even if the readonly flag
- * is set in the WIM header; this can be used in combination with
+/** Do not write the WIM as "pipable". This is the default behavior, unless the
+ * WIM was pipable already. */
+#define WIMLIB_WRITE_FLAG_NOT_PIPABLE 0x00000008
+
+/** Recompress all resources, even if they could otherwise be copied from a
+ * different WIM with the same compression type (in the case of
+ * wimlib_export_image() being called previously). This flag is also valid in
+ * the @p wim_write_flags of wimlib_join(), in which case all resources included
+ * in the joined WIM file will be recompressed. */
+#define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000010
+
+/** Call fsync() just before the WIM file is closed. */
+#define WIMLIB_WRITE_FLAG_FSYNC 0x00000020
+
+/** wimlib_overwrite() only: Re-build the entire WIM file rather than appending
+ * data to it if possible. */
+#define WIMLIB_WRITE_FLAG_REBUILD 0x00000040
+
+/** wimlib_overwrite() only: Specifying this flag overrides the default
+ * behavior of wimlib_overwrite() after one or more calls to
+ * wimlib_delete_image(), which is to rebuild the entire WIM. With this flag,
+ * only minimal changes to correctly remove the image from the WIM will be
+ * taken. In particular, all streams will be left alone, even if they are no
+ * longer referenced. This is probably not what you want, because almost no
+ * space will be saved by deleting an image in this way. */
+#define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000080
+
+/** wimlib_overwrite() only: Allow overwriting the WIM even if the readonly
+ * flag is set in the WIM header. This can be used in combination with
* wimlib_set_wim_info() with the ::WIMLIB_CHANGE_READONLY_FLAG flag to actually
- * set the readonly flag on the on-disk WIM file. */
-#define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000020
+ * set the readonly flag on the on-disk WIM file. */
+#define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100
/******************************
* WIMLIB_INIT_FLAG_*
******************************/
/** Assume that strings are represented in UTF-8, even if this is not the
- * locale's character encoding. */
+ * locale's character encoding. Not used on Windows. */
#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
+/** Windows-only: do not attempt to acquire additional privileges (currently
+ * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and
+ * SeTakeOwnershipPrivilege) when initializing the library. This is intended
+ * for the case where the calling program manages these privileges itself.
+ * Note: no error is issued if privileges cannot be acquired, although related
+ * errors may be reported later, depending on if the operations performed
+ * actually require additional privileges or not. */
+#define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002
+
/** Specification of an update to perform on a WIM image. */
struct wimlib_update_command {
enum wimlib_error_code {
WIMLIB_ERR_SUCCESS = 0,
WIMLIB_ERR_ALREADY_LOCKED,
- WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
WIMLIB_ERR_DECOMPRESSION,
WIMLIB_ERR_DELETE_STAGING_DIR,
WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED,
WIMLIB_ERR_ICONV_NOT_AVAILABLE,
WIMLIB_ERR_IMAGE_COUNT,
WIMLIB_ERR_IMAGE_NAME_COLLISION,
- WIMLIB_ERR_INSUFFICIENT_PRIVILEGES_TO_EXTRACT,
WIMLIB_ERR_INTEGRITY,
WIMLIB_ERR_INVALID_CAPTURE_CONFIG,
WIMLIB_ERR_INVALID_CHUNK_SIZE,
WIMLIB_ERR_INVALID_COMPRESSION_TYPE,
- WIMLIB_ERR_INVALID_DENTRY,
- WIMLIB_ERR_INVALID_HEADER_SIZE,
+ WIMLIB_ERR_INVALID_HEADER,
WIMLIB_ERR_INVALID_IMAGE,
WIMLIB_ERR_INVALID_INTEGRITY_TABLE,
WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY,
+ WIMLIB_ERR_INVALID_METADATA_RESOURCE,
WIMLIB_ERR_INVALID_MULTIBYTE_STRING,
WIMLIB_ERR_INVALID_OVERLAY,
WIMLIB_ERR_INVALID_PARAM,
WIMLIB_ERR_INVALID_PART_NUMBER,
+ WIMLIB_ERR_INVALID_PIPABLE_WIM,
WIMLIB_ERR_INVALID_REPARSE_DATA,
WIMLIB_ERR_INVALID_RESOURCE_HASH,
- WIMLIB_ERR_INVALID_RESOURCE_SIZE,
WIMLIB_ERR_INVALID_SECURITY_DATA,
WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
WIMLIB_ERR_INVALID_UTF16_STRING,
WIMLIB_ERR_NOTEMPTY,
WIMLIB_ERR_NOT_A_REGULAR_FILE,
WIMLIB_ERR_NOT_A_WIM_FILE,
+ WIMLIB_ERR_NOT_PIPABLE,
WIMLIB_ERR_NO_FILENAME,
WIMLIB_ERR_NTFS_3G,
WIMLIB_ERR_OPEN,
WIMLIB_ERR_RENAME,
WIMLIB_ERR_REOPEN,
WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED,
+ WIMLIB_ERR_RESOURCE_NOT_FOUND,
WIMLIB_ERR_RESOURCE_ORDER,
+ WIMLIB_ERR_SET_ATTRIBUTES,
+ WIMLIB_ERR_SET_SECURITY,
+ WIMLIB_ERR_SET_TIMESTAMPS,
WIMLIB_ERR_SPECIAL_FILE,
WIMLIB_ERR_SPLIT_INVALID,
WIMLIB_ERR_SPLIT_UNSUPPORTED,
WIMLIB_ERR_STAT,
WIMLIB_ERR_TIMEOUT,
+ WIMLIB_ERR_UNEXPECTED_END_OF_FILE,
WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE,
WIMLIB_ERR_UNKNOWN_VERSION,
WIMLIB_ERR_UNSUPPORTED,
WIMLIB_ERR_VOLUME_LACKS_FEATURES,
+ WIMLIB_ERR_WIM_IS_READONLY,
WIMLIB_ERR_WRITE,
WIMLIB_ERR_XML,
- WIMLIB_ERR_WIM_IS_READONLY,
- WIMLIB_ERR_RESOURCE_NOT_FOUND,
};
/**
* Appends an empty image to a WIM file. This empty image will initially
* contain no files or directories, although if written without further
- * modifications, a root directory will be created automatically for it.
+ * modifications, a root directory will be created automatically for it. After
+ * calling this function, you can use wimlib_update_image() to add files to the
+ * new WIM image. This gives you slightly more control over making the new
+ * image compared to calling wimlib_add_image() or
+ * wimlib_add_image_multisource() directly.
*
* @param wim
* Pointer to the ::WIMStruct for the WIM file to which the image is to be
*
* @retval ::WIMLIB_ERR_DECOMPRESSION
* Could not decompress the metadata resource for @a image.
- * @retval ::WIMLIB_ERR_INVALID_DENTRY
- * A directory entry in the metadata resource for @a image in the WIM is
- * invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @a image does not exist in the WIM and is not ::WIMLIB_ALL_IMAGES.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
* @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
* One or more of the names being given to an exported image was already in
* use in the destination WIM.
- * @retval ::WIMLIB_ERR_INVALID_DENTRY
- * A directory entry in the metadata resource for @a src_image in @a
- * src_wim is invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @a src_image does not exist in @a src_wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @retval ::WIMLIB_ERR_DECOMPRESSION
* Could not decompress a resource (file or metadata) for @a image in @a
* wim.
- * @retval ::WIMLIB_ERR_INVALID_DENTRY
- * A directory entry in the metadata resource for @a image in @a wim is
- * invalid.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @a target was @c NULL, or both ::WIMLIB_EXTRACT_FLAG_HARDLINK and
* ::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags; or
* One of the dentries in the image referenced a stream not present in the
* WIM's lookup table (or in any of the lookup tables of the split WIM
* parts).
+ * @retval ::WIMLIB_ERR_SET_ATTRIBUTES
+ * Failed to set attributes on a file.
+ * @retval ::WIMLIB_ERR_SET_SECURITY
+ * Failed to set security descriptor on a file
+ * (only if ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS) specified in @p
+ * extract_flags.
+ * @retval ::WIMLIB_ERR_SET_TIMESTAMPS
+ * Failed to set timestamps on a file (only if
+ * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS) specified in @p extract_flags.
* @retval ::WIMLIB_ERR_SPLIT_INVALID
* The WIM is a split WIM, but the parts specified do not form a complete
* split WIM because they do not include all the parts of the original WIM,
unsigned num_additional_swms,
wimlib_progress_func_t progress_func);
+/**
+ * Since wimlib v1.5.0: Extract one or more images from a pipe on which a
+ * pipable WIM is being sent.
+ *
+ * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information
+ * about pipable WIMs.
+ *
+ * This function operates in a special way to read the WIM fully sequentially.
+ * As a result, there is no ::WIMStruct is made visible to library users, and
+ * you cannot call wimlib_open_wim() on the pipe. (You can, however, use
+ * wimlib_open_wim() to transparently open a pipable WIM if it's available as a
+ * seekable file, not a pipe.)
+ *
+ * @param pipe_fd
+ * File descriptor, which may be a pipe, opened for reading and positioned
+ * at the start of the pipable WIM.
+ * @param image_num_or_name
+ * String that specifies the 1-based index or name of the image to extract.
+ * It is translated to an image index using the same rules that
+ * wimlib_resolve_image() uses. However, unlike wimlib_extract_image(),
+ * only a single image (not all images) can be specified. Alternatively,
+ * specify @p NULL here to use the first image in the WIM if it contains
+ * exactly one image but otherwise return @p WIMLIB_ERR_INVALID_IMAGE.
+ * @param target
+ * Same as the corresponding parameter to wimlib_extract_image().
+ * @param extract_flags
+ * Same as the corresponding parameter to wimlib_extract_image(), except
+ * for the following exceptions: ::WIMLIB_EXTRACT_FLAG_SEQUENTIAL is
+ * always implied, since data is always read from @p pipe_fd sequentially
+ * in this mode; also, ::WIMLIB_EXTRACT_FLAG_TO_STDOUT is invalid and will
+ * result in ::WIMLIB_ERR_INVALID_PARAM being returned.
+ * @param progress_func
+ * Same as the corresponding parameter to wimlib_extract_image().
+ *
+ * @return 0 on success; nonzero on error. The possible error codes include
+ * those returned by wimlib_extract_image() as well as the following:
+ *
+ * @retval ::WIMLIB_ERR_NOT_PIPABLE
+ * The WIM being piped in a @p pipe_fd is a normal WIM, not a pipable WIM.
+ */
+extern int
+wimlib_extract_image_from_pipe(int pipe_fd,
+ const wimlib_tchar *image_num_or_name,
+ const wimlib_tchar *target, int extract_flags,
+ wimlib_progress_func_t progress_func);
+
/**
* Extracts the XML data of a WIM file to a file stream. Every WIM file
* includes a string of XML that describes the images contained in the WIM.
/**
* Initialization function for wimlib. Call before using any other wimlib
- * function.
+ * function except wimlib_set_print_errors(). (However, currently this is not
+ * strictly necessary and it will be called automatically if not done manually,
+ * but you should not rely on this behavior.)
*
* @param init_flags
- * On UNIX, specify ::WIMLIB_INIT_FLAG_ASSUME_UTF8 if wimlib should assume
- * that all input data, including filenames, are in UTF-8 rather than the
- * locale-dependent character encoding which may or may not be UTF-8, and
- * that UTF-8 data can be directly printed to the console. On Windows, use
- * 0 for this parameter.
+ * Bitwise OR of ::WIMLIB_INIT_FLAG_ASSUME_UTF8 and/or
+ * ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES.
*
* @return 0; other error codes may be returned in future releases.
*/
/**
* Since wimlib 1.2.6: Cleanup function for wimlib. This is not re-entrant.
* You are not required to call this function, but it will release any global
- * memory allocated by the library.
+ * resources allocated by the library.
*/
extern void
wimlib_global_cleanup(void);
* Could not decompress the metadata resource for @a image in @a wim.
* @retval ::WIMLIB_ERR_FUSE
* A non-zero status was returned by @c fuse_main().
- * @retval ::WIMLIB_ERR_INVALID_DENTRY
- * A directory entry in the metadata resource for @a image in @a wim is
- * invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @a image does not specify an existing, single image in @a wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
* The header of @a wim_file says that resources in the WIM are compressed,
* but the header flag indicating LZX or XPRESS compression is not set.
- * @retval ::WIMLIB_ERR_INVALID_HEADER_SIZE
+ * @retval ::WIMLIB_ERR_INVALID_HEADER
* The length field of the WIM header is not 208.
* @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE
* ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @a open_flags and @a
* The lookup table for the WIM contained duplicate entries that are not
* for metadata resources, or it contained an entry with a SHA1 message
* digest of all 0's.
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p wim_ret was @c NULL.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocated needed memory.
* @retval ::WIMLIB_ERR_NOT_A_WIM_FILE
*
* By default, error messages are not printed.
*
+ * This can be called before wimlib_global_init().
+ *
* @param show_messages
* @c true if error messages are to be printed; @c false if error messages
* are not to be printed.
extern int
wimlib_split(WIMStruct *wim,
const wimlib_tchar *swm_name,
- size_t part_size,
+ uint64_t part_size,
int write_flags,
wimlib_progress_func_t progress_func);
* @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
* The capture configuration structure specified for an add command was
* invalid.
- * @retval ::WIMLIB_ERR_INVALID_DENTRY
- * A directory entry for @a image in @a wim is invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @a image did not specify a single, existing image in @a wim.
* @retval ::WIMLIB_ERR_INVALID_OVERLAY
* @param path
* The path to the file to write the WIM to.
* @param image
- * The image inside the WIM to write. Use ::WIMLIB_ALL_IMAGES to include all
- * images.
+ * The 1-based index of the image inside the WIM to write. Use
+ * ::WIMLIB_ALL_IMAGES to include all images.
* @param write_flags
- * Bitwise OR of the flags ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY,
- * ::WIMLIB_WRITE_FLAG_RECOMPRESS, ::WIMLIB_WRITE_FLAG_FSYNC, and/or
- * ::WIMLIB_WRITE_FLAG_SOFT_DELETE.
+ * Bitwise OR of any of the flags prefixed with @c WIMLIB_WRITE_FLAG.
* @param num_threads
* Number of threads to use for compressing data. If 0, the number of
* threads is taken to be the number of online processors. Note: if no
* write_flags).
* @param progress_func
* If non-NULL, a function that will be called periodically with the
- * progress of the current operation.
+ * progress of the current operation. The possible messages are
+ * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
+ * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END, and
+ * ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS.
*
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_DECOMPRESSION
* Failed to decompress a metadata or file resource in @a wim.
- * @retval ::WIMLIB_ERR_INVALID_DENTRY
- * A directory entry in the metadata resource for @a image in @a wim is
- * invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @a image does not specify a single existing image in @a wim, and is not
* ::WIMLIB_ALL_IMAGES.
* wimlib_add_image() was concurrently modified, so it failed the SHA1
* message digest check.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * @a path was @c NULL.
+ * @p path was @c NULL.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
* The metadata resource for @a image in @a wim is invalid.
* @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate needed memory.
* @retval ::WIMLIB_ERR_OPEN
- * Failed to open @a path for writing, or some file resources in @a
- * wim refer to files in the outside filesystem, and one of these files
- * could not be opened for reading.
+ * Failed to open @a path for writing, or some file resources in @a wim
+ * refer to files in the outside filesystem, and one of these files could
+ * not be opened for reading.
* @retval ::WIMLIB_ERR_READ
* An error occurred when trying to read data from the WIM file associated
* 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_SPLIT_UNSUPPORTED
- * @a wim is part of a split WIM. You may not call this function on a
- * split WIM.
+ * @a wim is part of a split WIM, not a standalone WIM.
* @retval ::WIMLIB_ERR_WRITE
- * An error occurred when trying to write data to the new WIM file at @a
- * path.
+ * An error occurred when trying to write data to the new WIM file.
*/
extern int
wimlib_write(WIMStruct *wim,
unsigned num_threads,
wimlib_progress_func_t progress_func);
+/**
+ * Since wimlib v1.5.0: Same as wimlib_write(), but write the WIM directly to a
+ * file descriptor, which need not be seekable if the write is done in a special
+ * pipable WIM format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p
+ * write_flags. This can, for example, allow capturing a WIM image and
+ * streaming it over the network. See the documentation for
+ * ::WIMLIB_WRITE_FLAG_PIPABLE for more information about pipable WIMs.
+ *
+ * The file descriptor @p fd will not be closed when the write is complete; the
+ * calling code is responsible for this.
+ *
+ * Return values are mostly the same as wimlib_write(), but also:
+ *
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p fd was not seekable, but ::WIMLIB_WRITE_FLAG_PIPABLE was not
+ * specified in @p write_flags.
+ */
+extern int
+wimlib_write_to_fd(WIMStruct *wim,
+ int fd,
+ int image,
+ int write_flags,
+ unsigned num_threads,
+ wimlib_progress_func_t progress_func);
+
/**
* This function is equivalent to wimlib_lzx_compress(), but instead compresses
* the data using "XPRESS" compression.
git://wimlib.net / wimlib / blobdiff