| .TH SGM_DD "8" "February 2005" "sg3_utils-1.13" SG3_UTILS |
| .SH NAME |
| sgm_dd \- copies data to and from files and devices. Specialised for |
| devices that understand the SCSI command set. |
| .SH SYNOPSIS |
| .B sgm_dd |
| [\fIbpt=<n>\fR] [\fIbs=<n>\fR] [\fIcdbsz=6|10|12|16\fR] [\fIcount=<n>\fR] |
| [\fIdio=0|1\fR] [\fIfua=0|1|2|3\fR] [\fIibs=<n>\fR] [\fIif=<ifile>\fR] |
| [\fIobs=<n>\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 any files. Specialised for "files" that are |
| Linux SCSI generic (sg) devices and raw devices. Uses memory mapped IO on |
| sg devices. Similar syntax and semantics to |
| .B dd(1) |
| but does not perform any conversions. |
| .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. |
| .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 (or block devices when "blk_sgio=1" is given). |
| Default is 10 byte SCSI command blocks (unless calculations indicate |
| that a 4 byte block number may be exceeded, in which case it defaults |
| to 16 byte SCSI commands). |
| .TP |
| count=BLOCKS |
| copy this number of blocks from 'if' to 'of'. Default is the |
| minimum (of 'if' and 'of') number of blocks that sg devices return from |
| READ CAPACITY SCSI commands or that block devices (or their partitions) |
| report. Normal files are not probed for their size. If 'skip' |
| or 'seek' are given and the count is derived (i.e. not explicitly given) |
| then the derived count is scaled back so that the copy will not overrun the |
| device. If the file name is a block device partition and count is not given |
| then the size of the partition rather than the size of the whole device is |
| used. If count is not given and cannot be derived then an error message |
| is issued and no copy takes place. |
| .TP |
| dio=0 | 1 |
| permits direct IO to be selected on the write-side (i.e. "of"). Only |
| allowed when the read-side (i.e. "if") is a sg device. When 1 there |
| may be a "zero copy" copy (i.e. mmap-ed IO on the read into the user |
| space and direct IO from there on the write, potentially two DMAs and |
| no data copying from the CPU). Default is 0 |
| .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 (the default), 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 which is the default. A file name of "-" |
| is taken to be stdin. Starts reading at the beginning of FILE |
| unless "skip" is given. |
| .TP |
| obs=BYTES |
| if given must be the same as bs |
| .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 |
| start writing BLOCKS bs-sized blocks from the start of the output file. |
| Default is block 0 (i.e. start of file). |
| .TP |
| skip=BLOCKS |
| start reading BLOCKS bs-sized blocks from the start of input file. |
| Default is block 0 (i.e. start of file). |
| .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 sgm_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" |
| before use. |
| .PP |
| 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 one of these multiplicative suffixes: |
| c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; |
| MB *1,000,000 . This pattern continues for "G", "T" and "P". The latter two |
| suffixes can only be used for count, skip and seek values). Also a suffix of |
| the form "x<n>" multiplies the leading number by <n>. These multiplicative |
| suffixes are compatible with GNU's dd command (since 2002) which claims |
| compliance with SI and with IEC 60027-2. |
| .PP |
| Alternatively numerical values can be given in hexadecimal preceded by |
| either "0x" or "0X". When hex numbers are given multipliers cannot be |
| used. |
| .PP |
| The count, skip and seek parameters can take 64 bit values (i.e. very |
| big numbers). Other values are limited to what can fit in a signed |
| 32 bit number. |
| .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). |
| With memory mapped IO a kernel buffer reserved by sg is memory mapped |
| (see the |
| .B mmap(2) |
| system call) into the user space. When this is done |
| the second (redundant) copy from kernel buffers to user space is |
| not needed. Hence the transfer is faster and requires less "grunt" |
| from the CPU. |
| .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 |
| See the examples given in the man page for |
| .B sg_dd(8). |
| .SH NOTE |
| For sg devices this utility issues READ and WRITE (SBC) SCSI commands |
| which are appropriate for disks and reading from CD/DVD drives. Those |
| commands are not formatted correctly for tape devices so sgm_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 at interlog dot com>. |
| .SH COPYRIGHT |
| Copyright \(co 2000-2005 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" |
| The simplest variant of this utility is called |
| .B sg_dd. |
| A POSIX threads version of this utility called |
| .B sgp_dd |
| is in the sg3_utils package. The lmbench package contains |
| .B lmdd |
| which is also interesting. |
| .B raw(8), dd(1) |