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