
*******************************************************************************
*******              Wiimms ISO Toolset v3.05a - 2024-07-14             *******
*******************************************************************************

Wiimms ISO Toolset (WIT) is a command line tool set for linux and for other
unix like operating systems including cygwin. The tools manage WBFS partitions
and ISO Images. WWT cotains the following tools:

The both main tools are:
  wit      : Wiimms ISO Tool manage ISO files.
  wwt      : Wiimms WBFS Tool manage WBFS partitions.

And these are special WDF and CISO tools:
  wdf-cat  : a 'cat' like programm with special handling of WDF files.
  wdf-dump : dump the data structure of a WDF file.

The software is developed under the GPL 2.0 license. See file gpl-2.0.txt
or URI http://www.gnu.org/licenses/gpl-2.0.txt for details.

The most current source is available under:
  https://wit.wiimm.de/r/viewvc/
The source of this revision (8638) is available under:
  https://wit.wiimm.de/r/viewvc/?pathrev=8638
You can also checkout the SVN repository:
  http://opensvn.wiimm.de/wii/trunk/wiimms-iso-tools//

See https://wit.wiimm.de/ for announcements and discussions.

This files describes the main tool 'wwt'.


*******************************************************************************
*******                     Content of all documents                  *********
*******************************************************************************

The documentation is divided into several files:

  DOCUMENTATION.txt : General overview.
  FAQ.txt           : FAQ of all tools.
  HISTORY.txt       : Complete development history.

  wit.txt           : Documentation about the tool 'wit'.
  wwt.txt           : Documentation about the tool 'wwt'.

  WDF.txt           : Definition of a WDF file.
  WBFS.txt          : Interesting things about WBFS



*******************************************************************************
*******                    Overview about this document               *********
*******************************************************************************

Contents:

    Output of 'wwt --help'
    @file
    Commands in detail
    Processing partitions
    Processing ISO files
    Processing ID6 parameters
    Processing exclude options
    Processing title db
    Processing split options
    Processing size options
    Some options in detail
    Hidden options (for testing)
    Environment variables
    Signals


*******************************************************************************
*******                      Output of 'wwt --help'                   *********
*******************************************************************************


*******************************************************************************
*******                             @file                               *******
*******************************************************************************

If a parameter beginns with '@' the text behind that '@' is a filename.
Each line of the file is taken as a parameter (not option, not command).
Each line may terminate with LF or CR+LF. Handling of '@' is *not* recurse.

The special filename '-' means: read from standard input (stdin).


*******************************************************************************
*******                        Commands in detail                       *******
*******************************************************************************

Command abbreviations are allowed as long as they are unique. The commands
are listed in alphabetic order:


-------------------------------------------------------------------------------

 The ADD command adds all given ISO images to all given WBFS partitions. The
 filename '-' means 'read from stdin'. The three options --all, --auto and
 --part decides which partitions will be modified (see section "Options in
 detail: partitions" for details).

 If a given file does not exist or isn't a ISO image (maybe shrinked with WDF)
 an error message will be printed. The option --ignore suppresses this message.
 ADD accept plain ISO files, WDF ISO files, WBFS files and directories as
 source. For a directory each valid ISO file is used as source. The option
 --recurse allow a definition of a directory which is search recursive.

 Existing WBFS discs will be ignored if --update is set. They are only over-
 written if the option --overwrite is set. After successfull operation and if
 --remove is set, the ISO images will be removed from the source file system.

 If option --sync is set than before adding all discs that are not part of
 the soruce list are removed from the WBFS. The option --sync includes
 the option --update. After operation the WBFS contains exactly the ISO images
 which ae defined in the source list.

 If the option --newer is set and source and destination 'mtime' (last modi-
 fication time) for the current job are both available and non zero, then the
 options --update and --overwrite are ignored and the destination is over-
 written if the source is newer (younger) than the destination.
 
 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.

 If the --test option is set the programm does nothing, neither copying nor
 removing. Instead it will print some 'WOULD ...' messages.

 Before modifying the WBFS a check (see CHECK) is done. If there are any
 problematic errors detected the 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.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    JOB_IGNORED         : a source file is ignored.
    SYNTAX ERROR        : at least one syntax error in command line found.
    MISSING PARAMETERS  : no parameters (iso images) given.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.
    WRITE ERROR         : error while writing a WBFS.
    REMOVE ERROR        : error while removing a disc from a WBFS.
    READ ERROR          : error while reading an ISO image or a WBFS.


-------------------------------------------------------------------------------


-------------------------------------------------------------------------------

 Command CHECKS checks WBFS partions for block errors in 5 categories:
   - Find discs with invalid blocks.
   - Find discs with no valid blocks.
   - Find discs which uses same blocks.
   - Find free blocks that marked as used.
   - Find used blocks that marked as free.

 If the option --repair is set then the detected error are fixed. Fixing the
 free blocks table is the last action. Be carfull because discs will be removed.

 The repair modes in detail: 

    -   | NONE       : reset = ignore previous settings

    F   | FBT        : repair free blocks table
    I   | INODES     : setup all missing inode infos
    STD | STANDARD   : default setting: FBT,INODES

    RI  | RM-INVALID : remove discs with invalid blocks
    RO  | RM-OVERLAP : remove discs with overlaped blocks
    RF  | RM-FREE    : remove discs with free marked blocks
    RE  | RM-EMPTY   : remove discs with no valid blocks
    RA  | RM-ALL     : remove all discs with errors

    *   | ALL        : repair all

    All keyword can be prefixed by
      + : enable repair mode (default)
      - : disable repair mode
      = : enable repair mode and disable all others


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.
    WBFS INVALID        : An invalid WBFS found (WBFS with errors)


-------------------------------------------------------------------------------

 The DUMP command dumps out the data structure of all WBFS. data. The three
 options --all, --auto and --part decides where partitions will be searched
 (see section "Options in detail: partitions" for details).

 If at least one parameter ('wbfs_partition') is given ther option --all well
 be enabled and all names are insterted into the partition list like --auto.
 This enables an easy lookup like 'wwt find *.wbfs'.

 DUMP will dumps the data structure of all WBFS partitions found. If the
 option --long is set then all Wii discs of each WBFS partition will be dumped
 too. If option --long is set at least twice an additional memory map for each
 disc will be printed. If --long is set at least three times an additional
 memory map for the whole WBFS is printed at the end. Failures (overlapped
 areas) are marked with '!'.

 If the option --inode is set, all inodes (invalid inodes with with proper
 inforamtions too) are shown. This implies at least one --long. When --long
 is four or more times the option --inode is set automatically.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

 EDIT is a dangerous command. It let you (de-)activate the disc slots and
 edit the block assignments. Exact 1 WBFS must be specified. All parameters
 are sub commands. Modifications are only done if option --force is set.

     **********************************************************
     *****  WARNING: This command can damage your WBFS!!  *****
     **********************************************************

 Each parameter is one sub command. The case of commands is ignored. After
 editing a check of the WBFS is made and a status printed if errors found.
 The general subcommand syntax is:

    subcommand=parameter[,parameter]...

 List of subcommands:

   RM=a,b-c,...
   R=a,b-c,...
      Remove disc in slot 'a' or the slot range 'b-c' from wbfs. The slot is
      only marked as free, no blocks are freed. EDIT does not allow undefined
      slot numbers. The indices are null based.

   ACT=a,b-c,...
   A=a,b-c,...
      Activate disc in slot 'a' or the slot range 'b-c' from wbfs. The slot 
      is only marked as activated without any tests. EDIT does not allow
      undefined slot numbers. The indices are null based.

   INV=a,b-c,...
   I=a,b-c,...
      Like 'ACT' but the slot is additionally marked as invalid.

   FREE=a,b-c,...
   F=a,b-c,...
      Modify the free blocks table and mark the single block 'a' or the range
      of blocks 'b-c' as free.  EDIT does not allow undefined block numbers.

   USE=a,b-c,...
   U=a,b-c,...
      Modify the free blocks table and mark the single block 'a' or the range
      of blocks 'b-c' as used. EDIT does not allow undefined block numbers.

   ID6=a:b,c-d:e,...
      For the game with ID6:
         Set ISO block 'a' to WBFS block 'b' or set ISO blocks 'c-d' to WBFS
         blocks 'e...'. If 'e' is zero then set ISO blocks 'c-d' to zero
         (=unused). EDIT does not allow undefined block numbers.

 Note: The block size for all sub commands is always the WBFS block size,
       but never the ISO block size.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

 The command ERROR translate an exit code to a text message. Without parameters
 print all error names and error messages. With a given 'error_code' the error
 message that belongs the number is printed to stdout and the program exits
 with exit status is 0 (success). If the error_code is unknown or invalid the
 error message is '?' and the program exits with exit status is 1 (failure).

 Without 'error_code' a list of all error codes is printed. The output
 contains three columns separated with colons. The format is:

    error code ':' error name ':' error messages

 If the option --sections is set, then the layout is completly changed to a
 sections base output. This output is machine readable. The output looks like:

	[error-CODE]
	code=ERROR_NUMBER
	name=ERROR_NAME
	text=ERROR_TEXT


 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.
    SEMANTIC ERROR : unkown error_code given.


-------------------------------------------------------------------------------

 The command 'EXCLUDE' builts the exclude data base and prints the result to
 stdout. The handling of the additional files works like the --exclude option.
 The section "Processing exclude options" explains the options in detail.


 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.


-------------------------------------------------------------------------------


-------------------------------------------------------------------------------

 The command 'FILETYPE' prints for each given file one status line like:
    FILETYPE ID6 SIZE_MIB REGION SPLIT FILENAME
 Columns 'ID6' and 'SPLIT' are only printed if option --long is set. For non
 ISO images the ID6 is '-'. If the file is splitted than column 'SPLIT' shows
 the number of split files instead of '-'. Columns 'SIZE_MIB' and 'REGION'
 are only printed if option --long is set at least two times.

 'SIZE_MIB' is the calculatet size of a scrubbed ISO image. For this all used
 sectors of a ISO image are counted. The usage depends of the options --psel
 and --raw.

 Filetypes are:
    NO-FILE  : No file found
    DIR      : Not a file but a directory
    WBFS     : A WBFS
    WBFS/    : A WBFS used like directory with id6 or index or pos
    WDF+WBFS : A WBFS shrinked with WDF (this make no sense expect transporting)
    ISO      : A ISO image.
    WDF+ISO  : A ISO image shrinked with WDF.
    WDF      : Any other WDF file (not WBFS or ISO)
    WIA      : A ISO image packed into the WIA (Wii ISO Archive). 
    GCZ      : Dolphins GameCup-Zip images.
    OTHER    : Any other file

 Remark: The test for WBFS is poor and must be improved.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.


-------------------------------------------------------------------------------

 The FIND command makes a quick search for WBFS partitions: it scans only the
 WBFS-Header. The three options --all, --auto and --part decides where partitions
 will be searched (see section "Options in detail: partitions" for details).

 If at least one parameter ('wbfs_partition') is given the option --all will be
 enabled and all names are inserted into the partition list like --auto.
 This enables an easy lookup like 'wwt find *.wbfs'.

 Without option --long only a list of found WBFS partition will print out,
 each partition in one line.

 With a single --long option an aligned list of all partitions, wbfs or not,
 is printed with 5 colums:
    type       : 'PLAIN' for plain files or 'BLOCK' for block devices.
    wbfs       : 'WBFS' or '--'
    disc usage : allocated size in MiB.
    size       : file size in MiB.
    file       : the given path name of the file.
 The option --no-header suppress the output of header and footer.

 With a double (or more) --long option the layout is changed:
    type       : 'PLAIN' for plain files or 'BLOCK' for block devices.
    wbfs       : 'WBFS' or '--'
    disc usage : allocated size in MiB.
    size       : file size in bytes.
    full path  : the real path name of the file.
 The option --no-header suppress the output of header and footer.

 The 'disc usage' is smaller than the 'file length' if the file contains holes
 (sparse files). For block devices it is always printed as zero.

 If the option --quiet is set then FIND is absolut quiet. If at least one of
 the examined partitions or files is a valid WBFS then the return status is
 'OK' (0). If none is a WBFS the return status is 'NO WBFS FOUND' (not null).

 
 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

 The command FORMAT format block devices and plain files with a WBFS. All data
 on the destination will be lost.

 The command works in test mode if the option --test is set or the option
 --force is not set. So you must set the option --force to format.

 The option --size is irrelevant for already existing files. Non existing
 files will be created as sparse files. Therefor the option --size is needed.
 The option needs a integer number and an optional factor sign.

 The option --hss defines the HD sector size of the WBFS partition. The default
 is 512 bytes and most other tools and USB loaders will only support this 512.
 But the wbfs framwork supports any value >=16 but it must be a power of 2.
 WWT forces values >= 512.

 The option --wss defines the WBFS sector size. If not set the INIT function
 calculates a good value.
 
 The parameters of the size options --size and --sector-size are discussed in
 the section "Processing size options".

 If the option --recover is set, the WBFS will be formatted in recover mode:
  - If --hss or --wss is not set then an internal call to ANALYZE (output
    suppressed) is made to determine the values. The data of the first
    virtual row is used to override the default values of --hss and --wss.
  - Only the header of the WBFS is written. The inodes are not cleared.
  - All empty discs slots are marked as used.
  - All WBFS blocks are marked as used.
  - A silent check and repair is done:
     - Drop discs with invalid magic or without ID.
     - Drop rescued discs with invalid block numbers. (--repair=RM-INVALID)
     - Drop rescued discs without any block. (--repair=RM-EMPTY)
     - Free unused blocks in the free blocks table. (--repair=FBT)
  - A verbose check is done (like "wwt check --verbose") to find and report
    other errors.

 WARNING:
    Before using "wwt INIT --recover" you should call "wwt ANALYZE" and
    control the output!


 See also:
    wwt RECOVER: Recover discs without reformatting.


 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 (iso images) given.
    WRITE ERROR         : error while writing/formatting a WBFS.


-------------------------------------------------------------------------------

 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.


-------------------------------------------------------------------------------

 The command 'ID6' lists the ID6 of all discs for each partition, one ID per row.
 The three options --all, --auto and --part decides where partitions
 will be searched (see section "Options in detail: partitions" for details).

 If neither --part nor --auto is set then the options --auto and --all are
 assumed. So the usage of 'id6' without options is easy.

 If --uniqe is set each game disc with same ID6, name, size and region is only
 printed once. The --unique option implies the --all option.

 The sort order can be set by the --sort option. Sort=none means, that the ID
 will be shown in order of the WBFS partition. The default sort order is 'ID'.

 If the option --long is set the output is "WBFS_FILE/ID6" for each game.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.


-------------------------------------------------------------------------------

 The command 'LIST' lists infos of all discs for each partition, one disc per
 row. The three options --all, --auto and --part decides where partitions will
 be searched (see section "Options in detail: partitions" for details).

 If neither --part nor --auto is set then thr options --auto and --all are
 assumed. So the usage of 'list' without options is easy.

 Without --long the ID and the name are printed. With option --long the ID,
 size, region and the name are printed.  The option --no-header suppress the
 output of header and footer.

 Printing of timestamps is enabled by the options --time, --itime, --mtime
 --ctime, --atime or when --long is set at least twice. --time=off disables
 time printing. All time options (not --long) supersede the previous options.
 The option --time take a comma separated list of the following keywords:

    OFF    : Disable time printing. All other option enable time printing.
    ON     : Enable time printing.

    SINGLE : Print only a single column (last time specified.
    MULTI  : Print columns for all specified times. (default)

    I      : Use itime (insertion time) for processing.
    M      : Use mtime (last modicifaction time) for processing. (default)
    C      : Use ctime (last staus change time) for processing.
    A      : Use atime (last access time) for processing.

    NONE   : Disable all 4 times above
    ALL    : Enable all 4 times above
    
    DATE   : Print time in format 'YYYY-MM-DD'. (default)
    TIME   : Print time in format 'YYYY-MM-DD HH:MM'.
    MIN    : Alternative keyword for 'TIME'.
    SEC    : Print time in format 'YYYY-MM-DD HH:MM:SS'.

    *DATE  : Short cut for '*,DATE'. '*' is one of 'I', 'M', 'C' or 'A'.
    *TIME  : Short cut for '*,TIME'. '*' is one of 'I', 'M', 'C' or 'A'.
    *MIN   : Alternative keywords for '*TIME'.
    *SEC   : Short cut for '*,SEC'.  '*' is one of 'I', 'M', 'C' or 'A'.

 With --mixed all discs of all partitions were mixed together. If --uniqe is
 set each game disc identified by ID6 is only printet once. The --mixed option
 implies the --all option. The --unique option implies the --mixed and the
 --all options.

 If the option --long is set three or more time together with --mixed then a
 WBFS table is printed at the top with a WBFS-Index ('WI') and the filename.
 The game table contains an additional column with this WBFS-Index.

 If the option --sections is set, then the layout is completly changed to a
 sections base output. This output is machine readable. The output looks like:

        [section_name-index]
        parameter=value
        parameter=value
        ...

 The sort order can be set by the --sort option. Sort=none means, that the ID
 will be shown in order of the WBFS partition. The default sort order is
 'TITLE'.

 If available the name of the title database is used as game name. use the
 option -T0 to disable database titles.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

COMMANDS:
    LIST-L   | LL    [wbfs_partition]...
    LIST-LL  | LLL   [wbfs_partition]...
    LIST-A   | LA    [wbfs_partition]...
    LIST-M   | LM    [wbfs_partition]...
    LIST-U   | LU    [wbfs_partition]...

 'LIST-L'   is a synonym for 'LIST --long'.
 'LIST-LL'  is a synonym for 'LIST --long --long'.
 'LIST-A'   is a synonym for 'LIST --long --long --all --auto'.
 'LIST-M'   is a synonym for 'LIST --long --long --all --mixed'.
 'LIST-U'   is a synonym for 'LIST --long --long --all --unique'.
 See command 'LIST' for options and details.


-------------------------------------------------------------------------------

 The PHANTOM commands adds multiple discs to WBFS partitions. The content of
 the discs is undefined, only the WBFS inode and the ISO header (first 256
 bytes) are written to  WBFS. The PHANTOM command is implemented for test
 purposes; it can fill a WBFS very fast with multiple discs with random size.

 The ID6 of phantom discs are 'PHT###', where '###' is the lowest unused
 decimal number.

 The syntax of each subcommand is: [ NUM 'x' ] SIZE ['m'|'g']

 NUM defines a number of discs to add. NUM is a unsigned integer or a range
 like '2-5'. If a range is given, wwt add a random number of discs specified
 by this range. The default number is '1'

 SIZE defines the size of the discs in GiB. SIZE is a unsigned integer or a
 range like '1-9'. If a range is given, wwt calculates the real size
 as random number in the specified discs. If a 'm' (or 'M') is follows the
 size, SIZE is specified in MiB and not in GiB.

 Example: wwt PHANTOM 3-5x1-9
    create 3, 4 or 5 discs, each with a random size between 1 and 9 GiB.

 Multiple subcommands are allowed. The program terminates the filling
 process automatically and without errors if the WBFS becomes full.
 Full means that are slots are used or that no more data space is left.
 If the data space runs out the last phantom will be cutted silently
 so that all data blocks in the WBFS are used.

 Before modifying the WBFS a check (see CHECK) is done. If there are any
 problematic errors detected the 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.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

 The command RECOVER tries to recover presious removed discs. It recover only
 discs without block collisions (2 ore mor discs shares the same memory).

 Recovering work like this:
  - All empty discs slots are marked as used.
  - All WBFS blocks are marked as used.
  - A silent check and repair is done:
     - Drop discs with invalid magic or without ID.
     - Drop rescued discs with invalid block numbers. (--repair=RM-INVALID)
     - Drop rescued discs without any block. (--repair=RM-EMPTY)
     - Free unused blocks in the free blocks table. (--repair=FBT)
  - A verbose check is done (like "wwt check --verbose") to find and report
    other errors.

 See also:
    wwt FORMAT --recover: Format WBFS and recoverdiscs.

 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 (iso images) given.
    WRITE ERROR         : error while writing/formatting a WBFS.


-------------------------------------------------------------------------------

 The REMOVE command removes all discs identified by ID6 from all given WBFS
 partitions. The options --all, --auto and --part decides which partitions
 will be modified (see section "Options in detail: partitions" for details).

 Each parameter is scanned for an ID6. Possible formats are:
    '*' | '+'
    ID6
    ID6=name
    name [ID6]
    ID6 anything
 A single '*' (must be escaped by shells) or '+' means 'all'. A 'name' part
 will be ignored. Please read section "Processing ID6 parameters" for details.

 The option --ignore suppresses error messages about not found disc images.

 If the --quiet option is set only error messages will be printed.
 If the --verbose option is set run time claculations will be made too.

 If the --test option is set the programm does nothing, neither copying nor
 removing. Instead it will print some 'WOULD ...' messages.
 If the --test option is set two or more times then only a normalized ID6
 list is printed. For each ID6 one line is printed. If a destination
 filename is known 'ID=name' is printed, else 'ID6' alone.

 If the option --no-free is set then the disc is only marked as removed. The
 allocated blocks are not freed. After using --no-free you should use the
 command CHECK with --rapair=fbt to repair the free blocks table.

 Before modifying the WBFS a check (see CHECK) is done. If there are any
 problematic errors detected the 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.


 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  : 2 to 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 an ISO image or a WBFS.


-------------------------------------------------------------------------------

 This command 'RENAME' may change the ID6 and/or the title of discs. It can
 change the information in the WBFS inode or the information in the ISO header
 or both (the default).

 The alternative command 'SETTITLE' modifies only titles. The advantage of
 'SETTITLE' is, that it can modify all titles with 1 sub command.

 The syntax of a sub command is: id6=[new_id6][,new_title]
    'id6' is the ID of the disc to change.
    The optional 'new_id6' is the new ID of the disc.
    The optional 'new_title' is the new title of the disc.

 Processing the new title:

    The title string is parsed for escape sequences beginning with the escape
    character '%'. The accepted format is:

        '%cX'  or  '%mcX'  or  '%n-mcX'

    'n' is the number of skipped characters of the field.

    'm' is the zero based index of the last copied character.

    'c' is an optional character. If c is 'u' then the source will be
        converted to uppercase and if c is 'l' to lower case.

    'X' selects the source and is one of:

        'i' : the (new) ID6
        'I' : the (new) ID6
        'j' : The previous ID stored in the WBFS inode.
        'J' : The previous ID stored in the ISO header.

        'n' : The previous disc title stored in the WBFS inode.
        'N' : The previous disc title stored in the ISO ehader.

        't' : The title from the title database based on the new ID or, if not
              changed, on the ID of the WBFS inode. If no title found the disc
              name stored in the WBFS inode is used.
        'T' : Same as 't'
        'p' : The title from the title database based on the previous ID stored
              in the WBFS inode. If no title found the disc name stored in the
              WBFS inode is used.
        'P' : The title from the title database based on the previous ID stored
              in the ISO header. If no title found the disc name stored in the
              ISO header is used.

        If the object to change is not a WBFS then the ISO data is used instead
        of the WBFS inode data ('j', 'n', and 'p' conversions).

    To use the '%' sign itself just type '%%'.

    Instead of '%' an alternative escape character can be used. It is defined
    by the option --esc. This makes live easier if using the cygwin version
    together with the windows shell 'cmd'. Define the environment variables
    'WIT_OPT' and/or 'WWT_OPT' for a new default definition.


-------------------------------------------------------------------------------

 Command REPAIR checks and repairs WBFS partions for block errors. By default
 errors in the 'free blocks table' will be fixed. See command CHECK for details.

 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.
    WBFS INVALID        : An invalid WBFS found (WBFS with errors)


-------------------------------------------------------------------------------

 This command 'SETTITLE' may change the title of discs. It can change the
 information in the WBFS inode or the information in the ISO header or both
 (the default).

 The alternative command 'RENAME' can also change the ID of discs.

 The syntax of a sub command is: id6=new_title
    'id6' is the ID of the disc to change. If using '+' all discs are changed.
    The 'new_title' is the new title of the disc.

 Processing the new title:

    The title string is parsed for escape sequences beginning with the escape
    character '%'. The accepted format is:

        '%cX'  or  '%mcX'  or  '%n-mcX'

    'n' is the number of skipped characters of the field.

    'm' is the zero based index of the last copied character.

    'c' is an optional character. If c is 'u' then the source will be
        converted to uppercase and if c is 'l' to lower case.

    'X' selects the source and is one of:

        'i' : the (new) ID6
        'I' : the (new) ID6
        'j' : The previous ID stored in the WBFS inode.
        'J' : The previous ID stored in the ISO header.

        'n' : The previous disc title stored in the WBFS inode.
        'N' : The previous disc title stored in the ISO ehader.

        't' : The title from the title database based on the new ID or, if not
              changed, on the ID of the WBFS inode. If no title found the disc
              name stored in the WBFS inode is used.
        'T' : Same as 't'
        'p' : The title from the title database based on the previous ID stored
              in the WBFS inode. If no title found the disc name stored in the
              WBFS inode is used.
        'P' : The title from the title database based on the previous ID stored
              in the ISO header. If no title found the disc name stored in the
              ISO header is used.

        If the object to change is not a WBFS then the ISO data is used instead
        of the WBFS inode data ('j', 'n', and 'p' conversions).

    To use the '%' sign itself just type '%%'.

    Instead of '%' an alternative escape character can be used. It is defined
    by the option --esc. This makes live easier if using the cygwin version
    together with the windows shell 'cmd'. Define the environment variables
    'WIT_OPT' and/or 'WWT_OPT' for a new default definition.


-------------------------------------------------------------------------------

 The SPACE command makes a quick search for WBFS partitions: it scans only the
 WBFS-Header. The three options --all, --auto and --part decides where partitions
 will be searched (see section "Options in detail: partitions" for details).

 If at least one parameter ('wbfs_partition') is given ther option --all well be
 enabled and all names are insterted into the partition list like --auto.
 This enables an easy lookup like 'wwt find *.wbfs'.

 The SPACE/DF command prints:
    size  : file size in MiB.
    used  : space used by discs in MiB.
    used% : space used by discs in percent.
    free  : free space for discs in MiB.
    discs : number of wii discs / max number of discs
    file  : the given path name of the file.

 With option --long the real path instead aa the given filename is printed.
 The option --no-header suppress the output of header and footer.

 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

COMMAND: SYNC  iso_image_path...

'SYNC' is the same as 'ADD --snyc'. The command 'SNYC' does not accept the
options --update, --overwrite and --sync.

See command 'ADD' for options and details.


-------------------------------------------------------------------------------

 The command 'TITLES' builts the title data base and prints the result to
 stdout. The handling of the additional files works like the --title option.
 The section "Processing title db" explains the options in detail.


 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.


-------------------------------------------------------------------------------

 The TOUCH command changes the time stamps in rhe WBFS inodes of all discs
 identified by ID6 from all given WBFS partitions. The options --all, --auto
 and --part decides which partitions will be modified (see section "Options
 in detail: partitions" for details).

 Each parameter is scanned for an ID6. Possible formats are:
    '*' | '+'
    ID6
    ID6=name
    name [ID6]
    ID6 anything
 A single '*' (must be escaped by shells) or '+' means 'all'. A 'name' part
 will be ignored. Please read section "Processing ID6 parameters" for details.

 The option --ignore suppresses error messages about not found disc images.

 If the --quiet option is set only error messages will be printed.
 If the --verbose option is set run time claculations will be made too.

 If the --test option is set the programm does nothing, neither copying nor
 removing. Instead it will print some 'WOULD ...' messages.
 If the --test option is set two or more times then only a normalized ID6
 list is printed. For each ID6 one line is printed. If a destination
 filename is known 'ID=name' is printed, else 'ID6' alone.

 If the option --no-free is set then the disc is only makred as removed. The
 allocated blocks are not freed. Aufter using --no-free you should use the
 command CHECK with --rapair=fbt to repair the free blocks table.

 The options --itime, --mtime, --ctime, --atime decides which time stamp is
 modified. All 4 options can be combined. If none of these options is set
 then all 4 time stamps are modified.

 The time stamps are set to the current time (beginning of command touch).
 With the option --set-time=time an other date can be set. The format of
 'time' is one of the following (in terms of function strptime()):

    "%Y-%m-%d %H:%M:%S"
    "%Y-%m-%d %H:%M"
    "%Y-%m-%d %H%M%S"
    "%Y-%m-%d %H%M"
    "%Y-%m-%d %H"
    "%Y-%m-%d"
    "%Y%m%d %H%M%S"
    "%Y%m%d %H%M"
    "%Y%m%d %H"
    "%Y%m%d"
    "%s"

 Before modifying the WBFS a check (see CHECK) is done. If there are any
 problematic errors detected the 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.


 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  : 2 to 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 an ISO image or a WBFS.

-------------------------------------------------------------------------------

 The SPACE command makes a quick search for WBFS partitions: it scans only the
 WBFS-Header. The three options --all, --auto and --part decides where partitions
 will be searched (see section "Options in detail: partitions" for details).

 If at least one parameter ('wbfs_partition') is given ther option --all well be
 enabled and all names are insterted into the partition list like --auto.
 This enables an easy lookup like 'wwt find *.wbfs'.

 The SPACE/DF command prints:
    size  : file size in MiB.
    used  : space used by discs in MiB.
    used% : space used by discs in percent.
    free  : free space for discs in MiB.
    discs : number of wii discs / max number of discs
    file  : the given path name of the file.

 With option --long the real path instead aa the given filename is printed.
 The option --no-header suppress the output of header and footer.

 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

 The command TRUNCATE truncates WBFS to a minmal size. This is done by
 calculating the last used block within th WBFS. The WBFS is still valid
 and all modification may be done.

 Before modifying the WBFS a check (see CHECK) is done. If there are any
 problematic errors detected the 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.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.
    NO WBFS FOUND       : no WBFS partition found.
    TO MUCH WBFS FOUND  : 2 to more no WBFS partition found but --all missed.


-------------------------------------------------------------------------------

'UPDATE' is the same as 'ADD --update'. The command 'UPDATE' does not accept
the options --update and --overwrite.

See command 'ADD' for options and details.


-------------------------------------------------------------------------------


-------------------------------------------------------------------------------

 The command VERSION prints out the program version to standard out (stdout)
 and exit with status 0 (OK).

 The ouput line looks like:

 With option --sections the output is printed in a machine readable format:
    [version]
    prog=wwt
    name=Wiimms WBFS Tool
    version=3.05a
    beta=0
    revision=8638
    system=linux
    posix_c_source=200809L
    endian=1234 little
    have_stattime_nsec=1
    author=Dirk Clemens
    date=2024-07-14
    url=https://wit.wiimm.de/wwt
    


 Usual ERROR/EXIT CODES:

    0 == OK : all done without errors.


*******************************************************************************
*******                     Processing partitions                       *******
*******************************************************************************

-A --all          Use all WBFS partitions found.
-a --auto         Search for WBFS partitions using /proc/partitions.
-p --part  part   File of primary WBFS partition. Multiple usage allowed.
-p --part  @file  Special case: read partition list from 'file' ('-'=stdin).

These 3 options defines how to search for WBFS partitions.
The program generates an internal partition list. This partition list is
filled by --part and --auto. --part may be set multiple times.

Partitions set with the --part option must be existent, readable and valid WBFS
partitions (exceptions explained in the command documentation). Partitions set
with --auto are only used, if the partition is readable and the WBFS magic is
found. If more than one partition is defined by --part then --all is set.

If using the special case '--part @file' each line of the given file is one
partition. Each line may terminate with LF or CR+LF. Handling of '@' is
*not* recurse. The special filename '-' means: read from standard input (stdin).
This nice feature enables shell commands like: "wwt df -p@<(ls *.wbfs)".

The program terminates with an error if not exactly one valid WBFS partition is
found. When using --all at least one partition must be found.

If neither the option --part nor --auto is set then the environment variable
'WWT_WBFS' is searched. It contains a semicolon separated list of filenames.
If one ore more of this files is a valid WBFS partition it is silently added
to the partition list and the option --all is set.

If neither the option --part nor --auto is set, but option --all, than
option --auto is set automatically.


///////////////////////////////////////////////////////////////////////////////
///////////////                Processing ISO files             ///////////////
///////////////////////////////////////////////////////////////////////////////

Commands like "wwt ADD" or "wit COPY" uses ISO files as input. They accept
plain ISO files and ISO files in WDF, CISO and WBFS containers and FST
directories. In detail:

 /path/to/PLAIN_ISO:
    A PLAIN ISO file is a 1:1 copy of a Wii disc, may be scrubbed. It is not
    compressed and not part of any container. The standard extension is ".iso".

 /path/to/WDF_ISO:
    This is an ISO packed in a WDF container. WDF container may be used for
    any files and not only for ISO images. The standard extension is ".wdf".

 /path/to/CISO:
    This is an ISO packed in a CISO container. CISO container may be used for
    any files and not only for ISO images. The standard extensions are
    ".ciso" (default) and ".wbi".

 /path/to/WBFS_FILE
    An WBFS file/device is also accepted like a list of ISO files. The standard
    extension for WBFS files is ".wbfs".

 /path/to/WBFS_FILE/SELECTOR
    This is a special construct. The ISO image of the WBFS_FILE selected
    by SELECTOR is used as source. The selector may be one of:

     - 'ABCDEF' : ID6 of a disc (exact 6 characters)

     - index    : The zero based index of the disc. The range goes from zero
                  up to the number of discs in the WBFS minus 1.
                  (decimal number, but not 6 digits)

     - '#' slot : The decimal slot number within the WBFS. The range goes from
                  zero up to the maximal number of possible discs in the WBFS
                  minus 1.

    Examples:
      .../a.wbfs/rmcp01 : use "Mario Kart" from 'a.wbfs' as source.
      .../a.wbfs/5      : use the image with index #5 from 'a.wbfs' as source.
      .../a.wbfs/#5     : use the image at slot #5 from 'a.wbfs' as source.

 /path/do/FST_directory
    If the path is a directory and the directory contains a valid FST (File
    SysTem) structure then the directory structure is used to build an internal
    virtual ISO image. Most commands can use this virtual ISO image like a
    real image.


When writing ISO files the option --wdf, --iso, --ciso, --wbfs and --fst
control the output format. If writing a WBFS file this WBFS is truncated and
contains exactly one ISO image. The default file name of this WBFS is
'<ID6>.wbfs'. If none of --wdf, --iso, --ciso, --wbfs or --fst is set, the
destination filename will be analyzed. If the extension (ignoring case) is
".wdf", ".iso", ".ciso", ".wbi" (an alternative for ".ciso") or ".wbfs",
the specific output format is used. The default is WDF if all other fails.



*******************************************************************************
*******                    Processing ID6 parameters                    *******
*******************************************************************************

Discs in a WBFS partition are addressed by its ID6. Therfor commands like
EXTRACT and REMOVE needs as parameters an ID6 tag. And EXTRACT needs also
the name of the destination file. This section describes the processing
of ID6 parameters.

First all control characters (ASCII <32) will be replaced by a space. Spaces
at the beginning and a the end are removed. Multiples spaces will be replaced
by a single space.

In the second step each parameter will be processed by the following rules.
If one rule matches the processing terminates. ID6 are words that contains
exactly 6 characters in the range a-z, A-Z and 0-9. All other characters are
word separators. ID6 is converted into upper case.

The rules as overview:
    '*' | '+'
    ID4
    ID6
    ID6 = name
    name [ID6]
    ID6 anything


1.) '*' | '+'

    Both characters has the same meaning: Use all ID6 will be found on the
    given WFS partitions. The parameter will be replaced by the complete ID6
    list. A destination filename is not defined.

	Only the first occurrence will be processed. All other are ignord.

    Note: '*' is the natural 'all' placeholder but must be escaped in most
          shells. Therefor the additional '+' is possible.

2.) ID4

    If the parameter contains exactly one ID4 and nothing else the ID4 is
    used. Only for some commands/options a pure ID4 is allowd.

3.) ID6

    If the parameter contains exactly one ID6 and nothing else the ID6 is
    used. A destination filename is not defined.

4.) ID6 = name

    Use this format to set an ID6 and an destination filename. Blanks before
    and behind '=' are ignored. The name is used as the destination filename.

5.) name [ID6]

    The line is searched for an ID6 which is directly included in square
    bracktes. If more than 1 '[ID6]' is found the last one will be used.
    The whole parameter is used as the destination filename.

6.) ID6 anything

    This is the table support. The ID6 is taken and the remaining is ignored.
    A destination filename is not defined.

If the option --unique is supported and set then repeated parameters with the
same ID6 are eliminated. The last non empty destination filename is used.

If a destination filename is needed but none is set than the a name from the
title database or an internal name of the game will be used. Before creating
an ISO image the destination filename is post processed to eliminate unusal
characters. Only single spaces, A-Z, a-z, 0-9 and _+-='"$%&,.!()[]{}<> are
allowed.


*******************************************************************************
*******             Processing include and exclude options              *******
*******************************************************************************

The user may define ID inclusion and exclusion lists. Each element represents
an ID4 or an ID6. Discs with an ID in the exclusion list are ignored (not
added, extracted, removed or listed). If --include or --include-path is used,
only discs in the include list are processed.

The include list is controlled by the to options --include and --include-path
and the exclude list by the options --exclude and --exclude-path. All four
options can be used multiple times. The exclude list ha a higher priority
as the include list.

 -n --include id     Include oly discs with given ID4 or ID6 from operation.
 -n --include @file  Read include list from file.

 -N --include-path file_or_dir
                     ISO file or base of directory tree -> scan their ID6

 -x --exclude id     Exclude discs with given ID4 or ID6 from operation.
 -x --exclude @file  Read exclude list from file.

 -X --exclude-path file_or_dir
                     ISO file or base of directory tree -> scan their ID6

The parameters of --include and --exclude are scanned for ID6. Th section
"Processing ID6 parameters" describes this scanning in detail.

The parameter of --include-path and --exclude-path is a filename or a
directory name. The given file or each file of the directory tree (recurse,
max depth=15) are scanned. Subdirectories beginning with a dot ('.') are
ignored. If a file exists and is an ISO file the ID6 is extracted and inserted
into the include or exclude data base.

Example:

 You want to make a backup from all new discs of 2 USB drives. The new
 backups should be stored info the sub directory 'new-backup'. The existing
 backups are stored in 'old-backup'. The file names of the old backups does
 not matter:

 # wwt extract -aA --dest new-backup --exclude-path old-backup

The command 'EXCLUDE' use the options --exclude and --exclude-path to builtd
the exclude data base and prints the result to stdout.


*******************************************************************************
*******                      Processing title db                        *******
*******************************************************************************

Title files without path specification are search in up to 4 directories:
  1.) In the program path.
  2.) If the program end with "/bin/" in "<PROGRAM_PATH>/../share/wit/".
  3.) In the directory "/usr/local/share/wit/"
  4.) In the current working directory "./"
If you want to search only in the current working directory prefix the file
name with './'. If setting option --verbose at least 4 times (e.g. -vvvv)
the search paths will be logged.

The titles are loaded first time they needed. At first the following three
files are searched in the search path:
  - titles.txt (comes with the distribution)
  - titles-<LANG>.txt (see below)
  - titles.local.txt (for local specificatons)
After that all files specified by the --titles options are scanned.

The idea: The file "titles.txt" is the main title database. It is a copy from
http://wiitdb.com/titles.txt. The file "titles-<LANG>.txt" may contain
language specific definitions. "<LANG>" are the first lower case letters of
the environment variable "LC_CTYPE". The file "titles.local.txt" may contain
local definitions for the user.

The option -T / --titles in detail:

  --titles=0 .. --titles=9
     Set the title mode to a value between 0 and 9.
      0: disable title lookup.
      1: Use titles instead of real disc names. (deault)
      2..9: reserved.

  --titles=/
     Remove all previous --title definitions an do not load the default
     title files.

  --titles=@file
     Use the given file as a list of filenames. Each non empty line is
     interpreted as a filename.

  --titles=@-
     Read standard input (stdin). Each non empty line is interpreted as
     a filename.

  --titles=-
     Read standard input (stdin) and scan it for titles.

  --titles=file
     This is a filename without '/': Read the given file and scan it for
     titles. The file is searched in the search path described above.

  --titles=path/file
     Read the given file and scan it for titles.

If setting option --verbose at least 3 times (e.g. -vvv) all successfull
loaded titles files will be logged. If setting --verbose at least 4 times
the search paths and all searched title files will be logged.

Each line of each title file is scanned for title definitions:
    ID4 = name
    ID6 = name

The title database is build with both ID-types. A later file overides the
settings of all previous files: If an ID4 is found, all ID4 and ID6
definitions of all previous files are removed. If an ID6 is found, only
the previous ID6 definition is removed.

For each database lookup first an ID6 entry is searched. Only if this fails
an ID4 entry is searched.

The titles are expected in UTF-8 coding. Non UTF-8 characters are converted
into UTF-8. If the options --no-utf-8 is set than the title database is
converted into ANSI and all output will also be printed in ANSI.

The command 'TITLES' builts the title data base and prints the result to
stdout.


*******************************************************************************
*******                    Processing split options                     *******
*******************************************************************************

Output files may be splittet into multiple files. The options --split and
--split-size controls the output splitting:

  -z --split            Enable output file splitting, default size = 4 gb.
                        4 gb means 4.000.000.000 bytes (4 billion bytes).
                        The default size for a WBFS is different. It is
                        4GiB-32KiB = 0xffff8000 = 4.294.934.528 bytes.

  -Z --split-size size  Enable output file splitting and set split size.
                        See section "Processing size options" for detailed
                        infos about the 'size' argument.

A new file is created every time when the previous one reached the split size.
Input split files are automatically detected. Only the last file of the input
split file may grow if opened in modify mode.

The split size always rounded down to a multiply of 512 (0x200), the hd sector
size. For a WBFS it is rounde down to a multiply of 32 KiB (32768, 0x8000),
the WII ISO sector size.

There are two naming schemas for the splitted files:

WBFS files are named like (defined by oggzee):
    - name.wbfs
    - name.wbf1
    - name.wbf2
      ...
    - name.wbf9
    - name.wbf10
      ...

All other files are named like:
    - name.ext
    - name.ext.1
    - name.ext.2
      ...
    - name.ext.9
    - name.ext.10
      ...

The WIT tools supports splitted WDF files *not* following the rules for
splitted WDF files. All files are splitted hard by breaking the files into
peaces. This is done by the file layer so that other layer including the WDF
layer don't see the split.

These are the rules for automatic detection of split files. The automatic
detection works only for plain files but not for other files types like
block devices or pipes:

 WBFS file:
    The last character of the filename is replaced by '1'. If a file with
    this new filename is available, the split file support is enabled.

 WDF file:
    The WDF header is read. If the current WDF files is to short and a file
    with same filename plus '.1' exists, the split file support is enabled.

 ISO file:
    If the file is smaller than 4 GiB and a file with same filename plus '.1'
    exists then then split file support is enabled.


*******************************************************************************
*******                    Processing size options                      *******
*******************************************************************************

The different programs using different options to setup size values. These
options are --size, --split-size, --hss and --wss. The processing of the
arguments are identical for all size options.

The argument syntax is: term [ sign term ]... [sign]
with term := float [factor]

 'float' is any C like floating point number like '12', '1.2' or '1e5'.
 'sign' is either the character '+' or the character '-'.

 'factor' is one of the following characters:

    'c' : char, numeric factor = 1
    'b' : byte, numeric factor = 1

    'k' : kilo, numeric factor = 1 kB = 1000
    'm' : mega, numeric factor = 1 MB = 1000*1000
    'g' : giga, numeric factor = 1 GB = 1000*1000*1000
    't' : tera, numeric factor = 1 TB = 1000*1000*1000*1000
    'p' : peta, numeric factor = 1 PB = 1000*1000*1000*1000*1000
    'e' : exa,  numeric factor = 1 EB = 1000*1000*1000*1000*1000*1000

    'K' : kilo, numeric factor = 1 KiB = 1024
    'M' : mega, numeric factor = 1 MiB = 1024*1024
    'G' : giga, numeric factor = 1 GiB = 1024*1024*1024
    'T' : tera, numeric factor = 1 TiB = 1024*1024*1024*1024
    'P' : peta, numeric factor = 1 PiB = 1024*1024*1024*1024*1024
    'E' : exa,  numeric factor = 1 EiB = 1024*1024*1024*1024*1024*1024

    'u' | 'U' : size of a GameCube disc        = 1 459 978 240
    'w' | 'W' : size of a singe layer Wii disc = 4 699 979 776

  Without 'factor' a default factor is used. This default factor is different
  for the first term and for the other terms. The default factors depends on
  the used option.

The terms are added together. If there is at the very end of the term 1 sign
it wil be interpreted as '-1' or '+1' (using the default factor for other terms).

Option --size
    Default factor for first term:     1G
    Default factors for other terms:   1
    Minimal value:                    10m

Option --split-size
    Default factor for first term:     1G
    Default factors for other terms: 512
    Value must be multiples of:      512
    Minimal value:                   100m

Option --hss
    Default factor for all terms:      1
    Value must be power of:            2
    Minimal value:                   512

Option --wss
    Default factor for all terms:      1
    Value must be power of:            2
    Minimal value:                  1024

Examples:
    --split-size 2g     -> split at 2.000.000.000 bytes.
    --split-size 1g     -> split at 1.000.000.000 bytes.
    --split-size 1G     -> split at 1.073.741.824 bytes = 1 GiB.
    --split-size 0.5g   -> split at   500.000.000 bytes.
    --split-size 2G-1K  -> split at 2 GiB - 1 KiB.
    --split-size 2G-1   -> split at 2 GiB - 512
    --split-size 2-1    -> split at 2 GiB - 512
    --split-size 2-     -> split at 2 GiB - 512
    -Z2-                -> split at 2 GiB - 512


*******************************************************************************
*******                      Some options in detail                     *******
*******************************************************************************

The option --sort defines the sort mode for output lists.

  Syntax: --sort sort_mode | -S sort_mode

'sort_mode' is a comma separated list of the following keywords:

    -  | NONE    : Do not sort

         ID      : Sort by id
    T  | TITLE   : Sort by title taken from title db
    N  | NAME    : Sort by name of disc
    F  | FILE    : Sort by file name
    SZ | SIZE    : Sort by size
    OF | OFFSET  : Sort by offset (or index)
    R  | REGION  : Sort by region
         WBFS    : Sort by wbfs file name
         NPART   : Sort by number of partitions

    IT | ITIME   : Sort by itime (insertion time)
    MT | MTIME   : Sort by mtime (last modification time)
    CT | CTIME   : Sort by ctime (last status change time)
    AT | ATIME   : Sort by atime (last access time)
    TI | TIME    : Sort by itime|mtime|atime|atime, decided by the time options.
    D  | DATE    : Alternative keyword for 'TIME'

      DEFAULT    : Use the default sort method for that output

      ASCENDING  : Sort in ascending order.
      DESCENDING : Sort in descending order (reverse).
      REVERSE    : Alternative keyword for 'DESCEND'.

The latest keyword supersedes the previous one of the same group.
'NONE' resets all. Abbreviations are allowed as long as they are unique.


*******************************************************************************
*******                   Hidden options (for testing)                  *******
*******************************************************************************

There are some hidden options implemented for testing:

 --io value

    wwt and the other tools can handle files via open() (file mode) and via
    fopen() (stream mode). The option --io=value allows to control the method.
    Bit #0 is for opening WBFS and Bit #1 is for openening ISO images.

    --io=0 : WBFS=open()  ISO=open()  **default**
    --io=1 : WBFS=fopen() ISO=open()
    --io=2 : WBFS=open()  ISO=fopen()
    --io=3 : WBFS=fopen() ISO=fopen()


*******************************************************************************
*******                      Environment variables                      *******
*******************************************************************************

The user can define environment variables as additional way to submit options
to the tool. All options are accepted and used as default. 

See https://wit.wiimm.de/info/environ.html for details.


*******************************************************************************
*******                            Signals                              *******
*******************************************************************************

The WIT tools will handle the following signals:

 INT or TERM

    If catched first time the tool will finish after current job.
    If catched second time the tool will finish immediately with cleanup.
    If catched third time the tool will finish immediately without cleanup.

 USR1, USR2

    USR1 will decrease and USR2 increase the verbose level.
    The effect is delayed until beginning the next job.


*******************************************************************************
*******                              END                                *******
*******************************************************************************
