\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 5 January 2025
@set VERSION 1.29

@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

@ifnottex
@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
* Output::                Meaning of ddrescue's screen output
* Invoking ddrescue::     Command-line interface
* Argument syntax::       By convention, options start with a hyphen
* 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
* Command mode::          Copying parts of the input file on demand
* 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-2025 Antonio Diaz Diaz.

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


@node Introduction
@chapter Introduction
@cindex introduction

@uref{http://www.gnu.org/software/ddrescue/ddrescue.html,,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
efficiently, (only the blocks needed 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 blocks needed are read from the second and successive copies.

Ddrescue recommends @uref{http://www.nongnu.org/lzip/lzip.html,,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 reads as many sectors
as it can, while lziprecover uses other data to repair the sectors that
ddrescue was not able to read). If the cause of file corruption is a damaged
medium, the combination @w{ddrescue + lziprecover} is the recommended option
for recovering data from damaged files. @xref{lziprecover-example},
@ref{lziprecover-example2}, and @ref{lziprecover-example3}, for examples.
@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.

Because ddrescue needs to read and write at random places, it only works on
seekable (random access) input and output files. Therefore, the only way of
creating a compressed image with ddrescue is to create a normal
(uncompressed) image first, and then compress that image.

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

One of the 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).

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.


@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. @file{/dev/hda}, @file{/dev/sdb}, are device names
(file names associated to devices).

@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. @file{/dev/hda1}, @file{/dev/sdb3}, are partition names (file
names associated to partitions).

@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 may
define it with the options @option{--input-position}, @option{--size}, and
@option{--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 @w{8 EiB} minus 1 byte).

Ddrescue never tries to read any data outside 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 data shown by ddrescue (amount of data rescued, number of bad areas,
etc) 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 rescue domain
specified.

@item Sector
Hardware block. Smallest accessible amount of data on a block 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 (for example, udev enabled
systems). If you reboot such a system, pass the option @option{--ask} to
ddrescue and check that the device names match the model and serial number
of the input and output devices before allowing ddrescue to proceed. You may
also check the devices with commands like @w{@samp{hdparm -I /dev/sda}} or
@w{@samp{smartctl -i /dev/sda}}.

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.

When using a (graphical) frontend, be careful to not insert or remove any
devices to avoid changes in the mapping of devices to device names between
the moment the devices are selected in the frontend and the call to
ddrescue. Be careful even if the frontend passes @option{--ask} to ddrescue,
because @var{outfile} may be changed between user confirmation and actual
opening.

It is recommended to run ddrescue on a POSIX system, but if you run it on
Cygwin be prepared to find mysterious 'Permission denied' error messages
caused by Windows returning misleading error codes and then Cygwin mapping
some of those error codes to EACCES, making it impossible for ddrescue to
know what failed, or even whether the error is fatal or not.
@xref{--continue-on-errno}.


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

Versions of ddrescue prior to 1.19 used a divide-and-conquer strategy to
rescue the difficult parts of the drive. But that caused a lot of head
movement, which is bad for the drive. Therefore, newer versions try to
minimize head movement to minimize drive damage.

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 divided in four phases: copying, trimming,
scraping, and retrying. Each phase is described below. Disc sectors are
marked successively as non-tried, non-trimmed, non-scraped, and bad-sector
until they are successfully read and marked as finished. The user may
interrupt the process at any point, but a bad drive can block ddrescue for a
long time until the kernel gives up.

The amount of work remaining for a given phase can be calculated by
comparing the current size of the corresponding areas with their size at the
end of the previous pass. Namely the size of non-tried while copying, the
size of non-trimmed while trimming, the size of non-scraped while scraping,
and the size of bad-sector while retrying. @xref{Output}.

The steps of the algorithm are:

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 runs in the
opposite direction as the first pass and delimits the blocks skipped by the
first pass. The first two passes also skip beyond slow areas. The areas
skipped 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 the copying 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 retries sector by sector the edges of
the large block reads failed during the copying phase. Trimming is done in
one pass as follows. 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, sector by sector, 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 number of retry passes specified 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
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
@file{.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.
@xref{--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:

@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 Output
@chapter Meaning of ddrescue's screen output
@cindex output

The output of ddrescue looks like this:

@example
GNU ddrescue @value{VERSION}
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)
@end example

Ddrescue scrolls forward after each pass. This keeps on the screen the final
status of the previous pass, making it easier to estimate the amount of work
done by the current pass.

The meaning of each field is as follows:

@table @code
@item ipos
Input position. The position in the input file where data are being
currently read from.

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

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

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

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

@item slow reads
Number of times that the read rate fell below @option{--min-read-rate}
during the first two passes of the copying phase. @xref{--min-read-rate}.

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

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

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

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

@item bad areas
Number of separate bad-sector blocks inside the rescue domain. Non-trimmed
and non-scraped blocks are not considered bad areas. @xref{--max-bad-areas}.

@item read errors
Number of failed read attempts. @xref{--max-error-rate}.

@item current rate
The read rate measured during the last second.

@item average rate
The average read rate measured during the current run.

@item error rate
The read error rate measured during the last second.

@item run time
Time elapsed since the beginning of the current run.

@item 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 @option{--no-trim}), or that some
areas may be unrecoverable. Therefore it may be imprecise, may vary widely
during the rescue, and may show a nonzero 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.

@item time since last successful read
Time elapsed since the last successful read attempt.

@end table


@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 creates it. Be careful to not
specify by mistake an old @var{mapfile} from an unrelated rescue.

Ddrescue tries to create a backup copy of the mapfile, with the name
@var{mapfile}.bak, every time it is going to overwrite a fsynced
@var{mapfile}. @xref{--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.

@noindent
ddrescue supports the following options: @xref{Argument syntax}.

@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.
This version number should be included in all bug reports.

@anchor{--min-read-rate}
@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 during the first two passes of the copying
phase, ddrescue skips ahead a variable amount depending on rate and
error histories. The blocks skipped are tried in additional passes (before
trimming). @option{--min-read-rate} is ignored in all passes but the first two.

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

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

In rescue mode, any non-finished subsector that is found during the initial
read of the mapfile is joined to its corresponding sector (if it is also not
finished), marking the whole sector with the less processed state, so as to
make sure that sub-sector data is not discarded from a successful read
during the rescue. (A subsector is a block smaller than sector size).
Subsector joining is performed in all the mapfile, not only in the rescue
domain.

@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. @option{-C} can only be
used after a first rescue attempt, possibly limited with the option
@option{--size}, has produced a complete @var{mapfile}. If @option{-C} is
not specified, ddrescue extends the @var{mapfile} from position 0 to the
size of @var{outfile}, adding one non-tried block before the existing blocks
and another one after them if needed.

@item -d
@itemx --idirect
Use direct disc access to read from @var{infile}, bypassing the kernel
cache. (Opens the file with the flag @samp{O_DIRECT}). Sector size must be
correctly set for this to work. Not all systems support this.
@xref{Direct disc access}.

If your system does not support direct disc access, ddrescue warns you. If
the sector size is not correctly set, an unaligned read error may happen, in
which case ddrescue exits with error status 1.

@item -D
@itemx --odirect
Use direct disc access to write to @var{outfile}, bypassing the kernel
cache. (Opens the file with the flag @samp{O_DIRECT}). 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 warns you. If
the sector size is not correctly set, a write error is reported and no data
is 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}.

@anchor{--max-bad-areas}
@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}.
@xref{--max-read-errors}.

@anchor{--max-error-rate}
@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 @option{--input-position} and @option{--output-position}
of the original rescue run. See the chapter Generate mode (@pxref{Generate
mode}) for a complete description of the generate mode.

@anchor{--test-mode}
@item -H @var{file}
@itemx --test-mode=@var{file}
Build a map of good/bad blocks using the mapfile @var{file} and use it to
simulate read errors in @var{infile}. The blocks marked as finished in
@var{file} are read normally. All other block types are 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 check that
ddrescue produces accurate results in presence of read errors. Use a hyphen
@samp{-} as @var{file} to read the mapfile from standard input.
@xref{--pause-on-error}.

@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 option @option{--reverse} 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 --check-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 --check-on-error
After every read error, read again the last good sector found and check 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 are rounded to the next multiple of
sector size. The skip size is 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 is reset to @var{initial} when good data are 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 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.

@option{--skip-size} is independent from @option{--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 may be unordered, may overlap other blocks of the
same status, and 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 a hyphen
@samp{-} as @var{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.

@anchor{--retrim}
@item -M
@itemx --retrim
Mark all failed blocks inside the rescue domain as non-trimmed before
beginning the rescue. The effect is similar to @option{--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 @option{--input-position}. The bytes below @var{bytes}
aren't touched if they exist and truncation is not requested. Else they are
set to 0.

@anchor{--reopen-on-error}
@item -O
@itemx --reopen-on-error
Close @var{infile} and then reopen it after every read error encountered. If
@option{--min-read-rate} is set, also close and reopen @var{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. This option may also be
needed to reset the error status of the input device when using the option
@option{--continue-on-errno}. @xref{--min-read-rate}, @ref{--continue-on-errno}.

@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 options
@option{--input-position}, @option{--output-position}, @option{--size}, and
@option{--domain-mapfile}.

@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. The direction is
reversed after each pass. To retry bad sectors detected on a previous run,
you must specify a nonzero number of retry passes.

A command like @w{@samp{ddrescue -f -r-1 /dev/sdcard /dev/null mapfile}} can
be used to read repeatedly until the device controller succeeds and remaps
the bad sectors internally.

@item -R
@itemx --reverse
Reverse the direction of all passes (copying, trimming, scraping, and
retrying). Every pass that is normally run forwards is now run backwards,
and vice versa. @option{-R} 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. -1 removes any previous size limit. 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. Use this option only
with an empty or zeroed @var{outfile} because if a block in @var{outfile}
contains nonzero data, it won't be overwritten by a corresponding block of
zeros in @var{infile}, resulting in a corrupt copy.

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

@anchor{--timeout}
@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. @xref{--max-read-errors}.

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

@item -v
@itemx --verbose
Verbose mode. Further -v's (up to 4) increase the verbosity level.
Some large numbers in messages (like device sizes) are printed in groups of
3 digits separated by underscore characters to make them more readable.

@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, which means that the rescue
needs to be repeated or else @var{outfile} needs to be copied to a third
drive using @var{mapfile} as domain. @xref{--domain-mapfile}.

@item -W
@itemx --compare-before-write
Omit superfluous writes in rescue mode. Before writing each block of data to
@var{outfile}, compare the data already present there with the data about to
be written and, if they match, omit the write. Possible advantages are that
on some devices reads are faster than writes and it may reduce wear when
writing to a solid state device.

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

@anchor{--max-read-errors}
@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. @option{--max-read-errors=0} is similar but different to
@option{--timeout=0}, which waits until the screen status is refreshed (at
least 1 second). If there is at least one successful read per second,
@option{--timeout=0} does not make ddrescue to exit. @xref{--timeout}.

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

@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. Use
it to make sure that all writes have been committed to disc when ddrescue
finishes. Else the kernel may cache all the writes and pretend that it has
finished.

@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 --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
@option{--data-preview}) or the automatic algorithm (like @option{--max-errors}
or @option{--reverse}) have no effect in command mode. @xref{Command mode},
for a complete description of the command mode.

@anchor{--continue-on-errno}
@item --continue-on-errno=@var{code}[,@var{code}]...
Treat errno code @var{code} as non-fatal. This option may be useful on
systems that incorrectly return fatal errno codes for non-fatal errors. If
ddrescue exits because of a fatal read error, it prints in the final message
the value of the variable 'errno', which can then be used as argument to
this option. Multiple errno values may be specified with cumulative effect,
either in the same argument, or by specifying multiple instances of this
option. The option @option{--reopen-on-error} may be needed when using this
option. @xref{--reopen-on-error}.

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

@multitable {Examples of @var{range}} {1, 2, 3, 5}
@headitem Examples of @var{range} @tab Passes run
@item 1     @tab 1
@item 1,2,3 @tab 1, 2, 3
@item 2-4   @tab 2, 3, 4
@item 1,3-5 @tab 1, 3, 4, 5
@item 1-3,5 @tab 1, 2, 3, 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 @option{--timeout}
above. @xref{--timeout}.

@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 is 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 is
overwritten. Every read attempt and its result (position, size, copied size,
error size, and errno (if different from EIO)) 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.

@anchor{--mapfile-interval}
@item --mapfile-interval=[@var{save_interval}][,@var{sync_interval}]
Change the interval at which ddrescue saves and fsyncs the @var{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 @var{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.
@var{sync_interval} must be greater or equal than @var{save_interval}.
Intervals are formatted as in the option @option{--timeout} above.
@xref{--timeout}.

In practice, fsyncs are a subset of saves. I.e., some of the times when the
@var{mapfile} is saved, it is also fsync'ed. Therefore,
@option{--mapfile-interval=30,45} is really @option{--mapfile-interval=30,60}.
The time needed to write the @var{mapfile} is excluded from the mapfile save
and sync intervals. (Some mapfiles may take several seconds to write).

@anchor{--max-slow-reads}
@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 first two passes of the copying phase. Only works if a minimum read rate
has been set with @option{--min-read-rate}. @xref{--min-read-rate}.

@anchor{--pause-on-error}
@item --pause-on-error=@var{interval}
Time to wait after each read error. Also after each slow read if a minimum
read rate has been set with @option{--min-read-rate}. Defaults to 0.
@var{interval} is formatted as in the option @option{--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 @option{--test-mode} for
testing purposes. @xref{--min-read-rate}, @ref{--test-mode}, @ref{--timeout}.

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

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

@item --same-file
Allow @var{infile} and @var{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 @option{--input-position} and
@option{--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.

@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)}
@headitem 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)
@item R @tab ronnabyte  (10^27)       @tab | @tab Ri @tab robibyte  (2^90)
@item Q @tab quettabyte (10^30)       @tab | @tab Qi @tab quebibyte (2^100)
@end multitable

@sp 1
Exit status: 0 for a normal exit, 1 for environmental problems
(file not found, invalid command-line options, I/O errors, etc), 2 to
indicate a corrupt or invalid input file, 3 for an internal consistency
error (e.g., 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 Argument syntax
@chapter Syntax of command-line arguments
@cindex argument syntax

POSIX recommends these conventions for command-line arguments.

@itemize @bullet
@item A command-line argument is an option if it begins with a hyphen
(@samp{-}).

@item Option names are single alphanumeric characters.

@item Certain options require an argument.

@item An option and its argument may or may not appear as separate tokens.
(In other words, the whitespace separating them is optional).
Thus, @w{@option{-o foo}} and @option{-ofoo} are equivalent.

@item One or more options without arguments, followed by at most one option
that takes an argument, may follow a hyphen in a single token.
Thus, @option{-abc} is equivalent to @w{@option{-a -b -c}}.

@item Options typically precede other non-option arguments.

@item The argument @samp{--} terminates all options; any following arguments
are treated as non-option arguments, even if they begin with a hyphen.

@item A token consisting of a single hyphen character is interpreted as an
ordinary non-option argument. By convention, it is used to specify standard
input, standard output, or a file named @samp{-}.
@end itemize

@noindent
GNU adds @dfn{long options} to these conventions:

@itemize @bullet
@item A long option consists of two hyphens (@samp{--}) followed by a name
made of alphanumeric characters and hyphens. Option names are typically one
to three words long, with hyphens to separate words. Abbreviations can be
used for the long option names as long as the abbreviations are unique.

@item A long option and its argument may or may not appear as separate
tokens. In the latter case they must be separated by an equal sign @samp{=}.
Thus, @w{@option{--foo bar}} and @option{--foo=bar} are equivalent.
@end itemize

@noindent
The syntax of options with an optional argument is
@option{-<short_option><argument>} (without whitespace), or
@option{--<long_option>=<argument>}.


@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 also contains 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}
@headitem 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 the blocks specified
@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)}
@headitem 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 prints 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 tries 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 successfully,
ddrescue exits with status 1. Else it prints 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 content of the mapfile is 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 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 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.

@noindent
Example 1: Rescue a CD-ROM in @file{/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 @file{/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 @file{/dev/cdrom} using two CD drives from two
different computers, writing the image into an USB drive mounted on
@file{/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: Recover a lzip compressed backup from two copies on CD-ROM with
error-checked merging of copies.

@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 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 @file{/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 @file{/dev/sda} to @file{/dev/sdb}.@*
Note: you don't need to partition @file{/dev/sdb} beforehand, but if the
partition table on @file{/dev/sda} is damaged, you'll need to recreate it
somehow on @file{/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 @file{/dev/sda2} to @file{/dev/sdb2}.@*
Note: you need to create the partition sdb2 with fdisk first. sdb2 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 @file{/dev/sda} to
@file{/dev/sdb}, @file{/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 @file{/dev/sda} to
@file{/dev/sdb}, @file{/dev/sdb} fails and you have to rescue the data to a
third drive, @file{/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 @file{/dev/sda1} to the file
@file{hdimage}, @file{/dev/sda1} stops responding and begins returning read
errors, causing ddrescue to mark the rest of the partition as non-scraped.

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

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

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

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

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

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

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

@sp 1
@anchor{lziprecover-example2}
@noindent
Example 9: Recover a collection of photos from a damaged external drive
(@file{/dev/sdc1}). The photos are protected with forward error correction
(fec) files created by lziprecover. The photos are in directory @file{photos},
and the fec files are in directory @file{photos-fec}.

@example
ddrescue -b4096 -r10 /dev/sdc1 hdimage mapfile
mount -o loop,ro hdimage /mnt/hdimage
cp -a /mnt/hdimage/photos photos
cp -a /mnt/hdimage/photos-fec photos-fec
umount /mnt/hdimage
lziprecover -v -Fr --fec-file=photos-fec/ photos/*
  (Check and rename repaired files. They are named @file{photos/*_fixed})
@end example

@sp 1
@anchor{lziprecover-example3}
@noindent
Example 10: Recover a damaged backup with a zeroed sector of 4096 bytes at
file position 1019904, using as reference a previous backup. The damaged
backup comes from a damaged partition copied with ddrescue.

@example
ddrescue -b4096 -r10 /dev/sdc1 hdimage mapfile
mount -o loop,ro hdimage /mnt/hdimage
cp /mnt/hdimage/backup.tar.lz backup.tar.lz
umount /mnt/hdimage
lzip -t backup.tar.lz
  backup.tar.lz: Decoder error at pos 1020530
lziprecover -vv -e --reference-file=old_backup.tar backup.tar.lz
Reproducing bad area in member 1 of 1
  (begin = 1019904, size = 4096, value = 0x00)
  (master mpos = 1019903, dpos = 5857954)
warning: old_backup.tar: Partial match found at offset 5743778, len 9546.
Reference data may be mixed with other data.
Trying level -9
  Reproducing position 1015808
Member reproduced successfully.
Copy of input file reproduced successfully.
@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 option @option{--sector-size}
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 tries to read data outside the rescue domain.

Try the option @option{--idirect} 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 @file{/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 option @option{--size} or @option{--complete-only} 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.

@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 Command mode
@chapter Copying parts of the input file on demand
@cindex command mode

The command mode of ddrescue implements a scripting interface similar to
the one of @uref{http://www.gnu.org/software/ed/manual/ed_manual.html,,ed}.
@ifnothtml
@xref{Top,ed manual,,ed}.
@end ifnothtml
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
@w{"error: @var{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 the @samp{f} (finish) 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:

@table @code

@item c @var{pos} @var{size}
Copy command. Copies a block of data from @var{infile} to @var{outfile} and
updates the internal copy of the mapfile. The areas already marked as
finished in the mapfile are not copied again.

@item f
Finish command. Compacts the internal copy of the mapfile and writes it to
@var{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 @var{mapfile}
to disc fails, a non-interactive emergency save is tried before exiting.
@xref{Emergency save}.

@item q
Quit command. Exits ddrescue. Does not update the mapfile.

@item s @var{pos} @var{size}
Status command. Writes to standard output one or more lines in mapfile
format (@pxref{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.

@item u
Update mapfile command. Writes the internal copy of the mapfile to
@var{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 @var{mapfile}, before trying to update it again.

@end table


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

When ddrescue is invoked with the option @option{--fill-mode} it operates in
'fill mode', which is different from the default 'rescue mode'. That is, in
'fill mode' 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 in the
argument to @option{--fill-mode}.

If the argument to @option{--fill-mode} contains an @samp{l}, ddrescue
writes 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 the location of the error is known by
looking into the unfinished copy of the file.

In fill mode @var{infile} does not need to be seekable and it may be of any
size. If it is too small, the data is 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 is read. Then the same data is 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 @option{--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 @option{--output-position}, whereas when filling the
@var{outfile} of the original rescue run you should keep the original offset
between @option{--input-position} and @option{--output-position}.

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

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.

@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
ddrescue --fill-mode=- <(printf "BAD-SECTOR ") outfile mapfile
@end example

And the following command line fills all the non-finished areas in the
destination file with copies of the string @w{@samp{NON-RESCUED-SECTOR }}:

@example
ddrescue --fill-mode='?*/-' <(printf "NON-RESCUED-SECTOR ") 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

@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
@option{--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 option @option{--generate-mode} it operates
in 'generate mode', which is different from the default 'rescue mode'. That
is, in 'generate mode' 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{@samp{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
nonzero.

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 @option{--input-position}
and @option{--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. Other blocks
are left untouched.

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

@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 @file{/dev/sda} to @file{/dev/sdb}
and repair the file systems using badblocks lists generated with ddrescuelog.
File system block size is 4096.@*
Note: you do need to partition @file{/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
@anchor{double-b}
@noindent
Example 3: Rescue a whole disc with two ext2 partitions in @file{/dev/sda}
to @file{/dev/sdb} and repair the file systems using badblocks lists
generated with ddrescuelog. Disc sector size is 512 (first @option{-b}),
file system block size is 4096 (second @option{-b}). Arguments to options
@option{-i} and @option{-s} are the starting positions and sizes of the
partitions being rescued.@*
Note: you don't need to partition @file{/dev/sdb} beforehand, but if the
partition table on @file{/dev/sda} is damaged, you'll need to recreate it
somehow on @file{/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 a hyphen @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 @option{--create-mapfile} to standard output.

@noindent
ddrescuelog supports the following options: @xref{Argument syntax}.

@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.
This version number should be included in all bug reports.

@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
command @samp{tr} 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}
@itemx --sector-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. The position of each option @option{-b} in the
command line is significant; it changes the sector size for the following
options until a new option @option{-b} appears in the command line.
@xref{double-b}.

@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 sectors read from standard input. The
option @option{--format} determines the format of the input: either a list
of sector numbers, or a bitmap. The sector numbers may be unordered. Only
sectors included in the rescue domain are added to @var{mapfile}. If the
mapfile is being created displaced from the input domain, the offset between
@option{-i} and @option{-o} must be a multiple of the sector size. In this
case, remember to specify @option{-o} because it defaults to the same value
given to @option{-i}, producing a default offset of 0.

@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. If the mapfile is read from standard input, behave
like @option{--done-status}. (There is nothing to delete).

@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 -F @var{name}
@itemx --format=@var{name}
Select the input format for @option{--create-mapfile}, or the output format
for @option{--list-blocks}. The valid names are @samp{list}, @samp{bitmap},
@samp{bitmap-be} (big endian), and @samp{bitmap-le} (little endian). Plain
@samp{bitmap} is equivalent to @samp{bitmap-le}. The default format is
@samp{list} (a list of block numbers). In a big endian bitmap the first
block is represented by the most significant bit of the first byte. In a
little endian bitmap the first block is represented by the least significant
bit of the first byte.

@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}
By default print on standard output the sector numbers of the blocks
specified as any of @var{types} in @var{mapfile} and included in the rescue
domain. The list format is one sector number per line in decimal, like the
output of the program @samp{badblocks}, so that it can be used as input for
e2fsck or other similar filesystem repairing tool.

If a bitmap @option{--format} is specified, write to standard output a
bitmap of the endianness chosen, with ones for the sectors specified and
zeros for sectors from other block types. The bits set to 1 in the bitmap
should be equivalent to the list of blocks.

@var{types} contains one or more of the block status characters defined in
the chapter Mapfile structure (@pxref{Mapfile structure}). If the output
numbers or bits are being created displaced from their position in the input
domain, the offset between @option{-i} and @option{-o} must be a multiple of
the block size. In this case, remember to specify @option{-o} because it
defaults to the same value given to @option{-i}, producing a default offset
of 0.

A sector is listed (or set to 1 in bitmap output) if selected, even
partially. (The positions and sizes of the mapfile blocks are not required
to be multiples of the sector size).

@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 may be unordered, may overlap
other blocks of the same status, and 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. @option{--invert-mapfile} is equivalent to
@option{--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. It is used by the options @option{--create-mapfile},
@option{--list-blocks}, and @option{--shift}. Defaults to
@option{--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}. -1 removes any previous size limit.

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

@item --shift
Shift the positions of all the blocks in @var{mapfile} by the offset
@w{(@option{--output-position} - @option{--input-position})}, and write the
resulting mapfile to standard output. Either @option{--input-position} or
@option{--output-position} must be 0. Any blocks beyond the end of the
rescue domain are removed before performing the shift. The remaining blocks
are shifted even if they are outside the rescue domain. If the offset is
positive, a non-tried block is inserted before the first block to fill the
gap.

@end table

Exit status: 0 for a normal exit, 1 for environmental problems
(file not found, invalid command-line options, I/O errors, etc), 2 to
indicate a corrupt or invalid input file, 3 for an internal consistency
error (e.g., 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{@samp{ddrescue --version}}.


@node Concept index
@unnumbered Concept index

@printindex cp

@bye
