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