18
20
but does not perform any conversions. Uses POSIX threads to increase
19
21
the amount of parallelism. This improves speed in some cases.
23
The first group in the synopsis above are "standard" Unix
25
arguments. The second group are extra arguments added by this utility.
26
Both groups are defined below.
22
each IO transaction will be made using this number of blocks (or less if
23
near the end of count). Default is 128.
29
each IO transaction will be made using this number of blocks (or less if
30
near the end of count). Default is 128 for block sizes less that 2048
31
bytes, otherwise the default is 32. So for bs=512 the reads and writes
32
will each convey 64 KiB of data by default (less if near the end of the
33
transfer or memory restrictions). When cd/dvd drives are accessed, the
34
block size is typically 2048 bytes and bpt defaults to 32 which again
35
implies 64 KiB transfers.
28
40
be the block size of the physical device. Note that this differs from
30
which permits "bs" to be an integral multiple. Default is 512 which
31
is usually correct for disks but incorrect for cdroms (which normally
32
have 2048 byte blocks).
42
which permits 'bs' to be an integral multiple of the actual device block
43
size. Default is 512 which is usually correct for disks but incorrect for
44
cdroms (which normally have 2048 byte blocks).
33
46
cdbsz=6 | 10 | 12 | 16
34
47
size of SCSI READ and/or WRITE commands issued on sg device names.
35
Default is 10 byte SCSI command blocks
38
continue on error is 0 (off) by default. When it is 1 read errors
39
are stepped over (with a block (or blocks) of zeroes being output).
40
When 1, write errors are ignored (and alignment is maintained)
41
Similar to "conv=noerror" in
43
utility. Default is 0 which implies stop on error
48
Default is 10 byte SCSI command blocks (unless calculations indicate
49
that a 4 byte block number may be exceeded, in which case it defaults
50
to 16 byte SCSI commands).
46
copy this number of blocks from 'if' to 'of'. Default is the
47
minimum (of 'if' and 'of') number of blocks that sg devices return from
48
READ CAPACITY SCSI commands or that block devices report.
53
copy this number of blocks from 'if' to 'of'. Default is the minimum (
54
of 'if' and 'of') number of blocks that sg devices return from READ
55
CAPACITY SCSI commands or that block devices (or their partitions) report.
49
56
Normal files are not probed for their size. If 'skip'
50
or 'seek' are given and the count is derived (i.e. not explicitly given)
51
then the derived count is scaled back so that the copy will not overrun the
57
or 'seek' are given and the count is deduced (i.e. not explicitly given)
58
then that count is scaled back so that the copy will not overrun the
52
59
device. If the file name is a block device partition and count is not given
53
60
then the size of the partition rather than the size of the whole device is
54
used. If count is not given and cannot be derived then an error message
61
used. If count is not given and cannot be deduced then an error message
55
62
is issued and no copy takes place.
64
71
at completion. If direct IO is selected and /proc/scsi/sg/allow_dio
65
72
has the value of 0 then a warning is issued (and indirect IO is performed)
68
force unit access bit. When 3, fua is set on both "if" and "of", when 2, fua
69
is set on "if", when 1, fua is set on "of", when 0 (the default), fua is
70
cleared on both. 6 byte SCSI READ and WRITE commands (cdbsz=6) do not
71
support the fua bit. Only active for sg device file names.
74
if given must be the same as bs
75
if given must be the same value as 'bs'.
77
78
read from FILE instead of stdin. A file name of - is taken to be stdin.
78
Starts reading at the beginning of FILE unless "skip" is given.
79
Starts reading at the beginning of FILE unless 'skip=<n>' is given.
82
where FLAGS is a comma separated list of one or more flags outlined below.
83
These flags are associated with <ifile> and are ignored when <ifile> is
81
if given must be the same as bs
87
if given must be the same as 'bs'.
84
90
write to FILE instead of stdout. A file name of - is taken to be stdout.
85
91
If FILE is /dev/null then no actual writes are performed. If FILE is .
86
92
(period) then it is treated the same way as /dev/null (this is a
93
shorthand notation). Starts (over-)writing at the beginning of FILE
94
unless either 'seek=<n>' or 'oflag=append' is given (it is not permitted
98
where FLAGS is a comma separated list of one or more flags outlined below.
99
These flags are associated with <ofile> and are ignored when <ofile>
100
is /dev/null, . (period), or stdout.
90
103
start writing BLOCKS bs-sized blocks from the start of the output file.
95
108
Default is block 0 (i.e. start of file).
98
when 1, does SYNCHRONIZE CACHE command on "of" at the end of the transfer.
99
Only active when "of" is a sg device file name
111
when 1, does SYNCHRONIZE CACHE command on 'of' at the end of the transfer.
112
Only active when 'of' is a sg device file name
102
115
this is the number or worker threads (default 4) that attempt to
103
116
copy in parallel. Minimum is 0 and maximum is 16
106
when 1, times transfer and does throughput calculation, outputting the
107
results (to stderr) at completion. When 0 (default) doesn't perform timing
119
when 1, the transfer is timed and throughput calculation is
120
performed, outputting the results (to stderr) at completion. When
121
0 (default) no timing is performed.
124
outputs usage message and exits
110
127
outputs version number information and exits
129
Here is a list of flags and their meanings:
132
causes the O_APPEND flag to be added to the open of <ofile>. For normal
133
files this will lead to data appended to the end of any existing data.
134
Cannot be used together with the 'seek=<n>' option as they conflict.
135
The default action of this utility is to overwrite any existing data
136
from the beginning of the file or, if 'seek=<n>' is given, starting at
137
block <n>. Note that attempting to "append" to a device file will
138
usually be ignored or may cause an error to be reported.
141
continue on error. When given with 'iflag=', an error that is detected
142
in a single SCSI command (typically 'bpt' blocks) is noted (by an error
143
message sent to stderr), then zeroes are substituted into the buffer
144
for the corresponding write operation and the copy continues. Note that the
146
utility is more sophisticated in such error situations when 'iflag=coe'.
147
When given with 'oflag=', any error reported by a SCSI WRITE command is
148
reported to stderr and the copy continues (as if nothing went wrong).
151
causes the O_DIRECT flag to be added to the open of <ifile> and/or <ofile>.
152
This flag requires some memory alignment on IO. Hence user memory buffers
153
are aligned to the page size. Has no effect on sg, normal or raw files.
156
set the DPO bit (disable page out) in READ and WRITE SCSI commands. Not
157
supported for 6 byte cdb variants of READ and WRITE. Indicates that
158
data is unlikely to be required to stay in device (e.g. disk) cache.
159
May speed media copy and/or cause a media copy to have less impact
160
on other device users.
163
causes the O_SYNC flag to be added to the open of <ifile> and/or <ofile>.
164
The "d" is prepended to lower confusion with the 'sync=0|1' option which
165
has another action (i.e. a synchronisation to media at the end of the
169
causes the O_EXCL flag to be added to the open of <ifile> and/or <ofile>.
172
causes the FUA (force unit access) bit to be set in READ and/or WRITE
173
SCSI commands. This only has effect with sg devices. The 6 byte variants
174
of the READ and WRITE SCSI commands do not support the FUA bit.
175
Only active for sg device file names.
177
Here are some retired options that are still present:
180
continue on error is 0 (off) by default. When it is 1, it is
181
equivalent to 'iflag=coe oflag=coe' described in the FLAGS section
182
above. Similar to 'conv=noerror' in
184
utility. Default is 0 which implies stop on error. More advanced
185
coe=1 processing on reads is performed by the sg_dd utility.
188
force unit access bit. When 3, fua is set on both 'if' and 'of'; when 2, fua
189
is set on 'if'; when 1, fua is set on 'of'; when 0 (default), fua is cleared
190
on both. See the 'fua' flag.
112
192
A raw device must be bound to a block device prior to using sgp_dd.
115
195
for more information about binding raw devices. To be safe, the sg device
116
mapping to SCSI block devices should be checked with "cat /proc/scsi/scsi"
196
mapping to SCSI block devices should be checked with 'cat /proc/scsi/scsi'
119
The count is only deduced for sg devices (minimum > 0 if both input and
120
output are sg devices) otherwise it defaults to 0. This is for safety!
121
199
Raw device partition information can often be found with
123
201
[the "-ul" argument is useful in this respect].
125
BYTES and BLOCKS may be followed by the following multiplicative suffixes:
126
c C *1; b B *512; k *1,024; K *1,000; m *1,048,576; M *1,000,000;
127
g *1,073,741,824; G *1,000,000,000; t *1,099,511,627,776 and
128
T *1,000,000,000,000 (the latter two can only be used for count, skip
203
BYTES and BLOCKS may be followed by one of these multiplicative suffixes:
204
c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576;
205
MB *1,000,000 . This pattern continues for "G", "T" and "P". The latter two
206
suffixes can only be used for count, skip and seek values). Also a suffix of
207
the form "x<n>" multiplies the leading number by <n>. These multiplicative
208
suffixes are compatible with GNU's dd command (since 2002) which claims
209
compliance with SI and with IEC 60027-2.
131
211
Alternatively numerical values can be given in hexadecimal preceded by
132
either "0x" or "0X". When hex numbers are given multipliers cannot be
212
either "0x" or "0X". When hex numbers are given, multipliers cannot be
135
215
The count, skip and seek parameters can take 64 bit values (i.e. very
187
274
geometry (stepping over errors on the source disk):
189
276
sgp_dd if=/dev/sg0 of=/dev/sg1 bs=512 coe=1
278
The exit status of sgp_dd is 0 when it is successful. Otherwise see
279
the sg3_utils(8) man page. Since this utility works at a higher level
280
than individual commands, and there are 'coe' and 'retries' flags,
281
individual SCSI command failures do not necessary cause the process
191
284
Written by Doug Gilbert and Peter Allworth.
192
285
.SH "REPORTING BUGS"
193
286
Report bugs to <dgilbert at interlog dot com>.
195
Copyright \(co 2000-2004 Douglas Gilbert
288
Copyright \(co 2000-2006 Douglas Gilbert
197
290
This software is distributed under the GPL version 2. There is NO
198
291
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
200
A simpler, non-threaded version of this utility called
293
A simpler, non-threaded version of this utility but with more
294
advanced "continue on error" logic is called
202
is in the sg3_utils package. The lmbench package contains
296
and is also found in the sg3_utils package. The lmbench package contains
204
298
which is also interesting.
added
removed
sgp_dd.8
