1SG_XCOPY(8) SG3_UTILS SG_XCOPY(8)
2
6 sg_xcopy - copy data to and from files and devices using SCSI EXTENDED
7 COPY (XCOPY)
8
10 sg_xcopy [bs=BS] [conv=CONV] [count=COUNT] [ibs=BS] [if=IFILE]
11 [iflag=FLAGS] [obs=BS] [of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP]
12 [--help] [--version]
13 [bpt=BPT] [cat=0|1] [dc=0|1] [id_usage={hold|discard|disable}]
15 [list_id=ID] [prio=PRIO] [time=0|1] [verbose=VERB] [--on_dst|--on_src]
16 [--verbose]
17
19 Copy data to and from any files. Specialized for "files" that are Linux
20 SCSI devices that support the SCSI EXTENDED COPY (XCOPY) command.
21 During the draft stages of SPC-4 the T10 committee has expanded the
23 XCOPY command so that it now has two variants: "LID1" (for a List Iden‐
24 tifier length of 1 byte) and "LID4" (for a List Identifier length of 4
25 bytes). This utility supports the older, LID1 variant which is also
26 found in SPC-3 and earlier. While the LID1 variant in SPC-4 is command
27 level (binary) compatible with XCOPY as defined in SPC-3, some of the
28 command naming has changed. This utility uses the older, SPC-3 XCOPY
29 names.
30 This utility has similar syntax and semantics to dd(1) but with no
32 "conversions" is supported.
33 The first group in the synopsis above are "standard" Unix dd(1) oper‐
35 ands. The second group are extra options added by this utility. Both
36 groups are defined below in combined, alphabetical order.
37 By default the XCOPY command is sent to OFILE. This can be changed with
39 the --on_src or iflag=xflagoptions which cause the XCOPY command to be
40 sent to IFILE instead. Also see the section on ENVIRONMENT VARIABLES.
41 The ddpt utility supports the same xcopy(LID1) functionality as this
43 utility with the same options and flags. Additionally ddpt supports a
44 subset of xcopy(LID4) functionality variously called "xcopy version 2,
45 lite" or ODX. ODX is a market name and stands for Offloaded Data Xfer
46 (i.e. transfer).
47
49 bpt=BPT
50 each IO transaction will be made using BPT blocks (or less if
51 near the end of the copy). Default is 128 for block sizes less
52 that 2048 bytes, otherwise the default is 32. So for bs=512 the
53 reads and writes will each convey 64 KiB of data by default
54 (less if near the end of the transfer or memory restrictions).
55 When cd/dvd drives are accessed, the block size is typically
56 2048 bytes and bpt defaults to 32 which again implies 64 KiB
57 transfers.
58 bs=BS where BS must be the block size of the physical device (if
60 either the input or output files are accessed via SCSI com‐
61 mands). Note that this differs from dd(1) which permits BS to be
62 an integral multiple. Defaults to the device block size.
63 cat={0|1}
65 sets the SCSI EXTENDED COPY command segment descriptor CAT bit
66 to 0 or 1 (default: 0). The CAT bit (in conjunction with the PAD
67 bit) controls the handling of residual data. See section HAN‐
68 DLING OF RESIDUAL DATA for details.
69 dc={0|1}
71 sets the SCSI EXTENDED COPY command segment descriptor DC bit to
72 0 or 1 (default: 0). The DC bit controls whether COUNT refers to
73 the source (dc=0) or the target (dc=1) descriptor.
74 conv=CONV
76 all CONV arguments are ignored.
77 count=COUNT
79 copy COUNT blocks from IFILE to OFILE. Default is the minimum
80 (IFILE if dc=0 or OFILE if dc=1) number of blocks that SCSI
81 devices report from SCSI READ CAPACITY commands or that block
82 devices (or their partitions) report. Normal files are not
83 probed for their size. If skip=SKIP or skip=SEEK are given and
84 the count is derived (i.e. not explicitly given) then the
85 derived count is scaled back so that the copy will not overrun
86 the device. If the file name is a block device partition and
87 COUNT is not given then the size of the partition rather than
88 the size of the whole device is used. If COUNT is not given (or
89 count=-1) and cannot be derived then an error message is issued
90 and no copy takes place.
91 ibs=BS if given must be the same as BS given to 'bs=' option.
93 id_usage={hold|discard|disable}
95 sets the SCSI EXTENDED COPY command parameter list field called
96 LIST ID USAGE to 0 if the argument is 'hold', to 2 if the argu‐
97 ment is 'discard', or to '3' if the argument is 'disable'.
98 If the device has the ability to hold data (as indicated by
99 "held data limit" being greater than zero) then id_usage
100 defaults to 'hold' otherwise it defaults to 'discard'.
101 if=IFILE
103 read from IFILE instead of stdin. If IFILE is '-' then stdin is
104 read. Starts reading at the beginning of IFILE unless SKIP is
105 given.
106 iflag=FLAGS
108 where FLAGS is a comma separated list of one or more flags out‐
109 lined below. These flags are associated with IFILE and are
110 ignored when IFILE is stdin.
111 list_id=ID
113 sets the SCSI EXTENDED COPY command parameter list field called
114 LIST IDENTIFIER to ID. ID should be a value between 0 and 255
115 (inclusive). ID usually defaults to 1 unless id_usage=disable in
116 which case it defaults to 0.
117 obs=BS if given must be the same as BS given to 'bs=' option.
119 of=OFILE
121 write to OFILE instead of stdout. If OFILE is '-' then writes to
122 stdout. If OFILE is /dev/null then no actual writes are per‐
123 formed. If OFILE is '.' (period) then it is treated the same
124 way as /dev/null (this is a shorthand notation). If OFILE exists
125 then it is _not_ truncated; it is overwritten from the start of
126 OFILE unless 'oflag=append' or SEEK is given.
127 oflag=FLAGS
129 where FLAGS is a comma separated list of one or more flags out‐
130 lined below. These flags are associated with OFILE and are
131 ignored when OFILE is /dev/null, '.' (period), or stdout.
132 prio=PRIO
134 sets the SCSI EXTENDED COPY command parameter list field called
135 PRIORITY to PRIO. The default value is 1.
136 seek=SEEK
138 start writing SEEK bs-sized blocks from the start of OFILE.
139 Default is block 0 (i.e. start of file).
140 skip=SKIP
142 start reading SKIP bs-sized blocks from the start of IFILE.
143 Default is block 0 (i.e. start of file).
144 time={0|1}
146 when 1, times transfer and does throughput calculation, out‐
147 putting the results (to stderr) at completion. When 0 (default)
148 doesn't perform timing.
149 verbose=VERB
151 as VERB increases so does the amount of debug output sent to
152 stderr. Default value is zero which yields the minimum amount
153 of debug output. A value of 1 reports extra information that is
154 not repetitive. A value 2 reports cdbs and responses for SCSI
155 commands that are not repetitive (i.e. other that READ and
156 WRITE). Error processing is not considered repetitive. Values of
157 3 and 4 yield output for all SCSI commands (and Unix read() and
158 write() calls) so there can be a lot of output.
159 -h, --help
161 outputs usage message and exits.
162 --on_dst
164 send the XCOPY command to the output file/device (i.e. OFILE).
165 This is the default unless overridden by the --on_src or
166 iflag=xflag options. Also see the section below on ENVIRONMENT
167 VARIABLES.
168 --on_src
170 send the XCOPY command to the input file/device (i.e. IFILE).
171 -v, --verbose
173 equivalent to verbose=1. When used twice, equivalent to ver‐
174 bose=2, etc.
175 -V, --version
177 outputs version number information and exits.
178
180 Here is a list of flags and their meanings:
181 append causes the O_APPEND flag to be added to the open of OFILE. For
183 regular files this will lead to data appended to the end of any
184 existing data. Cannot be used together with the seek=SEEK
185 option as they conflict. The default action of this utility is
186 to overwrite any existing data from the beginning of the file
187 or, if SEEK is given, starting at block SEEK. Note that attempt‐
188 ing to 'append' to a device file (e.g. a disk) will usually be
189 ignored or may cause an error to be reported.
190 excl causes the O_EXCL flag to be added to the open of IFILE and/or
192 OFILE.
193 flock after opening the associated file (i.e. IFILE and/or OFILE) an
195 attempt is made to get an advisory exclusive lock with the
196 flock() system call. The flock arguments are "FLOCK_EX |
197 FLOCK_NB" which will cause the lock to be taken if available
198 else a "temporarily unavailable" error is generated. An exit
199 status of 90 is produced in the latter case and no copy is done.
200 null has no affect, just a placeholder.
202 pad sets the SCSI EXTENDED COPY command segment descriptor PAD bit.
204 The PAD bit (in conjunction with the CAT bit) controls the han‐
205 dling of residual data.(See section HANDLING OF RESIDUAL DATA
206 for details.
207 xcopy has no affect; for compatibility with ddpt.
209
211 The pad and cat bits control the handling of residual data. As the data
212 can be specified either in terms of source or target block size and
213 both might have different block sizes residual data is likely to happen
214 in these cases. If both block sizes are identical these bits have no
215 effect as residual data will not occur.
216 If none of these bits are set, the EXTENDED COPY command will be
218 aborted with additional sense 'UNEXPECTED INEXACT SEGMENT'.
219 If only the cat bit is set the residual data will be retained and made
221 available for subsequent segment descriptors. Residual data will be
222 discarded for the last segment descriptor.
223 If the pad bit is set for the source descriptor only, any residual data
225 for both source or destination will be discarded.
226 If the pad bit is set for the target descriptor only any residual
228 source data will be handled as if the cat bit is set, but any residual
229 destination data will be padded to make a whole block transfer.
230 If the pad bit is set for both source and target any residual source
232 data will be discarded, and any residual destination data will be
233 padded.
234
236 If the command line invocation does not explicitly (and unambiguously)
237 indicate whether the XCOPY SCSI command should be sent to IFILE (i.e.
238 the source) or OFILE (i.e. the destination) then a check is made for
239 the presence of the XCOPY_TO_SRC and XCOPY_TO_DST environment vari‐
240 ables. If either one exists (but not both) then it indicates where the
241 SCSI XCOPY command will be sent. By default the XCOPY command is sent
242 to OFILE.
243
245 Here are some retired options that are still present:
246 append=0 | 1
248 when set, equivalent to 'oflag=append'. When clear the action is
249 to overwrite the existing file (if it exists); this is the
250 default. See the 'append' flag.
251
253 Copying data behind an Operating System's back can cause problems. In
254 the case of Linux, users should look at this link:
255 http://linux-mm.org/Drop_Caches
256 This command sequence may be useful:
257 sync; echo 3 > /proc/sys/vm/drop_caches
258 Various numeric arguments (e.g. SKIP) may include multiplicative suf‐
260 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
261 in the sg3_utils(8) man page.
262 The COUNT, SKIP and SEEK arguments can take 64 bit values (i.e. very
264 big numbers). Other values are limited to what can fit in a signed 32
265 bit number.
266 All informative, warning and error output is sent to stderr so that
268 dd's output file can be stdout and remain unpolluted. If no options are
269 given, then the usage message is output and nothing else happens.
270 If a device supports xcopy operations then it should set the 3PC field
272 (3PC stands for Third Party Copy) in its standard INQUIRY response.
273 This utility will attempt a xcopy operation irrespective of the value
274 in the 3PC field but if it is zero (cleared) one would expect the xcopy
275 operation to fail.
276 The status of the SCSI EXTENDED COPY command can be queried with
278 sg_copy_results(sg3_utils)
279 Currently only block-to-block transfers are implemented; IFILE and
281 OFILE must refer to a SCSI block device.
282 No account is taken of partitions so, for example, /dev/sbc2, /dev/sdc,
284 /dev/sg2, and /dev/bsg/3:0:0:1 would all refer to the same thing: the
285 whole logical unit (i.e. the whole disk) starting at LBA 0. So any par‐
286 tition indication (e.g. /dev/sdc2) is ignored. The user should set
287 SKIP, SEEK and COUNT with information obtained from a command like
288 'fdisk -l -u /dev/sdc' to account for partitions.
289 XCOPY (LID1) capability has been added to the ddpt utility which is in
291 a package of the same name. The ddpt utility will run on other OSes
292 (e.g. FreeBSD and Windows) while sg_xcopy only runs on Linux. Also ddpt
293 permits the arguments to ibs= and ibs= to be different.
294
296 Copy 2M of data from the start of one device to another:
297 # sg_xcopy if=/dev/sdo of=/dev/sdp count=2048 list_id=2 dc=1
299 sg_xcopy: if=/dev/sdo skip=0 of=/dev/sdp seek=0 count=1024
300 Start of loop, count=1024, bpt=65535, lba_in=0, lba_out=0
301 sg_xcopy: 1024 blocks, 1 command
302 Check the status of the EXTENDED COPY command:
304 # sg_copy_results --status --list_id=2 /dev/sdp
306 Receive copy results (copy status):
307 Held data discarded: Yes
308 Copy manager status: Operation completed without errors
309 Segments processed: 1
310 Transfer count units: 0
311 Transfer count: 0
312
314 The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIG‐
315 PIPE output the number of remaining blocks to be transferred and the
316 records in + out counts; then they have their default action. SIGUSR1
317 causes the same information to be output yet the copy continues. All
318 output caused by signals is sent to stderr.
319
321 The exit status of sg_xcopy is 0 when it is successful. Otherwise see
322 the sg3_utils(8) man page.
323 An additional exit status of 90 is generated if the flock flag is given
325 and some other process holds the advisory exclusive lock.
326
328 Written by Hannes Reinecke and Douglas Gilbert.
329
331 Report bugs to <dgilbert at interlog dot com>.
332
334 Copyright © 2000-2015 Hannes Reinecke and Douglas Gilbert
335 This software is distributed under the GPL version 2. There is NO war‐
336 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
337 POSE.
338
340 There is a web page discussing sg_dd at
341 http://sg.danny.cz/sg/sg_dd.html
342 A POSIX threads version of this utility called sgp_dd is in the
344 sg3_utils package. Another version from that package is called sgm_dd
345 and it uses memory mapped IO to speed transfers from sg devices.
346 The lmbench package contains lmdd which is also interesting. For moving
348 data to and from tapes see dt which is found at http://www.scsi‐
349 faq.org/RMiller_Tools/index.html
350 To change mode parameters that effect a SCSI device's caching and error
352 recovery see sdparm(sdparm)
353 See also dd(1), sg_copy_results(sg3_utils), ddrescue(GNU),
355 ddpt,ddptctl(ddpt)
356sg3_utils-1.41 March 2015 SG_XCOPY(8)