285 lines
12 KiB
Groff
285 lines
12 KiB
Groff
.TH SGM_DD "8" "February 2019" "sg3_utils\-1.45" SG3_UTILS
|
|
.SH NAME
|
|
sgm_dd \- copy data to and from files and devices, especially SCSI
|
|
devices
|
|
.SH SYNOPSIS
|
|
.B sgm_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] [\fIcdbsz=\fR6|10|12|16] [\fIdio=\fR0|1] [\fIsync=\fR0|1]
|
|
[\fItime=\fR0|1] [\fIverbose=VERB\fR] [\fI\-\-dry\-run\fR]
|
|
[\fI\-\-verbose\fR]
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
Copy data to and from any files. Specialized for "files" that are
|
|
Linux SCSI generic (sg) devices and raw devices. Uses memory mapped
|
|
transfers on sg devices. Similar syntax and semantics to
|
|
.B dd(1)
|
|
but does not perform any conversions.
|
|
.PP
|
|
Will only perform memory mapped transfers when \fIIFILE\fR or \fIOFILE\fR
|
|
are SCSI generic (sg) devices.
|
|
.PP
|
|
If both \fIIFILE\fR and \fIOFILE\fR are sg devices then memory mapped
|
|
transfers are performed on \fIIFILE\fR. If no other flags are specified
|
|
then indirect IO is performed on \fIOFILE\fR. If 'oflag=dio' is given then
|
|
direct IO is attempted on \fIOFILE\fR. If direct IO is not available, then
|
|
this utility falls back to indirect IO and reports this at the end of the
|
|
copy.
|
|
.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 \fIBS\fR to be an integral multiple. Default is 512 which
|
|
is usually correct for disks but incorrect for cdroms (which normally
|
|
have 2048 byte blocks). For this utility the maximum size of each individual
|
|
IO operation is \fIBS\fR * \fIBPT\fR bytes.
|
|
.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
|
|
\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 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 \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 derived then an error message is issued and no copy takes place.
|
|
.TP
|
|
\fBdio\fR=0 | 1
|
|
permits direct IO to be selected on the write\-side (i.e. on \fIOFILE\fR).
|
|
Only allowed when the read\-side (i.e. \fIIFILE\fR) is a sg device. When
|
|
1 there may be a "zero copy" copy (i.e. mmap\-ed transfer 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.
|
|
The same action as 'dio=1' is also available with '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
|
|
\fBtime\fR=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
|
|
\fBverbose\fR=\fIVERB\fR
|
|
as \fIVERB\fR increases so does the amount of debug output sent to stderr.
|
|
Default value is zero which yields the minimum amount of debug output.
|
|
A value of 1 reports extra information that is not repetitive. A value
|
|
2 reports cdbs and responses for SCSI commands that are not repetitive
|
|
(i.e. other that READ and WRITE). Error processing is not considered
|
|
repetitive. Values of 3 and 4 yield output for all SCSI commands (and
|
|
Unix read() and write() calls) so there can be a lot of output.
|
|
.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
|
|
dio
|
|
is only active with oflag (i.e. 'oflag=dio'). Its action is described in
|
|
the 'dio=1' option description above.
|
|
.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
|
|
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
|
|
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 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 the lsscsi utility
|
|
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 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 transfers 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.
|
|
.PP
|
|
For sg devices this utility issues SCSI READ and WRITE (SBC) commands which
|
|
are appropriate for disks and reading from CD/DVD/BD drives. Those commands
|
|
are not formatted correctly for tape devices so sgm_dd should not be used
|
|
on tape devices.
|
|
.PP
|
|
This utility stops the copy if any error is encountered. For more
|
|
advanced "copy on error" logic see the
|
|
.B sg_dd
|
|
utility (and its 'coe' flag).
|
|
.SH EXAMPLES
|
|
See the examples given in the man page for
|
|
.B sg_dd(8).
|
|
.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 EXIT STATUS
|
|
The exit status of sgm_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\-2019 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 dd(1), ddpt(ddpt), raw(8)
|