prevnext   » WIT: Wiimms ISO Tools » wdf: Wiimms WDF Tool
Wiimms ISO Tools
Introduction
Features
Change Log
Guides
Download
Privacy Statement
Index
Tools
wit
wwt
wdf
wfuse
wdf commands
+cat, +c
+diff, +cmp
+dump, +d
+help, +h
+pack, +p
+unpack, +u
+version, +v
WDF
Overview
Internals

wdf: Wiimms WDF Tool

wdf is a support tool for WDF, WIA, CISO and GCZ images. It converts (packs and unpacks), compares and dumps WDF and CISO images. Additionally it dumps WIA and GCT image and unpacks WIA images. The default command depends on the program file name (see command descriptions). Usual names are wdf, unwdf, wdf-cat, wdf-cmp and wdf-dump (with or without minus signs). »wdf +CAT« replaces the old tool wdf-cat and »wdf +DUMP« the old tool wdf-dump.

Contents

1.   Syntax

wdf [options]... [+command] [options]... files...

2.   Commands

'wdf' is a multi purpose tool. The functionality depends of the filename and the optional command. The command is the first non option parameter, but only, if it starts with a plus sign. Possible commands are:

+VERSION +V Print program name, version and the defaults and exit.
+HELP +H Print help and exit. If the first non option is a valid command name, then a help for the given command is printed.
+PACK +P Pack sources into WDF or CISO images. This is the general default.
+UNPACK +U Unpack WDF, WIA and CISO images.

This is the default command, when the program name starts with the two letters 'un' in any case.
+CAT +C Concatenate files and print on the standard output. WDF, WIA and CISO files are extracted before printing, all other files are copied byte by byte.

This is the default command, when the program name contains the sub string 'cat' in any case. »wdf +CAT« replaces the old tool wdf-cat.
+DIFF +CMP Compare files and unpack WDF, WIA and CISO while comparing.

The standard is to compare two source files. If --dest or --DEST is set, than all source files are compared against files in the destination path with equal names. If the second source file is missed, then standard input (stdin) is used instead.

This is the default command, when the program name contains the sub string 'diff' or 'cmp' in any case.
+DUMP +D Dump the data structure of WDF, WIA, CISO and GCZ images and ignore other files.

This is the default command, when the program contains the sub string 'dump' in any case. »wdf +DUMP« replaces the old tool wdf-dump.

If no command is entered, the tools looks for its tool name (filename used for its call) to deceide its functionality. The list ist processed in this order:

  1. *dump*
    If the file name contains the 4 letters 'dump' (ignoring case), the command mode is set to +DUMP.
  2. *cmp*
    Otherwise, if the file name contains the 3 letters 'cmp' (ignoring case), the command mode is set to +CMP.
  3. *cat*
    Otherwise, if the file name contains the 3 letters 'cat' (ignoring case), the command mode is set to +CAT.
  4. un*
    Otherwise, if the file name beginns with the 2 letters 'un' (ignoring case), the command mode is set to +UNPACK.
  5. Otherwise, the command mode is set to +PACK.

The default file format is also determinded by analysing the file name:

  1. *wia*
    If the file name contains the 3 letters 'wia' (ignoring case), the default archive format is set to WIA.
  2. *ciso* | *wbi*
    Otherwise, if the file name contains the 4 letters 'ciso' or the 3 letters 'wbi' (ignoring case), the default archive format is set to CISO.
  3. Otherwise, the default archive format is set to WDF.
The default file format can be overridden by using one of the options --wdf, --wia, --ico, --ciso, --wbfs, --gcz or --fst. The default archive format is only needed for creating (packing) a new compressed file. All other commands look into the source file to determine the file format.

You can use softlinks and hardlinks to eneable the alternate file names. The installer set the hardlinks wdf-cat and wdf-dump to wdf for compatibility to old versions if the toolset.

2.1   Examples

File Name Default Functionality
wdf PACK the source and create a WDF.
wia PACK the source and create a WIA.
unciso UNPACK the source. The CISO format has only impact, if the +PACK command is explicitly set.
wdfcat
wdf-cat		 CAT the source. The WDF format has only impact, if the +PACK command is explicitly set.
wdfdump
wdf-dump		 DUMP the source. The WDF format has only impact, if the +PACK command is explicitly set.
xyz PACK the source and create a WDF.

3.   Options in alphabetic order

Options
Option Param Description
--align-wdf [align][,minhole] Parameter align defines the aligning factor for new WDF images. It must be a power of 2 and smaller or equal than 1 GiB. The default WDF alignment is 1 for WDF v1 and 4 for WDF v2. Usual values are 1, 512, 4K and 32K.

The optional parameter minhole defines the minimal hole size, before a new chunk is created. If NULL, an internal value is used to minimize the total file size. minhole can't be smaller than align.
--auto-split Enable auto split modus: Split only if necessary and determine the split size automatically.

THIS OPTION IS EXPERIMENTAL. In future versions it becomes the default.
--block-size size If a mismatch is found in raw or disc mode then the comparison is continued with the next block. This option sets the block size. The default value is 32K (Wii sector size). This option is ignored in quiet mode.
--chunk Print table with chunk header too.
--chunk-mode mode Defines an operation mode for --chunk-size and --max-chunks. Allowed keywords are 'ANY' to allow any values, '32K' to force chunk sizes with a multiple of 32 KiB, 'POW2' to force chunk sizes >=32K and with a power of 2 or 'ISO' for ISO images (more restrictive as 'POW2', best for USB loaders). The case of the keyword is ignored. The default key is '32K'.

--chm is a shortcut for --chunk-mode.
--chunk-size sz Define the minimal chunk size if creating a CISO or WIA file (for WIA details see option --compression}). The default is to calculate the chunk size from the input file size and find a good value by using a minimal value of 1 MiB for »--chunk-mode ISO« and 32 KiB for modes 32K and POW2. For the modes ISO and POW2 the value is rounded up to the next power of 2. This calculation also depends from option --max-chunks.

The parameter 'sz' is a floating point number followed by an optional unit factor (one of 'cb' [=1] or 'kmgtpe' [base=1000] or 'KMGTPE' [base=1024]). The default unit is 'M' (MiB). If the number is prefixed with a '=' then options --chunk-mode and --max-chunks are ignored and the given value is used without any rounding or changing.

If the input file size is not known (e.g. reading from pipe), its size is assumed as 12 GiB.

--chs is a shortcut for --chunk-size.
-C --ciso Force CISO output mode if packing and set the default suffix to '.ciso'.

This is the default, when the program name contains the sub string 'ciso' in any case.
--color [=modus] Define the modus for colored text output. Allowed keywords are: OFF or NO-COLORS to disable colors, AUTO (default) for automatic detection, ON for automatic detection but never OFF, 8-COLORS and 256-COLORS for 8 and 256 color support. Without parameter, ON is used.

AUTO will enable colorized output only for terminals. AUTO and ON use environment variable TERM to find the correct color modus.

If a command is prefixed by 'C-', then --color=ON is used implicitly as default.
--256-colors Short cut for --color=256-colors: Force colorized text with 256 color support.
--compression mode Select one compression method, level and chunk size for new WIA files. The syntax for mode is: [method] [.level] [@factor]

'method' is the name of the method. Possible compressions method are NONE, PURGE, BZIP2, LZMA and LZMA2. There are additional keywords: DEFAULT (=LZMA.5@20), FAST (=BZIP2.3@10), GOOD (=LZMA.5@20) BEST (=LZMA.7@50), and MEM (use best mode in respect to memory limit set by --mem). Additionally the single digit modes 0 (=NONE), 1 (=fast LZMA) .. 9 (=BEST)are defined. These additional keywords may change their meanings if a new compression method is implemented.

'.level' is a point followed by one digit. It defines the compression level. The special value .0 means: Use default compression level (=.5).

'@factor' is a factor for the chunk size. The base size is 2 MiB. The value @0 is replaced by the default factor @20 (40 MiB). If the factor is not set but option --chunk-size is set, the factor will be calculated by using a rounded value of that option.

All three parts are optional. All default values may be changed in the future. --compr is a shortcut for --compression and --wia=mode a shortcut for »--wia --compression mode«. The command »wit COMPR« prints an overview about all compression modes.
-d --dest path Define a destination path (directory/file).
-D --DEST path Like --dest, but create the directory path automatically.
--dsync [=mode] This option enables the usage of flag O_DSYNC when opening a partition at a hard drive for writing. With activated flag, writing an image is some percent slower, but the progress counters are exact again.

Parameter MODE is optional. If set, it is one of OFF (disable), ON (enable) or AUTO (default). With AUTO, DSYNC is enabled if the progress counters are active.

This option has only impact, if compiler and operation system support the flag O_DSYNC. Linux does.
--file-limit size This option is only used if comparing discs on file level. If not set or set to null, then all files will be compared. If set to a value greater than comparison is aborted for the current source image if the entered number of files differ. This option is ignored in quiet mode.
-h --help Stop parsing the command line, print a help message and exit.
--io flags Setup the IO mode for experiments. The standard file IO is based on open() function. The value '1' defines that WBFS IO is based on fopen() function. The value '2' defines the same for ISO files and value '4' for WIA files. You can combine the values by adding them.
-k --keep Keep (don't delete) input files during (un-)packing.
--limit num Limit the output to NUM messages.
-L --logging This debug option enables the logging of internal memory maps. If set twice second level memory maps are printed too.
-l --long Print (un)pack statistics, 1 line for each source. In dump mode: Print table with chunk header too (same as --chunk).
--max-chunks n Define the maximal number of chunks if creating a CISO file. The default value is 8192 for »--chunk-mode ISO« and 32760 (maximal value) for all other modes. If this value is set than the automatic calculation of --chunk-size will be modified too.

--mch is a shortcut for --max-chunks.
--mem size This option defines a memory usage limit for compressing files (in MiB if no other unit is entered). When compressing a file with method MEM (see --compression) the the compression method, level and chunk size are selected with respect to this limit.

If this option is not set or the value is 0, then the environment WIT_MEM is tried to read instead. If this fails, the tool tries to find out the total memory by reading /proc/meminfo. The limit is set to 80% of the total memory minus 50 MiB.
-1 --minus-1 If set the end address is the last address of a range. The standard is to print the first address that is not part of the address of a range.
--no-colors Short cut for --color=off: Deactivate colorized text. This is the default, if an output file is not a terminal.
--no-split Disable output file splitting. This is the default, but in future versions, the new option --auto-split becomes the default.
-o --overwrite Overwrite already existing files without warning.
--prealloc [=mode] This option enables or disables the disc space preallocation. If enabled the tools try to allocate disc space for the new files before writing the data. This reduces the fragmentation but also disables the sparse effect for preallocated areas.

The optional parameter decides the preallocation mode: OFF (or 0), SMART (or 1), ALL (or 2). If no parameter is set, ALL is used.

Mode 'OFF' disables the preallocation. Mode 'SMART' looks into the source disc to find out the writing areas. SMART is only available for ISO, CISO and WBFS file types. For other file types ALL is used instead. Mode 'ALL' (the default) preallocate the whole destination file. Because of the large holes in plain ISO images, the SMART mode is used for ISOs instead.
-p --preserve Preserve file times (atime+mtime) while copying an image. This option is enabled by default if an unmodified disc image is copied.
-q --quiet Be quiet and print only error messages.
-z --split Enable output file splitting. The default split size is 4 GB.
-Z --split-size sz Enable output file splitting and define a split size. The parameter 'sz' is a floating point number followed by an optional unit factor (one of 'cb' [=1] or 'kmgtpe' [base=1000] or 'KMGTPE' [base=1024]). The default unit is 'G' (GiB).
-c --stdout Write to standard output (stdout) and keep (don't delete) input files.

This is the default, when the program is reading from standard input (stdin).
-s --suffix .suf Use suffix '.suf' instead of '.wdf', '.wia', or '.ciso' for packed files.
-t --test Run in test mode, modify nothing.

>>> USE THIS OPTION IF UNSURE! <<<
-v --verbose Be verbose -> print program name.
-V --version Stop parsing the command line, print a version info and exit.
--wbi Force CISO output mode if packing and set the default suffix to '.wbi'.

This is the default, when the program name contains the sub string 'wbi' but not 'ciso' in any case.
-W --wdf [=param] Force WDF output mode if packing and set the default suffix to '.wdf'. This is the general default. --wdf=param is a short cut for »--wdf --align-wdf=param«.
--wdf1 [=param] Force WDF v1 output mode, if packing. Set the default suffix to '.wdf'. --wdf1=param is a short cut for »--wdf1 --align-wdf=param«.
--wdf2 [=param] Force WDF v2 output mode, if packing. Set the default suffix to '.wdf'. --wdf2=param is a short cut for »--wdf2 --align-wdf=param«.
--wia [=compr] Force WIA output mode if packing and set the default suffix to '.wia'. The optional parameter is a compression mode and --wia=mode is a shortcut for »--wia --compression mode«.

WIA output is the default, when the program name contains the sub string 'wia' in any case.
--width width Define the width (number of columns) for help and some other messages and disable the automatic detection of the terminal width.
--xhelp Stop parsing the command line and print a help message with all commands included. Exit after printing.