summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/tools
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2024-02-10 06:10:19 +1100
committer Vas Crabb <vas@vastheman.com>2024-02-10 06:21:05 +1100
commit5731492874513cfcd204aae6735cf70db4d6b6e0 (patch)
treea6c3bcb208780a759a2681eabea9a4c0cde51172 /docs/source/tools
parentd88e12714307ff5a9dc02d0e849ed84d3c4b4f93 (diff)
tools/chdman.cpp: Fixed numerous issues, including:
Support input start/size options for createdvd. Fixed not reporting an error on unrecognised command line options. Fixed --fix/-f option for verify command not working. Report an error when conflicting options are supplied (e.g. hard disk template and C/H/S geometry, or input start offset in both bytes and hunks). Previously the results would be unpredictable. Detect more invalid combinations of options, and detect when output unit size or hunk size doesn't match parent. Changed order of processing options for createhd so using a template cannot not inadvertently result in an invalid combination of sector size and hunk size. Don't require an explicit unit size for createraw if an output parent CHD file is supplied. Fixed an object leak in createcd.
Diffstat (limited to 'docs/source/tools')
-rw-r--r--docs/source/tools/chdman.rst109
1 files changed, 86 insertions, 23 deletions
diff --git a/docs/source/tools/chdman.rst b/docs/source/tools/chdman.rst
index f23a21cddf5..04612642764 100644
--- a/docs/source/tools/chdman.rst
+++ b/docs/source/tools/chdman.rst
@@ -27,6 +27,25 @@ used by multiple commands:
most commands that operate on CHD format input files. This option must be
used if the input file is a *delta CHD*, storing only the hunks that differ
from its parent CHD,
+--inputstartbyte <offset> / -isb <offset>
+ Specify the offset to the data in the input file in bytes. This is useful
+ for creating CHD format files from input files that contain a header before
+ the start of the data, or for extracting partial content from a CHD format
+ file. May not be specified in combination with the
+ ``--inputstarthunk``/``-ish`` option.
+--inputstarthunk <offset> / -ish <offset>
+ Specify the offset to the data in the input file in hunks. May not be
+ specified in combination with the ``--inputstartbyte``/``-isb`` option.
+--inputbytes <length> / -ib <length>
+ Specify the amount of input data to use in bytes, starting from the offset
+ to the data in the input file. This is useful for creating CHD format files
+ from input files that contain additional content after the data, or for
+ extracting partial content from a CHD format file. May not be specified in
+ combination with the ``--inputhunks``/``-ih`` option.
+--inputhunks <length> / -ih <length>
+ Specify the amount of input data to use in hunks, starting from the offset
+ to the data in the input file. May not be specified in combination with the
+ ``--inputbytes``/``-ib`` option.
--output <file> / -o <file>
Specify the output file name. This option is required for commands that
produce output files. The output file formats supported depend on the
@@ -86,13 +105,19 @@ verify
~~~~~~
Verify the integrity of a CHD format file. The input file must be a read-only
-CHD format file (the integrity of writable CHD files cannot be verified).
+CHD format file (the integrity of writable CHD files cannot be verified). Note
+that this command modifies its input file if the ``--fix``/``-f`` option is
+specified.
Common options supported:
* ``--input <file>`` / ``-i <file>`` (required)
* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+Additional options:
+
+* ``--fix`` / ``-f``
+
createraw
~~~~~~~~~
@@ -101,20 +126,34 @@ Create a CHD format file from a raw media image.
Common options supported:
* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
* ``--output <file>`` / ``-o <file>`` (required)
* ``--outputparent <chdfile>`` / ``-op <chdfile>``
* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
-* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--hunksize <bytes>`` / ``-hs <bytes>``
* ``--force`` / ``-f``
* ``--numprocessors <count>`` / ``-np <count>``
Additional options:
-* ``--unitsize <bytes>`` / ``-us <bytes>`` (required)
-* ``--inputstartbyte <offset>`` / ``-isb <offset>``
-* ``--inputstarthunk <offset>`` / ``-ish <offset>``
-* ``--inputbytes <length>`` / ``-ib <length>``
-* ``--inputhunks <length>`` / ``-ih <length>``
+--unitsize <bytes> / -us <bytes> (required)
+ The unit size for the output CHD file in bytes. This is the smallest unit
+ of data that can be addressed within the CHD file. It should match the
+ sector size or page size of the source media. The hunk size must be a whole
+ multiple of the unit size. The unit size must be specified if no parent CHD
+ file for the output is supplied. If a parent CHD file for the output is
+ supplied, the unit size must match the unit size of the parent CHD file.
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be:
+
+* The hunk size of the parent CHD file if a parent CHD file for the output is
+ supplied.
+* The smallest whole multiple of the unit size not larger than 4 KiB if the unit
+ size is not larger than 4 KiB (4096 bytes).
+* The unit size if it is larger than 4 KiB (4096 bytes).
If the ``--compression`` or ``-c`` option is not supplied, it defaults to
``lzma,zlib,huff,flac``.
@@ -126,7 +165,11 @@ Create a CHD format hard disk image file.
Common options supported:
-* ``--input <file>`` / ``-i <file>`` (required)
+* ``--input <file>`` / ``-i <file>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
* ``--output <file>`` / ``-o <file>`` (required)
* ``--outputparent <chdfile>`` / ``-op <chdfile>``
* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
@@ -140,13 +183,23 @@ Additional options:
* ``--size <bytes>`` / ``-s <bytes>``
* ``--chs <cylinders>,<heads>,<sectors>`` / ``-chs <cylinders>,<heads>,<sectors>``
* ``--template <template>`` / ``-tp <template>``
-* ``--inputstartbyte <offset>`` / ``-isb <offset>``
-* ``--inputstarthunk <offset>`` / ``-ish <offset>``
-* ``--inputbytes <length>`` / ``-ib <length>``
-* ``--inputhunks <length>`` / ``-ih <length>``
+
+Creates a blank (zero-filled) hard disk image if no input file is supplied. The
+input start/length (``--inputstartbyte``/``-isb``,
+``--inputstarthunk``/``-ish``, ``--inputbytes``/``-ib`` and
+``--inputhunks``/``-ih`` options) cannot be used if no input file is supplied.
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be:
+
+* The hunk size of the parent CHD file if a parent CHD file for the output is
+ supplied.
+* The smallest whole multiple of the sector size not larger than 4 KiB if the
+ sector size is not larger than 4 KiB (4096 bytes).
+* The sector size if it is larger than 4 KiB (4096 bytes).
If the ``--compression`` or ``-c`` option is not supplied, it defaults to
-``lzma,zlib,huff,flac``.
+``lzma,zlib,huff,flac`` if an input file is supplied, or ``none`` if no input
+file is supplied.
createcd
~~~~~~~~
@@ -163,6 +216,10 @@ Common options supported:
* ``--force`` / ``-f``
* ``--numprocessors <count>`` / ``-np <count>``
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be
+the hunk size of the parent CHD if a parent CHD file for the output is supplied,
+or eight sectors per hunk (18,816 bytes) otherwise.
+
If the ``--compression`` or ``-c`` option is not supplied, it defaults to
``cdlz,cdzl,cdfl``.
@@ -174,6 +231,10 @@ Create a CHD format DVD-ROM image file.
Common options supported:
* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
* ``--output <file>`` / ``-o <file>`` (required)
* ``--outputparent <chdfile>`` / ``-op <chdfile>``
* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
@@ -181,6 +242,10 @@ Common options supported:
* ``--force`` / ``-f``
* ``--numprocessors <count>`` / ``-np <count>``
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be
+the hunk size of the parent CHD if a parent CHD file for the output is supplied,
+or two sectors per hunk (4096 bytes) otherwise.
+
If the ``--compression`` or ``-c`` option is not supplied, it defaults to
``lzma,zlib,huff,flac``.
@@ -216,15 +281,12 @@ Common options supported:
* ``--input <file>`` / ``-i <file>`` (required)
* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
-* ``--output <file>`` / ``-o <file>`` (required)
-* ``--force`` / ``-f``
-
-Additional options:
-
* ``--inputstartbyte <offset>`` / ``-isb <offset>``
* ``--inputstarthunk <offset>`` / ``-ish <offset>``
* ``--inputbytes <length>`` / ``-ib <length>``
* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
extracthd
~~~~~~~~~
@@ -235,15 +297,12 @@ Common options supported:
* ``--input <file>`` / ``-i <file>`` (required)
* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
-* ``--output <file>`` / ``-o <file>`` (required)
-* ``--force`` / ``-f``
-
-Additional options:
-
* ``--inputstartbyte <offset>`` / ``-isb <offset>``
* ``--inputstarthunk <offset>`` / ``-ish <offset>``
* ``--inputbytes <length>`` / ``-ib <length>``
* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
extractcd
~~~~~~~~~
@@ -270,6 +329,10 @@ Common options supported:
* ``--input <file>`` / ``-i <file>`` (required)
* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
* ``--output <file>`` / ``-o <file>`` (required)
* ``--force`` / ``-f``