6 Invoking ddrescue

The format for running ddrescue is:

ddrescue [options] infile outfile [mapfile]

infile and outfile may be files, devices, or partitions. mapfile is a regular file and must be placed in an existing directory. If mapfile does not exist, ddrescue will create it. Be careful to not specify by mistake an old mapfile from an unrelated rescue.

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

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

ddrescue supports the following options:

-h

--help

Print an informative help message describing the options and exit.

-V

--version

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

-a bytes

--min-read-rate=bytes

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

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

-A

--try-again

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

-b bytes

--sector-size=bytes

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

In rescue mode, any non-finished subsector that is found during the initial read of the mapfile will be 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 will not be 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.

-B

--binary-prefixes

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

-c sectors

--cluster-size=sectors

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

-C

--complete-only

Limit rescue domain to the blocks listed in the mapfile. Don’t read new data beyond mapfile limits. This is useful when reading from devices of undefined size (like raw devices), when the drive returns an incorrect size, or when reading from a partial copy. -C can only be used after a first rescue attempt, possibly limited with the option --size, has produced a complete mapfile. If -C is not specified, ddrescue extends the mapfile from position 0 to the size of outfile, adding one non-tried block before the existing blocks and another one after them if needed.

-d

--idirect

Use direct disc access (see Direct disc access) to read from infile, bypassing the kernel cache. (Opens the file with the flag ‘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 will warn you. If the sector size is not correctly set, an unaligned read error will result and ddrescue will exit with status 1.

-D

--odirect

Use direct disc access to write to outfile, bypassing the kernel cache. (Opens the file with the flag ‘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 will warn you. If the sector size is not correctly set, a write error will result and no data will be rescued. Some OSs have a bug that prevents them from detecting write errors properly (or at all) on some devices if direct disc access is not used for outfile.

-e [+]n

--max-bad-areas=[+]n

Maximum number of bad areas allowed before giving up. Defaults to infinity. If n is preceded by ‘+’ the number refers to new bad areas found in this run, not counting those already present in the mapfile.

-E bytes

--max-error-rate=bytes

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

-f

--force

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

-F types

--fill-mode=types

Fill the blocks in outfile specified as any of types in mapfile, with data read from infile. types contains one or more of the status characters defined in the chapter Mapfile structure (see Mapfile structure) and an optional ‘l’ for sector location data. See the chapter Fill mode (see Fill mode) for a complete description of the fill mode.

-G

--generate-mode

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

-H file

--test-mode=file

Build a map of good/bad blocks using the mapfile file and use it to simulate read errors in infile. The blocks marked as finished in file will be read normally. All other block types will be considered read errors without even trying to read them from infile. The apparent size of infile is truncated to the extent of file. This mode is an aid in improving the algorithm of ddrescue and is also useful to verify that ddrescue produces accurate results in presence of read errors. Use a hyphen ‘-’ as file to read from standard input.

-i bytes

--input-position=bytes

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

-I

--verify-input-size

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

-J

--verify-on-error

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

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

-K [initial][,max]

--skip-size=[initial][,max]

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

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

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

-L

--loose-domain

Accept an incomplete synthetic (user fabricated) domain mapfile or test-mode mapfile, and fill the gaps in the list of data blocks with non-tried blocks. The blocks in the mapfile 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.

-m file

--domain-mapfile=file

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

-M

--retrim

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

-n

--no-scrape

Skip the scraping phase. Avoids spending a lot of time trying to rescue the most difficult parts of the file.

-N

--no-trim

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

-o bytes

--output-position=bytes

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

-O

--reopen-on-error

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

-p

--preallocate

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

-P[lines]

--data-preview[=lines]

Show lines lines of the latest data read in ‘16-byte hex + ASCII’ format. Valid values for lines range from 1 to 32. If lines is omitted, a default value of 3 is used.

-q

--quiet

Quiet operation. Suppress all messages.

-r n

--retry-passes=n

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

A command like ‘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.

-R

--reverse

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

-s bytes

--size=bytes

Maximum size of the rescue domain in bytes. It limits the amount of input data to be copied. -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 outfile. For example, the following command creates an outfile 300 bytes long, but only writes data on the last 200 bytes:

ddrescue -i 100 -s 200 infile outfile mapfile

-S

--sparse

Use sparse writes for outfile. (The blocks of zeros are not actually allocated on disc). May save a lot of disc space in some cases. Not all systems support this. Only regular files can be sparse. Use this option only with an empty or zeroed outfile because if a block in outfile contains non-zero data, it won’t be overwritten by a corresponding block of zeros in infile, resulting in a corrupt copy.

-t

--truncate

Truncate outfile to zero size before writing to it. Only works for regular files, not for drives or partitions.

-T interval

--timeout=interval

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

-u

--unidirectional

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

-v

--verbose

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

-w

--ignore-write-errors

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

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

-W

--compare-before-write

Omit superfluous writes in rescue mode. Before writing each block of data to 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.

-x bytes

--extend-outfile=bytes

Extend the size of outfile to make it at least bytes long. If the size of outfile is already equal or longer than bytes, then this option does nothing. Use this option to guarantee a minimum size for outfile. Only regular files can be extended.

-X n

--max-read-errors=n

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

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

-y

--synchronous

Use synchronous writes for outfile. (Issue a fsync call after every write). May be useful when forcing the drive to remap its bad sectors. 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.

-Z bytes

--max-read-rate=bytes

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

--ask

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

--command-mode

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

--cpass=range

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

Examples of range	Passes run
1	1
1,2,3	1, 2, 3
2-4	2, 3, 4
1,3-5	1, 3, 4, 5
1-3,5	1, 2, 3, 5

--delay-slow=interval

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

--log-events=file

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

--log-rates=file

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

--log-reads=file

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

--mapfile-interval=[save_interval][,sync_interval]

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

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

--max-slow-reads=n

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

--pause-on-error=interval

Time to wait after each read error. Also after each slow read if a minimum read rate has been set with --min-read-rate. Defaults to 0. interval is formatted as in the option --timeout above. If interval begins with ‘s’, the pause is simulated and interval can be smaller than one second; the time displayed is increased by interval but without performing any pause. Pause simulation can be useful in combination with --test-mode for testing purposes.

--pause-on-pass=interval

Time to wait between passes. Defaults to 0. interval is formatted as in the option --timeout above.

--reset-slow

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

--same-file

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

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

Table of SI and binary prefixes (unit multipliers):

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 mapfile and then terminates by raising the signal received.