diff options
Diffstat (limited to 'doc/sgp_dd.8')
| -rw-r--r-- | doc/sgp_dd.8 | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/doc/sgp_dd.8 b/doc/sgp_dd.8 new file mode 100644 index 00000000..b6184a03 --- /dev/null +++ b/doc/sgp_dd.8 @@ -0,0 +1,345 @@ +.TH SGP_DD "8" "August 2022" "sg3_utils\-1.47" SG3_UTILS +.SH NAME +sgp_dd \- copy data to and from files and devices, especially SCSI +devices +.SH SYNOPSIS +.B sgp_dd +[\fIbs=BS\fR] [\fIcount=COUNT\fR] [\fIibs=BS\fR] [\fIif=IFILE\fR] +[\fIiflag=FLAGS\fR] [\fIobs=BS\fR] [\fIof=OFILE\fR] [\fIoflag=FLAGS\fR] +[\fIseek=SEEK\fR] [\fIskip=SKIP\fR] [\fI\-\-help\fR] [\fI\-\-version\fR] +.PP +[\fIbpt=BPT\fR] [\fIcoe=\fR0|1] [\fIcdbsz=\fR6|10|12|16] [\fIdeb=VERB\fR] +[\fIdio=\fR0|1] [\fIsync=\fR0|1] [\fIthr=THR\fR] [\fItime=\fR0|1] +[\fIverbose=VERB\fR] [\fI\-\-chkaddr\fR] [\fI\-\-dry\-run\fR] +[\fI\-\-verbose\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) and raw devices. Similar syntax and semantics to +.B dd(1) +but does not perform any conversions. Uses POSIX threads (often +called "pthreads") to increase the amount of parallelism. This improves +speed in some cases. +.PP +The first group in the synopsis above are "standard" Unix +.B dd(1) +operands. The second group are extra options added by this utility. +Both groups are defined below. +.SH OPTIONS +.TP +\fBbpt\fR=\fIBPT\fR +each IO transaction will be made using \fIBPT\fR blocks (or less if +near the end of the copy). Default is 128 for block sizes less that 2048 +bytes, otherwise the default is 32. So for bs=512 the reads and writes +will each convey 64 KiB of data by default (less if near the end of the +transfer or memory restrictions). When cd/dvd drives are accessed, the +block size is typically 2048 bytes and bpt defaults to 32 which again +implies 64 KiB transfers. +.TP +\fBbs\fR=\fIBS\fR +where \fIBS\fR +.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 of the actual device block +size. Default is 512 which is usually correct for disks but incorrect for +cdroms (which normally have 2048 byte blocks). +.TP +\fBcdbsz\fR=6 | 10 | 12 | 16 +size of SCSI READ and/or WRITE commands issued on sg device names. +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 +\fBcoe\fR=0 | 1 +set to 1 for continue on error. Only applies to errors on sg devices. +Thus errors on other files will stop sgp_dd. Default is 0 which +implies stop on any error. See the 'coe' flag for more information. +.TP +\fBcount\fR=\fICOUNT\fR +copy \fICOUNT\fR blocks from \fIIFILE\fR to \fIOFILE\fR. Default is the +minimum (of \fIIFILE\fR and \fIOFILE\fR) number of blocks that sg devices +report from SCSI READ CAPACITY commands or that block devices (or their +partitions) report. Normal files are not probed for their size. If +\fIskip=SKIP\fR or \fIseek=SEEK\fR are given and the count is deduced (i.e. +not explicitly given) then that count is scaled back so that the copy will +not overrun the device. If the file name is a block device partition and +\fICOUNT\fR is not given then the size of the partition rather than the +size of the whole device is used. If \fICOUNT\fR is not given and cannot be +deduced then an error message is issued and no copy takes place. +.TP +\fBdeb\fR=\fIVERB\fR +outputs debug information. If \fIVERB\fR is 0 (default) then there is +minimal debug information and as \fIVERB\fR increases so does the amount +of debug (max debug output when \fIVERB\fR is 9). +.TP +\fBdio\fR=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 /sys/module/sg/parameters/allow_dio +has the value of 0 then a warning is issued (and indirect IO is performed) +For finer grain control use 'iflag=dio' or 'oflag=dio'. +.TP +\fBibs\fR=\fIBS\fR +if given must be the same as \fIBS\fR given to 'bs=' option. +.TP +\fBif\fR=\fIIFILE\fR +read from \fIIFILE\fR instead of stdin. If \fIIFILE\fR is '\-' then stdin +is read. Starts reading at the beginning of \fIIFILE\fR unless \fISKIP\fR +is given. +.TP +\fBiflag\fR=\fIFLAGS\fR +where \fIFLAGS\fR is a comma separated list of one or more flags outlined +below. These flags are associated with \fIIFILE\fR and are ignored when +\fIIFILE\fR is stdin. +.TP +\fBobs\fR=\fIBS\fR +if given must be the same as \fIBS\fR given to 'bs=' option. +.TP +\fBof\fR=\fIOFILE\fR +write to \fIOFILE\fR instead of stdout. If \fIOFILE\fR is '\-' then writes +to stdout. If \fIOFILE\fR is /dev/null then no actual writes are performed. +If \fIOFILE\fR is '.' (period) then it is treated the same way as +/dev/null (this is a shorthand notation). If \fIOFILE\fR exists then it +is _not_ truncated; it is overwritten from the start of \fIOFILE\fR +unless 'oflag=append' or \fISEEK\fR is given. +.TP +\fBoflag\fR=\fIFLAGS\fR +where \fIFLAGS\fR is a comma separated list of one or more flags outlined +below. These flags are associated with \fIOFILE\fR and are ignored when +\fIOFILE\fR is /dev/null, '.' (period), or stdout. +.TP +\fBseek\fR=\fISEEK\fR +start writing \fISEEK\fR bs\-sized blocks from the start of \fIOFILE\fR. +Default is block 0 (i.e. start of file). +.TP +\fBskip\fR=\fISKIP\fR +start reading \fISKIP\fR bs\-sized blocks from the start of \fIIFILE\fR. +Default is block 0 (i.e. start of file). +.TP +\fBsync\fR=0 | 1 +when 1, does SYNCHRONIZE CACHE command on \fIOFILE\fR at the end of the +transfer. Only active when \fIOFILE\fR is a sg device file name. +.TP +\fBthr\fR=\fITHR\fR +where \fITHR\fR is the number or worker threads (default 4) that attempt to +copy in parallel. Minimum is 1 and maximum is 1024. +.TP +\fBtime\fR=0 | 1 +when 1, the transfer is timed and throughput calculation is +performed, outputting the results (to stderr) at completion. When +0 (default) no timing is performed. +.TP +\fBverbose\fR=\fIVERB\fR +increase verbosity. Same as \fIdeb=VERB\fR. Added for compatibility with +sg_dd and sgm_dd. +.TP +\fB\-c\fR, \fB\-\-chkaddr\fR +this option checks that every block read contains the (32 bit) block address +of that block. If that check fails, the copy exits with a miscompare error. +This check complements the 'sg_dd iflag=00,ff' generation of blocks that +contain their own (32 bit, big endian) block address. When \fI\-\-chkaddr\fR +is used once, only the first block address in each block is checked. When +used twice, each block address (that fits in a block) is checked. +.TP +\fB\-d\fR, \fB\-\-dry\-run\fR +does all the command line parsing and preparation but bypasses the actual +copy or read. That preparation may include opening \fIIFILE\fR or +\fIOFILE\fR to determine their lengths. This option may be useful for +testing the syntax of complex command line invocations in advance of +executing them. +.TP +\fB\-h\fR, \fB\-\-help\fR +outputs usage message and exits. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +when used once, this is equivalent to \fIverbose=1\fR. When used +twice (e.g. "\-vv") this is equivalent to \fIverbose=2\fR, etc. +.TP +\fB\-V\fR, \fB\-\-version\fR +outputs version number information and exits. +.SH FLAGS +Here is a list of flags and their meanings: +.TP +append +causes the O_APPEND flag to be added to the open of \fIOFILE\fR. For normal +files this will lead to data appended to the end of any existing data. +Cannot be used together with the \fIseek=SEEK\fR option as they conflict. +The default action of this utility is to overwrite any existing data +from the beginning of the file or, if \fISEEK\fR is given, starting at +block \fISEEK\fR. Note that attempting to 'append' to a device file (e.g. +a disk) will usually be ignored or may cause an error to be reported. +.TP +coe +continue on error. When given with 'iflag=', an error that is detected +in a single SCSI command (typically 'bpt' blocks) is noted (by an error +message sent to stderr), then zeros are substituted into the buffer +for the corresponding write operation and the copy continues. Note that the +.B sg_dd +utility is more sophisticated in such error situations when 'iflag=coe'. +When given with 'oflag=', any error reported by a SCSI WRITE command is +reported to stderr and the copy continues (as if nothing went wrong). +.TP +dio +request the sg device node associated with this flag does direct IO. +If direct IO is not available, falls back to indirect IO and notes +this at completion. If direct IO is selected and +/sys/module/sg/parameters/allow_dio has the value of 0 then a warning is +issued (and indirect IO is performed). +.TP +direct +causes the O_DIRECT flag to be added to the open of \fIIFILE\fR and/or +\fIOFILE\fR. This flag requires some memory alignment on IO. Hence user +memory buffers are aligned to the page size. Has no effect on sg, normal +or raw files. +.TP +dpo +set the DPO bit (disable page out) in SCSI READ and WRITE commands. Not +supported for 6 byte cdb variants of READ and WRITE. Indicates that +data is unlikely to be required to stay in device (e.g. disk) cache. +May speed media copy and/or cause a media copy to have less impact +on other device users. +.TP +dsync +causes the O_SYNC flag to be added to the open of \fIIFILE\fR and/or +\fIOFILE\fR. The 'd' is prepended to lower confusion with the 'sync=0|1' +option which has another action (i.e. a synchronisation to media at the +end of the transfer). +.TP +excl +causes the O_EXCL flag to be added to the open of \fIIFILE\fR and/or +\fIOFILE\fR. +.TP +mmap +can only be used in the \fIiflag=FLAGS\fR or the \fIoflag=FLAGS\fR argument +list but not both. The nominated side of the copy will use memory mapped IO +based on the mmap(2) system call. The sg driver will remap its DMA +destination or source buffer into the user space when the mmap(2) system call +is used on a sg device. +.TP +fua +causes the FUA (force unit access) bit to be set in SCSI READ and/or WRITE +commands. This only has effect with sg devices. The 6 byte variants +of the SCSI READ and WRITE commands do not support the FUA bit. +Only active for sg device file names. +.TP +null +has no affect, just a placeholder. +.SH RETIRED OPTIONS +Here are some retired options that are still present: +.TP +coe=0 | 1 +continue on error is 0 (off) by default. When it is 1, it is +equivalent to 'iflag=coe oflag=coe' described in the FLAGS section +above. Similar to 'conv=noerror,sync' in +.B dd(1) +utility. Default is 0 which implies stop on error. More advanced +coe=1 processing on reads is performed by the sg_dd utility. +.TP +.TP +fua=0 | 1 | 2 | 3 +force unit access bit. When 3, fua is set on both \fIIFILE\fR and +\fIOFILE\fR; when 2, fua is set on \fIIFILE\fR;, when 1, fua is set on +\fIOFILE\fR; when 0 (default), fua is cleared on both. See the 'fua' flag. +.SH NOTES +A raw device must be bound to a block device prior to using sgp_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 'sg_map' +before use. +.PP +Raw device partition information can often be found with +.B fdisk(8) +[the "\-ul" argument is useful in this respect]. +.PP +Various numeric arguments (e.g. \fISKIP\fR) may include multiplicative +suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section +in the sg3_utils(8) man page. +.PP +The \fICOUNT\fR, \fISKIP\fR and \fISEEK\fR arguments 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). +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. +.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. +.PP +Why use sgp_dd? Because in some cases it is twice as fast as dd +(mainly with sg devices, raw devices give some improvement). +Another reason is that big copies fill the block device caches +which has a negative impact on other machine activity. +.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 EXAMPLES +.PP +Looks quite similar in usage to dd: +.PP + sgp_dd if=/dev/sg0 of=t bs=512 count=1MB +.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 +correspondingly scaled. Using a raw device to do something similar on a +ATA disk: +.PP + raw /dev/raw/raw1 /dev/hda +.br + sgp_dd if=/dev/raw/raw1 of=t bs=512 count=1MB +.PP +To copy a SCSI disk partition to an ATA disk partition: +.PP + raw /dev/raw/raw2 /dev/hda3 +.br + sgp_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 do a fast copy from one SCSI disk to another one with similar +geometry (stepping over errors on the source disk): +.PP + sgp_dd if=/dev/sg0 of=/dev/sg1 bs=512 coe=1 +.SH EXIT STATUS +The exit status of sgp_dd is 0 when it is successful. Otherwise see +the sg3_utils(8) man page. Since this utility works at a higher level +than individual commands, and there are 'coe' and 'retries' flags, +individual SCSI command failures do not necessary cause the process +to exit. +.SH AUTHORS +Written by Douglas Gilbert and Peter Allworth. +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2000\-2022 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 simpler, non\-threaded version of this utility but with more +advanced "continue on error" logic is called +.B sg_dd +and is also found in the sg3_utils package. The lmbench package contains +.B lmdd +which is also interesting. +.B raw(8), dd(1) |