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 IFILE. This can be changed with
39 the --on_dst option which causes the XCOPY command to be sent to OFILE
40 instead.
41
43 bpt=BPT
44 each IO transaction will be made using BPT blocks (or less if
45 near the end of the copy). Default is 128 for block sizes less
46 that 2048 bytes, otherwise the default is 32. So for bs=512 the
47 reads and writes will each convey 64 KiB of data by default
48 (less if near the end of the transfer or memory restrictions).
49 When cd/dvd drives are accessed, the block size is typically
50 2048 bytes and bpt defaults to 32 which again implies 64 KiB
51 transfers.
52 bs=BS where BS must be the block size of the physical device (if
54 either the input or output files are accessed via SCSI com‐
55 mands). Note that this differs from dd(1) which permits BS to be
56 an integral multiple. Defaults to the device block size.
57 cat={0|1}
59 sets the SCSI EXTENDED COPY command segment descriptor CAT bit
60 to 0 or 1 (default: 0). The CAT bit (in conjunction with the PAD
61 bit) controls the handling of residual data. See section HAN‐
62 DLING OF RESIDUAL DATA for details.
63 dc={0|1}
65 sets the SCSI EXTENDED COPY command segment descriptor DC bit to
66 0 or 1 (default: 0). The DC bit controls whether COUNT refers to
67 the source (dc=0) or the target (dc=1) descriptor.
68 conv=CONV
70 all CONV arguments are ignored.
71 app=APPEND
73 all APPEND arguments are ignored.
74 count=COUNT
76 copy COUNT blocks from IFILE to OFILE. Default is the minimum
77 (IFILE if dc=0 or OFILE if dc=1) number of blocks that SCSI
78 devices report from SCSI READ CAPACITY commands or that block
79 devices (or their partitions) report. Normal files are not
80 probed for their size. If skip=SKIP or skip=SEEK are given and
81 the count is derived (i.e. not explicitly given) then the
82 derived count is scaled back so that the copy will not overrun
83 the device. If the file name is a block device partition and
84 COUNT is not given then the size of the partition rather than
85 the size of the whole device is used. If COUNT is not given (or
86 count=-1) and cannot be derived then an error message is issued
87 and no copy takes place.
88 ibs=BS if given must be the same as BS given to 'bs=' option.
90 id_usage={hold|discard|disable}
92 sets the SCSI EXTENDED COPY command parameter list field called
93 LIST ID USAGE to 0 if the argument is 'hold', to 2 if the argu‐
94 ment is 'discard', or to '3' if the argument is 'disable'.
95 if=IFILE
97 read from IFILE instead of stdin. If IFILE is '-' then stdin is
98 read. Starts reading at the beginning of IFILE unless SKIP is
99 given.
100 iflag=FLAGS
102 where FLAGS is a comma separated list of one or more flags out‐
103 lined below. These flags are associated with IFILE and are
104 ignored when IFILE is stdin.
105 obs=BS if given must be the same as BS given to 'bs=' option.
107 of=OFILE
109 write to OFILE instead of stdout. If OFILE is '-' then writes to
110 stdout. If OFILE is /dev/null then no actual writes are per‐
111 formed. If OFILE is '.' (period) then it is treated the same
112 way as /dev/null (this is a shorthand notation). If OFILE exists
113 then it is _not_ truncated; it is overwritten from the start of
114 OFILE unless 'oflag=append' or SEEK is given.
115 oflag=FLAGS
117 where FLAGS is a comma separated list of one or more flags out‐
118 lined below. These flags are associated with OFILE and are
119 ignored when OFILE is /dev/null, '.' (period), or stdout.
120 list_id=ID
122 sets the SCSI EXTENDED COPY command parameter list field called
123 LIST IDENTIFIER to ID. ID should be a value between 0 and 255
124 (inclusive) and the default value is 1.
125 prio=PRIO
127 sets the SCSI EXTENDED COPY command parameter list field called
128 PRIORITY to PRIO. The default value is 1.
129 seek=SEEK
131 start writing SEEK bs-sized blocks from the start of OFILE.
132 Default is block 0 (i.e. start of file).
133 skip=SKIP
135 start reading SKIP bs-sized blocks from the start of IFILE.
136 Default is block 0 (i.e. start of file).
137 time={0|1}
139 when 1, times transfer and does throughput calculation, out‐
140 putting the results (to stderr) at completion. When 0 (default)
141 doesn't perform timing.
142 verbose=VERB
144 as VERB increases so does the amount of debug output sent to
145 stderr. Default value is zero which yields the minimum amount
146 of debug output. A value of 1 reports extra information that is
147 not repetitive. A value 2 reports cdbs and responses for SCSI
148 commands that are not repetitive (i.e. other that READ and
149 WRITE). Error processing is not considered repetitive. Values of
150 3 and 4 yield output for all SCSI commands (and Unix read() and
151 write() calls) so there can be a lot of output.
152 -h, --help
154 outputs usage message and exits.
155 --on_dst
157 send the XCOPY command to the output file/device.
158 --on_src
160 send the XCOPY command to the input file/device. This is the
161 default when this option and --on_dst are not given.
162 -v, --verbose
164 equivalent to verbose=1. When used twice, equivalent to ver‐
165 bose=2, etc.
166 -V, --version
168 outputs version number information and exits.
169
171 Here is a list of flags and their meanings:
172 append causes the O_APPEND flag to be added to the open of OFILE. For
174 regular files this will lead to data appended to the end of any
175 existing data. Cannot be used together with the seek=SEEK
176 option as they conflict. The default action of this utility is
177 to overwrite any existing data from the beginning of the file
178 or, if SEEK is given, starting at block SEEK. Note that attempt‐
179 ing to 'append' to a device file (e.g. a disk) will usually be
180 ignored or may cause an error to be reported.
181 excl causes the O_EXCL flag to be added to the open of IFILE and/or
183 OFILE.
184 flock after opening the associated file (i.e. IFILE and/or OFILE) an
186 attempt is made to get an advisory exclusive lock with the
187 flock() system call. The flock arguments are "FLOCK_EX |
188 FLOCK_NB" which will cause the lock to be taken if available
189 else a "temporarily unavailable" error is generated. An exit
190 status of 90 is produced in the latter case and no copy is done.
191 null has no affect, just a placeholder.
193 pad sets the SCSI EXTENDED COPY command segment descriptor PAD bit.
195 The PAD bit (in conjunction with the CAT bit) controls the han‐
196 dling of residual data.(See section HANDLING OF RESIDUAL DATA
197 for details.
198 xcopy has no affect; for compatibility with ddpt.
200
202 The pad and cat bits control the handling of residual data. As the data
203 can be specified either in terms of source or target block size and
204 both might have different block sizes residual data is likely to happen
205 in these cases. If both block sizes are identical these bits have no
206 effect as residual data will not occur.
207 If none of these bits are set, the EXTENDED COPY command will be
209 aborted with additional sense 'UNEXPECTED INEXACT SEGMENT'.
210 If only the cat bit is set the residual data will be retained and made
212 available for subsequent segment descriptors. Residual data will be
213 discarded for the last segment descriptor.
214 If the pad bit is set for the source descriptor only, any residual data
216 for both source or destination will be discarded.
217 If the pad bit is set for the target descriptor only any residual
219 source data will be handled as if the cat bit is set, but any residual
220 destination data will be padded to make a whole block transfer.
221 If the pad bit is set for both source and target any residual source
223 data will be discarded, and any residual destination data will be
224 padded.
225
227 Here are some retired options that are still present:
228 append=0 | 1
230 when set, equivalent to 'oflag=append'. When clear the action is
231 to overwrite the existing file (if it exists); this is the
232 default. See the 'append' flag.
233
235 Various numeric arguments (e.g. SKIP) may include multiplicative suf‐
236 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
237 in the sg3_utils(8) man page.
238 The COUNT, SKIP and SEEK arguments can take 64 bit values (i.e. very
240 big numbers). Other values are limited to what can fit in a signed 32
241 bit number.
242 All informative, warning and error output is sent to stderr so that
244 dd's output file can be stdout and remain unpolluted. If no options are
245 given, then the usage message is output and nothing else happens.
246 If a device supports xcopy operations then it should set the 3PC field
248 (3PC stands for Third Party Copy) in its standard INQUIRY response.
249 This utility will attempt a xcopy operation irrespective of the value
250 in the 3PC field but if it is zero (cleared) one would expect the xcopy
251 operation to fail.
252 The status of the SCSI EXTENDED COPY command can be queried with
254 sg_copy_results(sg3_utils)
255 Currently only block-to-block transfers are implemented; IFILE and
257 OFILE must refer to a SCSI block device.
258 No account is taken of partitions so, for example, /dev/sbc2, /dev/sdc,
260 /dev/sg2, and /dev/bsg/3:0:0:1 would all refer to the same thing: the
261 whole logical unit (i.e. the whole disk) starting at LBA 0. So any par‐
262 tition indication (e.g. /dev/sdc2) is ignored. The user should set
263 SKIP, SEEK and COUNT with information obtained from a command like
264 'fdisk -l -u /dev/sdc' to account for partitions.
265 XCOPY (LID1) capability has been added to the ddpt utility which is in
267 a package of the same name. The ddpt utility will run on other OSes
268 (e.g. FreeBSD and Windows) while sg_xcopy only runs on Linux. Also ddpt
269 permits the arguments to ibs= and ibs= to be different.
270
272 Copy 2M of data from the start of one device to another:
273 # sg_xcopy if=/dev/sdo of=/dev/sdp count=2048 list_id=2 dc=1
275 sg_xcopy: if=/dev/sdo skip=0 of=/dev/sdp seek=0 count=1024
276 Start of loop, count=1024, bpt=65535, lba_in=0, lba_out=0
277 sg_xcopy: 1024 blocks, 1 command
278 Check the status of the EXTENDED COPY command:
280 # sg_copy_results --status --list_id=2 /dev/sdp
282 Receive copy results (copy status):
283 Held data discarded: Yes
284 Copy manager status: Operation completed without errors
285 Segments processed: 1
286 Transfer count units: 0
287 Transfer count: 0
288
290 The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIG‐
291 PIPE output the number of remaining blocks to be transferred and the
292 records in + out counts; then they have their default action. SIGUSR1
293 causes the same information to be output yet the copy continues. All
294 output caused by signals is sent to stderr.
295
297 The exit status of sg_xcopy is 0 when it is successful. Otherwise see
298 the sg3_utils(8) man page.
299 An additional exit status of 90 is generated if the flock flag is given
301 and some other process holds the advisory exclusive lock.
302
304 Written by Hannes Reinecke and Douglas Gilbert.
305
307 Report bugs to <dgilbert at interlog dot com>.
308
310 Copyright © 2000-2013 Hannes Reinecke and Douglas Gilbert
311 This software is distributed under the GPL version 2. There is NO war‐
312 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
313 POSE.
314
316 There is a web page discussing sg_dd at
317 http://sg.danny.cz/sg/sg_dd.html
318 A POSIX threads version of this utility called sgp_dd is in the
320 sg3_utils package. Another version from that package is called sgm_dd
321 and it uses memory mapped IO to speed transfers from sg devices.
322 The lmbench package contains lmdd which is also interesting. For moving
324 data to and from tapes see dt which is found at http://www.scsi‐
325 faq.org/RMiller_Tools/index.html
326 To change mode parameters that effect a SCSI device's caching and error
328 recovery see sdparm(sdparm)
329 See also dd(1), sg_copy_results(sg3_utils), ddrescue(GNU), ddpt(ddpt)
331sg3_utils-1.37 October 2013 SG_XCOPY(8)