» WIT: Wiimms ISO Tools » wwt: Wiimms WBFS Tool » wwt extract

# wwt extract

Extract discs from WBFS partitions and store them as Wii or GameCube images.

## 1. Syntax

    wwt EXTRACT id6[=dest]...

## 2. Options

Options
Option | Param | Description
--- | --- | ---
`-T` | `--titles` | file | Read file for disc titles. -T/ disables automatic search for title files.
| `--utf-8` |  | Enables UTF-8 support for filenames (default).
| `--no-utf-8` |  | Disables UTF-8 support for filenames.
| `--lang` | lang | Define the language for titles.
`-a` | `--auto` |  | Search for WBFS partitions using '/proc/partitions' or searching hard disks in '/dev/'.
`-A` | `--all` |  | Use all WBFS partitions found.
`-p` | `--part` | part | Define a primary WBFS file or partition. Multiple usage possible.
| `--no-check` |  | Disable automatic check of WBFS before modifications.
`-x` | `--exclude` | id | A comma separated list with ID4 and ID6 values is expected. '.' is a wildcard for exact 1 character and '+' is a wildcard for any number characters. If the parameter begins with a '@' the given file is read and each line is scanned for one ID. Images with the given ID are excluded from operation. Each use of this option expands the exclude list. See --include-first for precedence issues.
`-X` | `--exclude-path` | file_or_dir | Scan the ID of the source and add it to the exclude list. If the source is a directory then scan all images of the directory. Images with the given ID are excluded from operation. Each use of this option expands the exclude list. See --include-first for precedence issues.
`-n` | `--include` | id | A comma separated list with ID values is expected. '.' is a wildcard for exact 1 character and '+' is a wildcard for any number characters. If the parameter begins with a '@' the given file is read and each line is scanned for one ID. Only images with the given ID are included into the operation. Each use of this option expands the include list. See --include-first for precedence issues.
`-N` | `--include-path` | file_or_dir | Scan the ID of the source and add it to the include list. If the source is a directory then scan all images of the directory. Only images with the given ID are included into the operation. Each use of this option expands the include list. See --include-first for precedence issues.
| `--include-first` |  | The options --include, --include-path, --exclude and --exclude-path decide which discs are included into the operation. If neither include nor exclude options are used, than all disc are included into the operation. If only include options are used, than only the specified discs are operated. If only exclude options are used, than all all discs but not the excluded are operated. If include and exclude options are used together and --include-first is not set, than all discs are operated that are specified by any include option and not by any exclude option. If --include-first is set, than all discs are ignored that are specified by any exclude option and not by any include option.
`-1` | `--one-job` |  | Execute only the first job and exit. This is a shortcut for »--job-limit 1«.
| `--job-limit` | num | Execute only the first 'num' jobs and exit. If done without errors the exit status is OK (zero).
`-q` | `--quiet` |  | Be quiet and print only error messages.
`-v` | `--verbose` |  | Show a runtime summary for each job. If set twice enable progress information. If set three times the progress information is more detailed.
`-P` | `--progress` |  | Print progress counter. If --verbose is set at least twice, printing is enabled too. If progress is enabled, the default of --dsync is changed.
| `--scan-progress` |  | Print a message for each found image while scanning the file system.
`-l` | `--long` |  | Print a summary line while extracting files. If set at least twice, print a status line for each extracted files.
| `--sections` |  | Print in machine readable sections and parameter lines.
`-t` | `--test` |  | Run in test mode, modify nothing. >>> USE THIS OPTION IF UNSURE! <<<
`-d` | `--dest` | path | Define a destination path (directory or file). The destination path is scanned for escape sequences (see option --esc) to allow generic paths.
`-D` | `--DEST` | path | Like --dest, but create the directory path automatically.
`-E` | `--esc` | char | Define an alternative escape character for destination files. The default is '%'. For Windows (CYGWIN) it is a good choice to set '-E$' to avoid conflicts with command shell variables.
| `--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.
| `--no-split` |  | Disable output file splitting. This is the default, but in future versions, the new option --auto-split becomes the default.
`-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).
| `--disc-size` | size | Define a minimal (virtual) ISO disc size.
| `--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.
| `--trunc` |  | Truncate PLAIN ISO and WBFS images after creating or copying to the minimal needed size with respect to the block size.
| `--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 'ISO'. --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.
| `--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.
| `--enc` | encoding | Define the encoding mode. The mode is one of NONE, HASHONLY, DECRYPT, ENCRYPT, SIGN or AUTO. The case of the keywords is ignored. The default mode is 'AUTO'.
| `--modify` | list | This patching option defines the impact of the options --name and --id. It expects a comma separated list of the following keywords (case ignored) as parameter: NONE, DISC, BOOT, TICKET, TMD, WBFS, TT, ALL and AUTO (default). All keywords can be prefixed by '+' to enable that option, by a '-' to disable it or by a '=' to enable that option and disable all others.
| `--name` | name | This patching option changes the name (disc title) of the disc to the given parameter. Up to 63 characters are expected. The disc header and boot.bin are objects to modify. The option --modify selects the objects.
| `--id` | id | This patching option changes the ID of the disc to the given parameter. 1 to 6 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. The disc header, boot.bin, ticket.bin and tmd.bin are objects to modify. The option --modify selects the objects.
| `--disc-id` | id | This patching option changes the ID of the disc header to the given parameter. 1 to 6 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. Option --disc-id overrides the definition of option --id.
| `--boot-id` | id | This patching option changes the ID of boot.bin to the given parameter. 1 to 6 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. Option --boot-id overrides the definition of option --id.
| `--ticket-id` | id | This patching option changes the ID of ticket.bin to the given parameter. 1 to 4 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 4 characters. Option --ticket-id overrides the definition of option --id.
| `--tmd-id` | id | This patching option changes the ID of tmd.bin to the given parameter. 1 to 4 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 4 characters. Option --tmd-id overrides the definition of option --id.
| `--tt-id` | id | This is a short cut for »--ticket id --tmd id«. If TICKET and TMD differ, the game will freeze after loading. So it makes only sense to change TICKET and TMD IDs together.
| `--wbfs-id` | id | This patching option changes the ID of the WBFS header to the given parameter if adding a file to a WBFS or if creating a WBFS file. 1 to 6 characters are expected. The already patched disc ID of the source is used as base and only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. Option --wbfs-id overrides the definition of option --id.
| `--region` | region | This patching option defines the region of the disc. The region is one of JAPAN, USA, EUROPE, KOREA, FILE or AUTO (default). The case of the keywords is ignored. Unsigned numbers are also accepted.
| `--common-key` | index | This patching option defines the common key index as part of the TICKET. Keywords 0, STANDARD, 1 and KOREAN are accepted.
| `--ios` | ios | This patching option defines the system version (IOS to load) within TMD. The format is 'HIGH:LOW' or 'HIGH-LOW' or 'LOW'. If only LOW is set than HIGH is assumed as 1 (standard IOS).
| `--http` |  | This patching option replaces 'https' request to 'http' in the files 'main.dol' and 'rel/StaticR.rel', if the files exist. It also replaces the sub-domain 'naswii' to 'nas'.
| `--domain` | domain | This patching option replaces the domain 'nintendowifi.net' by the new domain. The length of the new domain must not be larger than the old length (16 characters). If the new domain length is not larger than 11, then 'gamespy.com' of 'sake.gamespy.com' is replaced too. This is a special support for 'Super Smash Bros. Brawl'.
| `--security-fix` |  | Try to fix a security bug in the game. This is game dependent.
| `--wiimmfi` |  | Patch the images for Wiimmfi, the new custom server. It is a short cut for »--http --domain wiimmfi.de --security-fix«.
| `--rm-files` | ruleset | This patching option defines filter rules to remove real files and directories from the FST of the DATA partition. Fake signing of the TMD is necessary. The processing order of file options is: »--rm-files --zero-files --ignore-files«.
| `--zero-files` | ruleset | This patching option defines filter rules to zero (set size to zero) real files of the FST of the DATA partition. Fake signing of the TMD is necessary. The processing order of file options is: »--rm-files --zero-files --ignore-files«.
| `--psel` | list | This option set the scrubbing mode and defines, which disc partitions are handled. It expects a comma separated list of keywords, numbers and names; all together called parameter. All parameters are case insensitive and non ambiguous abbreviations of keywords are allowed. Each parameter becomes a rule and each rule is appended to a rule list. Rules prefixed by a minus sign are DENY rules. Rules prefixed by a plus sign or without a prefix are ALLOW rules. Each partition is compared with each rule until a rule matches the partition. If a match it found, the partition is enabled for a ALLOW rule or disabled for a DENY rule. The allowed keywords are: DATA, UPDATE, CHANNEL, PTAB0 .. PTAB3, ID, ALL, WHOLE and RAW. The following input formats are accepted too: ptype, #index, #<index, #<=index, #>index, #>=index and #tab_index.part_index.
| `--raw` |  | Abbreviation of »--psel RAW«.
`-W` | `--wdf` | [=param] | Set the image output file type to WDF (Wii Disc Format). The output format is either WDFv1 or WDFv2 (default). It depends of the input file format and of the aligning. --wdf=param is a short cut for »--wdf --align-wdf=param«.
`-I` | `--iso` |  | Set image output file type to PLAIN ISO.
`-C` | `--ciso` |  | Set image output file type to CISO (Compact ISO, same as WBI).
`-B` | `--wbfs` |  | Set image output file type to WBFS (Wii Backup File System, default).
| `--wia` | [=compr] | Set image output file type to WIA (Wii ISO Archive). The optional parameter is a compression mode and --wia=mode is a shortcut for »--wia --compression mode«.
| `--gcz` |  | Set image output file type to GCZ (Dolphins GameCube Zip).
| `--gcz-zip` |  | If creating a GCZ image, a blockwise z-compression is tried. If the compressed data is larger than 98.5%, the uncompressed data is stored. Encrypted blocks are stored directly as uncompressed data, because the 98.5% test fails all the time. Option --gcz-zip disables this optimization for encrypted data and makes the creation process slower.
| `--gcz-block` | size | The value defines the block size, if creating a GCZ image. The default is 16K (also Dolphins default). Smaller values enlarge the managment data and reduce the compression ratio. Use the option with caution!
| `--fst` |  | Set image output mode to 'file system' (extracted ISO).
| `--pmode` | p-mode | This options set the prefix mode for listed or extracted files. One of the following values is allowed: AUTO, NONE, POINT, ID, NAME, INDEX, COMBI. The default value is 'AUTO'.
| `--flat` |  | While extracting a disc image strip all path names of the source file and store all files in the same directory. This option sets the default for --pmode to NONE.
| `--files` | ruleset | Append file select rules. This option can be used multiple times to extend the rule list. Rules beginning with a '+' or a '-' are allow or deny rules rules. Rules beginning with a ':' are macros for predefined rule sets.
| `--copy-gc` |  | If extracting a GameCube disc image, don't extract the real files to '/files/...'. Instead create a copy of the source image and store it as 'game.iso'. If the source image is already in this format, try to create a hard link and copy only if it fails.
| `--no-link` |  | Don't try to create a hard link if copying the image forced by the option --copy-gc.
| `--neek` |  | Abbreviation of »--psel data --pmode none --files :neek --copy-gc«. The old name --sneek is accepted too.
| `--links` |  | Detect soft and hard linked source files while composing or extracting discs and try to create hard links instead of independent copies on the destination file system.
`-U` | `--unique` |  | Eliminate multiple ID6 from the source list.
`-i` | `--ignore` |  | Ignore non existing discs without any warning.
`-R` | `--remove` |  | Remove source files/discs if operation is successful. If the source is an extracted file systems (FST) it isn't removed.
`-u` | `--update` |  | Copy only non existing discs.
`-o` | `--overwrite` |  | Overwrite already existing files without warning.

## 3. Description

The EXTRACT command extracts all discs identified by ID6 from all given WBFS partitions. The options --all, --auto and --part decides which partitions will are used as source. Before accessing the WBFS a check (see command CHECK) is done. If there are detected any problematic errors the source WBFS is ignored. If the option --force is set, the test is done but the result is ignored. The option --no-check disables this automatic check.

Each parameter is scanned for an ID6, see »Disc IDs« for detals. Each ID can be followed by =path to explicitly define a destination path for this ID.

For each found disc a Wii ISO image is created in the current working directory as base. The option --dest can be used to define an other base destination directory. Option --DEST is like --dest, but the directory path is created automaticaly. New images are created in the base directory. If the ID contains a path extension (=path) the entered path is used as destination directory. Relative pathes uses the base destination directoryas origin.

If a disc is found on 2 or more WBFS partitions the disc image will only extracted from the first source. To overwrite an existing file the option --overwrite must be set. The option --ignore suppresses error messages about non found disc images. If the option --remove is set then the discs which are extracted without errors are removed from all WBFS partitions.

The output is scrubbed. The scrubbing can be controlled or disabled with the options --psel and --raw. The options --split and --split-size control the splitting. If option --remove is set then the souce file is removed after successfull operation. The output file format can be selected by option or filename. The destination filename can be filled with esacpe sequences to generate content dependent filenames. See »Writing an image« for details.

If the --quiet option is set only error messages will be printed. If the --verbose option is set run time calculations will be made too. If the --verbose option is at least twice a progress status will be shown. The progress output is also enabled by setting --progress.

If the --test option is set the programm does nothing, neither copying nor removing. Instead it will print some 'WOULD ...' messages. If the --testoption is set at least twice then only a normalized ID6 list is printed, each ID in one line. If a destination filename is known 'ID=name' is printed.

## 4. Usual error/exit codes:

    0 == OK             : All done without errors.
    SYNTAX ERROR        : At least one syntax error in command line found.
    MISSING PARAMETERS  : No parameters (ID6) given.
    NO WBFS FOUND       : No WBFS partition found.
    TO MUCH WBFS FOUND  : Two or more no WBFS partition found but --all missed.
    WDISC NOT FOUND     : Disc not found on any WBFS partition.
    REMOVE ERROR        : Error while removing a disc from a WBFS.
    READ ERROR          : Error while reading the WBFS.
    WRITE ERROR         : Error while writing a ISO image.