\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename ddrescue.info
@documentencoding ISO-8859-15
@settitle GNU ddrescue Manual
@finalout
@c %**end of header

@set UPDATED 3 February 2017
@set VERSION 1.22

@dircategory GNU Packages
@direntry
* Ddrescue: (ddrescue).         Data recovery tool
@end direntry


@ifnothtml
@titlepage
@title GNU ddrescue
@subtitle Data recovery tool
@subtitle for Ddrescue version @value{VERSION}, @value{UPDATED}
@author by Antonio Diaz Diaz

@page
@vskip 0pt plus 1filll
@end titlepage

@contents
@end ifnothtml

@node Top
@top

This manual is for GNU ddrescue (version @value{VERSION}, @value{UPDATED}).

@menu
* Introduction::          Purpose and features of GNU ddrescue
* Basic concepts::        Blocks, clusters, devices, files, sectors, etc
* Important advice::      Read this or risk losing your data
* Algorithm::             How ddrescue recovers the data
* Invoking ddrescue::     Command line interface
* Mapfile structure::     Detailed format of the mapfile
* Emergency save::        Saving the mapfile in case of trouble
* Optical media::         Copying CD-ROMs and DVDs
* Examples::              A small tutorial with examples
* Direct disc access::    Bypassing the kernel cache
* Fill mode::             Selectively overwriting the output file
* Generate mode::         Generating an approximate mapfile
* Ddrescuelog::           Tool for ddrescue mapfiles
* Invoking ddrescuelog::  Command line interface
* Problems::              Reporting bugs
* Concept index::         Index of concepts
@end menu

@sp 1
Copyright @copyright{} 2004-2017 Antonio Diaz Diaz.

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


@node Introduction
@chapter Introduction
@cindex 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 is rescued very
efficiently, (only the needed blocks are read). Also you can 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.
@xref{lziprecover-example}, for an 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).


@node Basic concepts
@chapter Basic concepts
@cindex basic concepts

@table @asis
@item 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.

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

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

@item 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.

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

@item 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

@item Rescue domain
Block or set of blocks to be acted upon (rescued, listed, etc). You can
define it with the options @samp{--input-position}, @samp{--size} and
@samp{--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
@w{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 (@pxref{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.

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

@end table


@node Important advice
@chapter Using ddrescue safely
@cindex 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 (eg. 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.


@node Algorithm
@chapter Algorithm
@cindex 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) Read the non-tried parts of the input file,
marking the failed blocks as non-trimmed and skipping beyond them. Skip
also beyond slow areas. The skipped areas are tried later in four
additional passes (before trimming), reversing the direction after each
pass until all the rescue domain is tried.

The second pass delimits the blocks skipped by the first pass. 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.

@sp 1
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. Non-trimmed and non-scraped
blocks are not considered bad areas. 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.

The @samp{remaining time} is calculated using the average rate of the
last 30 seconds and does not take into account that some parts may be
excluded from the rescue (for example with @samp{--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.

The mapfile is periodically saved to disc, as well as when ddrescue
finishes or is interrupted. 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 with
@samp{--mapfile-interval}.

Also, 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:

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

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

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


@node Invoking ddrescue
@chapter Invoking ddrescue
@cindex invoking ddrescue
@cindex options
@cindex usage
@cindex version

The format for running ddrescue is:

@example
ddrescue [@var{options}] @var{infile} @var{outfile} [@var{mapfile}]
@end example

@var{infile} and @var{outfile} may be files, devices or partitions.
@var{mapfile} is a regular file and must be placed in an existing
directory. If @var{mapfile} does not exist, ddrescue will create it.

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:

@table @code
@item -h
@itemx --help
Print an informative help message describing the options and exit.

@item -V
@itemx --version
Print the version number of ddrescue on the standard output and exit.

@item -a @var{bytes}
@itemx --min-read-rate=@var{bytes}
Minimum read rate of good non-tried areas, in bytes per second. If the
read rate falls below this value, ddrescue will skip ahead a variable
amount depending on rate and error histories. The skipped blocks are
tried in additional passes (before trimming).

If @var{bytes} is 0 (auto), the minimum read rate is recalculated every
second as @w{(average_rate / 10)}.

@item -A
@itemx --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 @samp{--retrim} is also specified, mark all failed blocks
inside the rescue domain as non-tried.

@item -b @var{bytes}
@itemx --sector-size=@var{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.

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

@item -c @var{sectors}
@itemx --cluster-size=@var{sectors}
Number of sectors to copy at a time. Defaults to @w{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.

@item -C
@itemx --complete-only
Limit rescue domain to the blocks listed in the @var{mapfile}. Don't
read new data beyond @var{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
@samp{--size} option, has produced a complete @var{mapfile}.

@item -d
@itemx --idirect
Use direct disc access (@pxref{Direct disc access}) to read from
@var{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.

@item -D
@itemx --odirect
Use direct disc access to write to @var{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 @var{outfile}.

@item -e [+]@var{n}
@itemx --max-bad-areas=[+]@var{n}
Maximum number of bad areas allowed before giving up. Defaults to
infinity. If @var{n} is preceded by @samp{+} the number refers to new
bad areas found in this run, not counting those already present in the
@var{mapfile}.

@item -E @var{bytes}
@itemx --max-error-rate=@var{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.

@item -f
@itemx --force
Force overwrite of @var{outfile}. Needed when @var{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.

@item -F @var{types}
@itemx --fill-mode=@var{types}
Fill the blocks in @var{outfile} specified as any of @var{types} in
@var{mapfile}, with data read from @var{infile}. @var{types} contains
one or more of the status characters defined in the chapter Mapfile
structure (@pxref{Mapfile structure}) and an optional @samp{l} for
sector location data. See the chapter Fill mode (@pxref{Fill mode}) for
a complete description of the fill mode.

@item -G
@itemx --generate-mode
Generate an approximate @var{mapfile} from the @var{infile} and
@var{outfile} of the original rescue run. Note that you must keep the
original offset between @samp{--input-position} and
@samp{--output-position} of the original rescue run. See the chapter
Generate mode (@pxref{Generate mode}) for a complete description of the
generate mode.

@item -H @var{file}
@itemx --test-mode=@var{file}
Builds a map of good/bad blocks using the mapfile @var{file} and uses it
to simulate read errors in @var{infile}. The blocks marked as finished
in @var{file} will be read normally. All other block types will be
considered read errors without even trying to read them from
@var{infile}. The apparent size of @var{infile} is truncated to the
extent of @var{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 @samp{-} as @var{file} to read
from standard input.

@item -i @var{bytes}
@itemx --input-position=@var{bytes}
Starting position of the rescue domain in @var{infile}, in bytes.
Defaults to 0. This is not the point from which ddrescue starts copying.
(For example, if you pass the @samp{--reverse} option to ddrescue, it
starts copying from the end of the rescue domain). In fill mode it
refers to a position in the @var{infile} of the original rescue run. See
the chapter Fill mode (@pxref{Fill mode}) for details.

@item -I
@itemx --verify-input-size
Compare the size of @var{infile} with the size calculated from the list
of blocks contained in the @var{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
@var{mapfile} may be incomplete, for example after doing a partial
rescue.

@item -J
@itemx --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.

@item -K [@var{initial}][,@var{max}]
@itemx --skip-size=[@var{initial}][,@var{max}]
Set limits to skip size during the copying phase. At least one of
@var{initial} or @var{max} must be specified. @var{initial} is the size
to skip on the first read error or slow read, in bytes. @var{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 @var{max} or, if @var{max} is
omitted, 1% of the size of @var{infile}, and will be reset to
@var{initial} when good data is found. Valid values range from @w{64 KiB}
to @w{1 EiB}. @var{initial} defaults to @w{@var{infile_size} / 100_000}
with a minimum value of @w{64 KiB}. An @var{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 can 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 can reduce the maximum skip size, or disable
skipping.

@samp{--skip-size} is independent from @samp{--cluster-size}. The size
to skip is calculated from the end of the block that just failed.

@item -L
@itemx --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.

@anchor{--domain-mapfile}
@item -m @var{file}
@itemx --domain-mapfile=@var{file}
Restrict the rescue domain to the blocks marked as finished in the
mapfile @var{file}. This is useful for merging partially recovered
images of backups, or if the destination drive fails during the rescue.
Use @samp{-} as @var{file} to read from standard input.

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

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

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

@item -o @var{bytes}
@itemx --output-position=@var{bytes}
Starting position of the image of the rescue domain in @var{outfile}, in
bytes. Defaults to @samp{--input-position}. The bytes below @var{bytes}
aren't touched if they exist and truncation is not requested. Else they
are set to 0.

@item -O
@itemx --reopen-on-error
Close @var{infile} and then reopen it after every read error and, if
@samp{--min-read-rate} is set, after every slow read encountered both
during 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.

@item -p
@itemx --preallocate
Preallocate space on disc for @var{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 @samp{--input-position}, @samp{--output-position}, @samp{--size},
and @samp{--domain-mapfile} options.

@item -P[@var{lines}]
@itemx --data-preview[=@var{lines}]
Show @var{lines} lines of the latest data read in @w{@samp{16-byte hex +
ASCII}} format. Valid values for @var{lines} range from 1 to 32. If
@var{lines} is omitted, a default value of 3 is used.

@item -q
@itemx --quiet
Quiet operation. Suppress all messages.

@item -r @var{n}
@itemx --retry-passes=@var{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.

@item -R
@itemx --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. @samp{--reverse} does not modify the size of
the blocks copied during each phase, just the order in which they are
tried.

@item -s @var{bytes}
@itemx --size=@var{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 @var{outfile}. For
example, the following command creates an @var{outfile} 300 bytes long,
but only writes data on the last 200 bytes:

@example
ddrescue -i 100 -s 200 infile outfile mapfile
@end example

@item -S
@itemx --sparse
Use sparse writes for @var{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.

@item -t
@itemx --truncate
Truncate @var{outfile} to zero size before writing to it. Only works for
regular files, not for drives or partitions.

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

@item -u
@itemx --unidirectional
Run all passes in the same direction. Forwards by default, or backwards
if the option @samp{--reverse} is also given.

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

@item -w
@itemx --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 @var{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 and forces to repeat the
rescue or to copy @var{outfile} to a third drive using @var{mapfile} as
domain (@pxref{--domain-mapfile}).

@item -x @var{bytes}
@itemx --extend-outfile=@var{bytes}
Extend the size of @var{outfile} to make it at least @var{bytes} long.
If the size of @var{outfile} is already equal or longer than @var{bytes}
then this option does nothing. Use this option to guarantee a minimum
size for @var{outfile}. Only regular files can be extended.

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

@samp{--max-read-errors=0} is also similar but different to
@samp{--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 @samp{--max-bad-areas=+0} does not make
ddrescue to exit.

@item -y
@itemx --synchronous
Use synchronous writes for @var{outfile}. (Issue a fsync call after
every write). May be useful when forcing the drive to remap its bad
sectors.

@item -Z @var{bytes}
@itemx --max-read-rate=@var{bytes}
Maximum read rate, in bytes per second. If @var{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.

@item --ask
Ask for user confirmation before starting the copy. If the first letter
of the answer is @samp{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
@w{[@var{model}::@var{serial_number}] (@var{size})}

@item --cpass=@var{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
@samp{--no-trim} and @samp{--no-scrape}. @samp{--cpass=0} skips the
copying phase entirely.

@multitable {Examples of @var{range}} {1, 2, 3 and 5}
@item Examples of @var{range} @tab Passes run
@item 1                       @tab 1
@item 1,2,3                   @tab 1, 2 and 3
@item 2-4                     @tab 2, 3 and 4
@item 1,3-5                   @tab 1, 3, 4 and 5
@item 1-3,5                   @tab 1, 2, 3 and 5
@end multitable

@item --delay-slow=@var{interval}
Initial delay before ddrescue starts checking for slow reads. Defaults
to 30 seconds. @var{interval} is formatted as in the option
@samp{--timeout} above.

@item --log-events=@var{file}
Log all significant events (start of each pass and end of run) in
@var{file}. If @var{file} already exists, the new events are appended at
the end of @var{file}. For each event a line is printed containing a
time stamp, the percentage rescued and a message describing the event.
The @samp{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 @var{file}.

@item --log-rates=@var{file}
Log rates and error sizes every second in @var{file}. If @var{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 @var{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).

@item --log-reads=@var{file}
Log all read operations in @var{file}. If @var{file} already exists, it
will be overwritten. Every read attempt and its result (position, size,
copied size and error size) is written to @var{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 @var{file} may become very large very
quickly. Use lzip to compress @var{file} if you need to store or
transmit it.

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

@item --max-slow-reads=@var{n}
Maximum number of slow reads allowed before giving up. Defaults to
infinity. Exit with status 1 if more than @var{n} slow reads are
encountered during the copying phase. Only works if a minimum read rate
has been set with @samp{--min-read-rate}.

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

@item --pause-on-pass=@var{interval}
Time to wait between passes. Defaults to 0. @var{interval} is formatted
as in the option @samp{--timeout} above.

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

@end table

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 @samp{B} for "byte". The @samp{s} multiplier may be
appended to any of the other multipliers. For example, @samp{ks} means
kilosectors @w{(1000 * sector_size)}, and @samp{Kis} means kibisectors
@w{(1024 * sector_size)}.

Table of SI and binary prefixes (unit multipliers):

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

@sp 1
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 @var{mapfile} and
then terminates by raising the signal received.


@node Mapfile structure
@chapter Mapfile structure
@cindex mapfile structure

NOTE: In versions of ddrescue prior to 1.20 the mapfile was called
@samp{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 @samp{#} 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:

@multitable {Character} {generating approximate mapfile}
@item Character @tab Meaning
@item '?'       @tab copying non-tried blocks
@item '*'       @tab trimming non-trimmed blocks
@item '/'       @tab scraping non-scraped blocks
@item '-'       @tab retrying bad sectors
@item 'F'       @tab filling specified blocks
@item 'G'       @tab generating approximate mapfile
@item '+'       @tab finished
@end multitable

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:

@multitable {Character} {failed block bad-sector(s)}
@item Character @tab Meaning
@item '?'       @tab non-tried block
@item '*'       @tab failed block non-trimmed
@item '/'       @tab failed block non-scraped
@item '-'       @tab failed block bad-sector(s)
@item '+'       @tab finished block
@end multitable

@noindent
And here is an example mapfile:

@example
# Mapfile. Created by GNU ddrescue version @value{VERSION}
# 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  ?
@end example

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.


@node Emergency save
@chapter Saving the mapfile in case of trouble
@cindex emergency save

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:

@example
Error writing mapfile '@var{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.
@end example

You may try to fix the problem, for example deleting some files to make
room for the mapfile, and press @key{Return} to retry.

If the problem can't be fixed, you may press @key{e} followed by
@key{Return} to try an emergency save and exit. Ddrescue will try to
write the mapfile to the file @file{ddrescue.map} in the current
directory or, if this fails, to @file{$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 @key{q} followed by @key{Return} to quit and exit with
status 1. In this case the contents of the mapfile will be lost.


@node Optical media
@chapter Copying CD-ROMs and DVDs
@cindex optical media

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 @samp{sync} conversion and a block size larger than the
sector size are specified.

In some cases, a specialized tool like dvdisaster may be a better option
than ddrescue for recovering data from CD-ROMs 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.
Just 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.

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

@example
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)
@end example

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

@example
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)
@end example

@sp 1
@noindent
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.

@example
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)
@end example

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

@example
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)
@end example

@sp 1
@anchor{lziprecover-example}
@noindent
Example 5: Rescue a lzip compressed backup from two copies on CD-ROM
with error-checked merging of copies.
@ifnothtml
(@xref{Top,lziprecover manual,,lziprecover},
@end ifnothtml
@ifhtml
(See the
@uref{http://www.nongnu.org/lzip/manual/lziprecover_manual.html,,lziprecover manual}
@end ifhtml
for details about lziprecover).

@example
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
@end example


@node Examples
@chapter A small tutorial with examples
@cindex 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 is 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.

@xref{Optical media}, for rescue examples of CD-ROMs and DVDs.

@sp 1
@noindent
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.

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

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

@example
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)
@end example

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

@example
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
@end example

@sp 1
@noindent
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.

@example
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
@end example

@sp 1
@noindent
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.

@example
ddrescue -f -n /dev/sda1 hdimage mapfile     <-- /dev/sda1 fails here
  (restart /dev/sda or reboot computer)
ddrescue -f -n -A -i<pos> /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 of the last block marked as
   non-scraped in the mapfile)
ddrescue -d -f -r3 /dev/sda1 hdimage mapfile
@end example

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

@example
ddrescue -f -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 -f -r3 /dev/sda1 hdimage mapfile
@end example


@node Direct disc access
@chapter Direct disc access
@cindex direct disc access
@cindex raw devices

If you notice that the positions and sizes in @var{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 @var{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 @samp{--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 @samp{--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 @samp{--size} or
@samp{--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.

@sp 1
@noindent
Example 1: using direct disc access.

@example
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
@end example

@sp 1
@noindent
Example 2: using a raw device.

@example
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
@end example


@node Fill mode
@chapter Fill mode
@cindex fill Mode

When ddrescue is invoked with the @samp{--fill-mode} option it operates
in "fill mode", which is different from the default "rescue mode". That
is, if you use the @samp{--fill-mode} option, ddrescue does not rescue
anything. It only fills with data read from @var{infile} the blocks of
@var{outfile} whose status character from @var{mapfile} coincides with
one of the type characters specified as argument to the
@samp{--fill-mode} option.

If the argument of the @samp{--fill-mode} option contains an @samp{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 @var{infile} may have 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 @var{infile} is always read from position 0. If
you specify a @samp{--input-position}, it refers to the original
@var{infile} from which @var{mapfile} was built, and is only used to
calculate the offset between input and output positions.

Note also that when filling the @var{infile} of the original rescue run
you should not set @samp{--output-position}, whereas when filling the
@var{outfile} of the original rescue run you should keep the original
offset between @samp{--input-position} and @samp{--output-position}.

The @samp{--fill-mode} option implies the @samp{--complete-only} option.

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

@sp 1
@noindent
The fill mode has a number of uses. See the following examples:

@noindent
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 @samp{-} (bad-sector) with copies of the string
@w{@samp{BAD SECTOR }}:

@example
printf "BAD SECTOR " > tmpfile
ddrescue --fill-mode=- tmpfile outfile mapfile
@end example

@noindent
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.

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

@noindent
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.

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

@sp 1
@noindent
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 (@samp{+}) and
bad-sector (@samp{-}) 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
@samp{--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.

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

@example
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
@end example


@node Generate mode
@chapter Generate mode
@cindex generate Mode

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

So you didn't read the manual and started ddrescue without a
@var{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 @w{@code{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 @samp{sync} conversion argument.

Don't despair (yet). Ddrescue can in some cases generate an approximate
@var{mapfile}, from @var{infile} and the (partial) copy in
@var{outfile}, that is almost as good as an exact @var{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 @var{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:
@example
ddrescue infile outfile
or
dd if=infile of=outfile conv=noerror,sync
@end example

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

@noindent
Note that you must keep the original offset between
@samp{--input-position} and @samp{--output-position} of the original
rescue run.


@node Ddrescuelog
@chapter Ddrescuelog
@cindex 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.

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

@example
ddrescue -f /dev/sda /dev/sdb mapfile
ddrescuelog -d mapfile
@end example

@sp 1
@noindent
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.

@example
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
@end example

@sp 1
@noindent
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 @samp{-i} and @samp{-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.

@example
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
@end example


@node Invoking ddrescuelog
@chapter Invoking ddrescuelog
@cindex invoking ddrescuelog

The format for running ddrescuelog is:

@example
ddrescuelog [@var{options}] @var{mapfile}
@end example

Use @samp{-} as @var{mapfile} to read the mapfile from standard input
(also in the options taking a mapfile argument) or to write the mapfile
created by @samp{--create-mapfile} to standard output.

Ddrescuelog supports the following options:

@table @code
@item -h
@itemx --help
Print an informative help message describing the options and exit.

@item -V
@itemx --version
Print the version number of ddrescuelog on the standard output and exit.

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

@item -A
@itemx --annotate-mapfile
Add comments containing the human-readable positions and sizes of the
blocks in @var{mapfile} which are included in the rescue domain, and
write the resulting mapfile to standard output.

@item -b @var{bytes}
@itemx --block-size=@var{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.

@item -B
@itemx --binary-prefixes
Show units with binary prefixes (powers of 1024).@*
SI prefixes (powers of 1000) are used by default. (See table above,
@ref{Invoking ddrescue}).

@item -c[@var{type1}@var{type2}]
@itemx --create-mapfile[=@var{type1}@var{type2}]
Create a @var{mapfile} from a list of block numbers read from standard
input. Only blocks included in the rescue domain will be added to
@var{mapfile}.

@var{type1} and @var{type2} are block status characters as defined in
the chapter Mapfile structure (@pxref{Mapfile structure}). @var{type1}
sets the type for blocks included in the list, while @var{type2} sets
the type for the rest of @var{mapfile}. If not specified, @var{type1}
defaults to @samp{+} and @var{type2} defaults to @samp{-}.

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

@item -d
@itemx --delete-if-done
Delete the given @var{mapfile} if all the blocks in the rescue domain
have been successfully recovered. The exit status is 0 if @var{mapfile}
could be deleted, 1 otherwise.

@item -D
@itemx --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.

@item -f
@itemx --force
Force overwrite of @var{mapfile}.

@item -i @var{bytes}
@itemx --input-position=@var{bytes}
Starting position of the rescue domain, in bytes. Defaults to 0. It
refers to a position in the original @var{infile}.

@item -l @var{types}
@itemx --list-blocks=@var{types}
Print on standard output the block numbers of the blocks specified as
any of @var{types} in @var{mapfile} and included in the rescue domain.
@var{types} contains one or more of the block status characters defined
in the chapter Mapfile structure (@pxref{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.

@item -L
@itemx --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.

@item -m @var{file}
@itemx --domain-mapfile=@var{file}
Restrict the rescue domain to the blocks marked as finished in the
mapfile @var{file}.

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

@item -o @var{bytes}
@itemx --output-position=@var{bytes}
Starting position of the image of the rescue domain in the original
@var{outfile}, in bytes. Is used by the @samp{--list-blocks} option.
Defaults to @samp{--input-position}.

@item -p @var{file}
@itemx --compare-mapfile=@var{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 @var{file} and
@var{mapfile}, 1 otherwise.

@item -P @var{file}
@itemx --compare-as-domain=@var{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
@var{file} and @var{mapfile}, 1 otherwise. Two files comparing equal
with this option are equivalent when used as domain mapfiles.

@item -q
@itemx --quiet
Quiet operation. Suppress all messages.

@item -s @var{bytes}
@itemx --size=@var{bytes}
Maximum size of the rescue domain, in bytes. It refers to a size in the
original @var{infile}.

@item -t
@itemx --show-status
Print a summary of the contents of each @var{mapfile} to the standard
output. This option allows more than one @var{mapfile}. If the domain
setting options are used, the summary can be restricted to one or
several parts of @var{mapfile}.

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

@item -x @var{file}
@itemx --xor-mapfile=@var{file}
Perform a logical XOR (exclusive OR) operation between the finished
blocks in @var{file} and those in @var{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.

@item -y @var{file}
@itemx --and-mapfile=@var{file}
Perform a logical AND operation between the finished blocks in
@var{file} and those in @var{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.

@item -z @var{file}
@itemx --or-mapfile=@var{file}
Perform a logical OR operation between the finished blocks in @var{file}
and those in @var{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.

@end table

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.


@node Problems
@chapter Reporting bugs
@cindex bugs
@cindex getting help

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
@email{bug-ddrescue@@gnu.org}. Include the version number, which you can
find by running @w{@code{ddrescue --version}}.


@node Concept index
@unnumbered Concept index

@printindex cp

@bye
