The Linux sg_dd utility

The Linux sg_dd utility

Introduction

The sg_dd utility is a variant of the standard Unix command dd which copies files. The sg_dd utility is specialized for devices that use the SCSI command set in the Linux operating system. The sg_dd utility is found in the sg3_utils package which targets the linux kernel 2.4 and 2.6 series.

Not all SCSI device types are supported by the sg_dd utility. Obviously those device types that deal with enclosures and medium changers don't have addressable blocks and are not supported. The supported device types are direct access devices (e.g. disks) and cd/dvd devices. The SCSI tape device type is not be supported (but could be to a limited degree). When instructed, the sg_dd utility issues SCSI commands that are defined in SPC-3 (primary commands), SBC-2 (commands for direct access devices (e.g. disks)) and MMC-4 (commands for CD/DVD devices). These SCSI command sets can be found at www.t10.org .

It is becoming common for non-SCSI devices (e.g. ATA disks) to appear as SCSI devices to an operating system via a protocol conversion in an external enclosure and via some transport such as USB or IEEE 1394. The sg_dd utility should work with most of these devices as it tends to use exactly the same SCSI commands that the normal block layer would use. However, advanced options (e.g. using the 'cdbsz' and 'iflag=fua') most likely will be ignored. Apart from CD players over 10 years old, almost all CD/DVD players use the Multi Media Command set (MMC or MMC-2,3,4,5) as their native command set. The fact that the most common transport for CD/DVD drives is ATAPI (i.e. the ATA packet interface) is irrelevant to the sg_dd utility; they use SCSI command sets.

This page outlines the features of the sg_dd utility version 5.48 found in the sg3_utils version 1.20 package.

dd like features

The basic syntax of the sg_dd utility is the same as the dd command in Unix. That said, the syntax of the dd command in Unix is different from almost all other standard Unix commands. Those familiar with the dd command should not be too surprised by the syntax and semantics of the sg_dd utility. Those not familiar with the dd syntax should be very careful, especially with the 'of' and 'seek' options, both with dd and sg_dd. The recent GNU implementation of the dd command is used as a reference point.

The main options of dd are:

Standard dd options	Default	Brief description
bs=<block_size>	512	Number of bytes in each block
count=<count_of_blocks>	blocks in input file	Number of blocks to copy
if=<input_file>	stdin	file (or device) to read from
of=<output_file>	stdout	file (or device) to write to. sg_dd doesn't bother writing anything if <output_file> is /dev/null or . (period).

When either dd or sg_dd are given these options with suitable arguments, they will copy (<block_size> *<count_of_blocks>) bytes from the beginning of <input_file> to the beginning of <output_file>. One restriction that sg_dd imposes when either the <input_file> or <output_file> are accessed via SCSI commands is that <block_size> must match that of the device. Further, if both the <input_file> and <output_file> are accessed via SCSI commands then <block_size> must match that of both devices.

The following extensions are found in sg_dd. An <input_file> of "-" is interpreted as stdin; an <output_file> of "-" is interpreted as stdout while an <output_file> of "." is interpreted as /dev/null. [dd interprets input and output file names of "-" literally. dd interprets an output file of "." as the current directory and will not accept it.] The sg_dd utility does not truncate the <output_file> before starting the copy (the dd command does if it is a normal file). Hence a user may need to delete the output file before using the sg_dd utility (if the size of that file is greater than what sg_dd is going to copy over it).

If the 'count' option is not given then an attempt is made to determine the remaining blocks in the file, device or partition. If the input file is stdin and no count is given then a copy will continue until an EOF is detected on the input stream (or something else goes wrong). If the 'count' option is not given then the remaining blocks on both the input and output files are determined (if possible) and if both are found then the minimum of the two counts is used. The 'skip' option for an input file and the 'seek' option for an output file are taken into account when calculating the remaining number of blocks in a file, device or partition.

If the 'count' option is given then no further checks regarding the remaining length of the input and output files are done and the sg_dd will attempt to copy that number of blocks. A 'count=0' option is valid and all the normal preparations are made including files being opened but no copy takes place. Hence the 'count=0' option can be used to check that the syntax is in order and that the files are present (see the "Verbose" section below).

Other dd options supported by sg_dd:

Standard dd options	Default	Brief description
ibs=<block_size>	same as bs	number of bytes in each block of <input_file>
iflag=<flags>		[new in sg3_utils 1.18] similar to option found in recent GNU dd versions, see below
obs=<block_size>	same as bs	number of bytes in each block of <output_file>
oflag=<flags>		[new in sg3_utils 1.18] similar to option found in recent GNU dd versions, see below
seek=<n_blocks_of>	0	block number (origin 0) in <output_file> to commence writing
skip=<n_blocks_of>	0	block number (origin 0) in <input_file> to commence reading
--help		print usage message then exit
--version		print version number and its date then exit

If either ibs and/or obs are given to sg_dd then they must be the same as bs (i.e. they are essentially dummies). The 'skip' option cannot be used on an input stream (e.g. stdin) while the 'seek' option cannot be used on an output stream (e.g. stdout).

All numeric arguments can take a multiplier suffix. From sg3_utils version 1.13 sg_dd's multiplier prefixes have been brought into line with those of GNU's dd. GNU's dd is found in coreutils and its changelog notes the change to this suffix pattern on 2001-12-18:

Multiplier	Meaning
x<n>	*<n>
c	*1
w	*2
b	*512
k K KiB	*1024
KB	*1000
m M MiB	*1048576
MB	*1000000
g G GiB	2**30
GB	10**9
t T TiB	2**40
TB	10**12

The pattern that starts with "k" and proceeds to "m", "g" and "t" then to "p", "e", "z" and "y" (not shown in above table). sg_dd only implements as far as "p" (10**15 or 2**50). sg_dd only allows multipliers based on "t" and "p" for 'count', 'skip' and 'seek'.

sg_dd allows numeric arguments to be given in hexadecimal in which case they must be prefixed by either "0x" or "0X". A numeric argument cannot both be in hex and have a suffix multiplier. Hence "0x9" is interpreted as hexadecimal 9 [not (0 * 9)==0]. This is valid "2x4x0xa" and yields 80 (but it isn't very clear).

From sg3_utils version 1.19 (sg_dd version 5.46) hexadecimal numbers can also be indicated by a trailing "h" or "H". The "h" suffiz cannot be used together with a suffix multiplier.

The "<flags>" argument of "iflag=" and "oflag=" is a comma separated list of items chosen from one or more entries in this table:

flag	sg device	block device	regular file	comments
append	ignored	applied on <ofile>	applied on <ofile>	use O_APPEND open flag. Conflicts with 'seek=<n>' when "n > 0"
coe	applied	applied if using SG_IO ioctl	ignored	continue on error; best effort recovery then continue. N.B. can be used multiple times (e.g. 'iflag=coe,coe')
direct	applied	applied	applied	use O_DIRECT open flag, no effect with sg devices
dpo	applied	applied if using SG_IO ioctl	ignored	"disable page out" set for READ and/or WRITE SCSI commands
dsync	applied	applied	applied	use O_SYNC open flag, no effect with sg devices
excl	applied	applied	applied	Use O_EXCL open flag
fua	applied	applied if using SG_IO ioctl	ignored	"force unit access" set for READ and/or WRITE SCSI commands
sgio	ignored	use SG_IO ioctl	ignored	access block device via SG_IO ioctl (only supported in lk 2.6 series)

Recent versions of GNU's dd command have these flags with similar semantics: 'append', 'direct' and 'sync' (which is called 'dsync' in sg_dd). So 'coe', 'dpo', 'excl', 'fua' and 'sgio' are sg_dd extensions.

The following dd options are not supported by sg_dd:

cbs=<bytes>
conv=<keyword>

Basically sg_dd does not supported the conversion features of dd. If a conversion is really needed then sg_dd could be piped through dd (or vice versa).

sg_dd extras

The extra options of sg_dd (not found in GNU's dd) are:

extra options in sg_dd	default	Brief description
append=0\|1	0	append to output file (rather than overwrite). Better to use 'iflag=append' and/or 'oflag=append'.
blk_sgio=0\|1	0	when set access devices via SCSI commands (SG_IO ioctl). May use 'iflag=sgio' and/or 'oflag=sgio' instead.
bpt	128 or 32	blocks_per_transfer (granularity of each IO). Default is 128 when bs < 2048 (bytes) else the default is 32. For block devices (bpt * bs) is constrained by /sys/block/<device>/queue/max_sectors_kb .
cdbsz=6\|10\|12\|16	10 or 16	cdb size of SCSI READ and/or WRITE commands. Only applicable to sg devices or when the SG_IO ioctl is being used (e.g. when blk_sgio=1). Defaults to 10 byte cdb unless the largest address exceeds 32 bits or bpt exceeds 16 bits. In either case a 16 cdb is used.
coe=0\|1\|2\|3	0	when non-zero, continue_on_error for sg devices and block devices using the SG_IO ioctl. May use 'iflag=coe' and/or 'oflag=coe' instead. An equivalent of 'coe=2' is 'iflag=coe,coe'
dio=0\|1	0	direct IO (only via sg device nodes)
fua=0\|1\|2\|3	0	force_unit_access, 1->of, 2->if, 3->of+if . Better to use 'iflag=fua' and/or 'oflag=fua'.
odir=0\|1	0	O_DIRECT flag on open() when set. Better to use 'iflag=direct' and/or 'oflag=direct'.
sync=0\|1	0	when set, sends SYNCHRONIZE CACHE SCSI command to <ofile> if it is a sg device or accessed via the SG_IO ioctl.
time=0\|1	0	when set print elapsed time and throughput calculation at the completion of the copy
verbose=<n>	0	larger <n> is the greater the debug output. 1 and 2 print the cdbs for setup commands; 3 and 4 print the cdbs for all commands

The sg_dd utility examines the files it is given and treats them differently depending on their file type. Depending on 'iflag=<flags>' and 'oflag=<flags>' settings: O_DIRECT, O_SYNC, O_APPEND and O_EXCL flags may be added to the relevant open() command.

File type	open [when input]	open [when output]	IO method	Notes
normal	O_RDONLY	O_WRONLY \| O_CREAT	Unix read() write()	N.B. A normal output file is overwritten (not truncated).
stdin or stdout	[do nothing]	[do nothing]	Unix read() write()	hence open() flags have no effect (e.g. 'oflag=direct' is ignored)
/dev/null or . (period)	O_RDONLY	[do nothing]	Unix read() if input	if output file then nothing is written
block device	O_RDONLY	O_WRONLY \| O_CREAT	Unix read() write()
block device [sgio flag given]	O_RDWR or O_RDONLY	O_RDWR	SCSI commands	Opens input O_RDONLY if O_RDWR fails. The 'blk_sgio=1' option equates to both 'iflag=sgio' and 'oflag=sgio'. Partitions ignored.
sg device	O_RDWR or O_RDONLY	O_RDWR	SCSI commands	Opens input O_RDONLY if O_RDWR fails
raw device	O_RDONLY	O_WRONLY	Unix read() write()	O_DIRECT open flag in lk 2.6 series is a replacement for raw devices
scsi tape device	x	x	no IO	error reported

Some of the above combinations are not sensible (e.g. 'append=1' on a block device). Raw devices were introduced in the lk 2.4 series and are still available in the lk 2.6 series but opening a block device or a normal file with O_DIRECT (in sg_dd using the option 'odir=1') is preferred in the lk 2.6 series. If either the input or output file is a raw device, or 'odir=1' is given then the internal buffers used by sg_dd are aligned to a memory page boundary. A memory page is 4 kilobytes in the i386 architecture. This memory alignment is required by both raw devices and normal block devices that implement O_DIRECT.

The 'blk_sgio=1' option (or 'iflag=sgio' and/or 'oflag=sgio') is only valid in the lk 2.6 series. This option instructs the sg_dd utility to use the SG_IO ioctl to issue SCSI commands even though the file type is not a scsi generic (sg) device. Currently this will work for all cd/dvd devices irrespective of the transport (except for some very old devices ( > 10 years old)) and block devices representing SCSI disks (e.g. /dev/sda). Even though SCSI tape (st) devices now accept the SG_IO ioctl in the lk 2.6 series, the sg_dd utility expects direct access devices (whereas tapes are sequential access) so sg_dd generates an error if a st device is detected. When the input or output file is a sg device then the 'blk_sgio' option is ignored as IO with that file is always via SCSI commands. When 'blk_sgio=1' is used with a block device and the value given to 'bpt' is too high then the first read may report an EIO (input/output) error; the solution is to lower the 'bpt' value. [The EIO error occurred often with CD/DVD drives which have 2048 bytes sectors, so the 'bpt' default value was reduced for block size >= 2048 bytes.]

If a partition of block device is accessed (e.g. /dev/sda2) when 'blk_sgio=0' (or is not given) then logical block address 0 for the purposes of sg_dd (and its skip and seek options) is the beginning of that partition while the calculated count (e.g. when a 'count' option is not given) is the extent of that partition. However if a partition of block device is accessed (e.g. /dev/sda2) when 'blk_sgio=1' then the partition is ignored and the underlying device is accessed. This means logical block address 0 for the purposes of sg_dd (and its skip and seek options) is the beginning of the device while the calculated count (e.g. when a 'count' option is not given) is the extent of that device.

When a CD is accessed via SCSI commands and the 'count' option is not given then the READ CAPACITY SCSI command is used by sg_dd to determine the number of blocks to read. Unfortunately some MMC standards allow a few of the final blocks to be invalid ("run out" sectors) and this can result in IO errors when the sg_dd utility is used to copy such a CD. The isosize utility can be used to determine the actual size of an ISO9660 file system residing on such a CD. It is often a few blocks shorter than READ CAPACITY reports (for good reason).

If a SIGUSR1 signal is sent to the process identifier (pid) of a running sg_dd utility then the number of blocks copied to that point is output. The copy continues.

When the 'time' option is set, the elapsed time for the copy plus the throughput measured in megabytes (10**6 bytes) per second is output when the copy is complete (or an error stops the copy). If a SIGUSR1 signal is sent to the process identifier (pid) of a running sg_dd utility which has the 'time' option set the elapsed time and the throughput of the copy to that point is output and the copy continues.

Continue on error (coe)

Recent additions to the sg_dd utility allow it to be used as a copy "of last resort" from failing media. Read errors on an input file taking SCSI commands are "tolerated" when the 'coe' option is non-zero. Write errors from SCSI commands are reported and ignored and the sg_dd utility continues when the 'coe' option is non-zero. [In the case where media errors are causing write errors the user should check the setting of the AWRE bit in the SCSI "read write error recovery" mode page (see SBC-2 at http://www.t10.org).]

When a SCSI READ command detects an unrecoverable read error it responds with a sense key of MEDIUM ERROR or HARDWARE ERROR. Additionally it responds with the logical block address of the first (lowest) block that it failed to read in the current READ command. Any valid blocks prior to the "bad" block may or may not have been transferred (depending on several other settings). If 'coe=0' then the sg_dd utility will simply terminate at this point (with a reasonable amount of debug information sent to stderr) and good blocks prior to the bad block may not be copied (depending on the setting of 'bpt'). If 'coe' is non-zero then the first thing sg_dd will try to do is a truncated read up to, but not including, the bad block. The remaining discussion in this section assumes 'coe' is non-zero.

The "bad" block may or may not be readable by the device. If it is readable then most likely the associated ECC data indicates that it is corrupt and the ECC data cannot recover it. [It is possible that all the corruption is in the ECC data and the payload data is ok.] Such blocks can be retrieved with the READ LONG command. If the READ LONG fails then a block of zeroes is substituted for the bad block in the transfer buffer. When 'coe=1' then READ LONG is not attempted and the "bad" block is replaced by zeroes. When 'coe=2' (or 'iflag=coe,coe') then a READ LONG is attempted. When 'coe=3' then a READ LONG with its CORRCT bit set is attempted. Only SBC devices (primarily SCSI disks) optionally support READ LONG. CD/DVD devices (covered in the MMC-4 (draft) standard) do not, so a block of zeroes is substituted for them. Even if READ LONG succeeds on a "bad" block, the recovered data may not be useful. There are no guarantees that the user data will appear "as is" in the first 512 bytes.

There still remain blocks after the "bad" block that need to be fetched. Further bad blocks may be detected and if so the algorithm in the last two paragraphs is repeated. The result of this process is an imperfect copy with blocks that were read properly placed in the correct relative position in the output. When the 'coe=1' option is given two addition counters are output on completion:

unrecovered errors (number of bad blocks)
read_longs that "successfully" fetched part of those bad blocks

The first counter is the number of unrecovered (read) errors encountered. Any number greater than zero flags an imperfect copy. The second counter (always less than or equal to the first) is the number of "successful" READ LONG SCSI commands performed. If the source media is a CD or DVD then this number will be zero.

Recovered errors

Often errors are recovered using ECC data or by the device retrying (usually re-reading) the media. Typically at the first sign of trouble, recoverable errors lead to the block in question being reassigned to another location on the media (automatically when the AWRE and ARRE bits are set in the "read write error recovery" mode page). The user of such a disk may be blissfully unaware that the disk may be reaching the end of its useful life. Error counters are maintained in the "Read error counter" and "Write error counter" logs pages which can be viewed with smartctl (from smartmontools) and sg_logs (from the same sg3_utils package that sg_dd comes from). Any block that is automatically or manually re-assigned adds a new entry to the "grown" defect list which can be viewed with 'sginfo -G' or 'sg_reassign -g' (both found in the sg3_utils package).

A disk can be instructed to report RECOVERED ERRORs by setting the PER bit in the "read write error recover" mode page. Most often this bit is clear. When sg_dd detects RECOVERED ERRORs it reports them, counts them and continues the copy. Only the lba of the last recovered error in a READ or WRITE SCSI command is reported so there could be more than one recovered error per SCSI command. The 'bpt=1' option could be chosen to limit every SCSI command to a single block transfer (but that would slow things down a fair amount). If the count of recovered errors is greater than zero at the end of the copy then this count is output as well.

There can be other reasons for a sense key of RECOVERED ERROR not directly related to data being currently read or written. SMART alerts (called in SCSI documents "Informational Exceptions") can be conveyed via a RECOVERED ERROR sense key (see the MRIE field in the Informational Exceptions mode page). Such alerts have additional sense codes like "Failure prediction threshold exceeded" and those that contain "impending failure".

Verbose

In the Unix style, sg_dd doesn't output anything (to stderr) during large IO transfers. To get a progress report the SIGUSR1 signal can be sent to the sg_dd process. In the Unix dd command style, sg_dd outputs two lines on completion that show the number of full and partial records in (on the first line) and out (on the second line). Some modern versions of the dd command also output elapsed time and throughput figures (to get this with sg_dd use the "time=1" option).

The sg_dd has a 'verbose' option whose default value is zero. When set this option has the following actions:

show categorization and INQUIRY data (where applicable) for the input and output files. For files, other than streams, the file/device size (and device block size) are output.
same output as 1 plus data for Unix and SCSI commands (cdbs) that are not repeated (i.e. other than Unix read/write and SCSI READ/WRITE commands). Increased error reporting for all SCSI commands
same output as 2 plus data for Unix and SCSI commands (cdbs) that are repeated. For a large copy this will be a lot of output.
maximum amount of debug output. For a large copy this will be a lot of output.

All verbose output is sent to stderr (so that sg_dd usage with "of=-" (copy output to stdout) is not corrupted).

Following is an example of using 'verbose=1' to find information about /dev/sda . If no copy is required then setting 'count=0' will see to that. Since "dev/sda" is a block device then it would normally be accessed via Unix system commands. The 'verbose=1' output is relatively short when 'blk_sgio=0' (its default value). The second invocation is with 'blk_sgio=1' and a lot more is output. That includes INQUIRY standard response data (e.g. "SEAGATE ..." line). See the SBC-2 drafts at www.t10.org for more information.

$ sg_dd if=/dev/sda of=. bs=512 verbose=1 count=0 blk_sgio=0
>> Input file type: block device
        open input, flags=0x0
>> Output file type: null device
      [bgs64] number of blocks=17781521 [0x10f5311], block size=512
0+0 records in
0+0 records out

$ sg_dd if=/dev/sda of=. bs=512 verbose=1 count=0 blk_sgio=1
>> Input file type: block device
        open input(sg_io), flags=0x2
    /dev/sda: SEAGATE   ST39173LC         1234 [pdt=0]
>> Output file type: null device
      number of blocks=17781521 [0x10f5311], block size=512
0+0 records in
0+0 records out

Some of the output above is out of order, the "number of blocks" line relates to the input file.

Mode page settings can be examined and changed with a utility like sdparm .

sgp_dd, sgm_dd and sg_read

These three sg3_utils utilities are closely related to sg_dd . They all have their own man pages.

sgp_dd uses POSIX threads (default: 4 threads) to potentially speed the copy. The syntax and semantics of sgp_dd are very similar to sg_dd. The "continue on error" processing in sgp_dd is simpler than what is described above for sg_dd.

sgm_dd uses memory mapped IO to speed copies from or to sg device nodes. Memory mapped IO will bypass the kernel buffers used by the sg driver for normal data transfers. With memory mapped IO the Host Bus Adapter (HBA) DMA mechanism will transfer data directly from the external bus (e.g. fibre channel) to the user space. Even though this may seem like a major performance win, there are various low level details (e.g. alignment and signal processing) that complicate the picture.

sg_read uses a similar syntax to sg_dd but has no 'of=<ofile>'. It is designed to measure the performance of device (e.g. disk) caches, the throughput of the transport and command overhead. It perform a read (either a SCSI READ command or a Unix read()) from the given skip block address (default logical block address 0) and continues doing reads until 'count=<blocks>' is exhausted. If multiple reads are performed (i.e. when "count > bpt") then they are all from the same logical address. For example, with SCSI READs, exactly the same READ cdb is issued for each read operation. The data is thrown away. Zero block reads can also be issued using a negative count value. This is useful for measuring SCSI command overhead.

Conclusion

The sg_dd utility maintains syntactic and semantic compatibility with the Unix/GNU dd command while allowing precise control over SCSI devices such as SCSI disks and CD/DVD drives. Amongst other uses, it can copy data from failing media, continuing as best it can in the presence of MEDIUM errors, while recovering as much data as possible.

Return to main page.

Last updated: 29th May 2006