1DDPT(8) DDPT DDPT(8)
2
6 ddpt - copies data between files and storage devices. Support for
7 devices that understand the SCSI command set.
8
10 ddpt [bpt=BPT[,OBPC]] [bs=BS] [cdbsz={6|10|12|16|32}] [coe={0|1}]
11 [coe_limit=CL] [conv=CONVS] [count=COUNT] [ddpt=VERS] [delay=MS[,W_MS]]
12 [ibs=IBS] [id_usage=LIU] if=IFILE [iflag=FLAGS] [intio={0|1}]
13 [iseek=SKIP] [ito=ITO] [list_id=LID] [obs=OBS] [of=OFILE] [of2=OFILE2]
14 [oflag=FLAGS] [oseek=SEEK] [prio=PRIO] [protect=RDP[,WRP]]
15 [retries=RETR] [rtf=RTF] [rtype=RTYPE] [seek=SEEK] [skip=SKIP] [sta‐
16 tus=STAT] [to=TO] [verbose=VERB] [--dry-run] [--flexible] [--help]
17 [--job=JF] [--odx] [--prefetch] [--quiet] [--verbose] [--verify]
18 [--version] [--wscan] [--xcopy] [ddpt] [JF]
19 For comparison here is the synopsis for GNU's dd command:
21 dd [bs=BS] [cbs=CBS] [conv=CONVS] [count=COUNT] [ibs=IBS] [if=IFILE]
23 [iflag=FLAGS] [obs=OBS] [of=OFILE] [oflag=FLAGS] [seek=SEEK]
24 [skip=SKIP] [status=STAT] [--help] [--version]
25
27 Copies data between files or simply reads data from a file. Alterna‐
28 tively if the --verify option is given, the IFILE and OFILE contents
29 are compared, stopping if an inequality is found. This utility is spe‐
30 cialized for "files" that are storage devices, especially those that
31 can use the SCSI command sets (e.g. SATA and SAS disks). It can issue
32 SCSI commands in pass-through ("pt") mode. Similar syntax and semantics
33 to the Unix dd(1) command.
34 For comparison, the SYNOPSIS section above shows both the ddpt command
36 line operands and options followed by GNU's dd(1) command line operands
37 and options. Broadly speaking ddpt can be considered a super-set of dd.
38 See the section on DD DIFFERENCES for significant differences between
39 ddpt and dd.
40 This utility either does direct copies, based on read-write sequences,
42 or offloaded copies. In an offloaded copy the data being copied does
43 not necessarily pass through the memory of the the machine originating
44 the copy operation; this can save a significant amount of time and
45 lessen CPU usage.
46 When doing a direct copy, this utility breaks the copy into segments
48 since computer RAM is typically a scarce resource. First it reads in
49 BPT*IBS bytes from IFILE (or less if near the end of the copy) into a
50 copy buffer. In the absence of the various operand and flags that
51 bypass the write operation, the copy buffer is then written out to
52 OFILE. The copy process continues working its way along IFILE and
53 OFILE until either COUNT is exhausted, an end of file is detected, or
54 an error occurs. If IBS and OBS are different, ddpt restricts the value
55 of OBS such that the copy buffer is an integral number of output blocks
56 (i.e. (((IBS * BPT) % OBS) == 0) ). In the following descriptions,
57 "segment" refers to all or part of a copy buffer.
58 The term "pt device" is used for a pass-through device to which SCSI
60 commands like READ(10), WRITE(10) or POPULATE TOKEN may be sent. A pt
61 device may only be able to process SCSI commands in which case the "pt"
62 flag is assumed. The ability to recognize such a pt only device may
63 vary depending on the operating system (e.g. in Linux /dev/sg2 and
64 /dev/bsg/3:0:1:0 are recognized). However if a device can process
65 either normal UNIX read()/ write() calls or pass-through SCSI commands
66 then the default is to use UNIX read()/write() calls. That default can
67 be overridden by using the "pt" flag (e.g. "if=/dev/sdc iflag=pt").
68 When pt access is specified any partition information is ignored. So
69 "if=/dev/sdc2 iflag=pt skip=3" will start at logical block address 3 of
70 '/dev/sdc'. As a protection measure ddpt will only accept that if the
71 force flag is also given (i.e. 'iflag=pt,force').
72 This utility supports two types of offloaded copies. Both are based on
74 the EXTENDED COPY (XCOPY or xcopy) family of SCSI commands. The first
75 uses the XCOPY(LID1) command to do a disk to disk copy. LID1 stands for
76 List IDentifier length of 1 byte and the commands are described in the
77 SPC-4 and earlier SPC-3 and SPC-2 standards. The SPC-4 standard (ANSI
78 INCITS 513-2015) added the XCOPY(LID4) sub-family of copy offloaded
79 commands. Now SPC-5 drafts have dropped the LID1 variants and removed
80 the LID4 suffix on the remaining XCOPY family of commands. To differen‐
81 tiate, this man page will continue to use the LID1 and LID4 suffixes.
82 There is a subset of XCOPY(LID4), specialized for offloaded disk to
83 disk copies, that is known by the market name: ODX. In the descriptions
84 below "xcopy" refers to copies based on XCOPY(LID1) while "odx" refers
85 to either full or partial ODX copies. See the XCOPY and ODX sections
86 below for more information.
87 The syntax of the dd command is somewhat unique in Unix and ddpt fol‐
89 lows in a similar fashion. Operands (i.e. those with the <name>=<some‐
90 thing> structure) are shown in OPERANDS section. The more familiar Unix
91 options (i.e. those starting with one or two hyphens) are shown in the
92 OPTIONS section. Then there are a few arguments which are command line
93 entities that are neither operands nor options, see the ARGUMENTS sec‐
94 tion.
95
97 The operands are listed alphabetically (by <name>) below. The <name> is
98 the part that is to the left of the equal sign. All <names> start with
99 a lower case alphabetical character.
100 bpt=BPT[,OBPC]
102 where BPT is Blocks Per Transfer. A direct copy is made up of
103 multiple transfers, each first reading BPT input blocks (i.e.
104 BPT * IBS bytes) from IFILE into the copy buffer and then from
105 that copy buffer writing (BPT * IBS) / OBS output blocks to
106 OFILE. This continues until the copy is finished, with the last
107 transfer being potentially shorter. The default BPT value varies
108 depending on IBS. When IBS < 8, BPT is 8192; when IBS < 64, BPT
109 is 1024; when IBS < 1024, BPT is 128; when IBS < 8192, BPT is
110 16; when IBS < 32768, BPT is 4; else BPT defaults to 1. If BPT
111 is given as 0 it is treated as the default value. For "bs=512",
112 BPT defaults to 128 so that 64 KiB (or less) is read from IFILE
113 into the copy buffer. This operand is treated differently in ODX
114 and is typically only needed for testing; see ODX section.
115 The optional OBPC (Output Blocks Per Check) argument controls
116 the granularity of sparse writes, write sparing and trim checks.
117 The default granularity is the size of the copy buffer (i.e. BPT
118 * IBS bytes). That can be reduced by specifying OBPC. The finest
119 granularity is when OBPC is 1 which implies the unit of each
120 check is OBS bytes. When OBPC is 0, or not given, the default
121 granularity is used. Large OBPC values are rounded down so that
122 OBPC*OBS does not exceed the size of the copy buffer.
123 odx: may be used to limit the data represented by each ROD.
124 Mainly for testing.
125 If BPT is too large on Linux, the obscure "Invalid argument"
126 error value (EINVAL) is returned.
127 bs=BS where BS is the IFILE and OFILE block size in bytes. Conflicts
129 with either the "ibs=" or "obs=" operands. The value of BS is
130 placed in IBS and OBS. If IFILE or OFILE is a "pt" device then
131 BS must be the logical block size of the device. See the DD DIF‐
132 FERENCES section below. The default is 512 bytes unless overrid‐
133 den by the DDPT_DEF_BS environment variable. Note that newer
134 disks use 4096 byte blocks with perhaps larger block sizes com‐
135 ing in the future. CD/DVD/BD media use a logical block size of
136 2048 bytes.
137 cdbsz={6|10|12|16|32}
139 size of SCSI READ and/or WRITE commands issued to pt devices.
140 The default is 10 byte SCSI command blocks unless calculations
141 indicate that a 4 byte block number may be exceeded or BPT is
142 greater than 16 bits (i.e. more than 65535 blocks), in which
143 case it defaults to 16 byte SCSI commands.
144 coe={0|1}
146 set to 1 for continue on error. Applies to errors on input and
147 output for pt devices but only on input from block devices or
148 regular files. Errors on other files will stop ddpt. Default is
149 0 which implies stop on any error. See the 'coe' flag for more
150 information.
151 coe_limit=CL
153 where CL is the maximum number of consecutive bad blocks stepped
154 over due to "coe=1" on reads before the copy terminates. The
155 default is 0 which is implies no limit. This operand is meant to
156 stop the copy soon after unrecorded media is detected while
157 still offering "continue on error" capability for infrequent,
158 randomly distributed errors.
159 conv=CONVS
161 see the CONVERSIONS section below.
162 count=COUNT
164 copy COUNT input blocks from IFILE to OFILE. If this operand is
165 not given (or COUNT is '-1') then the COUNT may be deduced from
166 either IFILE or OFILE. See the COUNT section below.
167 If a 'hard' gather list is given to skip=SKIP or a 'hard' scat‐
168 ter list is given to seek=SEEK then typically count=COUNT should
169 not be supplied. This is because a 'hard' scatter gather list
170 implies a transfer count. If both are given then ddpt will exit
171 if they are unequal, the force flag can be used to override this
172 action. See the SCATTER GATHER LISTS section below for a discus‐
173 sion of 'hard' and 'soft' scatter gather lists.
174 ddpt=VERS
176 causes a syntax error while parsing the command line if the cur‐
177 rent version of the ddpt utility is less than VERS. VERS can
178 take one of two forms: starting with a digit in which case is
179 should have the form "<major_vn>.<minor_vn>" or starting with
180 the letter "r" followed by "<svn.rev>". The latter case is the
181 subversion revision number. Both numbers can be found in the
182 output of the --version option. The purpose of this operand is
183 to be placed in job files so that they are not run on older ver‐
184 sions of this utility
185 delay=MS[,W_MS]
187 after each segment is copied (typically every (IBS * BPT) bytes)
188 a delay (sleep) of MS milliseconds is performed. The default
189 value for MS is 0 which implies no delay. If W_MS is given and
190 greater than 0 (its default value) then there is an additional
191 delay of W_MS milliseconds associated with each actual write
192 operation that is performed. If MS is greater than 0 then there
193 is not a delay before the first copy segment (or after the
194 last); if W_MS is greater than 0 then there is not a delay
195 before the first write segment. These delays can be used for a
196 bandwidth limiting.
197 odx: the MS delay is implemented in the same fashion after each
198 ROD is copied, apart from the last. If W_MS is greater than 0
199 then that delay occurs before each WUT command, apart from the
200 first.
201 ibs=IBS
203 where IBS is the IFILE block size in bytes. The default value is
204 BS or its default (512). Conflicts the "bs=" operand (i.e. giv‐
205 ing both "bs=512 ibs=512" is considered a syntax error).
206 id_usage=LIU
208 xcopy: SCSI EXTENDED COPY parameter list LIST ID USAGE field is
209 set to LIU. The default value is 0 or 2 . LIU can be a number
210 between 0 and 3 inclusive or a string. The strings can be
211 either: 'hold' for 0, 'discard' for 2 or 'disable' for 3.
212 if=IFILE
214 read from IFILE. If IFILE is '-' then stdin is read. Starts
215 reading at the beginning of IFILE unless SKIP is given.
216 This operand must be given (apart from one odx case and when
217 iflag=00 or iflag=ff is given).
218 odx: the rtf=RTF operand may replace the if=IFILE operand as
219 input. See the ODX section.
220 iflag=FLAGS
222 where FLAGS is a comma separated list of one or more flags out‐
223 lined in the FLAGS section below. These flags are associated
224 with IFILE and are mostly ignored when IFILE is stdin.
225 intio={0|1}
227 set to 1 for allow signals (SIGINT, SIGPIPE and SIGUSR1 (or SIG‐
228 INFO)) to be received during IO from IFILE or IO to OFILE or
229 OFILE2. Default is 0 which causes these signals to be masked
230 during IO operations with a check for signals prior each IO. As
231 long as IO operations don't lock up (e.g. SCSI READ and WRITE
232 commands) the default is the safer option. Even if IO operations
233 do lock up it is best to let the kernel take care of that.
234 iseek=SKIP
236 in its simplest form, SKIP is a single number: start reading
237 after SKIP blocks (each of IBS bytes) from the start of IFILE.
238 Default is block 0 (i.e. start of file). This operand is a syn‐
239 onym for skip=SKIP, see its description.
240 ito=ITO
242 odx: ITO is the inactivity timeout whose units are seconds. The
243 default value is 0 which means the copy manager will take the
244 default inactivity timeout value from the Block Device ROD Token
245 Limits descriptor in the Third Party Copy VPD page. ITO is
246 ignored if it it exceeds the maximum inactivity timeout value in
247 the same descriptor (unless the force flag is given).
248 list_id=LID
250 LID is the xcopy LIST IDENTIFIER field or the STR_ID field for
251 the WRITE STREAM command. Fo xcopy it is used to associate an
252 originating xcopy command with follow-up commands such as
253 RECEIVE ROD TOKEN INFORMATION. If given, the LID should not
254 clash with any other xcopy LID currently in use on this I_T
255 nexus.
256 xcopy: LID is a 1 byte (8 bit) value whose default value is 1
257 or, if id_usage=disable, 0 . LID must not exceed 255.
258 odx: LID is a 4 byte (32 bit) value whose default value is 257
259 (i.e. 0x101) and, if a second default is needed, 258 (0x102) is
260 used. If a clash is detected on the default list identifier
261 value then the next higher value is tried (stopping after 10
262 attempts).
263 oflag=wstream: LID is a 2 byte (16 bit) value whose default
264 value is 0. It is the Stream Identifier (STR_ID field) for the
265 WRITE STREAM(16) command. Valid Stream identifiers are 0x1 to
266 0xffff (65535) inclusive, so the default value of 0 is invalid.
267 obs=OBS
269 where OBS is the OFILE block size in bytes. The default value is
270 BS or its default (512). Conflicts the "bs=" operand (e.g. giv‐
271 ing both "bs=512 obs=512" is considered a syntax error). If OBS
272 is given then it has the following restriction: the integer
273 expression (((IBS * BPT) % OBS) == 0) must be true. Stated
274 another way: the copy buffer size must be an integral multiple
275 of OBS. If of2=OFILE2 is given then OBS is its block size as
276 well.
277 of=OFILE
279 write to OFILE. The default value is /dev/null . If OFILE is '-'
280 then writes to stdout. If OFILE is /dev/null then no actual
281 writes are performed. If OFILE is '.' (period) then it is
282 treated the same way as /dev/null . If OFILE exists then it is
283 _not_ truncated unless "oflag=trunc" is given. See section on DD
284 DIFFERENCES.
285 odx: if this operand (of=OFILE) is not given and the rtf=RTF op‐
286 erand is given then the RTF file may be thought of as receiving
287 the output in the form of one or more ROD Tokens. See the ODX
288 section.
289 of2=OFILE2
291 write output to OFILE2. The default action is not to do this
292 additional write (i.e. when this operand is not given). OFILE2
293 is assumed to be a regular file or a fifo (i.e. a named pipe).
294 OFILE2 is opened for writing and is created if necessary. If
295 OFILE2 is a fifo (named pipe) then some other command should be
296 consuming that data (e.g. 'md5sum OFILE2'), otherwise this util‐
297 ity will block. The write to OFILE2 occurs before the write to
298 OFILE and prior to sparse writing and write sparing logic. So
299 everything read is written to OFILE2.
300 OFILE2 is not truncated before writing. Assuming that the OFILE2
301 length is shorter than what is written (or it is created) then
302 its contents should be the concatenation of all segments (each
303 of ibs*bpt bytes long, with the last segment being possibly
304 shorter). The gather list given to skip=SKIP effects what is
305 read into each segment so it indirectly effects what is written
306 to OFILE2. However the scatter list given to seek=SEEK has no
307 effect on what is written to OFILE2.
308 oflag=FLAGS
310 where FLAGS is a comma separated list of one or more flags out‐
311 lined in the FLAGS section. These flags are associated with
312 OFILE and are ignored when OFILE is /dev/null, '.' (period), or
313 stdout.
314 oseek=SEEK
316 start writing SEEK blocks (each of OBS bytes) from the start of
317 OFILE. Default is block 0 (i.e. start of file). This operand is
318 a synonym for seek=SEEK, see its description.
319 prio=PRIO
321 xcopy: SCSI EXTENDED COPY parameter list PRIORITY field is set
322 to PRIO. The default value is 1 .
323 protect=RDP[,WRP]
325 where RDP is the RDPROTECT field in SCSI READ commands and WRP
326 is the WRPROTECT field in SCSI WRITE commands. The default value
327 for both is 0 which implies no additional protection information
328 will be transferred. Both RDP and WRP can be from 0 to 7. If
329 RDP is greater than 0 then IFILE must be a pt device. If WRP is
330 greater than 0 then OFILE must be a pt device. See the PROTEC‐
331 TION INFORMATION section below.
332 retries=RETR
334 sometimes retries at the host are useful, for example when there
335 is a transport error. When RETR is greater than zero then SCSI
336 READs and WRITEs are retried on error, RETR times. Default value
337 is zero. Only applies to errors on pt devices.
338 rtf=RTF
340 odx: where RTF is a filename. One or more ROD tokens are written
341 to RTF during a read to tokens variant or a full copy variant.
342 One or more ROD tokens are read from RTF during a write from
343 token variant. This operand is not required on a full copy
344 variant. ROD Tokens are 512 bytes long and an extra 8 byte
345 (big-endian) integer containing the 'number of bytes repre‐
346 sented' is placed after each ROD Token if rtf_len is given.
347 rtype=RTYPE
349 odx: where RTYPE is the ROD Type. The default value (0) indi‐
350 cates that the copy manager (in the source) decides. RTYPE can
351 be a decimal number, a hex number (prefixed by 0x or with a "h"
352 appended) or one of "pit-def", "pit-vuln", "pit-pers",
353 "pit-cow", "pit-any" or "zero". The final truncated word can be
354 spelt out (e.g. "pit-vulnerable"). The "pit-" prefix is a
355 shortening of "point in time" copy. The "zero" causes a special
356 Block device zero Token to be created.
357 seek=SEEK
359 start writing SEEK blocks (each of OBS bytes) from the start of
360 OFILE. Default is block 0 (i.e. start of file). The SEEK value
361 may exceed the number of OBS-sized blocks in OFILE.
362 SEEK can be a scatter (gather) list: see the SCATTER GATHER
363 LISTS section below.
364 skip=SKIP
366 start reading SKIP blocks (each of IBS bytes) from the start of
367 IFILE. Default is block 0 (i.e. start of file). The SKIP value
368 must be less than the number of IBS-sized blocks in IFILE.
369 SKIP can be a (scatter) gather list: see the SCATTER GATHER
370 LISTS section below.
371 status=STAT
373 the STAT value of 'noxfer' suppresses the throughput speed and
374 the copy time reporting at the end of the copy. A STAT value of
375 'none' additionally suppresses the records in and out reporting
376 after the copy. So 'status=none' makes ddpt act like a tradi‐
377 tional Unix command in which "no news is good news". The
378 default action of ddpt is to show the throughput (in megabytes
379 per second) and the time taken to do the copy after the "records
380 in" and "records out" lines at the end of the copy. A STAT value
381 of 'sgl' together with '-vv' option will print internally gener‐
382 ated scatter gather lists before the copy begins. When the '-vv'
383 options is given alone then internal scatter lists headers are
384 printed, but not individual elements. In most cases these scat‐
385 ter gather lists will be the same lists given to the seek=SEEK
386 and skip=SKIP operands. As a convenience the value 'null' is
387 accepted for STAT and does nothing.
388 A STAT value of 'progress' prints a progress report (to stderr)
389 every two minutes. If 'progress' is used twice, either by
390 repeating the 'status=progress' operand or by entering 'sta‐
391 tus=progress,progress', then a progress report is printed every
392 minute. If it is used thrice, the a progress report is printed
393 every 30 seconds. Note that care is taken not to flood the OS
394 with calls to check the time which would slow down the copy
395 process. The amount of data output by the progress reports can
396 modified at runtime (e.g. during a long copy). If the verbose
397 flag is 0 or 1 (but not higher and not if the --quiet option is
398 given) then sending a SIG_USR1 (or SIGINFO in FreeBSD) signal to
399 the running ddpt process will toggle the verbose flag between 0
400 and 1.
401 Note that GNU's dd supports 'noxfer', 'none' and 'progress' with
402 similar semantics.
403 to=TO odx, xcopy: where TO is am xcopy originating command timeout in
405 seconds. The default value is 0 which is converted internally
406 to 600 seconds (10 minutes). Best to set this timeout value well
407 above the expected copy time. In a odx full copy this timeout
408 is applied to both the POPULATE TOKEN and WRITE USING TOKEN com‐
409 mands.
410 verbose=VERB
412 as VERB increases so does the amount of debug reporting sent to
413 stderr. Default value is zero which yields the minimum amount
414 of debug reporting. A value of 1 reports extra information that
415 is not repetitive. A value 2 reports cdbs and responses for SCSI
416 commands that are not repetitive (i.e. other that READ and
417 WRITE). Error processing is not considered repetitive. Values of
418 3 and 4 yield reporting for all SCSI commands, plus Unix read()
419 and write() calls, so there can be a lot of output.
420 If VERB is "-1" then reporting that would have been sent to
421 stderr is redirected to /dev/null essentially throwing it away.
422 It has the same action as the --quiet option.
423 In some cases the position of verbose=VERB (or --verbose) on the
424 command line is significant. For example to debug (or at least
425 list out) a scatter gather list given to skip=SKIP or seek=SEEK
426 the verbose=VERB operand (or --verbose) should appear before
427 skip and/or seek.
428
430 Options are listed in alphabetical order, sorted by their long name.
431 -d, --dry-run
433 does all the operand and option processing, opens given file and
434 devices but bypasses the copy stage. For complex command line
435 invocations or for testing invocations to be placed in script
436 files, this option may be useful to check for syntax and related
437 errors.
438 When used once the logic bypasses the copy just before it would
439 normally start copying. When used twice (or more) it goes deeper
440 into the copy to the IO call level before bypassing the calls.
441 To see (on stderr) information for each IO this option combina‐
442 tion may be useful: '-ddvv'.
443 -f, --flexible
445 this option currently only effects the parsing of sgl_s in files
446 that are in hexadecimal plus they have a leading line with 'HEX'
447 in them. Without this option any such line must be invoked with
448 'H@' before the filename; in other words the 'H' in the invoca‐
449 tion needs to match the HEX in the file. With this option a sgl
450 in a file can be invoked with '@' and if a line with HEX is
451 parsed before any LBA,NUM pairs then it switches to hexadecimal
452 mode; so all the parsed LBA,NUM pairs are assumed to be in hexa‐
453 decimal.
454 -h, --help
456 reports usage message then exits.
457 --job=JF
459 where JF is a file name. That file can contain operands and
460 options listed in this and the previous sections. See the JOB
461 FILES section below.
462 -o, --odx
464 indicates to this utility that one of the four odx variants is
465 requested. See ODX section.
466 -p, --prefetch
468 this option is only active when the --verify option is also
469 given. It causes the SCSI PER-FETCH(OFILE, IMMED) command to be
470 sent at the start of each copy segment. See the VERIFY section
471 below.
472 -q, --quiet
474 redirects the messages (sent to stderr) to /dev/null which is
475 essentially throwing them away. That redirect takes place after
476 the command line operands and options are parsed and associated
477 sanity checks performed.
478 -v, --verbose
480 equivalent of verbose=1. If --verbose appears twice then that is
481 equivalent to verbose=2. Also -vv is equivalent to verbose=2.
482 -X, --verify
484 rather than copy, a comparison is done between IFILE and OFILE.
485 The compare continues until an inequality is found at which
486 point the operation stops. This is only available if OFILE is a
487 pass-through device that implements VERIFY(10 or 16) with BYTCHK
488 set to 1. See the VERIFY section below.
489 -V, --version
491 reports version number information then exits.
492 -w, --wscan
494 this option is available in Windows only. It lists storage
495 device names and the corresponding volumes, if any. When used
496 twice it adds the "bus type" of the closest transport (e.g. a
497 SATA disk in a USB connected enclosure has bus type USB). When
498 used three times a SCSI adapter scan is added. When used four
499 times only a SCSI adapter scan is shown. See EXAMPLES section
500 below and the README.win32 file.
501 -x, --xcopy
503 this option will attempt to call the SCSI EXTENDED COPY(LID1)
504 command. In the absence of another indication the xcopy command
505 will be sent to the destination (i.e. OFILE). See the section on
506 ENVIRONMENT VARIABLES below.
507
509 Arguments do not start with hyphen nor contain a "=".
510 ddpt this string is just a marker. It must not appear in the command
512 line and it must appear in the contents of a job file that isn't
513 part of a comment (i.e. following a "#" on a line). A syntax
514 error is generated (and no copy occurs) if these rules are vio‐
515 lated.
516 JF a command line element that does not contain a '=' (i.e. a ddpt
518 operand) and does not start with '-', apart from the string
519 "ddpt" is treated as a job file (i.e. JF). See the JOB FILES
520 section below.
521
523 One or more conversions can be given to the "conv=" option. If more
524 than one is given, they should be comma separated. ddpt does not per‐
525 form the traditional dd conversions (e.g. ASCII to EBCDIC). Recently
526 added conversions inherited from GNU's dd overlap somewhat with the
527 some of ddpt flags.
528 fdatasync
530 equivalent to "oflag=fdatasync". Flushes data associated with
531 the OFILE to storage at the end of the copy. This conversion is
532 for compatibility with GNU's dd.
533 fsync equivalent to "oflag=fsync". Flushes data and meta-data associ‐
535 ated with the OFILE to storage at the end of the copy. This con‐
536 version
537 no_del_tkn
539 equivalent to "oflag=no_del_tkn".
540 noerror
542 this conversion is very close to "iflag=coe" and is treated as
543 such. See the "coe" flag. Note that an error on a block device
544 or regular file OFILE will stop the copy.
545 notrunc
547 this conversion is accepted for compatibility with dd and
548 ignored since the default action of this utility is not to trun‐
549 cate OFILE.
550 null has no affect, just a placeholder.
552 prefer_rcs
554 equivalent to "oflag=prefer_rcs".
555 resume See "resume" in the FLAGS sections for more information.
557 rtf_len
559 equivalent to "oflag=rtf_len".
560 sparing
562 See "sparing" in the FLAGS sections for more information.
563 sparse FreeBSD's dd supports "conv=sparse" and now GNU's dd does as
565 well so the same syntax is supported in ddpt. See "sparse" in
566 the FLAGS sections for more information.
567 sync is ignored by ddpt. With dd it means supply zero fill (rather
569 than skip) and is typically used like this "conv=noerror,sync"
570 to have the same functionality as ddpt's "iflag=coe".
571 trunc if OFILE is a regular file then truncate it prior to starting
573 the copy. See "trunc" in the FLAGS section.
574
576 A list of flags and their meanings follow. The flag name is followed by
577 one or two indications in square brackets. The first indication is
578 either "[i]", "[o]" or "[io]" indicating this flag is active for the
579 IFILE, OFILE or both the IFILE and the OFILE. The second indication
580 contains some combination of "reg", "blk" "pt", "odx", or "xcopy".
581 These indicate whether the flag applies to a regular file, a block
582 device (accessed via Unix read() and write() commands, a pass-through
583 device, an ODX offloaded copy or a XCOPY(LID1) offloaded copy respec‐
584 tively. Other special file types that are sometimes referred to are
585 "fifo" and "tape".
586 00 [i] This flag may replace IFILE with a source of zero (0x0) bytes.
588 If IFILE is given and is shorter than OFILE then it continues to
589 copy after IFILE is exhausted supplying zero fill bytes. Can
590 only be used on input. Zeros can also be generated by using
591 "if=/dev/zero" or an equivalent.
592 If both '00' and 'ff' flags are given then a marching byte pat‐
593 tern is placed in the segment prior to writing it out. It starts
594 at 0x0 and wraps after 0xff (if the segment is large enough, as
595 it usually is).
596 append [o] [reg], [io] [odx]
598 causes the O_APPEND flag to be added to the open of OFILE. For
599 regular files this will lead to data being appended to the end
600 of any existing data. Conflicts the seek=SEEK option. The
601 default action of this utility is to overwrite any existing data
602 from the beginning of OFILE or, if SEEK is given, starting at
603 block SEEK. Note that attempting to 'append' to a device file
604 (e.g. a disk) will usually be ignored or may cause an error to
605 be reported.
606 odx: if the rtf=RTF option is given, RTF exists, is a regular
607 file and this utility wants to write to RTF then new ROD Tokens
608 are appended to RTF. The default action is to truncate RTF
609 before new ROD Tokens are written to it.
610 atomic [o] [pt]
612 this flag changes the pass-through SCSI WRITE command to the
613 SCSI WRITE ATOMIC(16) command on OFILE (and the
614 cdbsz={6|10|12|16|32} option is ignored for OFILE). If this flag
615 is applied to IFILE or to a non pass-through file then it is
616 ignored.
617 block [io] [pt]
619 pass-through file opens are non-blocking by default and may
620 report the pt device is busy. Use this flag to open blocking so
621 utility may wait until another process locking (or with an
622 exclusive open) is complete before continuing.
623 bytchk [o] [pt]
625 only active when used together with oflag=wverify. Sets the
626 BYTCHK field in the SCSI WRITE AND VERIFY command. Since that
627 field is two bits wide, this flag can be specified multiple
628 times (up to three) to place the corresponding value in the
629 field.
630 cat [io] [xcopy]
632 xcopy: set CAT (residual data handling) bit in EXTENDED
633 COPY(LID1) parameter list segment descriptor header. May appear
634 in either flag list when xcopy is being used. Works with the PAD
635 bit for handling residual data on the destination side. See the
636 XCOPY section below.
637 coe [io] [pt], [i] [reg,blk]
639 continue on error. 'iflag=coe oflag=coe' and 'coe=1' are equiva‐
640 lent. Errors occurring on output regular or block files will
641 stop ddpt. Error messages are sent to stderr. This flag is sim‐
642 ilar to 'conv=noerror,sync' in the dd(1) utility. Unrecovered
643 errors are counted and reported in the summary at the end of the
644 copy.
645 This paragraph concerns coe on pt devices. A medium, hardware or
647 blank check error during a read operation will will cause the
648 following: first re-read blocks prior to the bad block, then try
649 to recover the bad block (supplying zeros if that fails), and
650 finally re-read the blocks after the bad block. A medium, hard‐
651 ware or blank check error while writing is reported but other‐
652 wise ignored. SCSI disks may automatically try and remap faulty
653 sectors (see the AWRE and ARRE in the read write error recovery
654 mode page (the sdparm utility can access these attributes)). If
655 bad LBAs are reported by the pass-through then the LBA of the
656 lowest and highest bad block is also reported.
657 This paragraph concerns coe on input regular files and block
659 devices. When a EIO or EREMOTEIO error is detected on a normal
660 segment read then the segment is re-read one block (i.e. IBS
661 bytes) at a time. Any block that yields a EIO or EREMOTEIO error
662 is replaced by zeros. Any other error, a short read or an end of
663 file will terminate the copy, usually after the data that has
664 been read is written to the output file.
665 dc [io] [blk,pt]
667 xcopy: set DC (destination counter) bit in EXTENDED COPY(LID1)
668 parameter list segment descriptor header. May appear in either
669 flag list when xcopy is being used.
670 direct [io] [reg,blk]
672 causes the O_DIRECT flag to be added to the open of IFILE and/or
673 OFILE. This flag requires some memory alignment on IO. Hence
674 user memory buffers are aligned to the page size. May have no
675 effect on pt devices. This flag will bypass caching/buffering
676 normally done by block layer. Beware of data coherency issues if
677 the same locations have been recently accessed via the block
678 layer in its normal mode (i.e. non-direct). See open(2) man
679 page.
680 dpo [io] [pt]
682 set the DPO bit (disable page out) in SCSI READ and WRITE com‐
683 mands. Not supported for 6 byte cdb variants of READ and WRITE.
684 Indicates that data is unlikely to be required to stay in device
685 (e.g. disk) cache. May speed media copy and/or cause a media
686 copy to have less impact on other device users.
687 errblk [i] [pt] [experimental]
689 attempts to create or append to a file called "errblk.txt" in
690 the current directory the logical block addresses of blocks that
691 cannot be read. The first (appended) line is "# start <time‐
692 stamp>". That is followed by the LBAs in hex (and prefixed with
693 "0x") of any block that cannot be read, one LBA per line. If the
694 sense data does not correctly identify the LBA of the first
695 error in the range it was asked to read then a LBA range is
696 reported in the form of the lowest and the highest LBA in the
697 range separated by a "-". At the end of the copy a line with "#
698 stop <timestamp>" is appended to "errblk.txt". Typically used
699 with "coe".
700 excl [io] [reg,blk]
702 causes the O_EXCL flag to be added to the open of IFILE and/or
703 OFILE. See open(2) man page.
704 fdatasync [o] [reg,blk]
706 Flushes data associated with the OFILE to storage at the end of
707 the copy.
708 ff [i] This flag may replace IFILE with a source of 0xff bytes. If
710 IFILE is given and is shorter than OFILE then it continues to
711 copy after IFILE is exhausted supplying 0xff fill bytes. Can
712 only be used on input.
713 If both '00' and 'ff' flags are given then a marching byte pat‐
714 tern is placed in the segment prior to writing it out. It starts
715 at 0x0 and wraps after 0xff (if the segment is large enough, as
716 it usually is).
717 flock [io] [reg,blk,pt]
719 after opening the associated file (i.e. IFILE and/or OFILE) an
720 attempt is made to get an advisory exclusive lock with the
721 flock() system call. The flock arguments are "FLOCK_EX |
722 FLOCK_NB" which will cause the lock to be taken if available
723 else a "temporarily unavailable" error is generated. An exit
724 status of 90 is produced in the latter case and no copy is done.
725 See flock(2) man page.
726 force [io] [pt] [xcopy,odx]
728 override difference between given block size and the block size
729 found by the SCSI READ CAPACITY command. Use the given block
730 size. Without this flag the copy would not be performed. pt
731 access to what appears to be a block partition is aborted in
732 version 0.92; that can be overridden by the force flag. For
733 related reasons the 'norcap' flag requires this flag when
734 applied to a block device accessed via pt.
735 xcopy and odx: various limits imposed by associated VPD pages or
736 the RECEIVE COPY OPERATING PARAMETERS command can be overridden
737 (i.e. exceeded) if this flag is given. Note that the copy man‐
738 ager will probably object.
739 fsync [o] [reg,blk]
741 Flushes data and metadata (describing the file) associated with
742 the OFILE to storage at the end of the copy.
743 fua [io] [pt]
745 causes the FUA (force unit access) bit to be set in SCSI READ
746 and/or WRITE commands. The 6 byte variants of the SCSI READ and
747 WRITE commands do not support the FUA bit.
748 fua_nv [io] [pt]
750 causes the FUA_NV (force unit access non-volatile cache) bit to
751 be set in SCSI READ and/or WRITE commands. This only has an
752 effect with pt devices. The 6 byte variants of the SCSI READ
753 and WRITE commands do not support the FUA_NV bit. The FUA_NV bit
754 was made obsolete in SBC-3 revision 35d.
755 ignoreew [o] [tape]
757 ignore the early warning indication (of end of tape) when writ‐
758 ing to tape. See TAPE section.
759 immed [io] [odx]
761 sets the IMMED bit in the POPULATE TOKEN (when [i]) or WRITE
762 USING TOKEN (when [o]) command. That command should return sta‐
763 tus promptly after starting the data transfer. The RECEIVE ROD
764 TOKEN INFORMATION command is then used to poll for completion.
765 SCSI command timeouts should not be exceeded, even for very
766 large RODs, if this flag is used.
767 nocache [io] [reg,blk]
769 use posix_fadvise(POSIX_FADV_DONTNEED) to advise corresponding
770 file there is no need to fill the file buffer with recently read
771 or written blocks. If used with "iflag=" it will increase the
772 read ahead on IFILE.
773 no_del_tkn [o] [odx]
775 will clear the DEL_TKN bit on the last WRITE USING TOKEN command
776 of each ROD Token in a odx full copy. In a large odx full copy
777 several ROD Tokens may be used (one after the other). The
778 default action is to set the DEL_TKN bit on the last WUT command
779 of each ROD. Either way it should not make much difference
780 because the copy manager deletes a ROD Token when its inactivity
781 time-out occurs.
782 nofm [o] [tape]
784 no File Mark (FM) on close when writing to tape. See TAPE sec‐
785 tion.
786 nopad [o] [tape]
788 when the block to be written to a tape drive contains less than
789 OBS bytes, then this option causes the partial block to be writ‐
790 ten as is. The default action for a tape in this case is to pad
791 the block. See TAPE section.
792 norcap [io] [pt]
794 do not perform SCSI READ CAPACITY command on the corresponding
795 pt device. If used on block device accessed via pt then 'force'
796 flag is also required. This is to warn about using pt access on
797 what may be a block device partition.
798 nowrite [o] [reg,blk,pt]
800 bypass writes to OFILE. The "records out" count is not incre‐
801 mented. OFILE is still opened but "oflag=trunc" if given is
802 ignored. Also the ftruncate call associated with the sparse flag
803 is ignored (i.e. bypassed). Commands such as trim and SCSI SYN‐
804 CHRONIZE CACHE are still sent.
805 null [io]
807 has no affect, just a placeholder.
808 odx [io] [odx]
810 indicates to this utility that one of the four variants of an
811 odx copy is requested. Using any of the --odx, rtf=RTF or
812 rtype=RTYPE options also indicates that odx is requested. See
813 the ODX section.
814 pad [o] [reg,blk,pt], [io] [xcopy]
816 when the block to be written (typically the last block) contains
817 less than OBS bytes, then this option causes the block to be
818 padded with zeros (i.e. bytes of binary zero). The default
819 action for a regular file and a fifo is to do a partial write.
820 The default action of a block and a pt device is to ignore the
821 partial write. The default action of a tape is to pad, so this
822 flag is not needed (see the nopad flag).
823 xcopy: sets the PAD bit in the CSCD descriptor of the associated
824 IFILE or OFILE. Is associated with residual data handling and
825 works together with the cat flag. See the XCOPY section below.
826 prealloc [o] [reg]
828 use the fallocate() call prior to starting a copy to set OFILE
829 to its expected size.
830 prefer_rcs [o] [odx]
832 prefer RECEIVE COPY STATUS (RCS) command to the RECEIVE ROD
833 TOKEN INFORMATION (RRTI) command which is the default. This only
834 is active when polling after a WUT command (since polling after
835 a PT command needs to fetch the ROD Token so it needs the RRTI
836 command).
837 pt [io] [blk,pt]
839 causes a device to be accessed in "pt" mode. In "pt" mode SCSI
840 READ and WRITE commands are sent to access blocks rather than
841 standard UNIX read() and write() commands. The "pt" mode may be
842 implicit if the device is only capable of passing through SCSI
843 commands (e.g. the /dev/sg* and some /dev/bsg/* devices in
844 Linux). This flag is needed for device nodes that can be
845 accessed both via standard UNIX read() and write() commands as
846 well as SCSI commands. Such devices default standard UNIX read()
847 and write() commands in the absence of this flag.
848 rarc [i] [pt]
850 bit set in READ(10, 12, 16 and 32) to suppress RAID rebuild
851 functions when a bad (or recovered after difficulties) block is
852 detected.
853 resume [o] [reg]
855 when a copy is interrupted (e.g. with Control-C from the key‐
856 board) then using the same invocation again with the addition of
857 "oflag=resume" will attempt to restart the copy from the point
858 of the interrupt (or just before that point). It is harmless to
859 use "oflag=resume" when OFILE doesn't exist or is zero length.
860 If the length of OFILE is greater than or equal to the length
861 implied by a ddpt invocation that includes "oflag=resume" then
862 no further data is copied.
863 self [io] [pt]
865 used together with trim flag to do a self trim (trim of segments
866 of a pt device that contain all zeros). If OFILE is not given,
867 then it is set to the same as IFILE. If SEEK is not given it set
868 to the same value as SKIP (possibly adjusted if IBS and OBS are
869 different). Implicitly sets "nowrite" flag.
870 sparing [o] [reg,blk,pt]
872 during the copy each IBS * BPT byte segment is read from IFILE
873 into a buffer. Then, instead of writing that buffer to OFILE,
874 the corresponding segment is read from OFILE into another buf‐
875 fer. If the two buffers are different, the former buffer is
876 written to the OFILE. If the two buffers compare equal then the
877 write to OFILE is not performed. Write sparing is useful when a
878 write operation is significantly slower than a read. Under some
879 conditions flash memory devices have slow writes plus an upper
880 limit on the number of times the same cell can be rewritten. The
881 granularity of the comparison can be reduced from the default
882 IBS * BPT byte segment with the the OBPC value given to the
883 "bpt=" option. The finest granularity is when OBPC is 1 which
884 implies OBS bytes.
885 sparse [io] [reg,blk,pt]
887 after each IBS * BPT byte segment is read from IFILE, it is
888 checked to see if it is all zeros. If so, that segment is not
889 written to OFILE. See the section on SPARSE WRITES below for the
890 difference between using this flag once or twice. The granular‐
891 ity of the zero comparison can be reduced from the default IBS *
892 BPT byte segment with the OBPC value given to the "bpt=" option.
893 The sparse flag may be used on input when a file is only being
894 read (e.g. when of=OFILE is not given or OFILE is /dev/null) to
895 determine how many blocks are contained in sparse segments of
896 IFILE.
897 ssync [o] [pt]
899 if OFILE is in "pt" mode then the SCSI SYNCHRONIZE CACHE command
900 is sent to OFILE at the end of the copy.
901 strunc [o] [reg]
903 perform a sparse copy with a ftruncate system call to extend the
904 length of the OFILE if required. Sets the sparse flag internally
905 if this has not been specified on the command line. See the
906 sparse flag and the section on SPARSE WRITES below.
907 sync [io] [reg,blk]
909 causes the O_SYNC flag to be added to the open of IFILE and/or
910 OFILE. See open(2) man page.
911 rtf_len [io] [odx]
913 odx: with the 'read to tokens' variant, after 512 bytes of each
914 ROD Token are written to RTF an additional 8 byte (big endian)
915 integer is written. That integer is the number of bytes that the
916 associated ROD represents. The draft standards say for standard
917 ROD types the ROD Token contains this value. However vendor spe‐
918 cific ROD types may be used or vendors may choose not to comply.
919 Either way the 'write from tokens' variant needs to know the
920 data size associated with the ROD it is writing from.
921 trim [io] [pt] [experimental]
923 similar logic to the "sparse" option. However instead of skip‐
924 ping segments that are full of zeros a "trim" command is sent to
925 OFILE. Usually set as an oflag argument but for self trim can be
926 used as an iflag argument (e.g. "iflag=self,trim"). Depending on
927 the usage this may require the device to support "deterministic
928 read zero after trim". See the TRIM, UNMAP AND WRITE SAME sec‐
929 tion below.
930 trunc [o] [reg]
932 if OFILE is a regular file then it is truncated prior to start‐
933 ing the copy. If SEEK is not given or 0 then OFILE is truncated
934 to zero length; when SEEK is larger than zero the truncation
935 takes place at file byte pointer SEEK*OBS. Ignored if
936 "oflag=append". Conflicts with "oflag=sparing".
937 unmap [io] [pt]
939 same as the trim flag.
940 wverify [o] [pt]
942 this causes SCSI WRITE AND VERIFY commands to be sent to OFILE
943 (instead of SCSI WRITE (or WRITE ATOMIC) commands). Note that
944 the fua flag is ignored when this flag is given. The BYTCHK
945 field in the SCSI WRITE AND VERIFY commands is set to zero
946 unless the bytchk flag is also given.
947 wstream [o] [pt]
949 this causes SCSI WRITE STREAM(16) command to be sent to OFILE
950 (instead of SCSI WRITE. The Stream Identify (valid range: 1 to
951 0xffff (65535)) should be given via the list_id=LID operand
952 (note that it defaults to 0 which is invalid). The stream can be
953 created (closed (for write) or its status checked) with the
954 sg_stream_ctl utility. It is the user's responsibility to open a
955 stream before calling "ddpt ... oflag=wstream list_id=<strm_id>"
956 and close it after, if required.
957 xcopy [io] [pt]
959 invoke SCSI XCOPY(LID1) logic and send the XCOPY command to the
960 either IFILE or OFILE depending on which flag this called. If
961 both are given (i.e. an invocation including 'iflag=xcopy
962 oflag=xcopy') then send the XCOPY(LID1) to OFILE.
963
965 When the count=COUNT option is not given (or COUNT is '-1') then an
966 attempt is made to deduce COUNT as follows.
967 When both or either IFILE and OFILE are block devices, then the minimum
969 size, expressed in units of input blocks, is used. When both or either
970 IFILE and OFILE are pass-through devices, then the minimum size,
971 expressed in units of input blocks, is used.
972 If a regular file is used as input, its size, expressed in units of
974 input blocks (and rounded up if necessary) is used. Note that the
975 rounding up of the deduced COUNT may result in a partial read of the
976 last input block and a corresponding partial write to OFILE if it is a
977 regular file. After a regular file to regular file copy the length of
978 OFILE will be the same as IFILE unless OFILE existed and its length was
979 already greater than that of IFILE. To get a copy like the standard
980 Unix cp command, use oflag=trunc with ddpt.
981 The size of pt devices is deduced from the SCSI READ CAPACITY command.
983 Block device sizes (or their partition sizes) are obtained from the
984 operating system, if available.
985 If skip=SKIP or seek=SEEK are given and the COUNT is deduced (i.e. not
987 explicitly given) then that size is scaled back so that the copy will
988 not overrun the file or device.
989 If COUNT is not given and IFILE is a fifo (and stdin is treated as a
991 fifo) then IFILE is read until an EOF is detected. If COUNT is not
992 given and IFILE is a /dev/zero (or equivalent) then zeros are read
993 until an error occurs (e.g. file system full).
994 If COUNT is not given and cannot be deduced then an error message is
996 issued and no copy takes place.
997
999 Some operands can have long arguments (e.g. skip=SKIP and iflag=FLAGS)
1000 so that the command line can become quite long. Also scatter gather
1001 lists can be arbitrarily long and may be generated by a program; then
1002 it would be tiresome and error-prone to re-type them on the command
1003 line. So the job file was introduced to hold this utility's operands
1004 and options.
1005 A job file is invoked by either the --job=JF option or by placing the
1007 job filename (JF) unadorned on the command line. The job filename can‐
1008 not contain a "=", start with a hyphen nor be called "ddpt". It is
1009 parsed when it is detected, in a left to right scan of the command
1010 line. The JF file must contain the string "ddpt" and may invoke other
1011 job files (to a maximum depth of 4). A job file should not invoke
1012 itself. Also the first line of the job file should not contain any
1013 characters (bytes) with their top bit set; in other words it should be
1014 restricted to 7 bit ASCII (otherwise sanity checks might think it is a
1015 binary file and reject it).
1016 The operands and options within a job file are processed in the order
1018 they are found (i.e. parsing lines left to right, top (of file) to bot‐
1019 tom). The operands and options may contradict (and cause a syntax
1020 error), override or accumulate with earlier ones, the same as if they
1021 appeared on the command line. For example '-v' on the command line fol‐
1022 lowed by a job file containing '-vv' will result in a verbosity level
1023 of '-vvv' during the copy phase. Empty lines, lines only containing
1024 whitespace(s) and anything from and including a '#' in a job file line
1025 are ignored.
1026
1028 Each element of a scatter gather list (sgl, plural: sgl_s) is made up
1029 of a starting logical block address (LBA, plural: LBAs), and a number
1030 of blocks (NUM) to be accessed from that starting LBA.
1031 The skip=SKIP and seek=SEEK options (and their aliases) can take scat‐
1033 ter gather lists. These can be explicit on the command line, fed in
1034 through stdin or in a file whose name is prefixed by "@" or "H@" on the
1035 command line. For large scatter gather lists, placing them in a file is
1036 the most practical as command lines are limited in length. Scatter
1037 gather list (sgl) is a collective term for either a scatter list or a
1038 gather list. The actual implementation of each sgl is an array. Syn‐
1039 tactically a scatter list and a gather list are the same.
1040 Conceptually these sgl_s refer to what happens at the "far end" (e.g.
1042 within a hard disk or SSD), not what happens in the computer's memory.
1043 So a gather list is associated with the read part of a copy (i.e. the
1044 first half) where a list of Logical Blocks (LBs, identified by their
1045 addresses, hence LBAs) and a number of consecutive, following blocks
1046 are "gathered" from the medium (e.g. a SSD). They are formed into a
1047 linear sequence of bytes that is transferred into a segment in the com‐
1048 puter's RAM. The second half of the copy, the write part, may use a
1049 scatter list. A scatter list starts with a linear sequence of bytes,
1050 taken from the segment, that is transferred to the device and then
1051 "scattered" on the medium as indicated by the list of LBA,NUM pairs.
1052 In the simplest case a sgl is given on the command line and has the
1054 form: LBA1,NUM1[,LBA2,NUM2[,LBA3,NUM3...]]. There must be an even num‐
1055 ber of items (i.e. for every LBAn there should be a following NUMn)
1056 with one exception: when LBA1 alone is given, in which case the value 0
1057 is assumed for NUM1. Comma is the simplest separator for the command
1058 line, but whitespace may also be used (but needs to be escaped because
1059 the shell usually interprets whitespace as an option separator). In a
1060 file (or read from stdin or file redirection) more flexibility is per‐
1061 mitted in the format. The LBA,NUM pairs could all appear on one line
1062 in a file but the line length is limited to 1024 characters (with a
1063 maximum of 256 parseable items on it). So for longer sgl_s one pair per
1064 line is recommended in file format. Also in file format everything
1065 from and including '#' to the end of that line is ignored as are lines
1066 that are empty or only contain whitespace(s).
1067 Each pair becomes one element (or more, see below) of the sgl. By
1069 default all numbers given for LBA and NUM items are in decimal with
1070 optional suffix multipliers. Hex numbers use either a "0x" prefix or a
1071 'h' suffix (hex notation and suffix multipliers cannot be mixed). In
1072 the case of a 'H@' lead-in to the filename on the command line, all
1073 numbers are interpreted as hex with no suffix multipliers permitted.
1074 Further, with the 'H@' lead-in the file may contain the string 'HEX'
1075 before any numbers are given. The 'HEX' is ignored. The point of this
1076 is to catch when a sgl file with default hexadecimal numbers is given
1077 without the 'H@' lead-in; in this case this utility will exit saying
1078 that file is in the wrong format. This "wrong format" action can be
1079 bypassed with the --flexible option.
1080 Allowing sgl_s brings lots of flexibility (including the possibility to
1082 use the SCSI WRITE SCATTERED command) but with that comes complexity.
1083 Every sgl is scanned to determine if it is monotonic and whether it has
1084 overlapping elements. The term monotonic is used to indicate whether
1085 each LBA is in ascending order, with each LBA greater than the previous
1086 element's LBA. Overlapping refers to the situation when any element's
1087 LBA range intersects with any other element's range. Elements that have
1088 zero number of blocks (described here as "degenerate") are ignored for
1089 determining monotonic and overlapping (and the lowest LBA). Overlapping
1090 elements are not ideal (but not necessarily fatal). The above mentioned
1091 WRITE SCATTERED command allows the medium's logic to write elements in
1092 any order it prefers. That means if elements overlap, then the user
1093 doesn't know which one gets written last (overwriting the one written
1094 to the same LBA earlier). Determining whether element ranges overlap
1095 is difficult in the general case (so this utility doesn't do it) but
1096 easy in the case of a monotonic sgl (so this utility does do it). Warn‐
1097 ings are issued in dangerous situations, with the force flag allowing
1098 the warning to be overridden.
1099 A degenerate sgl element is one that has zero in its NUM field. Nor‐
1101 mally degenerate elements are ignored with some exceptions. The defini‐
1102 tion of the SCSI WRITE SCATTERED command clearly states that degenerate
1103 elements are valid, thus do not cause an error, but cause no associated
1104 action. This utility uses the concept of a 'hard' and 'soft' sgl: a
1105 'soft' sgl is one in which the last element's NUM is zero (i.e. its
1106 last element is degenerate). A sgl with a non-zero NUM in its last ele‐
1107 ment is considered 'hard'. In a 'soft' sgl the LBA of the last element
1108 should be greater than or equal to any LBA+NUM of earlier elements.
1109 Because this is hard to check it is not enforced, so the decision is
1110 made on whether a sgl is hard or soft simply by checking the NUM of
1111 that last element. The difference between a hard and soft sgl is the
1112 way the sum of NUM of all elements is used by this utility. For a
1113 'hard' sgl that sum is used for COUNT when the count=COUNT option is
1114 not given; and if count=COUNT is given and the counts differ then those
1115 two values are output and this utility exits with a syntax error. For a
1116 'soft' sgl the degenerate last element is interpreted as "from the
1117 highest LBA in the list to the end of the copy" where the COUNT is
1118 determined some other way. The "highest LBA" is calculated from all
1119 elements that have a non-zero number of blocks plus the LBA of the last
1120 element (regardless of whether it is degenerate or not).
1121 The rules in the above paragraph make a one item skip or seek argument
1123 (e.g. skip=0x123) in this utility first become a one element sgl (e.g.
1124 containing the pair [0x123, 0x0]). Since this is the last element, it
1125 is a soft sgl and the transfer will start from the given lba (i.e.
1126 0x123) and continues for the number of blocks indicated by some other
1127 mechanism (e.g. an option such as count=COUNT or the length of IFILE).
1128 This mirrors what the classic dd command does with its skip= and seek=
1129 options.
1130 Some sgl implementation details: LBAs are stored in 64 bit integers
1132 which is more than sufficient to span even the largest disk array
1133 behind a logical device, even if the block size is one byte, which is
1134 unlikely. The NUM field is a 32 bit integer and this is more problem‐
1135 atic. The reason is that SCSI WRITE commands (and their variants) only
1136 allocate at most a 32 bit integer for this value. Further, modern oper‐
1137 ating systems do not allow any driver to get large amounts of contigu‐
1138 ous system RAM, even if the machine has it available. A 32 bit integer
1139 for NUM with each block at 512 bytes is around 2 TB of storage. Unix
1140 system calls (in Linux) also limit each read(2) and write(2) system
1141 call to 32 bits of single bytes which is 4 GB. The problem for this
1142 utility is that the NUM can easily exceed 32 bits when a single scatter
1143 gather list element refers to the whole device. The action taken by
1144 this utility is to allow larger than 32 bit NUM values to be given on
1145 the command line (or in a scatter gather list file). However such a
1146 large element will be split into multiple elements internally. This
1147 will be visible to the user when the verbose=VERB option (or one of its
1148 variants) is used with an elevated value.
1149 There is a helper utility called ddpt_sgl in this package for generat‐
1151 ing, manipulating and checking scatter gather lists. See its manpage.
1152
1154 With powerful data tools, the ability to accidentally overwrite and
1155 hence lose important data is ever present. So a significant portion of
1156 the code is dedicated to checking the input arguments for duplications
1157 and contradictions. Still nothing is better than re-reading the command
1158 line (which can be quite long) before hitting the enter key.
1159 Other useful possibilities are to use job files (see the JF argument
1161 and the --job=JF option) and the --dry-run option. The "dry run"
1162 option is becoming popular in modern command line utilities and more or
1163 less does what the user would expect. Firstly it parses all the command
1164 line arguments then opens IFILE, OFILE and OFILE2 as directed by the
1165 command line and does any meta-data operations that it would typically
1166 do (e.g. check a pass-though or block device's logical block size and
1167 object if it differs from BS, IBS or OBS (whichever applies)). Then
1168 just at the point where the code would commence the actual copy (or
1169 read) it does a premature exit. If the --dry-run option is given twice,
1170 the code continues into the copy logic and bypasses the low level read
1171 and write calls (and file repositioning). That inner level of "dry run"
1172 is useful for debugging and can be used with multiple verbose=VERB
1173 options.
1174 The verbose=VERB option sends diagnostic messages to stderr. The higher
1176 value of VERB (in verbose=VERB) or the more times that -v is used, the
1177 greater the volume of diagnostic messages. When use three or more times
1178 then diagnostic messages are generated for each read to, and write
1179 from, the working copy buffer; so the volume of messages is propor‐
1180 tional to the number of reads and writes that are done; this can easily
1181 be in the megabyte range. If used less than three times, the reads and
1182 writes associated with the copy do not generate diagnostic messages
1183 (unless abnormal situations are encountered). These diagnostic messages
1184 are mainly associated with command line parsing and fetching meta-data
1185 about the given files, plus messages from the cleanup at the end of the
1186 copy.
1187 The following command line arguments are checked that they don't appear
1189 more than once: bpt=BPT[,OBPC], bs=BS, count=COUNT, ibs=IBS, if=IFILE,
1190 iseek=SKIP, obs=OBS, of=OFILE, of2=OFILE2, oseek=SEEK, seek=SEEK and
1191 skip=SKIP. On the other hand, some arguments are additive, for example
1192 iflag=FLAGS, oflag=FLAGS, status=STAT and --verbose and may appear as
1193 many times as required.
1194
1196 This section describes XCOPY(LID1) support with this utility. For ODX
1197 support (XCOPY(LID4) subset) see the ODX section.
1198 A device (logical unit (LU)) that supports XCOPY operations should set
1200 the 3PC field (3PC stands for Third Party Copy) in its standard INQUIRY
1201 response. That is not checked when this utility does an xcopy operation
1202 but if it fails, that is one thing that the user may want to check.
1203 If the xcopy starts and fails while underway, then 'sg_copy_results -s'
1205 may be useful to view the copy status. It might also be used from a
1206 different process with the same I_T nexus (i.e. the same machine) to
1207 check status during an xcopy operation.
1208 The pad and cat flags control the handling of residual data. As the
1210 data can be specified either in terms of source or target block size
1211 and both might have different block sizes residual data is likely to
1212 happen in these cases. If both block sizes are identical these bits
1213 have no effect as residual data will not occur.
1214 If neither of these flags are set, the EXTENDED COPY command will be
1216 aborted with additional sense 'UNEXPECTED INEXACT SEGMENT'.
1217 If only the cat flag is set the residual data will be retained and made
1219 available for subsequent segment descriptors. Residual data will be
1220 discarded for the last segment descriptor.
1221 If the pad flag is set for the source descriptor only, any residual
1223 data for both source or destination will be discarded.
1224 If the pad flag is set for the target descriptor only any residual
1226 source data will be handled as if the cat flag is set, but any residual
1227 destination data will be padded to make a whole block transfer.
1228 If the pad flag is set for both source and target any residual source
1230 data will be discarded, and any residual destination data will be
1231 padded.
1232 There is a web page discussing ddpt, XCOPY and ODX at
1234 http://sg.danny.cz/sg/ddpt_xcopy_odx.html
1235
1237 This section describes ODX support (an XCOPY(LID4) subset) for this
1238 utility. ODX descriptions use the following command name abbrevia‐
1239 tions: PT for the POPULATE TOKEN command, RRTI for the READ ROD TOKEN
1240 INFORMATION command, and WUT for the WRITE USING TOKEN command.
1241 A device (logical unit (LU)) that supports ODX operations is required
1243 to set the 3PC field (3PC stands for Third Party Copy) in its standard
1244 INQUIRY response and support the Third Party Copy VPD page. If this
1245 utility generates errors noting the absence of these then the device in
1246 question probably does not support ODX.
1247 There a four variants of ODX supported by ddpt:
1249 full copy : ddpt --odx if=/dev/sg3 bs=512 of=/dev/sg4
1250 zero output blocks : ddpt if=/dev/null rtype=zero bs=512 of=/dev/sg4
1251 read to tokens : ddpt if=/dev/sg3 bs=512 skip=@gath.lst rtf=a.rt
1252 write from tokens : ddpt rtf=a.rt bs=512 of=/dev/sg4 seek=@scat.lst
1253 The full copy will call PT and WUT commands repeatedly until the copy
1255 is complete. More precisely the full copy will make the largest single
1256 call to PT allowed by the input's Third Party Copy VPD page (and, if
1257 given, allowed by the BPT argument in the bpt=BPT[,OBPC] option). Then
1258 one or more WUT calls are made to write out from the ROD created by the
1259 PT step. The largest single WUT call is constrained by the output's
1260 Third Party Copy VPD page (and, if given, allowed by the OBPC argument
1261 in the bpt=BPT[,OBPC] option). This sequence continues until the
1262 requested copy is complete.
1263 The zero output blocks variant is a special case of the full copy in
1265 which only WUT calls are made. ODX defines a special ROD Token to zero
1266 blocks. That special ROD Token has a fixed pattern (shown in SBC-3) and
1267 does not need to be created by a PT command like normal ROD Tokens.
1268 The read to tokens and the write from tokens variants are designed to
1270 be the read (input) and write (output) sides respectively of a network
1271 copy. Each can run on different machines by sending the RTF file from
1272 the machine doing the read to the machine doing the write. The read to
1273 tokens will make one or more PT calls and output the resulting ROD
1274 Tokens to the RTF file. RTF might be a regular file or a named pipe.
1275 All four variants can have the immed flag set. Then the PT and/or WUT
1277 commands are issued with the IMMED bit set and the RRTI command is used
1278 to poll for completion. The delay between the polls is as suggested by
1279 the RRTI command (or if no suggestion is made, 500 milliseconds).
1280 Either iflag=immed, oflag=immed or both can be given but are only
1281 effective if the corresponding IFILE or OFILE sends a PT or WUT com‐
1282 mand.
1283 Typically there is no need to give the list_id=LID option. If this
1285 option is not given then 257 is chosen. If that is busy then 258 is
1286 tried. That continues until a usable LID is found or 10 LIDs have been
1287 tried. In the latter case ddpt exits with status of 55 (operation in
1288 progress). If the user gives list_id=LID option and LID is busy then
1289 ddpt exits with exit status 55.
1290 If the block size of the input and output are different (i.e. IBS is
1292 not equal to OBS) then one must be a multiple of the other. So an input
1293 block size of 512 bytes and an output block size of 4096 bytes (or vice
1294 versa) is acceptable.
1295 The four ODX variants are distinguished as follows: if OFILE is a
1297 pass-through device, if=/dev/null (or equivalent) and rtype=zero then
1298 the zero output blocks variant is selected. If both IFILE and OFILE are
1299 pass-through devices and there is some indication of an ODX request
1300 (e.g. the --odx option), then the full copy variant is selected. The
1301 read to tokens and the write from token variants are indicated by the
1302 absence of either a of=OFILE or a if=IFILE option, respectively, plus
1303 the presence of a rtf=RTF option.
1304 The helper utility ddptctl contains options to issue a single PT, RRTI,
1306 WUT or COPY OPERATION ABORT command. It can also issue a series of
1307 polling RRTI commands. It can decode information in ROD Tokens (which
1308 is not as informative as it should be) and print the number of blocks
1309 and block size of a disk, plus protection information if available. See
1310 ddptctl.
1311 There is a web page discussing ddpt, XCOPY and ODX at
1313 http://sg.danny.cz/sg/ddpt_xcopy_odx.html
1314
1316 Bypassing writes of blocks full of zeros can save a lot of IO. However
1317 with regular files, bypassed writes at the end of the copy can lead to
1318 an OFILE which is shorter than it would have been without sparse
1319 writes. This can lead to integrity checking programs like md5sum and
1320 sha1sum generating different values.
1321 This utility has two ways of handling this file length problem: writing
1323 the last block (even if it is full of zeros) or using the ftruncate
1324 system call. A third approach is to ignore the problem (i.e. leaving
1325 OFILE shorter). The ftruncate approach is used when "oflag=strunc"
1326 while the last block is written when "oflag=sparse". To ignore the file
1327 length issue use "oflag=sparse,sparse". Note that if OFILE's length is
1328 already correct or longer than required, no action is taken.
1329 The support for sparse writing of regular files may depend on the OS,
1331 the file system and the settings of OFILE. POSIX makes few guarantees
1332 when the ftruncate system call is used to extend a file's length, as
1333 may occur when "oflag=strunc". Further, primitive file systems like
1334 VFAT may not accept sparse writes or simulate the effect by writing
1335 blocks of zeros. The latter approach will defeat any sparse writing
1336 performance gain.
1337
1339 This is a new storage feature often associated with Solid State Disks
1340 (SSDs) or disk arrays with "thin provisioning". In the ATA command set
1341 (ACS-2) the relevant command is DATA SET MANAGEMENT with the TRIM bit
1342 set. In the SCSI command set (SBC-3) it is either the UNMAP or WRITE
1343 SAME command. Note there is no TRIM command however the term is fre‐
1344 quently used in the technical press.
1345 Trim is a way of telling a storage device that blocks are no longer
1347 needed. Keeping the pool of unwritten blocks large is important for
1348 the write performance of SSDs and the thrifty use of real storage in
1349 thin provisioned arrays. Currently file systems in recent OSes may
1350 issue trims associated with file deletes. The trim option in ddpt may
1351 be useful when a partition or a whole SSD is to be "deleted". Note that
1352 ddpt is bypassing file systems in that it only offers trim on
1353 pass-through (pt) devices.
1354 This utility issues SCSI commands to pt devices and for "trim" cur‐
1356 rently issues a SCSI WRITE SAME(16) command with the UNMAP bit set. If
1357 the pt device is a SSD with a ATA interface then recent versions of
1358 Linux will translate the SCSI WRITE SAME to the ATA DATA SET MANAGEMENT
1359 command with the TRIM bit set. The maximum size of each "trim" command
1360 sent is the size of the copy buffer (i.e. IBS * BPT bytes). And that
1361 maximum can be reduced with the OBPC argument of the "bpt=" option.
1362 The trim can be used various ways. One way is a copy where the copy
1364 buffer (or some part of it) is checked for zeros as is done by the
1365 sparse oflag. When a zero segment is found, a trim "command" is sent to
1366 the OFILE. For example:
1367 ddpt if=dsk.img bs=512 of=/dev/sdc oflag=pt,trim
1369 The copy buffer is 64 KiB (since BPT and OBPC default to 128 when
1371 "bs=512") and it is checked for all zeros. If it is all zeros then a
1372 trim command is sent to the corresponding location of /dev/sdc which is
1373 accessed via the pt interface. If it is not all zeros then a SCSI WRITE
1374 command is sent. Another way is to trim all or part of a disk. To trim
1375 a whole disk (i.e. deleting all its data):
1376 ddpt if=/dev/zero bs=512 of=/dev/sdc oflag=pt,trim
1378 A third way is to "self-trim" which is to only trim those parts of a
1380 disk that contain segments full of zeros:
1381 ddpt if=/dev/sdc skip=0x2300 bs=512 iflag=pt,self,trim
1383 count=0x1234f0
1384 The "self" oflag automatically sets up the output side of the copy to
1386 send trim commands (if required) back the the same device (i.e.
1387 /dev/sdc). If this example was self-trimming a partition then the par‐
1388 tition would start at LBA 0x2300 and be 0x1234f0 blocks long.
1389 Some random product examples: the Intel X25-M G2 SSDs have trim with
1391 recent firmware and they do deterministic read zero after trim. The
1392 Seagate Pulsar SSD has an ATA interface which supports the determinis‐
1393 tic reads of zero after the DATA SET MANAGEMENT command with the TRIM
1394 option.
1395
1397 dd defaults "if=" and "of=" to stdin and stdout respectively. This fol‐
1398 lows Unix filter conventions. However since dd and ddpt are often used
1399 to read binary data for timing purposes, having to supply
1400 "of=/dev/null" can be easily forgotten. Without it dd will typically
1401 spew binary data on the console. So ddpt has changed its defaults: the
1402 "if=IFILE" is now mandatory for direct copies and to read from stdin
1403 "if=-" can be used; "of=OFILE" remains optional but its default changes
1404 to "/dev/null" (or "NUL" in Windows). To send output to stdout ddpt
1405 accepts "of=-".
1406 dd truncates OFILE unless "conv=notrunc" is given. When dd truncates,
1408 it truncates to zero length unless SEEK is greater than zero. ddpt does
1409 not truncate OFILE by default. If OFILE exists it will be overwritten.
1410 The overwrite starts at block zero unless SEEK or "oflag=append" is
1411 given. If OFILE is a regular file then "oflag=trunc" (or "conv=trunc")
1412 will truncate OFILE prior to the copy.
1413 Numeric arguments to ddpt can be given in hexadecimal, either with a
1415 leading "0x" or "0X" or with a trailing "h". Note that dd accepts
1416 "0x123" but interprets it as "0 * 123" (i.e. zero). ddpt will also
1417 interpret "x" as multiplies unless the left operand is zero (e.g.
1418 "0x123"). So both dd and ddpt will interpret "skip=2x123" as
1419 "skip=246".
1420 Terabyte size disks make it impractical to copy all the data into a
1422 single buffer of 512 bytes length before writing it out. Therefore both
1423 dd and ddpt read a relatively small amount of data into a copy (or
1424 transfer) buffer then write it out to the destination, repeating this
1425 process until the COUNT is exhausted.
1426 A major difference in ddpt is the addition of BPT (Blocks Per Transfer)
1428 to control the size of the copy buffer. With dd, IBS is the size of the
1429 copy buffer and the unit of SKIP and COUNT. With ddpt, IBS * BPT is the
1430 size of the copy buffer and IBS is the unit of SKIP and COUNT. This
1431 allows ddpt to have its IBS set to the logical block size of IFILE
1432 without unduly restricting the size of the copy buffer. And setting IBS
1433 (and OBS for OFILE) accurately is required when the pass-through inter‐
1434 face is used since with the SCSI READ and WRITE commands the logical
1435 block size is implicit.
1436 The way dd handles its copy buffer (outlined in SUSv4 description of
1438 dd) is relatively complex, especially when IBS and OBS are different
1439 sizes. The restriction that ddpt places on IBS and OBS ( i.e. (((IBS *
1440 BPT) % OBS) == 0) ) means that a single copy buffer can be used since
1441 its size is a multiple of both IBS and OBS. Being able to precisely
1442 define the copy buffer size in ddpt makes sparse writing, write sparing
1443 and trim operations simpler to define and the user to control.
1444 ddpt does not support dd's "cbs=" option (conversion block size). If
1446 the "cbs=" option is given to ddpt then it is ignored.
1447 ddpt adds two types of disk to disk, offloaded copies: XCOPY(LID1)
1449 first introduced in SPC-2 (standardized in 2001), and ODX which is a
1450 subset of XCOPY(LID4) first introduced in SPC-4 draft (revision 34,
1451 2012).
1452
1454 This section is about protection information which is typically an
1455 extra 8 bytes associated with each logical block. Those 8 byte are
1456 divided into 3 fields: logical block guard (16 bit (2 byte) CRC), logi‐
1457 cal block application tag (2 bytes) and the logical block reference tag
1458 (4 bytes). The acronym DIF is sometimes used for protection informa‐
1459 tion.
1460 The feature to read and/or write protection information by using the
1462 protect=RDP[,WRP] option is currently experimental. It should be used
1463 with care and may not "play well" with some other features such as
1464 write sparing and sparse writing. It should be used to copy user data
1465 plus the associated protection information to or from a regular file.
1466 It could also be used for a device to device copy assuming the "pt"
1467 interface is used for both. Also only modern SCSI disks support protec‐
1468 tion information.
1469 When RDP or WRP is greater than 0 then a copy with associated protec‐
1471 tion information is active. In this state IBS and OBS must be the same
1472 and equal to the logical block size of the device(s) formatted with
1473 protection information. If a SCSI disk with 512 byte logical block size
1474 has protection information then the actual number of bytes transferred
1475 for each logical block is typically 520 bytes. For such a disk BS=512
1476 is required even when additional protection information is being trans‐
1477 ferred.
1478
1480 By default numeric arguments to options are assumed to be decimal.
1481 Almost all numeric arguments to options (e.g. COUNT in the count=COUNT
1482 option) may include one of these multiplicative suffixes: c C *1; w W
1483 *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB
1484 *1,000,000 . This pattern continues for "G", "T" and "P". The latter
1485 two suffixes can only be used for 64 bit values. Some numeric arguments
1486 are limited to 32 bit values (e.g. BSin the bs=BS option). Also a suf‐
1487 fix of the form "x<n>" multiplies the leading number by <n>; however
1488 the combinations "0x" and "0X" are treated differently, see the next
1489 paragraph. These multiplicative suffixes are compatible with GNU's dd
1490 command (since 2002) which claims compliance with the SI and with IEC
1491 60027-2 standards.
1492 Alternatively numerical values can be given in hexadecimal indicated by
1494 either a leading "0x" or "0X", or by a trailing "h" or "H". When hex
1495 numbers are given, suffix multipliers cannot be used.
1496 If a numeric argument is required to fit in 32 bits and is too large
1498 then an error is reported. Usually negative numbers are not permitted
1499 but "count=-1" is a special case and means "all available"; "ver‐
1500 bose=-1" is another special case.
1501
1503 Copying data behind an Operating System's back can cause problems. In
1504 the case of Linux, users should look at this link:
1505 http://linux-mm.org/Drop_Caches
1506 This command sequence may be useful:
1507 sync; echo 3 > /proc/sys/vm/drop_caches
1508 A partial write is a write to the OFILE of less than OBS bytes. This
1510 typically occurs at the end of a copy. dd can do partial writes. ddpt
1511 does partial writes to regular files and fifos (including stdout). How‐
1512 ever ddpt ignores partial writes when OFILE is a block device or a pt
1513 device. When ddpt ignores a partial write, it sends a warning to the
1514 console (stderr).
1515 At the end of the copy two lines are reported to the console:
1517 <in_full>+<in_partial> records in
1518 <out_full>+<out_partial> records out
1519 The "records in" line is the number of full input blocks (each of IBS
1521 bytes) that have been read plus the number of partial blocks ( usually
1522 less than IBS bytes) that have been read. Following the lead of dd when
1523 'iflag=coe' is active a block that cannot be read (and has zeros sub‐
1524 stituted for its output) is regarded as a partial read. The "records
1525 out" line is the number of full output blocks (each of OBS bytes) that
1526 have been written plus the number of partial blocks (usually less than
1527 OBS bytes) that have been written.
1528 Block devices (e.g. /dev/sda and /dev/hda) can be given for IFILE. If
1530 neither 'iflag=direct' nor 'iflag=pt' is given then normal block IO
1531 involving buffering and caching is performed. If 'iflag=direct' is
1532 given then the buffering and caching is bypassed (this is applicable to
1533 both SCSI devices and ATA disks). When 'iflag=pt' is given SCSI com‐
1534 mands are sent to the device which bypasses most of the actions per‐
1535 formed by the block layer. The same applies for block devices given
1536 for OFILE.
1537 All informative, warning and error reports are sent to stderr so that
1539 dd's output file can be stdout and remain unpolluted. If no options are
1540 given, then no copying (nor reading) takes place and a brief message is
1541 sent to stderr inviting the user to invoke ddpt again but with '--help'
1542 option to get the usage message.
1543 Disk partition information can often be found with fdisk(8) [the "-ul"
1545 argument is useful in this respect]. Also parted(8) can be used like
1546 this: 'parted /dev/sda unit s print' .
1547 For pt devices this utility issues SCSI READ and WRITE (SBC) commands
1549 which are appropriate for disks and reading from CD/DVD/BD drives.
1550 Those commands are not formatted correctly for tape drives so ddpt can‐
1551 not be used on tape drives via a pt device. If the largest block
1552 address of the requested transfer exceeds a 32 bit block number (i.e
1553 0xffffffff) then a warning is issued and the pt device is accessed via
1554 SCSI READ(16) and WRITE(16) commands.
1555 The attributes of a block device (e.g. partitions) are ignored when the
1557 pt flag is used. Hence the whole device is read (rather than just the
1558 second partition) by this invocation:
1559 ddpt if=/dev/sdb2 iflag=pt of=t bs=512
1561 Assuming /dev/sdb and /dev/sg2 refer to the same device, then after the
1563 following two invocations, the contents of the files "t", "tt" and
1564 "ttt" should be same:
1565 ddpt if=/dev/sdb of=tt bs=512
1567 ddpt if=/dev/sg2 of=ttt bs=512
1569 The SCSI READ(32) and WRITE(32) commands are restricted to media that
1571 is formatted with protection type 2. This is a T10 restriction.
1572
1574 The signal handling has been borrowed from GNU's dd: SIGINT, SIGQUIT
1575 and SIGPIPE report the number of remaining blocks to be transferred and
1576 the records in + out counts; then they have their default action.
1577 SIGUSR1 (or SIGINFO) causes the same information to be output and the
1578 copy continues. All output caused by signals is sent to stderr.
1579 Like GNU's dd, ddpt respects the signal disposition of "ignored"
1581 (SIG_IGN) set by the shell, script or other program that invokes ddpt.
1582 So in that case it will ignore such signals. Further dd ignores SIGUSR1
1583 if the environment variable POSIXLY_CORRECT is set because POSIX
1584 defines dd will only act on SIGINFO (and Linux has no such signal);
1585 ddpt ignores the POSIXLY_CORRECT environment variable. As recommended
1586 by Susv3, ddpt does not expect the signal (blocking) mask to be block‐
1587 ing SIGUSR1 (SIGINFO), SIGINT or SIGPIPE on entry.
1588 Unix system calls that do IO can be interrupted by signal processing,
1590 typically returning an EINTR error number. The dd utility (and many
1591 other Unix utilities) restart the IO operation that was interrupted.
1592 While this will work most of the time for disk IO it is problematic for
1593 tape drives because the implicit position pointer on the tape may have
1594 moved. So the default (i.e. "intio=0") in this utility is to mask
1595 those signals during IO operations and only check them prior to start‐
1596 ing an IO operation. Most low level IO (e.g. using SCSI command to
1597 write to a disk) will timeout if there is a low level error. However
1598 NFS (the Network File System) will potentially wait for a long time
1599 (e.g. expecting a network problem will soon be fixed) and in this case
1600 using "intio=1" may be best.
1601
1603 The usual way to check the two disks (or part of the disks) are the
1604 same is to move through the segments to be compared, reading from both
1605 and comparing the returned buffers, stopping if there is an in equal‐
1606 ity.
1607 This utility takes a different approach that relies on the OFILE being
1609 a pass through device. That pass-through device needs to support the
1610 SCSI VERIFY command with the BYTCHK field set to 1. Optionally, for the
1611 --prefetch option to improve performance that pass-through device needs
1612 to support the SCSI PRE-FETCH command with its IMMED bit set.
1613 When the --verify option is given, instead of reading both IFILE and
1615 OFILE, only the IFILE is read. Then the result of that read is sent to
1616 the OFILE device as the data-out buffer of a VERIFY(BYTCHK=1) command.
1617 So the comparison is actually done on the OFILE device rather than the
1618 host computer's main memory.
1619 If the --prefetch option is also given, then before the IFILE read, a
1621 PRE-FETCH(OFILE, IMMED) is sent. The IMMED bit will make it return more
1622 or less immediately. The effect of the PRE-FETCH should be to bring the
1623 contents of the data to be used for the OFILE side of the comparison,
1624 into the OFILE device's cache. And that should make the later VER‐
1625 IFY(BYTCHK=1) command faster.
1626
1628 There is support for copies to and from tape drives in Linux. Only the
1629 st driver device names can be used (e.g. /dev/st0 and /dev/nst2). Hence
1630 use of Linux pass-through device names (e.g. /dev/sg2) for tape drives
1631 is not supported. On Debian-based distributions, it is suggested that
1632 the mt-st package is installed as it provides a more fully-featured
1633 version of the "mt" tape control program.
1634 Tape drives can operate in fixed- or variable-length block modes. In
1636 variable-block mode, each write to the tape writes a single block of
1637 that size. In fixed-block mode, each write to the tape must be a multi‐
1638 ple of the previously-selected block size.
1639 The block size/mode can be set with the mt command prior to invoking
1641 ddpt. For example:
1642 # mt -f /dev/nst0 setblk 0
1643 sets variable-block mode, and
1644 # mt -f /dev/nst0 setblk 32768
1645 sets fixed-block mode with block size 32768 bytes.
1646 Note that some tape drives support only fixed-block mode, and possibly
1648 even only one block size. (For example, QIC-150 tapes use a fixed block
1649 size of 512 bytes.) There may also be restrictions on the block size,
1650 e.g. it may have to be even.
1651 When using ddpt to write to tape, if the final read from the input is
1653 less than OBS, it is padded to OBS bytes before writing to tape to
1654 ensure that all blocks of the tape file are the same length. Having a
1655 shorter final block would fail if the drive is in fixed-block mode, and
1656 could create interchange problems. It is common to expect all blocks in
1657 a file on tape to be the same length. However, to tell ddpt to not pad
1658 the final block, use 'oflag=nopad'.
1659 The st tape driver normally writes a filemark when the file (e.g.
1661 /dev/nst0) is closed. To not have the filemark written, use
1662 'oflag=nofm'. One use case for that might be if using ddpt several
1663 times in succession to append more data to the same file on tape. In
1664 that case it is probably desirable to write the filemark at the end of
1665 the sequence. So either omit 'oflag=nofm' on the last ddpt invocation,
1666 or manually write a filemark using mt after ddpt exits:
1667 # mt -f /dev/nst0 weof 1
1668 For reading from an unknown tape where the block size(s) is not known,
1670 read in variable-block mode specifying a large IBS. The st driver
1671 returns a smaller amount of data if the size of the block read is
1672 smaller. Thus a command like:
1673 # ddpt if=/dev/nst0 of=output.bin bs=262144
1674 should read the file from tape regardless of the block size used
1675 (assuming no blocks are larger than 256KB). ddpt's verbose option will
1676 display what the actual block size(s) is.
1677
1679 If the command line invocation of an xcopy does not explicitly (and
1680 unambiguously) indicate whether the XCOPY SCSI command should be sent
1681 to IFILE (i.e. the source) or OFILE (i.e. the destination) then a
1682 check is made for the presence of the XCOPY_TO_SRC and XCOPY_TO_DST
1683 environment variables. If either one exists (but not both) then it
1684 indicates where the SCSI XCOPY command will be sent. By default the
1685 XCOPY command is sent to OFILE.
1686 The ODX write from tokens variant is very complex to implement if the
1688 amount of data held in each ROD is not known. The value should be found
1689 in the "number of bytes represented" field in the ROD Token but that is
1690 not well supported yet by vendors. So for such cases, that number can
1691 be appended as a big endian 8 byte integer following each ROD Token in
1692 the RTF file. The conv=rtf_len will cause that length to be appended.
1693 Specifying that option on each read to tokens and write from tokens
1694 invocation can be a nuisance. Setting the environment variable
1695 ODX_RTF_LEN will cause this utility to act as if the conv=rtf_len
1696 option has been given.
1697 Sometimes the default block size of 512 can be a nuisance. This can be
1699 overridden by the value associated with the DDPT_DEF_BS environment
1700 variable. If the environment variable is not found, the value cannot be
1701 decoded or is zero or less, then the default block size remains at 512
1702 bytes.
1703
1705 To aid scripts that call ddpt, the exit status is set to indicate suc‐
1706 cess (0) or failure (1 or more). Note that some of the lower values
1707 correspond to the SCSI sense key values. The exit status values are:
1708 0 success. Also conveys boolean true for actions that result in
1710 true or false (e.g. sgl equality tests)
1711 1 syntax error. Either illegal command line options, options with
1713 bad arguments or a combination of options that is not permitted.
1714 2 the device reports that it is not ready for the operation
1716 requested. The device may be in the process of becoming ready
1717 (e.g. spinning up but not at speed) so the utility may work
1718 after a wait.
1719 3 the device reports a medium or hardware error (or a blank
1721 check). For example an attempt to read a corrupted block on a
1722 disk will yield this value.
1723 5 the device reports an "illegal request" with an additional sense
1725 code other than "invalid operation code". This is often a sup‐
1726 ported command with a field set requesting an unsupported capa‐
1727 bility.
1728 6 the device reports a "unit attention" condition. This usually
1730 indicates that something unrelated to the requested command has
1731 occurred (e.g. a device reset) potentially before the current
1732 SCSI command was sent. The requested command has not been exe‐
1733 cuted by the device. Note that unit attention conditions are
1734 usually only reported once by a device.
1735 7 the device reports a "data protect" sense key. This implies some
1737 mechanism has blocked writes (or possibly all access to the
1738 media).
1739 9 the device reports an illegal request with an additional sense
1741 code of "invalid operation code" which means that it doesn't
1742 support the requested command.
1743 10 the device reports a "copy aborted". This implies another com‐
1745 mand or device problem has stopped and copy operation. The
1746 EXTENDED COPY family of commands (including WRITE USING TOKEN)
1747 may return this sense key.
1748 11 the device reports an aborted command. In some cases aborted
1750 commands can be retried immediately (e.g. if the transport
1751 aborted the command due to congestion).
1752 14 the DEVICE reports a miscompare sense key. VERIFY and COMPARE
1754 AND WRITE commands may report this.
1755 15 the utility is unable to open, close or use the given IFILE,
1757 OFILE or other file. The given file name could be incorrect or
1758 there may be permission problems. Adding the -v option may give
1759 more information.
1760 20 the device reports it has a check condition but "no sense". It
1762 is unlikely that this value will occur as an exit status.
1763 21 the device reports a "recovered error". The requested command
1765 was successful. Most likely a utility will report a recovered
1766 error to stderr and continue, probably leaving the utility with
1767 an exit status of 0 .
1768 24 the device reports a SCSI status of "reservation conflict". This
1770 means access to the device with the current command has been
1771 blocked because another machine (HBA or SCSI "initiator") holds
1772 a reservation on this device. On modern SCSI systems this is
1773 related to the use of the PERSISTENT RESERVATION family of com‐
1774 mands.
1775 25 the DEVICE reports a SCSI status of "condition met". Currently
1777 only the PRE-FETCH command (see SBC-4) yields this status.
1778 26 the DEVICE reports a SCSI status of "busy". SAM-5 defines this
1780 status as the logical unit is temporarily unable to process a
1781 command. It is recommended to re-issue the command.
1782 27 the DEVICE reports a SCSI status of "task set full".
1784 28 the DEVICE reports a SCSI status of "ACA active". ACA is "auto
1786 contingent allegiance" and is seldom used.
1787 29 the DEVICE reports a SCSI status of "task aborted". SAM-5 says:
1789 "This status shall be returned if a command is aborted by a com‐
1790 mand or task management function on another I_T nexus and the
1791 Control mode page TAS bit is set to one".
1792 31 error involving two or more command line options. Either they
1794 contradict or select an unsupported mode.
1795 32 the is a logic error in the utility. It corresponds to code com‐
1797 ments like "shouldn't/can't get here". Perhaps the author should
1798 be contacted.
1799 33 the command sent to device has timed out. This occurs in Linux
1801 only; in other ports a command timeout will appear as a trans‐
1802 port (or OS) error.
1803 36 no error has occurred. For actions that result in a boolean,
1805 this exit status indicates false.
1806 40 the command sent to a device has received an "aborted command"
1808 sense key with an additional sense code of 0x10. This group is
1809 related to problems with protection information (PI or DIF). For
1810 example this error may occur when reading a block on a drive
1811 that has never been written (or is unmapped) if that drive was
1812 formatted with type 1, 2 or 3 protection.
1813 48 this is an internal message indicating a NVMe status field (SF)
1815 is other than zero after a command has been executed (i.e. some‐
1816 thing went wrong). Work in this area is currently experimental.
1817 49 low level driver reports a response's residual count (i.e. num‐
1819 ber of bytes actually received by HBA is 'requested_bytes -
1820 residual_count') that is too high. So no useful processing can
1821 be done with that response.
1822 50 + <os_error_number>
1824 OS system calls that fail often return a small integer number to
1825 help indicate what the error is. For example in Unix the inabil‐
1826 ity of a system call to allocate memory returns (in 'errno')
1827 ENOMEM which often is associated with the integer 12. So 62
1828 (i.e. '50 + 12') may be returned by a utility in this case.
1829 90 the flock flag has been given on a device and some other process
1831 holds the advisory exclusive lock.
1832 97 the response to a SCSI command failed sanity checks.
1834 98 the device reports it has a check condition but the error
1836 doesn't fit into any of the above categories.
1837 99 any errors that can't be categorized into values 1 to 98 may
1839 yield this value. This includes transport and operating system
1840 errors after the command has been sent to the device.
1841 100 a command received a 'parameter list length error'.
1843 101 a command received 'illegal field in parameter list'. This may
1845 occur with an odx copy if some combination of parameters is
1846 illegal or not supported (e.g. iflag=immed).
1847 105 a command received 'operation in progress'. This may occur with
1849 an odx copy when the given LID is already being used by another
1850 process (e.g. also using odx) on the same machine. Choose
1851 another LID.
1852 110 a command received 'invalid token operation, cause not
1854 reportable'. This may occur with an odx operation when the given
1855 ROD Token is invalid. One reason for that may be the inactivity
1856 timeout has been reached and the copy manager has cancelled the
1857 ROD Token.
1858 110 + <asc_23h_ascq_code>
1860 these status values provide more information than exit status
1861 110. See SPC-5 ASC and ASCQ assignments (currently in Annex
1862 F.2), specifically the entries for asc=23h . For example exit
1863 status 112 corresponds to asc=23h, ascq=2h which implies the odx
1864 copy manager does not support copies between LUs in different
1865 targets. That is optional; an odx copy manager is required to
1866 support copies between LUs (that are block devices) in the same
1867 target.
1868 126 the utility was found but could not be executed. That might
1870 occur if the executable does not have execute permissions.
1871 127 This is the exit status for utility not found. That might occur
1873 when a script calls a utility in this package but the PATH envi‐
1874 ronment variable has not been properly set up, so the script
1875 cannot find the executable.
1876 128 + <signum>
1878 If a signal kills a utility then the exit status is 128 plus the
1879 signal number. For example if a segmentation fault occurs then a
1880 utility is typically killed by SIGSEGV which according to 'man 7
1881 signal' has an associated signal number of 11; so the exit sta‐
1882 tus will be 139 .
1883 255 the utility tried to yield an exit status of 255 or larger. That
1885 should not happen; given here for completeness.
1886
1888 The examples in this page use Linux device names. For suitable device
1889 names in other supported Operating Systems see this web page:
1890 http://sg.danny.cz/sg/device_name.html . The sg3_utils(8) man page in
1891 the sg3_utils package also covers device naming.
1892 ddpt usage looks quite similar to dd:
1894 ddpt if=/dev/sg0 of=t bs=512 count=1MB
1896 This will copy 1 million 512 byte blocks from the device associated
1898 with /dev/sg0 (which should have 512 byte blocks) to a file called t.
1899 Assuming /dev/sda and /dev/sg0 are the same device then the above is
1900 equivalent to:
1901 dd if=/dev/sda iflag=direct of=t bs=512 count=1000000
1903 although dd's speed may improve if bs was larger and count was suitably
1905 reduced. The use of the 'iflag=direct' option bypasses the buffering
1906 and caching that is usually done on a block device.
1907 The dd command's bs argument can be thought of as roughly equivalent to
1909 ddpt's bs*bpt . dd almost assumes buffering on a block device and will
1910 work as long as bs is a multiple of the actual logical block size.
1911 Since ddpt can work at a lower level in some cases the bs argument must
1912 be a disk's actual logical block size. Thus the bpt argument was intro‐
1913 duced to make the copy more efficient. So these two invocations are
1914 roughly equivalent:
1915 dd if=/dev/sda of=t bs=8k count=64
1917 ddpt if=/dev/sda of=t bs=512 bpt=16 count=1k
1918 In both cases the total number of bytes moved is bs*count . And that
1920 will be done by reading 8k (8192 bytes) into a buffer then writing out
1921 that buffer to the file t. The read write sequence continues until the
1922 count is complete or an error occurs.
1923 The 'of2=' option can save time when the input would otherwise need to
1925 be read twice. For example, to copy data and take a md5sum of it with‐
1926 out needing to re-read the data:
1927 mkfifo fif
1929 md5sum fif &
1930 ddpt if=/dev/sg3 iflag=coe of=sg3.img oflag=sparse of2=fif bs=512
1931 This will image /dev/sg3 (e.g. an unmounted disk) and place the con‐
1933 tents in the (sparse) file sg3.img . Without re-reading the data it
1934 will also perform a md5sum calculation on the image.
1935 Now we use sparse writing logic to get some idea of how many blocks on
1937 a disk are full of zeros. After a SCSI FORMAT UNIT command or an ATA
1938 SECURITY ERASE command a disk may be all zeros.
1939 ddpt if=/dev/sdc bs=512 oflag=sparse
1941 Since no "of=" option is given, output goes to /dev/null so nothing is
1943 actually written so the "records out" will be zero. However there will
1944 be a count of "records in" and "bypassed records out". If /dev/sdc is
1945 full of zeros then "records in" and "bypassed records out" will be the
1946 same. Since the "bpt=" option is not given it defaults to "bpt=128,128"
1947 so the copy buffer will be 64 KiB and the sparse check for zeros will
1948 be done with 64 KiB (128 block) granularity.
1949 For examples of the trim and self,trim options see the section above on
1951 TRIM, UNMAP AND WRITE SAME.
1952 Following is an example run on a Windows OS using the '--wscan' option
1954 which shows the available device names (e.g. PD1) and the associated
1955 volume name(s):
1956 ddpt -w
1958 PD0 [C] FUJITSU MHY2160BH 0000
1959 PD1 [DF] WD 2500BEV External 1.05 WD-WXE90
1960 CDROM0 [E] MATSHITA DVD/CDRW UJDA775 CB03
1961 So, for example, volumes D: and F: reside on PhysicalDisk1 (abbreviated
1963 to "PD1") which is manufactured by WD (Western Digital).
1964 Further examples can be found on this web page:
1966 http://sg.danny.cz/sg/ddpt.html . There is a text file containing exam‐
1967 ples called ddpt_examples.txt in the "doc" directory of this package's
1968 distribution tarball. The ddpt_examples.txt file contains some examples
1969 of using job files.
1970
1972 Written by Doug Gilbert
1973
1975 Report bugs to <dgilbert at interlog dot com>.
1976
1978 Copyright © 2008-2020 Douglas Gilbert
1979 This software is distributed under the GPL version 2. There is NO war‐
1980 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
1981 POSE.
1982
1984 This utility has companion/helper utilities ddptctl(8), ddpt_sgl(8)
1985 There is a web page discussing ddpt at http://sg.danny.cz/sg/ddpt.html
1986 The lmbench package contains lmdd which is also interesting. For moving
1988 data to and from tapes see dt which is found at http://www.scsi‐
1989 faq.org/RMiller_Tools/index.html
1990 To change mode parameters that effect a SCSI device's caching and error
1992 recovery see sdparm(sdparm)
1993 To verify the data on the media is readable see: sg_verify(sg3_utils)
1995 To scan and repair disk partitions see TestDisk (testdisk).
1997 Additional references: dd(1), open(2), flock(2),
1999 sg_xcopy,sg_copy_results, sg_dd(sg3_utils)
2000ddpt-0.96 March 2020 DDPT(8)