Manual-0.4.5

Authors:

0. About this manual

This is the manual for ddrescueview 0.4.5.
Manuals for other versions are linked on the [Versions] page.
The changelog can be viewed on the [Changelog] page.

1. Introduction

ddrescueview is a graphical viewer for GNU ddrescue mapfiles.
It allows the user to graphically examine ddrescue's mapfiles in a user friendly GUI application.
The program is released under the GNU GPL.

1.1 Main features

Show the rescue mapfile, as produced by ddrescue during the rescue.
Optionally, overlay the domain mapfile that you use to constrain ddrescue's operations.
Inspect the mapfile lines that make up a block in the grid.
Zoom into the details of the mapfile, down to sector level.
Show a summary of the rescue status, such as ddrescue's current operation, number of bad sectors...
Refresh the mapfile(s) on a regular interval.

1.2 Benefits

You can see the damage pattern on your rescue media and where damaged areas are located.
Keep track of the rescue progress. Spot slow and difficult areas. Watch ddrescue's algorithm in near-realtime.
Make better decisions on how to proceed with the rescue.
Screenshots of the program can be used to communicate the rescue status to others, or serve as a record.

1.3 What ddrescueview is not

ddrescueview is not a control interface for ddrescue. Instead have a look at DDRescue-GUI.
ddrescueview does not wrap or interfere with ddrescue, to monitor it directly. The mapfile is the only interface between the two programs. It's not necessary to run ddrescueview on the same machine as ddrescue, as long as you have access to the mapfile.
ddrescueview is not a tool to modify or generate mapfiles. Use ddrescuelog (part of ddrescue package) for various operations on mapfiles. ddrutility and partclone have proven useful for generating domain mapfiles for the used space of partitions, a powerful time-saver.
ddrescueview can not yet show the logs produced by ddrescue's --log-rates and --log-reads options.

1.4 Terminology

NOTE: Prior to ddrescue 1.20, mapfiles were called 'logfiles'. The name was changed to better reflect the purpose and structure of the files. However, the format stayed the same. All newer versions of ddrescueview use the new name.
rescue device The block device, partition, regular file or special file given to ddrescue as source for rescuing.
rescue mapfile The mapfile ddrescue produces during the rescue. It spans the whole rescue device, if its size is known.
domain mapfile The mapfile optionally passed to ddrescue, to limit the rescue domain. Can be generated by ddrescue, other utility programs such as ddrutility or partclone, or crafted manually. Its entries usually span the whole rescue device, although ddrescue contains support for incomplete domain mapfiles with the --loose-domain option. ddrescueview does not yet fully support such non-standard domain mapfiles.

2. Getting started

This section briefly helps you set up ddrescueview for usage.

2.1 Getting a copy

The source code and prebuilt binaries for Windows and GNU/Linux are available here.
The download button above takes you to your platform specific download, if available.
Mac users should build ddrescueview from source .

2.2 Compiling

The program is written in Object Pascal using the Lazarus IDE.
It can be compiled to run on Windows, GNU/Linux and OS X.
To build ddrescueview on Windows or GNU/Linux, it is recommended to use Lazarus 2.0.10 or later, although earlier versions may work as well.

Optionally, make sure Lazarus and the LCL are compiled with optimization and smart-linking (-O3 -CX -XX).
This will yield a smaller executable (on some platforms).
To accomplish this, click Tools -> Configure "Build Lazarus", then select "Optimized IDE". Add the smart-linking switches unter "Options" (-CX -XX), then click Build and wait for the process to complete and for Lazarus to restart.
Open the project file (ddrescueview.lpi) in Lazarus.
Select the correct build config for your platform. You can do this from Lazarus' Build Mode toolbar icon or in the Project Options.
Select GNU/Linux Release if you build on Linux. Select Win32 Release if you're on Windows. Select Native Release for other platforms or if you want a 64-bit build on Win64.
Click menu Run -> Compile.
If the compilation process succeeds, the binary can be found inside the project folder.

Mac users should follow the instructions in this forum post: Compiling ddrescueview on MacOS 10.14.

2.3 Installation

If you downloaded a binary distribution of ddrescueview, start with unpacking the archive.

2.3.1 Linux

Linux users can copy the binary to /usr/bin, which requires elevated privileges.
The archive also contains files for integration with the desktop environment. See resources/linux/linux-readme.txt in the archive.
Make sure to have the following dependencies installed, or ddrescueview will not start:

Shared object            Library name
libdl.so.2               libc6
libpthread.so.0          libc6
libc.so.6                libc6
libglib-2.0.so.0         libglib2.0
libgobject-2.0.so.0      libglib2.0
libgthread-2.0.so.0      libglib2.0
libX11.so.6              libx11
libgtk-x11-2.0.so.0      libgtk2.0
libgdk-x11-2.0.so.0      libgtk2.0
libgdk_pixbuf-2.0.so.0   libgdk-pixbuf-2.0
libpango-1.0.so.0        libpango-1.0
libcairo.so.2            libcairo2
libatk-1.0.so.0          libatk1.0

In case these dependencies cannot be satisfied on your distribution, you have to compile the program yourself.

2.3.2 Windows

Windows users can place ddrescueview.exe anywhere they like - if you have a Tools-folder, that's a perfect place for the program.
You might want to create a shortcut to ddrescueview on the Desktop and/or in the Start Menu.

2.4 Invocation

Being a GUI application, ddrescueview can be started by clicking its icon in your Launcher / Start Menu / on the desktop.
Once started, you can drag-and-drop a mapfile onto the main window.
However, if you choose to start ddrescueview from the terminal or from a script, you can make use of a few command-line options.
The full syntax is:

ddrescueview <options> -m domain-mapfile rescue-mapfile
  where rescue-mapfile must be the last argument and <options> can be:
   -r (off|5s|10s|30s|1m|2m|5m)  Set refresh interval, e.g. -r 30s
   -lp                           Show log panel
   -gs (4|6|..|24)               Set grid size, e.g. -gs 10
   -ub                           Use binary unit prefixes instead of decimal
   -x left                       X position of window on screen, in pixels
   -y top                        Y position of window on screen, in pixels
   -w width                      Client-width of window, in pixels
   -h height                     Client-height of window, in pixels
   -safe                         Turn off drawing optimizations

3. GUI Walkthrough

This section describes all visual components of ddrescueview, and the functionality behind them.

3.1 Main Window

When you open ddrescueview, you see the main window. It has a menu bar and a status bar at the bottom. The rest of the window can be separated into 3 areas: The top panel shows the rescue status, while to the left you see a thin vertical bar, the zoom bar (or scroll bar). Finally, most space is taken up by the block grid.
Rescue mapfiles can be directly drag-and-dropped onto the window, from a file browser.
The file names of the rescue mapfile and (optionally) domain mapfile are shown in the application title.

Most menu items should be self-explanatory, but here are some explanations:

Open mapfile allows you to open a rescue mapfile.
Open domain mapfile allows you to open a matching domain mapfile, once you have opened a rescue mapfile.
Close mapfile closes the rescue mapfile and the domain mapfile. The Block inspector window is also closed, if opened.
Save screenshot takes a screenshot of the main window and allow you to save it in PNG format. The screenshot is taken the moment you click 'save' in the file save dialog.
Exit closes all files and exits the program.

Refresh now allows you to instantaneously re-read the currently opened mapfile(s).
Center on current position When checked, keeps the Block Grid centered on the current rescue position.
This overrides much of the usual zooming functionality and deactivates interaction with the Zoom Bar.
Show zoom bar toggles the zoom bar, should you wish to save screen space. Handy to keep the rescue position on screen when zoomed in.
Show log panel toggles the bottom panel, which appears just above the status bar.

Automatic Refresh allows you to set a refresh interval. Please note that, by default, ddrescue writes the rescue mapfile in intervals ranging from 30 seconds to 5 minutes. The interval increases with the number of mapfile entries. Setting a refresh interval shorter than 30 sec makes sense when using ddrescue-1.22 or later with the --mapfile-interval switch to write the mapfile in shorter intervals.
When an interval is set, it can happen from time to time that ddrescueview reads the mapfile in the exact moment ddrescue writes to it. This leads to a failed attempt to parse the mapfile. In this case, ddrescueview makes a second attempt to read the mapfile after a short delay.
When an interval is set and the mapfile is read from a network location, it may occur that the contents don't seem to change when refreshing. If this is the case, please disable caching of the network location (e.g. in the mount options).
Grid size of the block grid can be adjusted to your preference. Smaller grid sizes show finer details but larger sizes may be easier on the eyes. 8 pixels is the default.
Unit prefixes can be toggled between KB, MB, GB... (decimal, SI) and KiB, MiB, GiB... (binary, IEC). ddrescueview defaults to decimal prefixes, like ddrescue.
Device Sector size: The setting defaults to 512 bytes and should be auto-detected correctly in most situations, from the ddrescue command line in the first comment line of the rescue mapfile. Most people probably do not need to change it, but here's a bit of background information: ddrescueview uses the device sector size as a 'smallest unit of measurement' in many of its internal calculations. Using integer arithmetic, this has the benefit of never splitting a sector in half. Grid blocks always span a multiple of the sector size. ddrescueview assumes that the device size is a multiple of the sector size and refuses to set one that doesn't fit.
Contiguous domain: The Contiguous domain mode can be switched on when a Domain mapfile is opened.
Settings: This opens the settings dialog, which currently contains mostly cosmetic settings.

About opens the About dialog, which shows the version number and some more information.

3.1.2 Top panel

The top panel shows status information, which is calculated from the rescue mapfile, along with a key for the colors used in the block grid.

The caption shows ddrescue's current phase, as indicated by the status character in the rescue mapfile. This is one of the following (taken from the ddrescue manual):

Character  Meaning
'?'        Copying non-tried blocks
'*'        Trimming non-trimmed blocks
'/'        Scraping non-scraped blocks
'-'        Retrying bad sectors
'F'        Filling specified blocks
'G'        Generating approximate mapfile
'+'        Finished

If the mapfile was created by ddrescue-1.22 or later, the current pass is displayed in the caption, too.

Below the caption, there are a number of labelled values, with an optional color indicator for the corresponding grid block color. The values can be selected and copied to the clipboard.
Tip: Most labels can be double-clicked to switch their values between three different formats:

automatic unit prefix with 2 decimal places (e.g. 122.84 MB)
number of sectors (e.g. 239921 s)
hexadecimal bytes (e.g. 0x075263C0).

Input size: This is the size of the rescue device. The input size is calculated as the sum of offset and size of the rescue mapfile's last entry.
Error count: This is the number of separate bad sector(s) regions in the rescue mapfile, as in the terminal output produced by ddrescue 1.20. Ddrescue 1.19 and earlier showed the combined amount of bad sector(s), non-trimmed and non-scraped / non-split areas here.
Pending: This value shows the combined amount of non-tried, non-trimmed and non-scraped blocks.
Rescued: Total space marked as 'rescued' in the rescue mapfile and in ddrescue's terminal output.
Bad sectors: Total space marked as 'bad sector(s)' in the rescue mapfile. Reported as 'errsize' by ddrescue as of version 1.20.
Current position: This is ddrescue's current position on the device. Reported as 'ipos' by ddrescue.
Non-tried: Total space marked as non-tried in the rescue mapfile.
Non-trimmed: Total space marked as non-trimmed in the rescue mapfile.
Non-scraped: Total space marked as non-scraped in the rescue mapfile. Before ddrescue 1.19 this was called 'non-split'. Ddrescue's splitting algorithm was ditched in favor of the 'scraping' algorithm, but the status character '/' was re-used. Just think 'non-split' when using an older version of ddrescue.
Domain size: Only visible when a domain mapfile is opened. This is the amount of space marked for rescuing.
Not in domain: Only visible when a domain mapfile is opened. This is the amount of space on the rescue device which is not inside the domain, calculated by (device size) - (domain size).

To the right hand side of the rescue status box, there is a pie chart, which shows the proportion of rescued, bad sector(s), non-tried, non-trimmed, non-scraped (and Not in domain) space.

3.1.3 Block grid

The main portion of the window is taken up by the grid of blocks. The block rows 'read' in top-to-bottom order, each row from left-to-right. All blocks span the same number of sectors, except the last one. Some blocks at the end of the grid can be entirely unused (gridline-colored). This is because the number of sectors per grid block which just fits, rarely divides the sector count of the rescue device (or zoomed section) evenly.
When the view is fully zoomed out, the entirety of blocks represents the whole rescue device.

The color for a grid block is determined as follows:

The mapfile is scanned for entries that overlap the grid block.
For each of these map entries, the grid block is flagged with the entries' status.
Finally, a color is blended from the status flags' colors and their weight.

By default, the status colors are: Red for bad sectors, gray for non-tried, green for rescued, yellow for non-trimmed, blue for non-scraped and dark gray for not in domain blocks.
The weights assigned to these colors by default are chosen to highlight bad blocks. For example, bad sector(s) have the highest weight.
The color blending mechanism and the color weights ensure that it is easy to spot a single bad sector in a grid block that otherwise contains thousands of rescued sectors.
Colors and weights can be customized in the Settings dialog.
The current position of ddrescue is indicated (by default) by a cyan-colored frame around the respective block.

The block grid supports a number of user interactions:

Left click on a grid block opens the Block Inspector for this block. As long as the Block Inspector is open, the selected block is indicated with a white frame.
Scrolling the mouse wheel zooms in or out. By default, the block previously under the mouse stays under the mouse after zooming in or out. An option in the Settings dialog allows to revert to the legacy behavior, in which the block under the mouse pointer becomes the center in the zoomed view, if possible.
The zoom factor is currently fixed at 150 % per zoom step.
The limit for zooming out is reached when the whole rescue mapfile is shown.
The limit for zooming in is reached when one grid block represents one device sector.
Dragging with the right mouse button zooms into the dragged selection.

3.1.4 Zoom bar

The zoom bar to the left of the block grid always shows the whole rescue mapfile in a top-to bottom stripe. Color blending is the same as for grid blocks.
When the block grid is zoomed in, the zoom bar marks the visible section. The zoom bar also shows ddrescue's current position.

The Zoom Bar supports the following user interactions:

Dragging with the left mouse button:
The visible section can be shifted by dragging it up/down with the left mouse button. Think of it as a scroll bar. This is useful at moderate zoom levels. When zoomed down to sector level, you may find zooming out and into another position more suitable to get around.
Dragging with the right mouse button:
This allows you to select the visible section directly on the Zoom Bar. The Block Grid is updated instantaneously.

3.1.5 Bottom panel

The bottom panel (or 'log panel') can be activated in the View menu.
To the left, ddrescue's comment lines from the rescue mapfile are shown. This allows to easily check ddrescue's command line, for example.
To the right, ddrescueview's debug log is shown. This is mostly interesting for developers.

3.1.6 Status bar

The status bar shows the full pathname of the currently opened rescue mapfile.

3.2 Block inspector

The block inspector window displays information about the currently selected grid block. It can be invoked by left-clicking a block on the grid.

Right at the top you see the block selection, where you can select the number of the grid block to show.
Tip: Use the mouse wheel on this control to quickly scroll a few blocks forward or backward.
The boundaries info (starting offset and size) of the block are noted right next to it.
Tip: Double-clicking the 'Block' label to the left of the block selection toggles the format of the boundaries info.

Below there is a breakdown of the number of sectors contained in this block, by status. The sum of all sectors matches the block size indicated in the boundaries info.

The main portion of the window is made up by the map entry list. All entries from the rescue mapfile that intersect the selected block are listed here.
Tip: You can select a line and press Ctrl+C to copy its contents to the clipboard.
If the entry which matches the current position appears in the list, it is prepended by '> '.

Finally, at the bottom of the window there is a close button and a checkbox, which says 'Track current position'.
When the checkbox is checked, the block inspector automatically selects the current position's block everytime the rescue mapfile is refreshed (either manually or at an interval). When you select another block manually, the checkbox is cleared.

3.3 Settings dialog

The settings dialog window allows you to customize the status colors and their associated weights.
'Zoom to mouse pos.' is checked by default. When unchecked, the program reverts to the old behaviour when zooming the Block Grid with the mouse wheel.
There is also a checkbox that toggles the experimental fast drawing routines. Uncheck it when you encounter problems with the drawing of the block grid on your platform. The fast drawing routines only work on displays with 24-bit or 32-bit color (8 bit per channel). ddrescueview should automatically disable them for other display modes.

The settings are non-persistent.

3.4 About dialog

The About dialog shows the program version, license information, project author and the home page URL.

4. Advanced topics

4.1 Domain mapfiles

Domain mapfiles are a powerful feature of ddrescue.
When using a domain mapfile with ddrescue, only the blocks marked as Rescued (+) are copied from the source to destination.

Possible applications mentioned in the ddrescue manual are

[...] merging partially recovered images of backups, or if the destination drive fails during the rescue.

These usage scenarios assume that ddrescue's source device was once the rescue destination.

A different scheme applies when you write the domain mapfile yourself, as preparation for a rescue session, or use a third-party program to do it for you. You could, for example, determine the start and end sectors of one or more partitions which are important to you, then craft a domain mapfile from these numbers. Give it to ddrescue, and it will copy only the specified sectors making up the partition(s) from the rescue device to the destination.

If you think further, you get a domain mapfile that only marks the used space of the partitions of interest.

ddrutility and partclone can generate such domain mapfiles. Of course, the drive's partition table and some filesystem structures must be readable. These programs typically generate a highly fragmented, and thus, large domain mapfile. The more files the filesystem holds and the more fragmented they are, the larger the domain mapfile gets.

Considerable thought has been put into ddrescueview, to view all kinds of domain mapfiles in a useful way.

Because domain mapfiles have the same format as regular rescue mapfiles, you could view them side-by-side with the rescue mapfile in another instance of ddrescueview. This may be useful in some cases, but there are other ways:

Opening a domain mapfile through the File menu introduces a new block status, called "not in domain". These blocks are colored dark gray by default and have the lowest weight in color blending. They are shown in the block grid where ddrescueview finds non-'Rescued' entries in the domain mapfile. "Not in domain"-blocks can also cut blocks from the rescue mapfile in half (e.g. if ddrescue was previously used without or with another domain mapfile). All other blocks from the rescue mapfile will be colored as usual.
The top bar shows two new values, 'Domain size' and 'Not in domain', along with the associated color.
This mode shows clearly which areas ddrescue should attempt to recover, while not changing much of the usual look and feel of ddrescueview.
This mode can, however, be problematic when using highly fragmented used-space domain mapfiles. At a low zoom level, many grid blocks in used-space areas would simply be colored a bit darker, due to the dark-gray color influence of small gaps in the rescue domain.

This is where the contiguous domain mode comes in. This mode can be enabled in the Options menu. Once enabled, notice how the top panel hides the 'Domain size' and 'Not in domain' values again.
As the name implies, this mode makes the rescue domain appear contiguous to all parts of ddrescueview. It emulates a rescue mapfile with all 'not in domain' areas cut out.
This has a number of implications:

The Rescue status in the top bar shows all values with respect to the emulated mapfile, e.g. 'Input size' shows what was previously 'Domain size'. All block types listed only count those inside the domain. 'Current position' does not refer to a position on the actual rescue device anymore.
The same applies to the map entries shown in the Block inspector. Additionally, consecutive entries may have the same status. Obviously, this may happen when cutting out sections from the mapfile, and ddrescueview does not merge these entries.
The benefit: 'Not in domain' blocks are not shown anymore, and you have a great overview of the rescue progress again.

Project Members:

Graham Inggs
MBit (admin)

Docs / Wiki: Changelog
Docs / Wiki: Versions

Discussion

Anonymous

ddrescueview Docs / Wiki

Graphical viewer for GNU ddrescue mapfiles