GNU ddrescue Manual
*******************

This manual is for GNU ddrescue (version 1.24, 24 February 2019).

   Copyright (C) 2004-2019 Antonio Diaz Diaz.

   This manual is free documentation: you have unlimited permission to
copy, distribute and modify it.

1 Introduction
**************

GNU ddrescue is a data recovery tool. It copies data from one file or
block device (hard disc, cdrom, etc) to another, trying to rescue the
good parts first in case of read errors.

   The basic operation of ddrescue is fully automatic. That is, you
don't have to wait for an error, stop the program, restart it from a
new position, etc.

   If you use the mapfile feature of ddrescue, the data are rescued very
efficiently, (only the needed blocks are read). Also you may interrupt
the rescue at any time and resume it later at the same point. The
mapfile is an essential part of ddrescue's effectiveness. Use it unless
you know what you are doing.

   Ddrescue does not write zeros to the output when it finds bad
sectors in the input, and does not truncate the output file if not
asked to. So, every time you run it on the same output file, it tries
to fill in the gaps without wiping out the data already rescued.

   Automatic merging of backups: If you have two or more damaged copies
of a file, cdrom, etc, and run ddrescue on all of them, one at a time,
with the same output file, you will probably obtain a complete and
error-free file.  This is so because the probability of having the same
area damaged in all copies is low (if the errors are randomly located).
Using the mapfile, only the needed blocks are read from the second and
successive copies.

   Ddrescue recommends lzip for compression of backups because the lzip
format is designed for long-term archiving and provides data recovery
capabilities which nicely complement those of ddrescue. (Ddrescue fills
unreadable sectors with data from other copies, while lziprecover
corrects corrupt sectors with data from other copies). If the cause of
file corruption is damaged media, the combination
ddrescue + lziprecover is the best option for recovering data from
multiple damaged copies. See lziprecover-example.

   Because ddrescue needs to read and write at random places, it only
works on seekable (random access) input and output files.

   If your system supports it, ddrescue can use direct disc access to
read the input file, bypassing the kernel cache.

   Ddrescue also features a 'fill mode' able to selectively overwrite
parts of the output file, which has a number of interesting uses like
wiping data, marking bad areas or even, in some cases, "repair" damaged
sectors.

   One of the great strengths of ddrescue is that it is
interface-agnostic, and so can be used for any kind of device supported
by your kernel (ATA, SATA, SCSI, old MFM drives, floppy discs, or even
flash media cards like SD).

2 Basic concepts
****************

Block
     Any amount of data. A block is described by its starting position
     and its size. The starting position (or beginning position) is the
     lowest position in the block. The end of the block is its starting
     position plus its size.

Cluster
     Group of consecutive sectors read or written in one go.

Device
     Piece of hardware containing data. Hard disc drives, cdrom drives,
     USB pendrives, are devices. /dev/hda, /dev/sdb, are device names.

File
     Files are named units of data which are stored by the operating
     system for you to retrieve later by name. Devices and partitions
     are accessed by means of their associated file names.

Partition
     Every part in which a device is divided. A partition normally
     contains a file system. /dev/hda1, /dev/sdb3, are partition names.

Recoverable formats
     As ddrescue uses standard library functions to read data from the
     device being rescued, only mountable device formats can be rescued
     with ddrescue. CD-ROMs and DVDs can be rescued, "compact disc
     digital audio" CDs can't, "video CDs"[1] maybe.
     [1] http://en.wikipedia.org/wiki/Video_CD

Rescue domain
     Block or set of blocks to be acted upon (rescued, listed, etc).
     You may define it with the options '--input-position', '--size' and
     '--domain-mapfile'. The rescue domain defaults to the whole input
     file or mapfile. If ddrescue can't determine the size of the input
     file, the rescue domain defaults to the maximum size of a block
     (at least 2^63 - 1 bytes, or 8 EiB minus 1 byte).

     Ddrescue will never try to read any data outside of the rescue
     domain except when unaligned direct disc access is requested
     (see Direct disc access). If it does, please, report it as a
     bug.

     The amount of data rescued, number of bad areas, etc, shown by
     ddrescue may vary or even become zero if you limit the rescue
     domain. Don't worry, they have not disappeared; they are simply
     out of the specified rescue domain.

Sector
     Hardware block. Smallest accessible amount of data on a device.

3 Using ddrescue safely
***********************

Ddrescue is like any other power tool. You need to understand what it
does, and you need to understand some things about the machines it does
those things to, in order to use it safely.

   Never try to rescue a r/w mounted partition. The resulting copy may
be useless. It is best that the device or partition to be rescued is not
mounted at all, not even read-only.

   Never try to repair a file system on a drive with I/O errors; you
will probably lose even more data.

   If you use a device or a partition as destination, any data stored
there will be overwritten.

   Some systems may change device names on reboot (e.g. udev enabled
systems). If you reboot, check the device names before restarting
ddrescue.

   If you interrupt the rescue and then reboot, any partially copied
partitions should be hidden before allowing them to be touched by any
operating system that tries to mount and "fix" the partitions it sees.

4 Algorithm
***********

GNU ddrescue is not a derivative of dd, nor is related to dd in any way
except in that both can be used for copying data from one device to
another. The key difference is that ddrescue uses a sophisticated
algorithm to copy data from failing drives causing them as little
additional damage as possible.

   Ddrescue manages efficiently the status of the rescue in progress and
tries to rescue the good parts first, scheduling reads inside bad (or
slow) areas for later. This maximizes the amount of data that can be
finally recovered from a failing drive.

   The standard dd utility can be used to save data from a failing
drive, but it reads the data sequentially, which may wear out the drive
without rescuing anything if the errors are at the beginning of the
drive.

   Other programs read the data sequentially but switch to small size
reads when they find errors. This is a bad idea because it means
spending more time at error areas, damaging the surface, the heads and
the drive mechanics, instead of getting out of them as fast as
possible. This behavior reduces the chances of rescuing the remaining
good data.

   The algorithm of ddrescue is as follows (the user may interrupt the
process at any point, but be aware that a bad drive can block ddrescue
for a long time until the kernel gives up):

   1) Optionally read a mapfile describing the status of a multi-part or
previously interrupted rescue. If no mapfile is specified or is empty or
does not exist, mark all the rescue domain as non-tried.

   2) (First phase; Copying) Copying is done in up to five passes. The
first pass reads the non-tried parts of the input file, marking the
failed blocks as non-trimmed and skipping beyond them. The second pass
delimits the blocks skipped by the first pass. The first two passes also
skip beyond slow areas. The skipped areas are tried later in one or
three additional passes (before trimming). The copying direction is
reversed after each pass until all the rescue domain is tried.

   The third and fourth passes read the blocks skipped due to slow areas
(if any) by the first two passes, in the same direction that each block
was skipped. For each block, passes 2 to 4 skip the rest of the block
after finding the first error in the block. The last pass is a sweeping
pass, with skipping disabled. The purpose of the multiple passes is to
delimit large bad areas fast, recover the most promising areas first,
keep the mapfile small, and produce good starting points for trimming.

   Only non-tried areas are read in large blocks. Trimming, scraping and
retrying are done sector by sector. Each sector is tried at most two
times; the first in this phase as part of a large block read, the second
in one of the phases below as a single sector read.

   3) (Second phase; Trimming) Trimming is done in one pass. For each
non-trimmed block, read forwards one sector at a time from the leading
edge of the block until a bad sector is found. Then read backwards one
sector at a time from the trailing edge of the block until a bad sector
is found. Then mark the bad sectors found (if any) as bad-sector, and
mark the rest of the block as non-scraped without trying to read it. If
any edge is already adjacent to a bad sector, it is considered as
already trimmed and is not trimmed again.

   4) (Third phase; Scraping) Scrape together the data not recovered by
the copying or trimming phases. Scraping is done in one pass. Each
non-scraped block is read forwards, one sector at a time. Any bad
sectors found are marked as bad-sector.

   5) (Fourth phase; Retrying) Optionally try to read again the bad
sectors until the specified number of retry passes is reached. The
direction is reversed after each pass. Every bad sector is tried only
once in each pass. Ddrescue can't know if a bad sector is unrecoverable
or if it will be eventually read after some retries.

   6) Optionally write a mapfile for later use.

   When ddrescue finishes the steps above, any areas marked as
bad-sector will remain untouched in the output file. If the output file
is a regular file created by ddrescue, the areas marked as bad-sector
will contain zeros. If it is a device or a previously existing file,
the areas marked as bad-sector will still contain the data previously
present there.

   The mapfile is periodically saved to disc, as well as when ddrescue
finishes or is interrupted. A backup copy of the mapfile with the
extension '.bak' is also periodically created (if possible). So in case
of a crash you can resume the rescue with little recopying. The default
interval between saves varies from 30 seconds to 5 minutes depending on
mapfile size (larger mapfiles are saved at longer intervals), but may
be overriden.  See --mapfile-interval.

   The same mapfile can be used for multiple commands that copy
different areas of the input file, and for multiple recovery attempts
over different subsets. See this example:

Rescue the most important part of the disc first.
     ddrescue -i0 -s50MiB /dev/sdc hdimage mapfile
     ddrescue -i0 -s1MiB -d -r3 /dev/sdc hdimage mapfile

Then rescue some key disc areas.
     ddrescue -i30GiB -s10GiB /dev/sdc hdimage mapfile
     ddrescue -i230GiB -s5GiB /dev/sdc hdimage mapfile

Now rescue the rest (does not recopy what is already done).
     ddrescue /dev/sdc hdimage mapfile
     ddrescue -d -r3 /dev/sdc hdimage mapfile

5 Meaning of ddrescue's screen output
*************************************

The output of ddrescue looks like this:

     GNU ddrescue 1.24
     Press Ctrl-C to interrupt
     Initial status (read from mapfile)
     rescued: 1665 MB, tried: 0 B, bad-sector: 0 B, bad areas: 0

     Current status
          ipos:    2874 MB, non-trimmed:        0 B,  current rate:  21479 kB/s
          opos:    2874 MB, non-scraped:        0 B,  average rate:  21023 kB/s
     non-tried:   13603 MB,  bad-sector:        0 B,    error rate:       0 B/s
       rescued:    2401 MB,   bad areas:        0,        run time:         35s
     pct rescued:   15.00%, read errors:        0,  remaining time:         10m
      slow reads:        5,        time since last successful read:          0s
     Copying non-tried blocks... Pass 1 (forwards)

   The meaning of each field is as follows:

'ipos'
     Input position. The position in the input file where data are being
     currently read from.

'opos'
     Output position. The position in the output file where data are
     being currently written to.

'non-tried'
     Size of the part of the rescue domain pending to be tried. This is
     the sum of the sizes of all the non-tried blocks.

'rescued'
     Size of the part of the rescue domain already successfully
     recovered.  This is the sum of the sizes of all the finished
     blocks.

'pct rescued'
     Percentage of the rescue domain that has been successfully
     recovered.

'slow reads'
     Number of times that the read rate fell below '--min-read-rate'
     during the first two passes of the copying phase. See
     --min-read-rate.

'tried'
     Size of the part of the rescue domain already tried but not yet
     rescued.  This is the sum of the sizes of all the non-trimmed,
     non-scraped and bad-sector blocks.

'non-trimmed'
     Size of the part of the rescue domain pending to be trimmed. This
     is the sum of the sizes of all the non-trimmed blocks.

'non-scraped'
     Size of the part of the rescue domain pending to be scraped. This
     is the sum of the sizes of all the non-scraped blocks.

'bad-sector'
     Total error size. This is the size of the part of the rescue domain
     formed by known bad sectors. The total error size is the sum of the
     sizes of all the bad-sector blocks. It increases during the
     trimming and scraping phases, and may decrease during the retrying
     phase. A sector is not marked as bad-sector and considered part of
     a bad area until it has been tried individually instead of as part
     of a large block read. Note that as ddrescue retries the
     bad-sector blocks, the good data found may divide them into
     smaller blocks, decreasing the total error size but increasing the
     number of bad areas.

'bad areas'
     Number of separate bad-sector blocks inside the rescue domain.
     Non-trimmed and non-scraped blocks are not considered bad areas.
     See --max-bad-areas.

'read errors'
     Number of failed read attempts. See --max-error-rate.

'current rate'
     The read rate measured during the last second.

'average rate'
     The average read rate measured during the current run.

'error rate'
     The read error rate measured during the last second.

'run time'
     Time elapsed since the beginning of the current run.

'remaining time'
     Estimated remaining time to rescue all the data in the rescue
     domain.  The remaining time is calculated using the average rate
     of the last 30 seconds and does not take into account that some
     parts of the rescue domain may be excluded from the rescue (for
     example with '--no-trim'), or that some areas may be
     unrecoverable. Therefore it may be very imprecise, may vary widely
     during the rescue, and may show a non-zero value at the end of the
     rescue. In particular it may go down to a few seconds at the end
     of the first pass, just to grow to hours or days in the following
     passes. Such is the nature of ddrescue; the good parts are usually
     recovered fast, while the rest may take a long time.

'time since last successful read'
     Time elapsed since the last successful read attempt.

6 Invoking ddrescue
*******************

The format for running ddrescue is:

     ddrescue [OPTIONS] INFILE OUTFILE [MAPFILE]

   INFILE and OUTFILE may be files, devices or partitions.  MAPFILE is
a regular file and must be placed in an existing directory.  If MAPFILE
does not exist, ddrescue will create it.

   Ddrescue tries to create a backup copy of the mapfile, with the name
MAPFILE.bak, every time it is going to overwrite a fsynced MAPFILE.
See --mapfile-interval.

   Always use a mapfile unless you know you won't need it. Without a
mapfile, ddrescue can't resume a rescue, only reinitiate it.

   ddrescue supports the following options:

'-h'
'--help'
     Print an informative help message describing the options and exit.

'-V'
'--version'
     Print the version number of ddrescue on the standard output and
     exit.  This version number should be included in all bug reports.

'-a BYTES'
'--min-read-rate=BYTES'
     Minimum read rate of good non-tried areas, in bytes per second. If
     the read rate falls below this value during the first two passes
     of the copying phase, ddrescue will skip ahead a variable amount
     depending on rate and error histories. The skipped blocks are
     tried in additional passes (before trimming).

     If BYTES is 0 (auto), the minimum read rate is recalculated every
     second as (average_rate / 10).

'-A'
'--try-again'
     Mark all non-trimmed and non-scraped blocks inside the rescue
     domain as non-tried before beginning the rescue. Try this if the
     drive stops responding and ddrescue immediately starts scraping
     failed blocks when restarted. If '--retrim' is also specified,
     mark all failed blocks inside the rescue domain as non-tried.

'-b BYTES'
'--sector-size=BYTES'
     Sector (hardware block) size of input device in bytes (usually 512
     for hard discs and 3.5" floppies, 1024 for 5.25" floppies, and
     2048 for cdroms). Defaults to 512.

'-B'
'--binary-prefixes'
     Show units with binary prefixes (powers of 1024).
     SI prefixes (powers of 1000) are used by default. (See table
     below).

'-c SECTORS'
'--cluster-size=SECTORS'
     Number of sectors to copy at a time. Defaults to
     64 KiB / sector_size.  Try smaller values for slow drives. The
     number of sectors per track (18 or 9) is a good value for floppies.

'-C'
'--complete-only'
     Limit rescue domain to the blocks listed in the MAPFILE. Don't
     read new data beyond MAPFILE limits. This is useful when reading
     from devices of undefined size (like raw devices), when the drive
     returns an incorrect size, or when reading from a partial copy. It
     can only be used after a first rescue attempt, possibly limited
     with the '--size' option, has produced a complete MAPFILE.

'-d'
'--idirect'
     Use direct disc access (see Direct disc access) to read from
     INFILE, bypassing the kernel cache. (Opens the file with the
     O_DIRECT flag). Sector size must be correctly set for this to
     work. Not all systems support this.

     If your system does not support direct disc access, ddrescue will
     warn you. If the sector size is not correctly set, an unaligned
     read error will result and ddrescue will exit with status 1.

'-D'
'--odirect'
     Use direct disc access to write to OUTFILE, bypassing the kernel
     cache. (Opens the file with the O_DIRECT flag). Sector size must be
     correctly set for this to work. Not all systems support this.

     If your system does not support direct disc access, ddrescue will
     warn you. If the sector size is not correctly set, a write error
     will result and no data will be rescued. Some OSs have a bug that
     prevents them from detecting write errors properly (or at all) on
     some devices if direct disc access is not used for OUTFILE.

'-e [+]N'
'--max-bad-areas=[+]N'
     Maximum number of bad areas allowed before giving up. Defaults to
     infinity. If N is preceded by '+' the number refers to new bad
     areas found in this run, not counting those already present in the
     MAPFILE.

'-E BYTES'
'--max-error-rate=BYTES'
     Maximum rate of read errors allowed before giving up, in bytes per
     second. Defaults to infinity. The rate being measured is that of
     actually failed reads, so ddrescue may exit because of this rate
     being exceeded even if the total error size (size of bad-sector
     areas) does not change because the areas being tried are being
     marked as non-trimmed or non-scraped, or are already marked as
     bad-sector.

'-f'
'--force'
     Force overwrite of OUTFILE. Needed when OUTFILE is not a regular
     file, but a device or partition. This option is just a safeguard
     to prevent the inadvertent destruction of partitions, and is
     ignored for regular files.

'-F TYPES'
'--fill-mode=TYPES'
     Fill the blocks in OUTFILE specified as any of TYPES in MAPFILE,
     with data read from INFILE. TYPES contains one or more of the
     status characters defined in the chapter Mapfile structure (see
     Mapfile structure) and an optional 'l' for sector location data.
     See the chapter Fill mode (see Fill mode) for a complete
     description of the fill mode.

'-G'
'--generate-mode'
     Generate an approximate MAPFILE from the INFILE and OUTFILE of the
     original rescue run. Note that you must keep the original offset
     between '--input-position' and '--output-position' of the original
     rescue run. See the chapter Generate mode (see Generate mode)
     for a complete description of the generate mode.

'-H FILE'
'--test-mode=FILE'
     Builds a map of good/bad blocks using the mapfile FILE and uses it
     to simulate read errors in INFILE. The blocks marked as finished
     in FILE will be read normally. All other block types will be
     considered read errors without even trying to read them from
     INFILE. The apparent size of INFILE is truncated to the extent of
     FILE. This mode is an aid in improving the algorithm of ddrescue
     and is also useful to verify that ddrescue produces accurate
     results in presence of read errors. Use '-' as FILE to read from
     standard input.

'-i BYTES'
'--input-position=BYTES'
     Starting position of the rescue domain in INFILE, in bytes.
     Defaults to 0. This is not the point from which ddrescue starts
     copying.  (For example, if you pass the '--reverse' option to
     ddrescue, it starts copying from the end of the rescue domain). In
     fill mode it refers to a position in the INFILE of the original
     rescue run. See the chapter Fill mode (see Fill mode) for
     details.

'-I'
'--verify-input-size'
     Compare the size of INFILE with the size calculated from the list
     of blocks contained in the MAPFILE, and exit with status 1 if they
     differ. This is not enabled by default because the size of some
     devices can't be known in advance and because the size derived
     from the MAPFILE may be incomplete, for example after doing a
     partial rescue.

'-J'
'--verify-on-error'
     After every read error, read again the last good sector found and
     verify that it returns the same data. Exit with status 2 if the
     read fails or returns inconsistent data. Exit with status 1 if a
     read error happens before a good sector is found.

     This option performs one extra read after each error, wearing the
     drive faster. Use it only on drives that stop responding or return
     garbage data after finding errors. You may need to power cycle the
     drive before restarting ddrescue.

'-K [INITIAL][,MAX]'
'--skip-size=[INITIAL][,MAX]'
     Set limits to skip size during the copying phase. At least one of
     INITIAL or MAX must be specified. INITIAL is the size to skip on
     the first read error or slow read, in bytes. MAX is the maximum
     size to skip. The values given will be rounded to the next
     multiple of sector size. The skip size will be doubled for each
     read error or slow read until it reaches MAX or, if MAX is
     omitted, 1% of the size of INFILE, and will be reset to INITIAL
     when good data are found. Valid values range from 64 KiB to 1 EiB.
     INITIAL defaults to INFILE_SIZE / 100_000 with a minimum value of
     64 KiB. An INITIAL value of 0 disables skipping entirely.

     If ddrescue is having difficulties skipping away from a large area
     with scattered errors, or if the device has large bad areas at
     regular intervals, you may increase the initial skip size with
     this option.  Inversely, if ddrescue is skipping too much, leaving
     large non-tried areas behind each error (which will be read later
     in the usually slower backwards direction), you may reduce the
     maximum skip size, or disable skipping.

     '--skip-size' is independent from '--cluster-size'. The size to
     skip is calculated from the end of the block that just failed.

'-L'
'--loose-domain'
     Accept an incomplete synthetic (user fabricated) domain mapfile or
     test-mode mapfile and fill the gaps in the list of data blocks with
     non-tried blocks. The blocks in the mapfile must be strictly
     ascending and non-overlapping, but they don't need to be
     contiguous. This option allows making quick edits to a mapfile
     without all the size calculations involved in making all data
     blocks contiguous again.

'-m FILE'
'--domain-mapfile=FILE'
     Restrict the rescue domain to the blocks marked as finished in the
     mapfile FILE. This is useful for merging partially recovered
     images of backups, or if the destination drive fails during the
     rescue.  Use '-' as FILE to read the domain mapfile from standard
     input.  Specialized tools like ddrutility or partclone can produce
     a domain mapfile listing all the used blocks in a partition,
     making the rescue more efficient.

'-M'
'--retrim'
     Mark all failed blocks inside the rescue domain as non-trimmed
     before beginning the rescue. The effect is similar to
     '--retry-passes=1', but the bad sectors are tried in a different
     order, making perhaps possible to rescue some of them.

'-n'
'--no-scrape'
     Skip the scraping phase. Avoids spending a lot of time trying to
     rescue the most difficult parts of the file.

'-N'
'--no-trim'
     Skip the trimming phase. Especially useful in the first parts of a
     multi-part rescue.

'-o BYTES'
'--output-position=BYTES'
     Starting position of the image of the rescue domain in OUTFILE, in
     bytes. Defaults to '--input-position'. The bytes below BYTES
     aren't touched if they exist and truncation is not requested. Else
     they are set to 0.

'-O'
'--reopen-on-error'
     Close INFILE and then reopen it after every read error encountered
     during the copying phase. If '--min-read-rate' is set, also close
     and reopen INFILE after every slow read encountered during the
     first two passes of the copying phase. Use this option if you
     notice a permanent drop in transfer rate after finding read errors
     or slow areas.  But be warned that most probably the slowing-down
     is intentionally caused by the kernel in an attempt to increase
     the probability of reading data from the device.

'-p'
'--preallocate'
     Preallocate space on disc for OUTFILE. Only space for regular
     files can be preallocated. If preallocation succeeds, rescue will
     not fail due to lack of free space on disc. If ddrescue can't
     determine the size to preallocate, you may need to specify it with
     some combination of the '--input-position', '--output-position',
     '--size', and '--domain-mapfile' options.

'-P[LINES]'
'--data-preview[=LINES]'
     Show LINES lines of the latest data read in '16-byte hex + ASCII'
     format. Valid values for LINES range from 1 to 32. If LINES is
     omitted, a default value of 3 is used.

'-q'
'--quiet'
     Quiet operation. Suppress all messages.

'-r N'
'--retry-passes=N'
     Exit after the given number of retry passes. Defaults to 0. -1
     means infinity. Every bad sector is tried only once in each pass.
     To retry bad sectors detected on a previous run, you must specify
     a non-zero number of retry passes.

'-R'
'--reverse'
     Reverse the direction of all passes (copying, trimming, scraping
     and retrying). Every pass that is normally run forwards will now
     be run backwards, and vice versa. '--reverse' does not modify the
     size of the blocks copied during each phase, just the order in
     which they are tried.

'-s BYTES'
'--size=BYTES'
     Maximum size of the rescue domain in bytes. It limits the amount of
     input data to be copied. If ddrescue can't determine the size of
     the input file, you may need to specify it with this option. Note
     that this option does not specify the size of the resulting
     OUTFILE. For example, the following command creates an OUTFILE 300
     bytes long, but only writes data on the last 200 bytes:

          ddrescue -i 100 -s 200 infile outfile mapfile

'-S'
'--sparse'
     Use sparse writes for OUTFILE. (The blocks of zeros are not
     actually allocated on disc). May save a lot of disc space in some
     cases.  Not all systems support this. Only regular files can be
     sparse.

'-t'
'--truncate'
     Truncate OUTFILE to zero size before writing to it. Only works for
     regular files, not for drives or partitions.

'-T INTERVAL'
'--timeout=INTERVAL'
     Maximum time since last successful read allowed before giving up.
     Defaults to infinity. INTERVAL is an integer or rational number
     (like 1.5 or 1/2) optionally followed by one of 's', 'm', 'h' or
     'd', meaning seconds, minutes, hours and days respectively. If no
     unit is specified, it defaults to seconds.  INTERVAL has a
     resolution of one second; fractions of a second are not allowed.

'-u'
'--unidirectional'
     Run all passes in the same direction. Forwards by default, or
     backwards if the option '--reverse' is also given.

'-v'
'--verbose'
     Verbose mode. Further -v's (up to 4) increase the verbosity level.

'-w'
'--ignore-write-errors'
     Make fill mode ignore write errors. This is useful to avoid
     ddrescue exiting because of new bad sectors developing while
     wiping the good sectors of a failing drive. Fill mode normally
     writes to OUTFILE one cluster at a time. With this option, after
     the first write error is found in an area, the rest of that area
     is filled sector by sector.

     Note that in rescue mode a write error is fatal, which means that
     the rescue needs to be repeated or else OUTFILE needs to be copied
     to a third drive using MAPFILE as domain (see
     --domain-mapfile).

'-x BYTES'
'--extend-outfile=BYTES'
     Extend the size of OUTFILE to make it at least BYTES long.  If the
     size of OUTFILE is already equal or longer than BYTES then this
     option does nothing. Use this option to guarantee a minimum size
     for OUTFILE. Only regular files can be extended.

'-X N'
'--max-read-errors=N'
     Maximum number of read errors allowed before giving up. Defaults to
     infinity. Exit with status 1 if more than N read errors are
     encountered. '--max-read-errors=0' is similar but different to
     '--timeout=0', which waits until the screen status is refreshed (at
     least 1 second). If there is at least one successful read per
     second, '--timeout=0' does not make ddrescue to exit.

     '--max-read-errors=0' is also similar but different to
     '--max-bad-areas=+0', which exits when a new bad area is found. If
     the read errors are adjacent to existing bad areas, no new bad
     areas are produced (just enlarged), and '--max-bad-areas=+0' does
     not make ddrescue to exit.

'-y'
'--synchronous'
     Use synchronous writes for OUTFILE. (Issue a fsync call after
     every write). May be useful when forcing the drive to remap its bad
     sectors.

'-Z BYTES'
'--max-read-rate=BYTES'
     Maximum read rate, in bytes per second. If BYTES is too small, the
     actual read rate is rounded up to the equivalent of a whole number
     of cluster reads per second. Use this option to limit the
     bandwidth used by ddrescue, for example when recovering over a
     network.

'--ask'
     Ask for user confirmation before starting the copy. If the first
     letter of the answer is 'y', ddrescue starts copying. Else it
     exits with status 1.
     If they can be obtained, ddrescue shows the model and serial
     number of the input and output devices. Ddrescue also shows the
     size in bytes of the corresponding file or device if it exists.
     The format used is [MODEL::SERIAL_NUMBER] (SIZE)

'--command-mode'
     Read commands from the standard input and execute them, copying
     parts of the input file on demand. Command line arguments
     controling the display (like '--data-preview') or the automatic
     algorithm (like '--max-errors' or '--reverse') have no effect in
     command mode. See Command mode, for a complete description of
     the command mode.

'--cpass=RANGE'
     Select what pass(es) to run during the copying phase. Valid pass
     values range from 1 to 5. To run only the given pass(es), specify
     also '--no-trim' and '--no-scrape'. '--cpass=0' skips the copying
     phase entirely.

     Examples of RANGE   Passes run
     1                   1
     1,2,3               1, 2 and 3
     2-4                 2, 3 and 4
     1,3-5               1, 3, 4 and 5
     1-3,5               1, 2, 3 and 5

'--delay-slow=INTERVAL'
     Initial delay before ddrescue starts checking for slow reads.
     Defaults to 30 seconds. INTERVAL is formatted as in the option
     '--timeout' above.

'--log-events=FILE'
     Log all significant events (start of each pass and end of run) in
     FILE. If FILE already exists, the new events are appended at the
     end of FILE. For each event a line is printed containing a time
     stamp, the percentage rescued and a message describing the event.
     The 'end of run' line also contains the current position and
     status. If ddrescue exits because of an error or interruption, the
     cause is also logged in FILE.

'--log-rates=FILE'
     Log rates and error sizes every second in FILE. If FILE already
     exists, it will be overwritten. Every time the screen is updated
     with new details, some of those details (time, input position,
     current and average rates, number of bad areas and total error
     size) are written to FILE in a format usable by plotting utilities
     like gnuplot.  This allows a posterior analysis of the drive to
     see if it has any weak zones (areas where the transfer rate drops
     well below the sustained average).

'--log-reads=FILE'
     Log all read operations in FILE. If FILE already exists, it will
     be overwritten. Every read attempt and its result (position, size,
     copied size and error size) is written to FILE. (The position
     written is always the beginning of the block tried, even if reading
     backwards). A line is also written at the beginning of each phase
     (copying, trimming, scraping and retrying). Finally, a line with a
     time mark is written every second (unless the read takes more
     time). Use this option with caution because FILE may become very
     large very quickly. Use lzip to compress FILE if you need to store
     or transmit it.

'--mapfile-interval=[SAVE_INTERVAL][,SYNC_INTERVAL]'
     Change the interval at which ddrescue saves and fsyncs the
     MAPFILE. At least one of SAVE_INTERVAL or SYNC_INTERVAL must be
     specified. A SAVE_INTERVAL of -1 chooses the default automatic
     interval (from 30 seconds to 5 minutes depending on mapfile size).
     A SAVE_INTERVAL of 0 saves the MAPFILE after every read (use with
     caution).  SYNC_INTERVAL is the interval between fsync calls.
     Default SYNC_INTERVAL is 5 minutes. Minimum SYNC_INTERVAL is 5
     seconds.  Intervals are formatted as in the option '--timeout'
     above.

'--max-slow-reads=N'
     Maximum number of slow reads allowed before giving up. Defaults to
     infinity. Exit with status 1 if more than N slow reads are
     encountered during the first two passes of the copying phase. Only
     works if a minimum read rate has been set with '--min-read-rate'.

'--pause-on-error=INTERVAL'
     Time to wait after each read error or slow read. Defaults to 0.
     INTERVAL is formatted as in the option '--timeout' above. If
     INTERVAL begins with 's', the pause is simulated and INTERVAL can
     be smaller than one second; the time displayed is increased by
     INTERVAL but without performing any pause. Pause simulation can be
     useful in combination with '--test-mode' for testing purposes.

'--pause-on-pass=INTERVAL'
     Time to wait between passes. Defaults to 0. INTERVAL is formatted
     as in the option '--timeout' above.

'--reset-slow'
     Reset the slow reads counter every time the read rate reaches or
     surpasses '--min-read-rate'. With this option, ddrescue only exits
     after the read rate has remained below '--min-read-rate' for at
     least as many seconds as the argument given to '--max-slow-reads'.

'--same-file'
     Allow INFILE and OUTFILE to be the same file or device. This may
     be used to test the writing ability of a drive. It may also be used
     to copy part of a file to another location inside or beyond the
     end of the same file by setting different values for
     '--input-position' and '--output-position'. If the data to be
     copied overlap with the destination, the right copying direction
     must be chosen to avoid overwriting the overlapping part before it
     is copied.

   Numbers given as arguments to options (positions, sizes, rates, etc)
may be expressed as decimal, hexadecimal or octal values (using the same
syntax as integer constants in C++), and may be followed by a multiplier
and an optional 'B' for "byte". The 's' multiplier may be appended to
any of the other multipliers. For example, 'ks' means kilosectors
(1000 * sector_size), and 'Kis' means kibisectors (1024 * sector_size).

   Table of SI and binary prefixes (unit multipliers):

Prefix   Value                     |   Prefix   Value
s        sectors                   |
k        kilobyte  (10^3 = 1000)   |   Ki       kibibyte (2^10 = 1024)
M        megabyte  (10^6)          |   Mi       mebibyte (2^20)
G        gigabyte  (10^9)          |   Gi       gibibyte (2^30)
T        terabyte  (10^12)         |   Ti       tebibyte (2^40)
P        petabyte  (10^15)         |   Pi       pebibyte (2^50)
E        exabyte   (10^18)         |   Ei       exbibyte (2^60)
Z        zettabyte (10^21)         |   Zi       zebibyte (2^70)
Y        yottabyte (10^24)         |   Yi       yobibyte (2^80)

   Exit status: 0 for a normal exit, 1 for environmental problems (file
not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or
invalid input file, 3 for an internal consistency error (eg, bug) which
caused ddrescue to panic.

   If ddrescue is interrupted by a signal, it updates MAPFILE and then
terminates by raising the signal received.

7 Mapfile structure
*******************

NOTE: In versions of ddrescue prior to 1.20 the mapfile was called
'logfile'. The format is the same; only the name has changed.

   The mapfile is a text file easy to read and edit. It is formed by
three parts, the heading comments, the status line, and the list of data
blocks. The character '#' at begin of line or after whitespace starts a
comment that extends to the end of the line.

   The heading comments contain the version of ddrescue or ddrescuelog
that created the mapfile, the command line used, and the time when the
program started. If the mapfile was created by ddrescue it will also
contain the current time when the mapfile was saved and a copy of the
status message from the screen describing the operation being performed
(copying, trimming, finished, etc). They are intended as information for
the user.

   The first non-comment line is the status line. It contains a
non-negative integer, a status character, and a positive decimal
integer. The first integer is the position being tried in the input
file. (The beginning of the block being tried in a forward pass or the
end of the block in a backward pass). The status character is one of
these:

Character   Meaning
'?'         copying non-tried blocks
'*'         trimming non-trimmed blocks
'/'         scraping non-scraped blocks
'-'         retrying bad sectors
'F'         filling specified blocks
'G'         generating approximate mapfile
'+'         finished

   Finally, the last integer is the number of the current pass in the
current phase. The status line allows ddrescue to resume the copying
phase instead of restarting it from pass 1. It also allows the retrying
phase to resume in the same direction it was interrupted.

   The blocks in the list of data blocks must be contiguous and
non-overlapping.

   Every line in the list of data blocks describes a block of data. It
contains 2 non-negative integers and a status character. The first
integer is the starting position of the block in the input file, the
second integer is the size (in bytes) of the block. The status character
is one of these:

Character   Meaning
'?'         non-tried block
'*'         failed block non-trimmed
'/'         failed block non-scraped
'-'         failed block bad-sector(s)
'+'         finished block

And here is an example mapfile:

     # Mapfile. Created by GNU ddrescue version 1.24
     # Command line: ddrescue -d -c18 /dev/fd0 fdimage mapfile
     # Start time:   2015-07-21 09:37:44
     # Current time: 2015-07-21 09:38:19
     # Copying non-tried blocks... Pass 1 (forwards)
     # current_pos  current_status  current_pass
     0x00120000     ?               1
     #      pos        size  status
     0x00000000  0x00117000  +
     0x00117000  0x00000200  -
     0x00117200  0x00001000  /
     0x00118200  0x00007E00  *
     0x00120000  0x00048000  ?

   If you edit the file, you may use decimal, hexadecimal or octal
values, using the same syntax as integer constants in C++, except for
current_pass, which must be a decimal integer.

8 Saving the mapfile in case of trouble
***************************************

The mapfile is an essential part of ddrescue's effectiveness. Without a
mapfile, ddrescue can't resume a rescue, only reinitiate it. Given that
a difficult rescue may take days to complete, it would be a serious
drawback if the mapfile were lost because of a solvable problem like a
lack of space on the device the mapfile is written to.

   In case of trouble writing the mapfile, ddrescue will print a message
like this:

     Error writing mapfile 'MAPFILE': No space left on device
     Fix the problem and press ENTER to retry,
                          or E+ENTER for an emergency save and exit,
                          or Q+ENTER to abort.

   You may try to fix the problem, for example deleting some files to
make room for the mapfile, and press <Return> to retry.

   If the problem can't be fixed, you may press <e> followed by
<Return> to try an emergency save and exit. Ddrescue will try to write
the mapfile to the file 'ddrescue.map' in the current directory or, if
this fails, to '$HOME/ddrescue.map'. If the mapfile is written
succesfully, ddrescue will exit with status 1. Else it will print the
above message again.

   Or you may press <q> followed by <Return> to quit and exit with
status 1. In this case the contents of the mapfile will be lost.

9 Copying CD-ROMs and DVDs
**************************

Ddrescue may be better than dd for copying recordable CD-ROMs because
the two lead out sectors at the end of some of them may cause a read
error that prevents the whole last record from being copied by dd,
potentially losing data. Also dd may create an image larger than the
original if the 'sync' conversion and a block size larger than the
sector size are specified.

   In the special case of reading CD-ROMs (but not DVDs), the
specialized tool dvdisaster may be a better option than ddrescue for
recovering data because dvdisaster can read and analyze raw CD sectors,
which ddrescue can't.

   Recordable CD and DVD media keep their data only for a finite time
(typically for some years). After that time, data loss develops slowly
with read errors growing from the outer media region towards the
inside. It is a good idea to make two (or more) copies of every
important CD-ROM/DVD you burn so that you can later recover them with
ddrescue.

   If you have only one copy of a CD-ROM or DVD that fails when being
copied, and if you have access to multiple optical media drives, you
have a better chance of recovering the bad sectors since one drive may
fail to read a particular sector, but another drive might be able to
squeeze the data out of it, depending on the laser frequency and the
sensitivity of the laser-sensor that reads the reflected laser light.

Example 1: Rescue a CD-ROM in /dev/cdrom.

     ddrescue -n -b2048 /dev/cdrom cdimage mapfile
     ddrescue -d -r1 -b2048 /dev/cdrom cdimage mapfile
       (if bad-sector size is zero, cdimage now contains a complete image
        of the CD-ROM and you can write it to a blank CD-ROM)

Example 2: Rescue a CD-ROM in /dev/cdrom from two copies.

     ddrescue -n -b2048 /dev/cdrom cdimage mapfile
     ddrescue -d -b2048 /dev/cdrom cdimage mapfile
       (insert second copy in the CD drive)
     ddrescue -d -r1 -b2048 /dev/cdrom cdimage mapfile
       (if bad-sector size is zero, cdimage now contains a complete image
        of the CD-ROM and you can write it to a blank CD-ROM)

Example 3: Rescue a CD-ROM in /dev/cdrom using two CD drives from two
different computers, writing the image into an USB drive mounted on
/mnt/mem.

     ddrescue -n -b2048 /dev/cdrom /mnt/mem/cdimage /mnt/mem/mapfile
     ddrescue -d -r1 -b2048 /dev/cdrom /mnt/mem/cdimage /mnt/mem/mapfile
       (umount the USB drive and move both USB drive and CD-ROM to second
        computer)
     ddrescue -d -r1 -b2048 /dev/cdrom /mnt/mem/cdimage /mnt/mem/mapfile
       (if bad-sector size is zero, /mnt/mem/cdimage now contains a complete
        image of the CD-ROM and you can write it to a blank CD-ROM)

Example 4: Merge the partially recovered images of 3 identical DVDs
using their mapfiles as domain mapfiles.

     ddrescue -m mapfile1 dvdimage1 dvdimage mapfile
     ddrescue -m mapfile2 dvdimage2 dvdimage mapfile
     ddrescue -m mapfile3 dvdimage3 dvdimage mapfile
       (if bad-sector size is zero, dvdimage now contains a complete image
        of the DVD and you can write it to a blank DVD)

Example 5: Rescue a lzip compressed backup from two copies on CD-ROM
with error-checked merging of copies.  See lziprecover manual (lziprecover),
for details about lziprecover.

     ddrescue -d -r1 -b2048 /dev/cdrom cdimage1 mapfile1
     mount -t iso9660 -o loop,ro cdimage1 /mnt/cdimage
     cp /mnt/cdimage/backup.tar.lz rescued1.tar.lz
     umount /mnt/cdimage
       (insert second copy in the CD drive)
     ddrescue -d -r1 -b2048 /dev/cdrom cdimage2 mapfile2
     mount -t iso9660 -o loop,ro cdimage2 /mnt/cdimage
     cp /mnt/cdimage/backup.tar.lz rescued2.tar.lz
     umount /mnt/cdimage
     lziprecover -m -v -o backup.tar.lz rescued1.tar.lz rescued2.tar.lz
       Input files merged successfully.
     lziprecover -tv backup.tar.lz
       backup.tar.lz: ok

10 A small tutorial with examples
*********************************

This tutorial is for those already able to use the dd command. If you
don't know what dd is, better search the net for some introductory
material about dd and GNU ddrescue first.

   A failing drive tends to develop more and more errors as time passes.
Because of this, you should rescue the data from a drive as soon as you
notice the first error. Be diligent because every time a physically
damaged drive powers up and is able to output some data, it may be the
very last time that it ever will.

   You should make a copy of the failing drive with ddrescue, and then
try to repair the copy. If your data are really important, use the
first copy as a master for a second copy, and try to repair the second
copy. If something goes wrong, you have the master intact to try again.

   If you are trying to rescue a whole partition, first repair the copy
with e2fsck or some other tool appropriate for the type of partition you
are trying to rescue, then mount the repaired copy somewhere and try to
recover the files in it.

   If the drive is so damaged that the file system in the rescued
partition can't be repaired or mounted, you will have to browse the
rescued data with an hex editor and extract the desired parts by hand
or use a file recovery tool like photorec.

   If the partition table is damaged, you may try to rescue the whole
disc, then try to repair the partition table and the partitions on the
copy.

   If the damaged drive is not listed in /dev, then you cannot rescue
it.  At least not with ddrescue.

   See Optical media, for rescue examples of CD-ROMs and DVDs.

Example 1: Fully automatic rescue of a whole disc with two ext2
partitions in /dev/sda to /dev/sdb.
Note: you don't need to partition /dev/sdb beforehand, but if the
partition table on /dev/sda is damaged, you'll need to recreate it
somehow on /dev/sdb.

     ddrescue -f -r3 /dev/sda /dev/sdb mapfile
     fdisk /dev/sdb
     e2fsck -v -f /dev/sdb1
     e2fsck -v -f /dev/sdb2

Example 2: Rescue an ext2 partition in /dev/sda2 to /dev/sdb2.
Note: you need to create the sdb2 partition with fdisk first. sdb2
should be of appropriate type and size.

     ddrescue -f -n /dev/sda2 /dev/sdb2 mapfile
     ddrescue -d -f -r3 /dev/sda2 /dev/sdb2 mapfile
     e2fsck -v -f /dev/sdb2
     mount -t ext2 -o ro /dev/sdb2 /mnt
       (read rescued files from /mnt)

Example 3: While rescuing the whole drive /dev/sda to /dev/sdb, /dev/sda
freezes up at position 12345678.

     ddrescue -f /dev/sda /dev/sdb mapfile       <-- /dev/sda freezes here
       (restart /dev/sda or reboot computer)
       (restart copy at a safe distance from the troubled sector)
     ddrescue -f -i 12350000 /dev/sda /dev/sdb mapfile
       (then copy backwards down to the troubled sector)
     ddrescue -f -R /dev/sda /dev/sdb mapfile

Example 4: While rescuing the whole drive /dev/sda to /dev/sdb, /dev/sdb
fails and you have to rescue data to a third drive, /dev/sdc.

     ddrescue -f -n /dev/sda /dev/sdb mapfile1     <-- /dev/sdb fails here
     ddrescue -f -m mapfile1 /dev/sdb /dev/sdc mapfile2
     ddrescue -f -n /dev/sda /dev/sdc mapfile2
     ddrescue -d -f -r3 /dev/sda /dev/sdc mapfile2

Example 5: While rescuing a partition in /dev/sda1 to the file hdimage,
/dev/sda1 stops responding and begins returning read errors, causing
ddrescue to mark the rest of the partition as non-scraped.

     ddrescue -n /dev/sda1 hdimage mapfile        <-- /dev/sda1 fails here
       (restart /dev/sda or reboot computer)
     ddrescue -n -A -i<pos> -O /dev/sda1 hdimage mapfile
       (if /dev/sda1 fails again, restart /dev/sda or reboot computer and
        then repeat the above command as many times as needed until it
        succeeds. <pos> is the position where the drive stopped responding)
     ddrescue -d -r3 /dev/sda1 hdimage mapfile

Example 6: While rescuing a partition in /dev/sda1 to the file hdimage,
sda1 disappears from /dev.

     ddrescue -n /dev/sda1 hdimage mapfile        <-- /dev/sda1 fails here
       (restart /dev/sda or reboot computer and then repeat the above
        command as many times as needed until it succeeds)
     ddrescue -d -r3 /dev/sda1 hdimage mapfile

Example 7: While rescuing a partition in /dev/sda1 to the file hdimage,
the partition table of /dev/sda becomes unreadable and the OS no longer
shows sda1 in /dev. The solution is to shift the mapfile and read the
rest of the partition sda1 from /dev/sda.  Note: you need to know the
offset of the partition sda1 in the drive sda and the size of sda1.

     ddrescue /dev/sda1 hdimage mapfile     <-- partition table fails here
     ddrescuelog --shift -o<offset> mapfile > shifted_mapfile
     ddrescue -i<offset> -o0 -s<size> /dev/sda hdimage shifted_mapfile

Example 8: After rescuing a partition in /dev/sda1 to the file hdimage,
expand hdimage to copy the whole drive in /dev/sda without recopying the
already copied partition /dev/sda1. The solution is to shift the
mapfile, move the data of sda1 to its final position in hdimage, and
then read the rest of the data from /dev/sda.  Note: you need to know
the offset of the partition sda1 in the drive sda and the size of sda1.

     ddrescue /dev/sda1 hdimage mapfile           <-- rescue partition
     ddrescuelog --shift -o<offset> mapfile > shifted_mapfile
     ddrescue --same-file -o<offset> -s<size> --reverse hdimage hdimage
     ddrescue /dev/sda hdimage shifted_mapfile    <-- rescue rest of drive

11 Direct disc access
*********************

If you notice that the positions and sizes in MAPFILE are always
multiples of the sector size, maybe your kernel is caching the disc
accesses and grouping them. In this case you may want to use direct disc
access for INFILE, or read from a raw device, to bypass the kernel
cache and rescue more of your data.

   NOTE! Sector size must be correctly set with the '--sector-size'
option for direct disc access to work.

   NOTE: Direct disc access can copy arbitrary domains by reading whole
sectors and then writing only the requested part. This is the only case
where ddrescue will try to read data outside of the rescue domain.

   Try the '--idirect' option first. If direct disc access is not
available in your system, try raw devices. Read your system
documentation to find how to bind a raw device to a regular block
device. Some OSs provide raw access through especial device names, like
/dev/rdisk.

   Ddrescue aligns its I/O buffer to the sector size so that it can be
used for direct disc access or to read from raw devices. For efficiency
reasons, also aligns it to the memory page size if page size is a
multiple of sector size.  On some systems, ddrescue can't determine the
size of a raw device, so an explicit '--size' or '--complete-only'
option may be needed.

   Using direct disc access, or reading from a raw device, may be
slower or faster than normal cached reading depending on your OS and
hardware. In case it is slower you may want to make a first pass using
normal cached reads and use direct disc access, or a raw device, only
to recover the good sectors inside the failed blocks.

Example 1: using direct disc access.

     ddrescue -f -n /dev/sdb1 /dev/sdc1 mapfile
     ddrescue -d -f -r3 /dev/sdb1 /dev/sdc1 mapfile
     e2fsck -v -f /dev/sdc1
     mount -t ext2 -o ro /dev/sdc1 /mnt

Example 2: using a raw device.

     raw /dev/raw/raw1 /dev/sdb1
     ddrescue -f -n /dev/sdb1 /dev/sdc1 mapfile
     ddrescue -C -f -r3 /dev/raw/raw1 /dev/sdc1 mapfile
     raw /dev/raw/raw1 0 0
     e2fsck -v -f /dev/sdc1
     mount -t ext2 -o ro /dev/sdc1 /mnt

12 Copying parts of the input file on demand
********************************************

The command mode of ddrescue implements a scripting interface similar to
the one of ed.  See ed manual (ed).  In this mode commands are
read from the standard input and executed to copy parts of the input
file to the output file, retrieve information from the mapfile or write
the mapfile to disc. Ddrescue's responses are written to standard
output. "done\n" for a successfully executed command, "error\n" for a
failed command (for example because of wrong arguments), and
"error: ERROR MESSAGE\n" for serious or fatal errors like write errors.

   If end-of-file is detected on standard input, ddrescue discards any
partial command being read and executes a 'f' command.

   All ddrescue commands are single characters, though some require
additonal parameters separated by spaces. Only one command is allowed
per line.  Ddrescue recognizes the following commands:

'c POS SIZE'
     Copy command. Copies a block of data from INFILE to OUTFILE and
     updates the internal copy of the mapfile. The areas already marked
     as finished in the mapfile are not copied again.

'f'
     Finish command. Compacts the internal copy of the mapfile and
     writes it to MAPFILE (if it was specified in the command line).
     Then prints "done\n" to standard output and quits. On startup, the
     mapfile is first compacted and then split following the rescue
     domain borders. The finish command compacts the mapfile again
     before exiting. If writing MAPFILE to disc fails, a
     non-interactive emergency save is tried before exiting.  See
     Emergency save.

'q'
     Quit command. Exits ddrescue. Does not update the mapfile.

's POS SIZE'
     Status command. Writes to standard output one or more lines in
     mapfile format (see Mapfile structure), showing the status of
     the areas included in the block requested. A line consisting of
     the string "done" marks the end of the list.

'u'
     Update mapfile command. Writes the internal copy of the mapfile to
     MAPFILE (if it was specified in the command line). If update
     mapfile fails, you may try to fix the problem, for example
     deleting some files to make room for MAPFILE, before trying to
     update it again.

13 Fill mode
************

When ddrescue is invoked with the '--fill-mode' option it operates in
"fill mode", which is different from the default "rescue mode". That
is, if you use the '--fill-mode' option, ddrescue does not rescue
anything. It only fills with data read from INFILE the blocks of
OUTFILE whose status character from MAPFILE coincides with one of the
type characters specified as argument to the '--fill-mode' option.

   If the argument of the '--fill-mode' option contains an 'l',
ddrescue will write location data (position, sector number and status)
into each sector filled. With bad sectors filled in this way, it should
be possible to retry the recovery of important files, as location of the
error is known by looking into the unfinished copy of the file.

   In fill mode INFILE does not need to be seekable and it may be of
any size. If it is too small, the data will be duplicated as many times
as necessary to fill the input buffer. If it is too big, only the data
needed to fill the input buffer will be read. Then the same data will be
written to every cluster or sector to be filled.

   Note that in fill mode INFILE is always read from position 0. If you
specify a '--input-position', it refers to the original INFILE from
which MAPFILE was built, and is only used to calculate the offset
between input and output positions.

   Note also that when filling the INFILE of the original rescue run
you should not set '--output-position', whereas when filling the
OUTFILE of the original rescue run you should keep the original offset
between '--input-position' and '--output-position'.

   The '--fill-mode' option implies the '--complete-only' option.

   In fill mode MAPFILE is updated to allow resumability when
interrupted or in case of a crash, but as nothing is being rescued
MAPFILE is not destroyed. The status line is the only part of MAPFILE
that is modified.

The fill mode has a number of uses. See the following examples:

Example 1: Mark parts of the rescued copy to allow finding them when
examined in an hex editor. For example, the following command line fills
all blocks marked as '-' (bad-sector) with copies of the string
'BAD-SECTOR ':

     ddrescue --fill-mode=- <(printf "BAD-SECTOR ") outfile mapfile

Example 2: Wipe only the good sectors, leaving the bad sectors alone.
This way, the drive will still test bad (i.e., with unreadable sectors).
This is the fastest way of wiping a failing drive, and is especially
useful when sending the drive back to the manufacturer for warranty
replacement.

     ddrescue --fill-mode=+ --force /dev/zero bad_drive mapfile

Example 3: Force the drive to remap the bad sectors, making it usable
again. If the drive has only a few bad sectors, and they are not caused
by drive age, you can probably just rewrite those sectors, and the drive
will reallocate them automatically to new "spare" sectors that it keeps
for just this purpose. WARNING! This may not work on your drive.

     ddrescue --fill-mode=- -f --synchronous /dev/zero bad_drive mapfile

Fill mode can also help you to figure out, independently of the file
system used, what files are partially or entirely in the bad areas of
the disc. Just follow these steps:

   1) Copy the damaged drive with ddrescue until finished. Don't use
sparse writes. This yields a mapfile containing only finished ('+') and
bad-sector ('-') blocks.

   2) Fill the bad-sector blocks of the copied drive or image file with
a string not present in any file, for example "DEADBEEF". Use
'--fill-mode=l-' if you want location data.

   3) Mount the copied drive (or the image file, via loopback device)
read-only.

   4) Grep for the fill string in all the files. Those files containing
the string reside (at least partially) in damaged disc areas. Note that
if all the damaged areas are in unused space, grep will not find the
string in any file, which means that no files are damaged.

   5) Take note of the location data of any important files that you
want to retry.

   6) Unmount the copied drive or image file.

   7) Retry the sectors belonging to the important files until they are
rescued or until it is clear that they can't be rescued.

   8) Optionally fill the bad-sector blocks of the copied drive or image
file with zeros to restore the disc image.

Example 4: Figure out what files are in the bad areas of the disc.

     ddrescue -b2048 /dev/cdrom cdimage mapfile
     printf "DEADBEEF" > tmpfile
     ddrescue --fill-mode=l- tmpfile cdimage mapfile
     rm tmpfile
     mount -t iso9660 -o loop,ro cdimage /mnt/cdimage
     find /mnt/cdimage -type f -exec grep -l "DEADBEEF" '{}' ';'
       (note that my_thesis.txt has a bad sector at pos 0x12345000)
     umount /mnt/cdimage
     ddrescue -b2048 -i0x12345000 -s2048 -dr9 /dev/cdrom cdimage mapfile
     ddrescue --fill-mode=- /dev/zero cdimage mapfile
     mount -t iso9660 -o loop,ro cdimage /mnt/cdimage
     cp -a /mnt/cdimage/my_thesis.txt /safe/place/my_thesis.txt

14 Generate mode
****************

When ddrescue is invoked with the '--generate-mode' option it operates
in "generate mode", which is different from the default "rescue mode".
That is, if you use the '--generate-mode' option, ddrescue does not
rescue anything. It only tries to generate a MAPFILE for later use.

   So you didn't read the manual and started ddrescue without a
MAPFILE. Now, two days later, your computer crashed and you can't know
how much data ddrescue managed to save. And even worse, you can't
resume the rescue; you have to restart it from the very beginning.

   Or maybe you started copying a drive with 'dd conv=noerror,sync' and
are now in the same situation described above.  In this case, note that
you can't use a copy made by dd unless it was invoked with the 'sync'
conversion argument.

   Don't despair (yet). Ddrescue can in some cases generate an
approximate MAPFILE, from INFILE and the (partial) copy in OUTFILE,
that is almost as good as an exact MAPFILE. It makes this by simply
assuming that sectors containing all zeros were not rescued.

   However, if the destination of the copy was a drive or a partition,
(or an existing regular file and truncation was not requested), most
probably you will need to restart ddrescue from the very beginning.
(This time with a MAPFILE, of course). The reason is that old data may
be present in the drive that have not been overwritten yet, and may be
thus non-tried but non-zero.

   For example, if you first tried one of these commands:
     ddrescue infile outfile
     or
     dd if=infile of=outfile conv=noerror,sync

   then you can generate an approximate mapfile with this command:
     ddrescue --generate-mode infile outfile mapfile

Note that you must keep the original offset between '--input-position'
and '--output-position' of the original rescue run.

15 Ddrescuelog
**************

Ddrescuelog is a tool that manipulates ddrescue mapfiles, shows mapfile
contents, converts mapfiles to/from other formats, compares mapfiles,
tests rescue status, and can delete a mapfile if the rescue is done.
Ddrescuelog operations can be restricted to one or several parts of the
mapfile if the domain setting options are used.

   When performing logic operations (AND, OR, XOR) on mapfiles of
different extension, only the blocks present in both files are
processed.

   Here are some examples of how to use ddrescuelog, alone or in
combination with other tools.

Example 1: Delete the mapfile if the rescue is finished (all data have
been recovered without errors left).

     ddrescue -f /dev/sda /dev/sdb mapfile
     ddrescuelog -d mapfile

Example 2: Rescue two ext2 partitions in /dev/sda to /dev/sdb and
repair the file systems using badblock lists generated with
ddrescuelog. File system block size is 4096.
Note: you do need to partition /dev/sdb beforehand.

     fdisk /dev/sdb                                 <-- partition /dev/sdb
     ddrescue -f /dev/sda1 /dev/sdb1 mapfile1
     ddrescue -f /dev/sda2 /dev/sdb2 mapfile2
     ddrescuelog -l- -b4096 mapfile1 > badblocks1
     ddrescuelog -l- -b4096 mapfile2 > badblocks2
     e2fsck -v -f -L badblocks1 /dev/sdb1
     e2fsck -v -f -L badblocks2 /dev/sdb2

Example 3: Rescue a whole disc with two ext2 partitions in /dev/sda to
/dev/sdb and repair the file systems using badblock lists generated with
ddrescuelog. Disc sector size is 512, file system block size is 4096.
Arguments to options '-i' and '-s' are the starting positions and sizes
of the partitions being rescued.
Note: you don't need to partition /dev/sdb beforehand, but if the
partition table on /dev/sda is damaged, you'll need to recreate it
somehow on /dev/sdb.

     ddrescue -f /dev/sda /dev/sdb mapfile
     fdisk /dev/sdb                                <-- get partition sizes
     ddrescuelog -l- -b512 -i63s -o0 -s767457s -b4096 mapfile > badblocks1
     ddrescuelog -l- -b512 -i767520s -o0 -s96520s -b4096 mapfile > badblocks2
     e2fsck -v -f -L badblocks1 /dev/sdb1
     e2fsck -v -f -L badblocks2 /dev/sdb2

16 Invoking ddrescuelog
***********************

The format for running ddrescuelog is:

     ddrescuelog [OPTIONS] MAPFILE

   Use '-' as MAPFILE to read the mapfile from standard input (also in
the options taking a mapfile argument) or to write the mapfile created
by '--create-mapfile' to standard output.

   Ddrescuelog supports the following options:

'-h'
'--help'
     Print an informative help message describing the options and exit.

'-V'
'--version'
     Print the version number of ddrescuelog on the standard output and
     exit.  This version number should be included in all bug reports.

'-a OLD_TYPES,NEW_TYPES'
'--change-types=OLD_TYPES,NEW_TYPES'
     Change the status of every block in the rescue domain from one
     type in OLD_TYPES to the corresponding type in NEW_TYPES, much like
     the 'tr' command does, and write the resulting mapfile to standard
     output. OLD_TYPES and NEW_TYPES are strings of block status
     characters as defined in the chapter Mapfile structure (see
     Mapfile structure). Blocks whose status is not in OLD_TYPES are
     left unchanged. If NEW_TYPES is shorter than OLD_TYPES the last
     type of NEW_TYPES is repeated as many times as necessary.

'-A'
'--annotate-mapfile'
     Add comments containing the human-readable positions and sizes of
     the blocks in MAPFILE which are included in the rescue domain, and
     write the resulting mapfile to standard output.

'-b BYTES'
'--block-size=BYTES'
     Block size used by ddrescuelog. Depending on the requested
     operation it may be the sector size of the input device, the block
     size of the rescued file system, etc. Defaults to 512.

'-B'
'--binary-prefixes'
     Show units with binary prefixes (powers of 1024).
     SI prefixes (powers of 1000) are used by default. (See table above,
     see Invoking ddrescue).

'-c[TYPE1TYPE2]'
'--create-mapfile[=TYPE1TYPE2]'
     Create a MAPFILE from a list of block numbers read from standard
     input. Only blocks included in the rescue domain will be added to
     MAPFILE.

     TYPE1 and TYPE2 are block status characters as defined in the
     chapter Mapfile structure (see Mapfile structure). TYPE1 sets
     the type for blocks included in the list, while TYPE2 sets the
     type for the rest of MAPFILE. If not specified, TYPE1 defaults to
     '+' and TYPE2 defaults to '-'.

'-C[TYPE]'
'--complete-mapfile[=TYPE]'
     Complete a synthetic (user fabricated) MAPFILE by filling the gaps
     with blocks of type TYPE, and write the completed mapfile to
     standard output. TYPE is one of the block status characters
     defined in the chapter Mapfile structure (see Mapfile structure).
     If TYPE is not specified, the gaps are filled with
     non-tried blocks.  All gaps in MAPFILE are filled. Domain options
     are ignored.

'-d'
'--delete-if-done'
     Delete the given MAPFILE if all the blocks in the rescue domain
     have been successfully recovered. The exit status is 0 if MAPFILE
     could be deleted, 1 otherwise.

'-D'
'--done-status'
     Test if all the blocks in the rescue domain have been successfully
     recovered. The exit status is 0 if all tested blocks are finished,
     1 otherwise.

'-f'
'--force'
     Force overwrite of MAPFILE.

'-i BYTES'
'--input-position=BYTES'
     Starting position of the rescue domain, in bytes. Defaults to 0. It
     refers to a position in the original INFILE.

'-l TYPES'
'--list-blocks=TYPES'
     Print on standard output the block numbers of the blocks specified
     as any of TYPES in MAPFILE and included in the rescue domain.
     TYPES contains one or more of the block status characters defined
     in the chapter Mapfile structure (see Mapfile structure).

     The list format is one block number per line in decimal, like the
     output of the badblocks program, so that it can be used as input
     for e2fsck or other similar filesystem repairing tool.

'-L'
'--loose-domain'
     Accept an incomplete synthetic (user fabricated) domain mapfile or
     compare-as-domain mapfile and fill the gaps in the list of data
     blocks with non-tried blocks. The blocks in the mapfile must be
     strictly ascending and non-overlapping, but they don't need to be
     contiguous.  This option allows making quick edits to a mapfile
     without all the size calculations involved in making all data
     blocks contiguous again.

'-m FILE'
'--domain-mapfile=FILE'
     Restrict the rescue domain to the blocks marked as finished in the
     mapfile FILE.

'-n'
'--invert-mapfile'
     Invert the types of the blocks in MAPFILE which are included in
     the rescue domain, and write the resulting mapfile to standard
     output.  Finished blocks ('+') are changed to bad-sector ('-'), all
     other types are changed to finished. '--invert-mapfile' is
     equivalent to '--change-types=?*/-+,++++-'

'-o BYTES'
'--output-position=BYTES'
     Starting position of the image of the rescue domain in the original
     OUTFILE, in bytes. Is used by the '--list-blocks' option.
     Defaults to '--input-position'.

'-p FILE'
'--compare-mapfile=FILE'
     Compare the types of the blocks included in the rescue domain. The
     exit status is 0 if all the blocks tested are the same in both
     FILE and MAPFILE, 1 otherwise.

'-P FILE'
'--compare-as-domain=FILE'
     Compare only the blocks marked as finished in the rescue domain.
     The exit status is 0 if all the blocks tested are the same in both
     FILE and MAPFILE, 1 otherwise. Two files comparing equal with this
     option are equivalent when used as domain mapfiles.

'-q'
'--quiet'
     Quiet operation. Suppress all messages.

'-s BYTES'
'--size=BYTES'
     Maximum size of the rescue domain in bytes. It refers to a size in
     the original INFILE.

'-t'
'--show-status'
     Print a summary of the contents of each MAPFILE to the standard
     output. This option allows more than one MAPFILE. If the domain
     setting options are used, the summary can be restricted to one or
     several parts of MAPFILE.

'-v'
'--verbose'
     Verbose mode. Further -v's (up to 4) increase the verbosity level.

'-x FILE'
'--xor-mapfile=FILE'
     Perform a logical XOR (exclusive OR) operation between the finished
     blocks in FILE and those in MAPFILE, and write the resulting
     mapfile to standard output. In other words, in the resulting
     mapfile a block is only shown as finished if it was finished in
     either of the two input mapfiles but not in both.

'-y FILE'
'--and-mapfile=FILE'
     Perform a logical AND operation between the finished blocks in
     FILE and those in MAPFILE, and write the resulting mapfile to
     standard output. In other words, in the resulting mapfile a block
     is only shown as finished if it was finished in both input
     mapfiles.

'-z FILE'
'--or-mapfile=FILE'
     Perform a logical OR operation between the finished blocks in FILE
     and those in MAPFILE, and write the resulting mapfile to standard
     output. In other words, in the resulting mapfile a block is shown
     as finished if it was finished in either of the two input mapfiles.

'--shift'
     Shift the positions of all the blocks in MAPFILE by the offset
     ('--output-position' - '--input-position'), and write the
     resulting mapfile to standard output. Either '--input-position' or
     '--output-position' must be 0. If the offset is positive, a
     non-tried block is inserted before the first block. Any blocks
     beyond the end of the rescue domain are removed before performing
     the shift.

   Exit status: 0 for a normal exit, 1 for environmental problems (file
not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or
invalid input file, 3 for an internal consistency error (eg, bug) which
caused ddrescuelog to panic.

17 Reporting bugs
*****************

There are probably bugs in ddrescue. There are certainly errors and
omissions in this manual. If you report them, they will get fixed. If
you don't, no one will ever know about them and they will remain unfixed
for all eternity, if not longer.

   If you find a bug in GNU ddrescue, please send electronic mail to
<bug-ddrescue@gnu.org>. Include the version number, which you can find
by running 'ddrescue --version'.