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=xflag options 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 logical block
52 sizes less that 2048 bytes, otherwise the default is 32. So for
53 bs=512 the reads and writes will each convey 64 KiB of data by
54 default (less if near the end of the transfer or memory restric‐
55 tions). When cd/dvd drives are accessed, the logical block size
56 is typically 2048 bytes and bpt defaults to 32 which again
57 implies 64 KiB transfers.
58 bs=BS where BS must be the logical block size of the physical device
60 (if 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 logical 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 app=APPEND
79 all APPEND arguments are ignored.
80 count=COUNT
82 copy COUNT blocks from IFILE to OFILE. Default is the minimum
83 (IFILE if dc=0 or OFILE if dc=1) number of blocks that SCSI
84 devices report from SCSI READ CAPACITY commands or that block
85 devices (or their partitions) report. Normal files are not
86 probed for their size. If skip=SKIP or skip=SEEK are given and
87 the count is derived (i.e. not explicitly given) then the
88 derived count is scaled back so that the copy will not overrun
89 the device. If the file name is a block device partition and
90 COUNT is not given then the size of the partition rather than
91 the size of the whole device is used. If COUNT is not given (or
92 count=-1) and cannot be derived then an error message is issued
93 and no copy takes place.
94 ibs=BS if given must be the same as BS given to 'bs=' option.
96 id_usage={hold|discard|disable}
98 sets the SCSI EXTENDED COPY command parameter list field called
99 LIST ID USAGE to 0 if the argument is 'hold', to 2 if the argu‐
100 ment is 'discard', or to '3' if the argument is 'disable'.
101 If the device has the ability to hold data (as indicated by
102 "held data limit" being greater than zero) then id_usage
103 defaults to 'hold' otherwise it defaults to 'discard'.
104 if=IFILE
106 read from IFILE instead of stdin. If IFILE is '-' then stdin is
107 read. Starts reading at the beginning of IFILE unless SKIP is
108 given.
109 iflag=FLAGS
111 where FLAGS is a comma separated list of one or more flags out‐
112 lined below. These flags are associated with IFILE and are
113 ignored when IFILE is stdin.
114 list_id=ID
116 sets the SCSI EXTENDED COPY command parameter list field called
117 LIST IDENTIFIER to ID. ID should be a value between 0 and 255
118 (inclusive). ID usually defaults to 1 unless id_usage=disable in
119 which case it defaults to 0.
120 obs=BS if given must be the same as BS given to 'bs=' option.
122 of=OFILE
124 write to OFILE instead of stdout. If OFILE is '-' then writes to
125 stdout. If OFILE is /dev/null then no actual writes are per‐
126 formed. If OFILE is '.' (period) then it is treated the same
127 way as /dev/null (this is a shorthand notation). If OFILE exists
128 then it is _not_ truncated; it is overwritten from the start of
129 OFILE unless 'oflag=append' or SEEK is given.
130 oflag=FLAGS
132 where FLAGS is a comma separated list of one or more flags out‐
133 lined below. These flags are associated with OFILE and are
134 ignored when OFILE is /dev/null, '.' (period), or stdout.
135 prio=PRIO
137 sets the SCSI EXTENDED COPY command parameter list field called
138 PRIORITY to PRIO. The default value is 1.
139 seek=SEEK
141 start writing SEEK bs-sized blocks from the start of OFILE.
142 Default is block 0 (i.e. start of file).
143 skip=SKIP
145 start reading SKIP bs-sized blocks from the start of IFILE.
146 Default is block 0 (i.e. start of file).
147 time={0|1}
149 when 1, times transfer and does throughput calculation, out‐
150 putting the results (to stderr) at completion. When 0 (default)
151 doesn't perform timing.
152 verbose=VERB
154 as VERB increases so does the amount of debug output sent to
155 stderr. Default value is zero which yields the minimum amount
156 of debug output. A value of 1 reports extra information that is
157 not repetitive. A value 2 reports cdbs and responses for SCSI
158 commands that are not repetitive (i.e. other that READ and
159 WRITE). Error processing is not considered repetitive. Values of
160 3 and 4 yield output for all SCSI commands (and Unix read() and
161 write() calls) so there can be a lot of output.
162 -h, --help
164 outputs usage message and exits.
165 --on_dst
167 send the XCOPY command to the output file/device (i.e. OFILE).
168 This is the default unless overridden by the --on_src or
169 iflag=xflag options. Also see the section below on ENVIRONMENT
170 VARIABLES.
171 --on_src
173 send the XCOPY command to the input file/device (i.e. IFILE).
174 -v, --verbose
176 equivalent to verbose=1. When used twice, equivalent to ver‐
177 bose=2, etc.
178 -V, --version
180 outputs version number information and exits.
181
183 Here is a list of flags and their meanings:
184 append causes the O_APPEND flag to be added to the open of OFILE. For
186 regular files this will lead to data appended to the end of any
187 existing data. Cannot be used together with the seek=SEEK
188 option as they conflict. The default action of this utility is
189 to overwrite any existing data from the beginning of the file
190 or, if SEEK is given, starting at block SEEK. Note that attempt‐
191 ing to 'append' to a device file (e.g. a disk) will usually be
192 ignored or may cause an error to be reported.
193 excl causes the O_EXCL flag to be added to the open of IFILE and/or
195 OFILE.
196 flock after opening the associated file (i.e. IFILE and/or OFILE) an
198 attempt is made to get an advisory exclusive lock with the
199 flock() system call. The flock arguments are "FLOCK_EX |
200 FLOCK_NB" which will cause the lock to be taken if available
201 else a "temporarily unavailable" error is generated. An exit
202 status of 90 is produced in the latter case and no copy is done.
203 null has no affect, just a placeholder.
205 pad sets the SCSI EXTENDED COPY command segment descriptor PAD bit.
207 The PAD bit (in conjunction with the CAT bit) controls the han‐
208 dling of residual data.(See section HANDLING OF RESIDUAL DATA
209 for details.
210 xcopy has no affect; for compatibility with ddpt.
212
214 The pad and cat bits control the handling of residual data. As the data
215 can be specified either in terms of source or target logical block size
216 and both might have different block sizes residual data is likely to
217 happen in these cases. If both logical block sizes are identical these
218 bits have no effect as residual data will not occur.
219 If none of these bits are set, the EXTENDED COPY command will be
221 aborted with additional sense 'UNEXPECTED INEXACT SEGMENT'.
222 If only the cat bit is set the residual data will be retained and made
224 available for subsequent segment descriptors. Residual data will be
225 discarded for the last segment descriptor.
226 If the pad bit is set for the source descriptor only, any residual data
228 for both source or destination will be discarded.
229 If the pad bit is set for the target descriptor only any residual
231 source data will be handled as if the cat bit is set, but any residual
232 destination data will be padded to make a whole block transfer.
233 If the pad bit is set for both source and target any residual source
235 data will be discarded, and any residual destination data will be
236 padded.
237
239 If the command line invocation does not explicitly (and unambiguously)
240 indicate whether the XCOPY SCSI command should be sent to IFILE (i.e.
241 the source) or OFILE (i.e. the destination) then a check is made for
242 the presence of the XCOPY_TO_SRC and XCOPY_TO_DST environment vari‐
243 ables. If either one exists (but not both) then it indicates where the
244 SCSI XCOPY command will be sent. By default the XCOPY command is sent
245 to OFILE.
246
248 Here are some retired options that are still present:
249 append=0 | 1
251 when set, equivalent to 'oflag=append'. When clear the action is
252 to overwrite the existing file (if it exists); this is the
253 default. See the 'append' flag.
254
256 Copying data behind an Operating System's back can cause problems. In
257 the case of Linux, users should look at this link:
258 http://linux-mm.org/Drop_Caches
259 This command sequence may be useful:
260 sync; echo 3 > /proc/sys/vm/drop_caches
261 Various numeric arguments (e.g. SKIP) may include multiplicative suf‐
263 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
264 in the sg3_utils(8) man page.
265 The COUNT, SKIP and SEEK arguments can take 64 bit values (i.e. very
267 big numbers). Other values are limited to what can fit in a signed 32
268 bit number.
269 All informative, warning and error output is sent to stderr so that
271 dd's output file can be stdout and remain unpolluted. If no options are
272 given, then the usage message is output and nothing else happens.
273 If a device supports xcopy operations then it should set the 3PC field
275 (3PC stands for Third Party Copy) in its standard INQUIRY response.
276 This utility will attempt a xcopy operation irrespective of the value
277 in the 3PC field but if it is zero (cleared) one would expect the xcopy
278 operation to fail.
279 The status of the SCSI EXTENDED COPY command can be queried with
281 sg_copy_results(sg3_utils)
282 Currently only block-to-block transfers are implemented; IFILE and
284 OFILE must refer to a SCSI block device.
285 No account is taken of partitions so, for example, /dev/sbc2, /dev/sdc,
287 /dev/sg2, and /dev/bsg/3:0:0:1 would all refer to the same thing: the
288 whole logical unit (i.e. the whole disk) starting at LBA 0. So any par‐
289 tition indication (e.g. /dev/sdc2) is ignored. The user should set
290 SKIP, SEEK and COUNT with information obtained from a command like
291 'fdisk -l -u /dev/sdc' to account for partitions.
292 XCOPY (LID1) capability has been added to the ddpt utility which is in
294 a package of the same name. The ddpt utility will run on other OSes
295 (e.g. FreeBSD and Windows) while sg_xcopy only runs on Linux. Also ddpt
296 permits the arguments to ibs= and ibs= to be different.
297
299 Copy 2M of data from the start of one device to another:
300 # sg_xcopy if=/dev/sdo of=/dev/sdp count=2048 list_id=2 dc=1
302 sg_xcopy: if=/dev/sdo skip=0 of=/dev/sdp seek=0 count=1024
303 Start of loop, count=1024, bpt=65535, lba_in=0, lba_out=0
304 sg_xcopy: 1024 blocks, 1 command
305 Check the status of the EXTENDED COPY command:
307 # sg_copy_results --status --list_id=2 /dev/sdp
309 Receive copy results (copy status):
310 Held data discarded: Yes
311 Copy manager status: Operation completed without errors
312 Segments processed: 1
313 Transfer count units: 0
314 Transfer count: 0
315
317 The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIG‐
318 PIPE output the number of remaining blocks to be transferred and the
319 records in + out counts; then they have their default action. SIGUSR1
320 causes the same information to be output yet the copy continues. All
321 output caused by signals is sent to stderr.
322
324 The exit status of sg_xcopy is 0 when it is successful. Otherwise see
325 the sg3_utils(8) man page.
326 An additional exit status of 90 is generated if the flock flag is given
328 and some other process holds the advisory exclusive lock.
329
331 Written by Hannes Reinecke and Douglas Gilbert.
332
334 Report bugs to <dgilbert at interlog dot com>.
335
337 Copyright © 2000-2018 Hannes Reinecke and Douglas Gilbert
338 This software is distributed under the GPL version 2. There is NO war‐
339 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
340 POSE.
341
343 There is a web page discussing sg_dd at
344 http://sg.danny.cz/sg/sg_dd.html
345 A POSIX threads version of this utility called sgp_dd is in the
347 sg3_utils package. Another version from that package is called sgm_dd
348 and it uses memory mapped IO to speed transfers from sg devices.
349 The lmbench package contains lmdd which is also interesting. For moving
351 data to and from tapes see dt which is found at http://www.scsi‐
352 faq.org/RMiller_Tools/index.html
353 To change mode parameters that effect a SCSI device's caching and error
355 recovery see sdparm(sdparm)
356 See also dd(1), sg_copy_results(sg3_utils), ddrescue(GNU),
358 ddpt,ddptctl(ddpt)
359sg3_utils-1.43 August 2018 SG_XCOPY(8)