| .TH SG_DD "8" "April 2003" "sg3_utils-1.04" SG3_UTILS |
| .SH NAME |
| sg_dd \- copies data to and from sg and raw devices |
| .SH SYNOPSIS |
| .B sg_dd |
| [\fIappend=0|1\fR] [\fIblk_sgio=0|1\fR] [\fIbpt=<n>\fR] [\fIbs=<n>\fR] |
| [\fIcdbsz=6|10|12|16\fR] [\fIcoe=0|1\fR] [\fIcount=<n>\fR] [dio=0|1] |
| [\fIfua=0|1|2|3\fR] [\fIibs=<n>\fR] [\fIif=<ifile>\fR] [\fIobs=<n>\fR] |
| [\fIodir=0|1\fR] [\fIof=<ofile>\fR] [\fIseek=<n>\fR] [\fIskip=<n>\fR] |
| [\fIsync=0|1\fR] [\fItime=0|1\fR] [\fI--version\fR] |
| .SH DESCRIPTION |
| .\" Add any additional description here |
| .PP |
| Copy data to and from Linux SCSI generic (sg) devices, raw devices and |
| those block devices that support the SG_IO ioctl (which are only found |
| in the lk 2.5 series). Data may be copied to and from normal files |
| as well. |
| Similar syntax and semantics to |
| .B dd(1) |
| but does not perform any conversions. |
| .TP |
| append=0 | 1 |
| when set to 1 the output will be appended to the normal file given |
| to the "of=<name>" argument. Appending only takes place to normal files: |
| not pipes nor raw files nor sg devices. Error message produced if |
| append=1 and seek=<n> where <n> > 0. Default is 0 which starts |
| output at offset of a normal file (subject to the "seek=" argument). |
| .TP |
| blk_sgio=0 | 1 |
| when set to 0 block devices (e.g. /dev/sda) are treated like |
| normal files. When set to 1 the block device is assumed to accept the |
| SG_IO ioctl; this is only appropriate for kernels later than lk 2.5.48 . |
| Default is 0. |
| .TP |
| bpt=BLOCKS |
| each IO transaction will be made using this number of blocks (or less if |
| near the end of count). Default is 128. So for an sg file and bs=512 each |
| SCSI command conveys 64KB of data by default. |
| .TP |
| bs=BYTES |
| this |
| .B must |
| be the block size of the physical device. Note that this differs from |
| .B dd(1) |
| which permits "bs" to be an integral multiple. Default is 512 which |
| is usually correct for disks but incorrect for cdroms (which normally |
| have 2048 byte blocks). |
| .TP |
| cdbsz=6 | 10 | 12 | 16 |
| size of SCSI READ and/or WRITE commands issued on sg device names. |
| Default is 10 byte SCSI command blocks |
| .TP |
| coe=0 | 1 |
| set to 1 for continue on error: if reading assume zeros read, if writing |
| then ignore and continue. Only applies to errors on sg devices (e.g. |
| errors on normal files will stop sg_dd). Error messages are still sent to |
| stderr. Default is 0 for do not continue on error |
| .TP |
| count=BLOCKS |
| copy this number of blocks. Default is minimum number that sg devices |
| return from READ CAPACITY (if that works) or 0 |
| .TP |
| dio=0 | 1 |
| default is 0 which selects indirect IO. Value of 1 attempts direct |
| IO which, if not available, falls back to indirect IO and notes this |
| at completion. If direct IO is selected and /proc/scsi/sg/allow_dio |
| has the value of 0 then a warning is issued (and indirect IO is performed) |
| .TP |
| fua=0 | 1 | 2 | 3 |
| force unit access bit. When 3, fua is set on both "if" and "of", when 2, fua |
| is set on "if", when 1, fua is set on "of", when 0, fua is cleared on both. |
| 6 byte SCSI READ and WRITE commands (cdbsz=6) do not support the fua bit. |
| Only active for sg device file names |
| .TP |
| ibs=BYTES |
| if given must be the same as bs |
| .TP |
| if=FILE |
| read from FILE instead of stdin. A file name of - is taken to be stdin |
| .TP |
| obs=BYTES |
| if given must be the same as bs |
| .TP |
| odir=0 | 1 |
| when set to one opens block devices (e.g. /dev/sda) with the O_DIRECT |
| flag. User memory buffers are aligned to the page size when set. The |
| default is 0 (i.e. the O_DIRECT flag is not used). The blk_sgio flag |
| takes precedence if it is also set. Has no effect on sg, normal or raw |
| files. |
| .TP |
| of=FILE |
| write to FILE instead of stdout. A file name of - is taken to be stdout. |
| If FILE is /dev/null then no actual writes are performed. If FILE is . |
| (period) then it is treated the same way as /dev/null (this is a |
| shorthand notation) |
| .TP |
| seek=BLOCKS |
| skip BLOCKS bs-sized blocks at start of output |
| .TP |
| skip=BLOCKS |
| skip BLOCKS bs-sized blocks at start of input |
| .TP |
| sync=0 | 1 |
| when 1, does SYNCHRONIZE CACHE command on "of" at the end of the transfer. |
| Only active when "of" is a sg device file name |
| .TP |
| time=0 | 1 |
| when 1, times transfer and does throughput calculation, outputting the |
| results (to stderr) at completion. When 0 (default) doesn't perform timing |
| .TP |
| --version |
| outputs version number information and exits |
| .PP |
| A raw device must be bound to a block device prior to using sg_dd. |
| See |
| .B raw(8) |
| for more information about binding raw devices. To be safe, the sg device |
| mapping to SCSI block devices should be checked with "cat /proc/scsi/scsi", |
| or sg_map before use. |
| .PP |
| The count is only deduced for sg devices (minimum > 0 if both input and |
| output are sg devices) otherwise it defaults to 0. This is for safety! |
| Raw device partition information can often be found with |
| .B fdisk(8) |
| [the "-ul" argument is useful in this respect]. |
| .PP |
| BYTES and BLOCKS may be followed by the following multiplicative suffixes: |
| c C *1; b B *512; k *1,024; K *1,000; m *1,048,576; M *1,000,000; |
| g *1,073,741,824; and G *1,000,000,000 |
| .PP |
| Data usually gets to the user space in a 2 stage process: first the |
| SCSI adapter DMAs into kernel buffers and then the sg driver copies |
| this data into user memory (write operations reverse this sequence). |
| This is called "indirect IO" and there is a "dio" option to select |
| "direct IO" which will DMA directly into user memory. Due to some |
| issues "direct IO" is disabled in the sg driver and needs a |
| configuration change to activate it. This is typically done with |
| "echo 1 > /proc/scsi/sg/allow_dio". |
| .PP |
| All informative, warning and error output is sent to stderr so that |
| dd's output file can be stdout and remain unpolluted. If no options |
| are given, then the usage message is output and nothing else happens. |
| .SH EXAMPLES |
| .PP |
| Looks quite similar in usage to dd: |
| .PP |
| sg_dd if=/dev/sg0 of=t bs=512 count=1M |
| .PP |
| This will copy 1 million 512 byte blocks from the device associated with |
| /dev/sg0 (which should have 512 byte blocks) to a file called t. |
| Assuming /dev/sda and /dev/sg0 are the same device then the above is |
| equivalent to: |
| .PP |
| dd if=/dev/sda of=t bs=512 count=1000000 |
| .PP |
| although dd's speed may improve if bs was larger and count was suitably |
| reduced. Using a raw device to do something similar on a IDE disk: |
| .PP |
| raw /dev/raw/raw1 /dev/hda |
| .br |
| sg_dd if=/dev/raw/raw1 of=t bs=512 count=1M |
| .PP |
| To copy a SCSI disk partition to an IDE disk partition: |
| .PP |
| raw /dev/raw/raw2 /dev/hda3 |
| .br |
| sg_dd if=/dev/sg0 skip=10123456 of=/dev/raw/raw2 bs=512 |
| .PP |
| This assumes a valid partition is found on the SCSI disk at the given |
| skip block address (past the 5 GB point of that disk) and that |
| the partition goes to the end of the SCSI disk. An explicit count |
| is probably a safer option. |
| .PP |
| To time a streaming read of the first 1 GB on a disk this command |
| could be used: |
| .PP |
| sg_dd if=/dev/sg0 of=/dev/null bs=512 count=2m time=1 |
| .PP |
| On completion this will output a line like: |
| "time to transfer data was 18.779506 secs, 57.18 MB/sec". The "MB/sec" |
| in this case is 1,000,000 bytes per second. |
| .SH NOTE |
| For sg devices this command issues READ_10 and WRITE_10 SCSI commands which |
| are appropriate for disks and CDROM players. Those commands are not |
| formatted correctly for tape devices so sg_dd should not be used on |
| tape devices. |
| .SH SIGNALS |
| The signal handling has been borrowed from dd: SIGINT, SIGQUIT and |
| SIGPIPE output the number of remaining blocks to be transferred and |
| the records in + out counts; then they have their default action. |
| SIGUSR1 causes the same information to be output yet the copy continues. |
| All output caused by signals is sent to stderr. |
| .SH AUTHORS |
| Written by Doug Gilbert and Peter Allworth. |
| .SH "REPORTING BUGS" |
| Report bugs to <dgilbert@interlog.com>. |
| .SH COPYRIGHT |
| Copyright \(co 2000-2003 Douglas Gilbert |
| .br |
| This software is distributed under the GPL version 2. There is NO |
| warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| .SH "SEE ALSO" |
| A POSIX threads version of this command called |
| .B sgp_dd |
| is in the sg3_utils package. Another version from that package is called |
| .B sgm_dd |
| and it uses memory mapped IO to speed transfers from sg devices. |
| The lmbench package contains |
| .B lmdd |
| which is also interesting. |
| .B raw(8), dd(1) |