\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 11 June 2012
@set VERSION 1.16

@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
* Algorithm::             How ddrescue recovers the data
* Invoking Ddrescue::     Command line interface
* Logfile Structure::     Detailed format of the logfile
* 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 logfile
* Ddrescuelog::           Tool for ddrescue logfiles
* Invoking Ddrescuelog::  Command line interface
* Problems::              Reporting bugs
* Concept Index::         Index of concepts
@end menu

@sp 1
Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
2012 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 hard to rescue
data 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, read the log, run it
backwards, etc.

If you use the logfile 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.

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 damaged
areas at the same places on different input files is very low. Using
the logfile, only the needed blocks are read from the second and
successive copies.

Ddrescue recommends lzip for compression of backups because of its
reliability and data recovery capabilities, including error-checked
merging of backup copies. The combination ddrescue + lziprecover is the
best option for recovering data from multiple damaged copies.
@xref{lziprecover-example}, for an example.

Recordable CD and DVD media keep their data only for a finite time
(typically for many 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/DVD you burn so
that you can later recover them with ddrescue.

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.


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

@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 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. DVDs can be mounted and they 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{--max-size}
and @samp{--domain-logfile}. The rescue domain defaults to the whole
input file or logfile.

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

@end table


@node Algorithm
@chapter Algorithm
@cindex algorithm

GNU 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 switch to small size reads when they find errors, but
they still read the data sequentially. 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 logfile describing the status of a multi-part or
previously interrupted rescue. If no logfile is specified or is empty or
does not exist, mark all the rescue domain as non-tried.

2) Read the non-tried parts of the input file, marking the failed blocks
as non-trimmed and skipping beyond them, until all the rescue domain is
tried. Only non-tried areas are read in large blocks. Trimming,
splitting and retrying are done sector by sector. Each sector is tried
at most two times; the first in this step as part of a large block read,
the second in one of the steps below as a single sector read.

3) Read backwards one sector at a time the non-trimmed blocks, until a
bad sector is found. For each non-trimmed block, mark the bad sector
found as bad-sector and mark the rest of that block as non-split.

4) Read forwards one sector at a time the non-split blocks, marking the
bad sectors found as bad-sector. After a number of consecutive bad
sectors is found in a block large enough, the block is split by half and
the reading continues on the second half. This recursively splits the
largest failed blocks without producing a logfile too large.

5) Optionally try to read again the bad sectors until the specified
number of retries is reached.

6) Optionally write a logfile for later use.

@sp 1
Note that as ddrescue splits the failed blocks, making them smaller, the
total error size may diminish while the number of errors increases.

The logfile 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.

Also, the same logfile 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/hdc hdimage logfile
ddrescue -i0 -s1MiB -d -r3 /dev/hdc hdimage logfile
@end example

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

@noindent
Now rescue the rest (does not recopy what is already done).
@example
ddrescue /dev/hdc hdimage logfile
ddrescue -d -r3 /dev/hdc hdimage logfile
@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{logfile}]
@end example

ddrescue supports the following options:

@table @samp
@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 history. The skipped blocks are tried
in additional passes (before trimming) where the minimum read rate is
divided by ten before each pass, until there are no more non-tried
blocks left. If @var{bytes} is 0 (auto), the minimum read rate is
recalculated for each block read as @w{(average_rate / 10)}.

Note that specifying a minimum read rate above the posibilities of the
input device will result in a very low average rate because all reads
will be considered slow reads and continuous skipping will occur. This
will also make the logfile grow disproportionately.

@item -A
@itemx --try-again
Mark all non-split and non-trimmed blocks inside the rescue domain as
non-tried before beginning the rescue. Try this if the drive stops
responding and ddrescue immediately starts splitting 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 --block-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{logfile}. Do not
read new data beyond @var{logfile} limits. This is useful when reading
from devices of undefined size, like raw devices, or when the drive
returns an incorrect size. It can only be used after a first rescue
attempt, possibly limited with the @samp{--max-size} option, has
produced a complete @var{logfile}.

@item -d
@itemx --direct
Use direct disc access to read from @var{infile}, bypassing the kernel
cache. (Open the file with the O_DIRECT flag). Use it only on devices or
partitions, not on regular files. 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, all reads will result in
errors, and no data will be rescued.

@item -D
@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 -e [+]@var{n}
@itemx --max-errors=[+]@var{n}
Maximum number of error areas allowed before giving up. Defaults to
infinity. If @var{n} is preceded by @samp{+} the number refers to new
error areas found in this run, not counting those already annotated in
the @var{logfile}.

@item -E @var{bytes}
@itemx --max-error-rate=@var{bytes}
Maximum rate of errors allowed before giving up, in bytes per second.
Defaults to infinity. The rate being measured is that of actually failed
reads, so the rescue may finish because of this rate being exceeded even
if the total error size (errsize) does not change because the areas
being tried are already marked as errors.

@item -f
@itemx --force
Force overwrite of @var{outfile}. Needed when @var{outfile} is not a
regular file, but a device or partition.

@item -F @var{types}
@itemx --fill=@var{types}
Fill the blocks in @var{outfile} specified as any of @var{types} in
@var{logfile}, with data read from @var{infile}. @var{types} contains
one or more of the status characters defined in the chapter Logfile
Structure (@pxref{Logfile Structure}). See the chapter Fill Mode
(@pxref{Fill Mode}) for a complete description of the fill mode.

@item -g
@itemx --generate-logfile
Generate an approximate @var{logfile} 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 -i @var{bytes}
@itemx --input-position=@var{bytes}
Starting position in @var{infile}, in bytes. Defaults to 0. 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{logfile}, 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{logfile} may be incomplete, for example after doing a partial
rescue.

@item -K @var{bytes}
@itemx --skip-size=@var{bytes}
Set the initial size to skip on the first read error or slow read. The
value given will be rounded to the next multiple of sector size. For
subsequent read errors or slow reads, ddrescue will modify the skip size
depending on error rate and error history. Valid values range from 64 KiB
to 1 GiB. Defaults to 64 KiB.

@item -m @var{file}
@itemx --domain-logfile=@var{file}
Restrict the rescue domain to the blocks marked as finished in the
logfile @var{file}. This is useful if the destination drive fails during
the rescue.

@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{--max-retries=1},
but the bad sectors are tried in a different order, making perhaps
possible to rescue some of them.

@item -n
@itemx --no-split
Skip the splitting pass. Avoids spending a lot of time trying to rescue
the most difficult parts of the file.

@item -o @var{bytes}
@itemx --output-position=@var{bytes}
Starting position 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 -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{--max-size}, and @samp{--domain-logfile} options.

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

@item -r @var{n}
@itemx --max-retries=@var{n}
Exit after given number of retry passes. Defaults to 0. -1 means
infinity. Every bad sector is tried only one time per pass. To retry bad
sectors detected on a previous run, you must specify a non-zero number
of retries.

@item -R
@itemx --reverse
Reverse direction of all copy operations. This makes copying, splitting
and retrying to be run backwards, and trimming to be run forwards.

@item -s @var{bytes}
@itemx --max-size=@var{bytes}
Maximum size of the input data to be copied, in bytes. If ddrescue can't
determine the size of the input device, you may need to specify it with
this option. Note that this option specifies the size of the input data
to be copied, not the size of the resulting @var{outfile}. So, 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 logfile
@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 a 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.

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

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

@end table

@sp 1
Numbers given as arguments to options (positions, sizes, retries, etc)
may be followed by a multiplier and an optional @samp{B} for "byte".

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   @tab                          @tab | @tab b  @tab hardware blocks
@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
Return values: 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.


@node Logfile Structure
@chapter Logfile Structure
@cindex logfile structure

The logfile 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.

Any line beginning with @samp{#} is a comment line. The blocks in the
list of data blocks must be contiguous and non-overlapping.

NOTE: Logfiles generated by a version of ddrescue prior to 1.6 lack the
status line. If you want to use an old logfile with ddrescue 1.6 or
later, you will have to insert a line like @samp{0 +} at the beginning
of the logfile.

The heading comments contain the version of ddrescue and the command
line used to create the logfile. They are intended as information for
the user.

The first non-comment line is the status line. It contains a
non-negative integer and a status character. The integer is the position
being tried in the input file. The status character is one of these:

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

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-split
@item '-'       @tab failed block bad-sector(s)
@item '+'       @tab finished block
@end multitable

@noindent
And here is an example logfile:

@noindent
# Rescue Logfile. Created by GNU ddrescue version @value{VERSION}@*
# Command line: ddrescue /dev/fd0 fdimage logfile@*
# current_pos  current_status@*
0x00120000     ?@*
#      pos         size   status@*
@multitable {0x00000000} {0x00000000} {status}
@item 0x00000000 @tab 0x00117000 @tab +
@item 0x00117000 @tab 0x00000200 @tab -
@item 0x00117200 @tab 0x00001000 @tab /
@item 0x00118200 @tab 0x00007E00 @tab *
@item 0x00120000 @tab 0x00048000 @tab ?
@end multitable

If you edit the file, you may use decimal, hexadecimal or octal values,
using the same syntax that integer constants in C++.


@node Examples
@chapter A small tutorial with examples
@cindex examples

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.

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.

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

IMPORTANT! Never try to rescue a r/w mounted partition. The resulting
copy may be useless.

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

IMPORTANT! 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.

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

If you are trying to rescue a whole partition, first repair the copy
with e2fsck or some other tool appropiate 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.

@sp 1
@noindent
Example 1: Rescue a whole disc with two ext2 partitions in /dev/hda to
/dev/hdb.@*
Note: you do not need to partition /dev/hdb beforehand, but if the
partition table on /dev/hda is damaged, you'll need to recreate it
somehow on /dev/hdb.

@example
ddrescue -f -n /dev/hda /dev/hdb logfile
ddrescue -d -f -r3 /dev/hda /dev/hdb logfile
fdisk /dev/hdb
e2fsck -v -f /dev/hdb1
e2fsck -v -f /dev/hdb2
@end example

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

@example
ddrescue -f -n /dev/hda2 /dev/hdb2 logfile
ddrescue -d -f -r3 /dev/hda2 /dev/hdb2 logfile
e2fsck -v -f /dev/hdb2
mount -t ext2 -o ro /dev/hdb2 /mnt
  (read rescued files from /mnt)
@end example

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

@example
ddrescue -n -b2048 /dev/cdrom cdimage logfile
ddrescue -d -b2048 /dev/cdrom cdimage logfile
  (write cdimage to a blank CD-ROM)
@end example

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

@example
ddrescue -n -b2048 /dev/cdrom cdimage logfile
ddrescue -d -b2048 /dev/cdrom cdimage logfile
  (insert second copy in the CD drive)
ddrescue -d -r1 -b2048 /dev/cdrom cdimage logfile
  (write cdimage to a blank CD-ROM)
@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 -b2048 /dev/cdrom cdimage1 logfile1
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 -b2048 /dev/cdrom cdimage2 logfile2
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 rescued.tar.lz rescued1.tar.lz rescued2.tar.lz
@end example

@sp 1
@noindent
Example 6: While rescuing the whole drive /dev/hda to /dev/hdb, /dev/hdb
fails and you have to rescue data to a third drive, /dev/hdc.

@example
ddrescue -f -n /dev/hda /dev/hdb logfile1     <-- /dev/hdb fails here
ddrescue -f -m logfile1 /dev/hdb /dev/hdc logfile2
ddrescue -f -n /dev/hda /dev/hdc logfile2
ddrescue -d -f -r3 /dev/hda /dev/hdc logfile2
@end example

@sp 1
@noindent
Example 7: While rescuing the whole drive /dev/hda to /dev/hdb, /dev/hda
stops responding and disappears from /dev.

@example
ddrescue -f -n /dev/hda /dev/hdb logfile      <-- /dev/hda fails here
  (restart /dev/hda or reboot computer as many times as needed)
ddrescue -f -n -A /dev/hda /dev/hdb logfile
ddrescue -d -f -r3 /dev/hda /dev/hdb logfile
@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 the log file 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 or a raw device to bypass the kernel cache and rescue more of
your data.

NOTE! Sector size must be correctly set with the @samp{--block-size}
option for this to work. Try the @samp{--direct} 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.

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. Ddrescue can't determine the size of a raw
device, so an explicit @samp{--max-size} or @samp{--complete-only}
option is 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/hdb1 /dev/hdc1 logfile
ddrescue -d -f -r3 /dev/hdb1 /dev/hdc1 logfile
e2fsck -v -f /dev/hdc1
mount -t ext2 -o ro /dev/hdc1 /mnt
@end example

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

@example
raw /dev/raw/raw1 /dev/hdb1
ddrescue -f -n /dev/hdb1 /dev/hdc1 logfile
ddrescue -C -f -r3 /dev/raw/raw1 /dev/hdc1 logfile
raw /dev/raw/raw1 0 0
e2fsck -v -f /dev/hdc1
mount -t ext2 -o ro /dev/hdc1 /mnt
@end example


@node Fill Mode
@chapter Fill Mode
@cindex Fill Mode

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

In fill mode the input file 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 block or
sector to be filled.

Note that in fill mode the input file is always read from position 0. If
you specify a @samp{--input-position}, it refers to the original input
file from which the logfile was built, and is only used to calculate the
offset between input and output positions.

Note also that when filling the input file of the original rescue run
you should set @samp{--input-position} and @samp{--output-position} to
identical values, whereas when filling the output file of the original
rescue run you should keep the original offset between
@samp{--input-position} and @samp{--output-position}.

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

In fill mode the logfile is updated to allow resumability when
interrupted or in case of a crash, but as nothing is being rescued the
logfile is not destroyed. The status line is the only part of the
logfile 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=- tmpfile outfile logfile
@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 specially
useful when sending the drive back to the manufacturer for warranty
replacement.

@example
ddrescue --fill=+ --force /dev/zero bad_drive logfile
@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=- --force --synchronous /dev/zero bad_drive logfile
@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. Do not use
sparse writes. This yields a logfile with 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".

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

4) Grep for the fill string in all the files. Those files containing the
string reside (at least partially) in damaged disc areas.

5) Unmount the copied drive or image file.

6) 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 logfile
printf "DEADBEEF" > tmpfile
ddrescue --fill=- tmpfile cdimage logfile
rm tmpfile
mount -t iso9660 -o loop,ro cdimage /mnt/cdimage
find /mnt/cdimage -type f -exec grep "DEADBEEF" '@{@}' ';'
umount /mnt/cdimage
ddrescue --fill=- /dev/zero cdimage logfile
@end example


@node Generate Mode
@chapter Generate-logfile Mode
@cindex Generate-logfile Mode

So you didn't read the tutorial and started ddrescue without a logfile.
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
logfile, from the input file and the (partial) copy, that is almost as
good as an exact logfile. 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 logfile, 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 logfile with this command:
@example
ddrescue --generate-logfile infile outfile logfile
@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 logfiles, shows logfile
contents, converts logfiles to/from other formats, compares logfiles,
tests rescue status, and can delete a logfile if the rescue is done.
Ddrescuelog operations can be restricted to one or several parts of the
logfile if the domain setting options are used.

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

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

@example
ddrescue -f /dev/hda /dev/hdb logfile
ddrescuelog -d logfile
@end example

@sp 1
@noindent
Example 2: Rescue two ext2 partitions in /dev/hda to
/dev/hdb and repair the file systems using badblock lists generated with
ddrescuelog. File system block size is 4096.@*
Note: you do need to partition /dev/hdb beforehand.

@example
fdisk /dev/hdb                                <-- partition /deb/hdb
ddrescue -f /dev/hda1 /dev/hdb1 logfile1
ddrescue -f /dev/hda2 /dev/hdb2 logfile2
ddrescuelog -l- -b4096 logfile1 > badblocks1
ddrescuelog -l- -b4096 logfile2 > badblocks2
e2fsck -v -f -L badblocks1 /dev/hdb1
e2fsck -v -f -L badblocks2 /dev/hdb2
@end example

@sp 1
@noindent
Example 3: Rescue a whole disc with two ext2 partitions in /dev/hda to
/dev/hdb 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 do not need to partition /dev/hdb beforehand, but if the
partition table on /dev/hda is damaged, you'll need to recreate it
somehow on /dev/hdb.

@example
ddrescue -f /dev/hda /dev/hdb logfile
fdisk /dev/hdb                                <-- get partition sizes
ddrescuelog -l- -b512 -i63b -o0 -s9767457b -b4096 logfile > badblocks1
ddrescuelog -l- -b512 -i9767520b -o0 -s128520b -b4096 logfile > badblocks2
e2fsck -v -f -L badblocks1 /dev/hdb1
e2fsck -v -f -L badblocks2 /dev/hdb2
@end example


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

The format for running ddrescuelog is:

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

Ddrescuelog supports the following options:

@table @samp
@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 logfile to standard
output. @var{old_types} and @var{new_types} are strings of block status
characters as defined in the chapter Logfile Structure (@pxref{Logfile
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 -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 -c[@var{type1}@var{type2}]
@itemx --create-logfile[=@var{type1}@var{type2}]
Create a logfile from a list of block numbers read from standard input.
Only blocks included in the rescue domain will be added to @var{logfile}.

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

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

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

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

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

@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{logfile} and included in the rescue domain.
@var{types} contains one or more of the block status characters defined
in the chapter Logfile Structure (@pxref{Logfile 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 -m @var{file}
@itemx --domain-logfile=@var{file}
Restrict the rescue domain to the blocks marked as finished in the
logfile @var{file}.

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

@item -o @var{bytes}
@itemx --output-position=@var{bytes}
Starting position in output file, in bytes. Is used by the
@samp{--list-blocks} option. Defaults to @samp{--input-position}.

@item -p @var{file}
@itemx --compare-logfile=@var{file}
Compare the types of the blocks included in the rescue domain. The exit
status is 0 if all tested blocks are the same in both files, 1
otherwise.

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

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

@item -t
@itemx --show-status
Print a summary of @var{logfile} contents on the standard output. The
summary can be restricted to one or several parts of @var{logfile} if
the domain setting options are used.

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

@item -x @var{file}
@itemx --xor-logfile=@var{file}
Perform a logical XOR (exclusive OR) operation between the finished
blocks in @var{file} and those in @var{logfile}, and write the resulting
logfile to standard output. In other words, in the resulting logfile a
block is only shown as finisned if it was finisned in either of the two
input logfiles but not in both.

@item -y @var{file}
@itemx --and-logfile=@var{file}
Perform a logical AND operation between the finished blocks in
@var{file} and those in @var{logfile}, and write the resulting logfile
to standard output. In other words, in the resulting logfile a block is
only shown as finisned if it was finisned in both input logfiles.

@item -z @var{file}
@itemx --or-logfile=@var{file}
Perform a logical OR operation between the finished blocks in @var{file}
and those in @var{logfile}, and write the resulting logfile to standard
output. In other words, in the resulting logfile a block is shown as
finisned if it was finisned in either of the two input logfiles.

@end table

@sp 1
Return values: 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{@samp{ddrescue --version}}.


@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye
