.TH DDPT "8" "April 2021" "ddpt\-0.97" DDPT
.SH NAME
ddpt \- copies data between files and storage devices. Support for
devices that understand the SCSI command set.
.SH SYNOPSIS
.B ddpt
[\fIbpt=BPT[,OBPC]\fR] [\fIbs=BS\fR] [\fIcdbsz=\fRIO_CDBSZ] [\fIcdl=CDL\fR]
[\fIcoe=\fR{0|1}] [\fIcoe_limit=CL\fR] [\fIconv=CONVS\fR] [\fIcount=COUNT\fR]
[\fIddpt=VERS\fR] [\fIdelay=MS[,W_MS]\fR] [\fIibs=IBS\fR]
[\fIid_usage=LIU\fR] \fIif=IFILE\fR [\fIiflag=FLAGS\fR] [\fIintio=\fR{0|1}]
[\fIiseek=SKIP\fR] [\fIito=ITO\fR] [\fIlist_id=LID\fR] [\fIobs=OBS\fR]
[\fIof=OFILE\fR] [\fIof2=OFILE2\fR] [\fIoflag=FLAGS\fR] [\fIoseek=SEEK\fR]
[\fIprio=PRIO\fR] [\fIprotect=RDP[,WRP]\fR] [\fIretries=RETR\fR]
[\fIrtf=RTF\fR] [\fIrtype=RTYPE\fR] [\fIseek=SEEK\fR] [\fIskip=SKIP\fR]
[\fIstatus=STAT\fR] [\fIto=TO\fR] [\fIverbose=VERB\fR] [\fI\-\-dry\-run\fR]
[\fI\-\-flexible\fR] [\fI\-\-help\fR] [\fI\-\-job=JF\fR] [\fI\-\-odx\fR]
[\fI\-\-prefetch\fR] [\fI\-\-progress\fR] [\fI\-\-quiet\fR]
[\fI\-\-verbose\fR] [\fI\-\-verify\fR] [\fI\-\-version\fR] [\fI\-\-wscan\fR]
[\fI\-\-xcopy\fR]
[\fIddpt\fR] [\fIJF\fR]
.PP
For comparison here is the synopsis for GNU's dd command:
.PP
.B dd
[\fIbs=BS\fR] [\fIcbs=CBS\fR] [\fIconv=CONVS\fR] [\fIcount=COUNT\fR]
[\fIibs=IBS\fR] [\fIif=IFILE\fR] [\fIiflag=FLAGS\fR] [\fIobs=OBS\fR]
[\fIof=OFILE\fR] [\fIoflag=FLAGS\fR] [\fIseek=SEEK\fR] [\fIskip=SKIP\fR]
[\fIstatus=STAT\fR] [\fI\-\-help\fR] [\fI\-\-version\fR]
.SH DESCRIPTION
.\" Add any additional description here
.PP
Copies data between files or simply reads data from a file. Alternatively
if the \fI\-\-verify\fR option is given, the \fIIFILE\fR and \fIOFILE\fR
contents are compared, stopping if an inequality is found. This utility is
specialized for "files" that are storage devices, especially those that can
use the SCSI command sets (e.g. SATA and SAS disks). It can issue SCSI
commands in pass\-through ("pt") mode. Similar syntax and semantics to the
Unix
.B dd(1)
command.
.PP
For comparison, the SYNOPSIS section above shows both the
.B ddpt
command line operands and options followed by GNU's
.B dd(1)
command line operands and options. Broadly speaking ddpt can be considered
a super\-set of dd. See the section on DD DIFFERENCES for significant
differences between ddpt and dd.
.PP
This utility either does direct copies, based on read\-write sequences,
or offloaded copies. In an offloaded copy the data being copied does not
necessarily pass through the memory of the the machine originating the copy
operation; this can save a significant amount of time and lessen CPU usage.
.PP
When doing a direct copy, this utility breaks the copy into segments since
computer RAM is typically a scarce resource. First it reads in \fIBPT*IBS\fR
bytes from \fIIFILE\fR (or less if near the end of the copy) into a copy
buffer. In the absence of the various operand and flags that bypass
the write operation, the copy buffer is then written out to \fIOFILE\fR.
The copy process continues working its way along \fIIFILE\fR and \fIOFILE\fR
until either \fICOUNT\fR is exhausted, an end of file is detected, or an
error occurs. If \fIIBS\fR and \fIOBS\fR are different, ddpt restricts the
value of \fIOBS\fR such that the copy buffer is an integral number of output
blocks (i.e. (((\fIIBS * BPT\fR) % \fIOBS\fR) == 0) ). In the following
descriptions, "segment" refers to all or part of a copy buffer.
.PP
The term "pt device" is used for a pass\-through device to which SCSI
commands like READ(10), WRITE(10) or POPULATE TOKEN may be sent. A pt device
may only be able to process SCSI commands in which case the "pt" flag is
assumed. The ability to recognize such a pt only device may vary depending
on the operating system (e.g. in Linux /dev/sg2 and /dev/bsg/3:0:1:0 are
recognized). However if a device can process either normal UNIX read()/
write() calls or pass\-through SCSI commands then the default is to use
UNIX read()/write() calls. That default can be overridden by using the "pt"
flag (e.g. "if=/dev/sdc iflag=pt"). When pt access is specified any
partition information is
.B ignored.
So "if=/dev/sdc2 iflag=pt skip=3" will start at logical block address 3
of '/dev/sdc'. As a protection measure ddpt will only accept that if the
force flag is also given (i.e. 'iflag=pt,force').
.PP
This utility supports two types of offloaded copies. Both are based on the
EXTENDED COPY (XCOPY or xcopy) family of SCSI commands. The first uses the
XCOPY(LID1) command to do a disk to disk copy. LID1 stands for List
IDentifier length of 1 byte and the commands are described in the SPC\-4 and
earlier SPC\-3 and SPC\-2 standards. The SPC\-4 standard (ANSI INCITS
513-2015) added the XCOPY(LID4) sub\-family of copy offloaded commands. Now
SPC\-5 drafts have dropped the LID1 variants and removed the LID4 suffix on
the remaining XCOPY family of commands. To differentiate, this man page will
continue to use the LID1 and LID4 suffixes. There is a subset of
XCOPY(LID4), specialized for offloaded disk to disk copies, that is known by
the market name: ODX. In the descriptions below "xcopy" refers to copies
based on XCOPY(LID1) while "odx" refers to either full or partial ODX copies.
See the XCOPY and ODX sections below for more information.
.PP
The syntax of the dd command is somewhat unique in Unix and ddpt follows in
a similar fashion. Operands (i.e. those with the <name>=<something>
structure) are shown in OPERANDS section. The more familiar Unix
options (i.e. those starting with one or two hyphens) are shown in the
OPTIONS section. Then there are a few arguments which are command line
entities that are neither operands nor options, see the ARGUMENTS section.
.SH OPERANDS
The operands are listed alphabetically (by <name>) below. The <name> is
the part that is to the left of the equal sign. All <names> start with
a lower case alphabetical character.
.TP
\fBbpt\fR=\fIBPT[,OBPC]\fR
where \fIBPT\fR is Blocks Per Transfer. A direct copy is made up of multiple
transfers, each first reading \fIBPT\fR input blocks (i.e. \fIBPT * IBS\fR
bytes) from \fIIFILE\fR into the copy buffer and then from that copy buffer
writing \fI(BPT * IBS) / OBS\fR output blocks to \fIOFILE\fR. This continues
until the copy is finished, with the last transfer being potentially
shorter. The default \fIBPT\fR value varies depending on \fIIBS\fR. When
\fIIBS\fR < 8, \fIBPT\fR is 8192; when \fIIBS\fR < 64, \fIBPT\fR is 1024;
when \fIIBS\fR < 1024, \fIBPT\fR is 128; when \fIIBS\fR < 8192, \fIBPT\fR
is 16; when \fIIBS\fR < 32768, \fIBPT\fR is 4; else \fIBPT\fR defaults
to 1. If \fIBPT\fR is given as 0 it is treated as the default value.
For "bs=512", \fIBPT\fR defaults to 128 so that 64 KiB (or less) is read
from \fIIFILE\fR into the copy buffer. This operand is treated differently
in ODX and is typically only needed for testing; see ODX section.
.br
The optional \fIOBPC\fR (Output Blocks Per Check) argument controls the
granularity of sparse writes, write sparing and trim checks. The default
granularity is the size of the copy buffer (i.e. \fIBPT * IBS\fR bytes). That
can be reduced by specifying \fIOBPC\fR. The finest granularity is when
\fIOBPC\fR is 1 which implies the unit of each check is \fIOBS\fR bytes.
When \fIOBPC\fR is 0, or not given, the default granularity is used. Large
\fIOBPC\fR values are rounded down so that \fIOBPC*OBS\fR does not exceed
the size of the copy buffer.
.br
odx: may be used to limit the data represented by each ROD. Mainly for
testing.
.br
If \fIBPT\fR is too large on Linux, the obscure "Invalid argument" error
value (EINVAL) is returned.
.TP
\fBbs\fR=\fIBS\fR
where \fIBS\fR is the \fIIFILE\fR and \fIOFILE\fR block size in bytes.
Conflicts with either the "ibs=" or "obs=" operands. The value of \fIBS\fR
is placed in \fIIBS\fR and \fIOBS\fR.
If \fIIFILE\fR or \fIOFILE\fR is a "pt" device then \fIBS\fR
.B must
be the logical block size of the device. See the DD DIFFERENCES section
below. The default is 512 bytes unless overridden by the DDPT_DEF_BS
environment variable. Note that newer disks use 4096 byte blocks
with perhaps larger block sizes coming in the future. CD/DVD/BD media use
a logical block size of 2048 bytes.
.TP
\fBcdbsz\fR=\fIIO_CDBSZ\fR
size of SCSI READ and/or WRITE (VERIFY) command descriptor blocks (cdb) in
bytes. \fIIO_CDBSZ\fR may be one number or two numbers separated by a comma.
The acceptable numbers are 0, 6, 10, 12, 16 or 32. The default 0 will usually
be set to 10 internally unless the (first and last) LBAs cannot fit in 32
bits in which case the 16 byte variant of each command is used. If one number
is given it applies both to the \fIIFILE\fR and \fOIFILE\fR. If two numbers
are given, the first applies to the \fIIFILE\fR (i.e. the READ command) and
the second applies to the \fIOFILE\fR.
.br
If \fIIFILE\fR or \fIOFILE\fR is not a SCSI pass\-through device then the
corresponding \fIIO_CDBSZ\fR value is ignored.
.TP
\fBcdl\fR=\fICDL\fR
allows setting of command duration limits. \fICDL\fR is either a single value
or two values separated by a comma. If one value is given, it applies to both
\fIIFILE\fR and \fIOFILE\fR (if they are pass\-through devices). If two
values are given, the first applies to \fIIFILE\fR while the second applies
to \fIOFILE\fR. The value may be from 0 to 7 where 0 is the default and means
there are no command duration limits. Command duration limits are only
supported by 16 and 32 byte READ and WRITE commands (and the WRITE SCATTERED
command which is not used by this utility). If the cdbsz operand is not given
and would have a value less than 16, then if \fICDL\fR is greater than 0, the
cdbsz is increased to 16.
.br
Command duration limits can be accesses and changed in the Command duration
limit A and B mode pages, plus the Command duration limit T2A and T2B mode
pages. The sdparm utility may be used to access and change these mode pages.
.TP
\fBcoe\fR={0|1}
set to 1 for continue on error. Applies to errors on input and output for pt
devices but only on input from block devices or regular files. Errors on
other files will stop ddpt. Default is 0 which implies stop on any error. See
the 'coe' flag for more information.
.TP
\fBcoe_limit\fR=\fICL\fR
where \fICL\fR is the maximum number of consecutive bad blocks stepped over
due to "coe=1" on reads before the copy terminates. The default is 0 which is
implies no limit. This operand is meant to stop the copy soon after
unrecorded media is detected while still offering "continue on error"
capability for infrequent, randomly distributed errors.
.TP
\fBconv\fR=\fICONVS\fR
see the CONVERSIONS section below.
.TP
\fBcount\fR=\fICOUNT\fR
copy \fICOUNT\fR input blocks from \fIIFILE\fR to \fIOFILE\fR. If this
operand is not given (or \fICOUNT\fR is '\-1') then the \fICOUNT\fR may be
deduced from either \fIIFILE\fR or \fIOFILE\fR. See the COUNT section below.
.br
If a 'hard' gather list is given to \fIskip=SKIP\fR or a 'hard' scatter list
is given to \fIseek=SEEK\fR then typically \fIcount=COUNT\fR should not be
supplied. This is because a 'hard' scatter gather list implies a transfer
count. If both are given then ddpt will exit if they are unequal, the force
flag can be used to override this action. See the SCATTER GATHER LISTS
section below for a discussion of 'hard' and 'soft' scatter gather lists.
.TP
\fBddpt\fR=\fIVERS\fR
causes a syntax error while parsing the command line if the current version
of the ddpt utility is less than \fIVERS\fR. \fIVERS\fR can take one of two
forms: starting with a digit in which case is should have the
form "<major_vn>.<minor_vn>" or starting with the letter "r" followed
by "<svn.rev>". The latter case is the subversion revision number. Both
numbers can be found in the output of the \fI\-\-version\fR option. The
purpose of this operand is to be placed in job files so that they are not
run on older versions of this utility
.TP
\fBdelay\fR=\fIMS[,W_MS]\fR
after each segment is copied (typically every (\fIIBS\fR * \fIBPT\fR) bytes)
a delay (sleep) of \fIMS\fR milliseconds is performed. The default value for
\fIMS\fR is 0 which implies no delay. If \fIW_MS\fR is given and greater than
0 (its default value) then there is an additional delay of \fIW_MS\fR
milliseconds associated with each actual write operation that is performed.
If \fIMS\fR is greater than 0 then there is not a delay before the first copy
segment (or after the last); if \fIW_MS\fR is greater than 0 then there is
not a delay before the first write segment. These delays can be used for a
bandwidth limiting.
.br
odx: the \fIMS\fR delay is implemented in the same fashion after each ROD is
copied, apart from the last. If \fIW_MS\fR is greater than 0 then that delay
occurs before each WUT command, apart from the first.
.TP
\fBibs\fR=\fIIBS\fR
where \fIIBS\fR is the \fIIFILE\fR block size in bytes. The default value
is \fIBS\fR or its default (512). Conflicts the "bs=" operand (i.e. giving
both "bs=512 ibs=512" is considered a syntax error).
.TP
\fBid_usage\fR=\fILIU\fR
xcopy: SCSI EXTENDED COPY parameter list LIST ID USAGE field is set to
\fILIU\fR. The default value is 0 or 2 . \fILIU\fR can be a number between
0 and 3 inclusive or a string. The strings can be either: 'hold' for
0, 'discard' for 2 or 'disable' for 3.
.TP
\fBif\fR=\fIIFILE\fR
read from \fIIFILE\fR. If \fIIFILE\fR is '\-' then stdin is read. Starts
reading at the beginning of \fIIFILE\fR unless \fISKIP\fR is given.
.br
This operand must be given (apart from one odx case and when \fIiflag=00\fR
or \fIiflag=ff\fR is given).
.br
odx: the \fIrtf=RTF\fR operand may replace the \fIif=IFILE\fR operand as
input. See the ODX section.
.TP
\fBiflag\fR=\fIFLAGS\fR
where \fIFLAGS\fR is a comma separated list of one or more flags outlined
in the FLAGS section below.  These flags are associated with \fIIFILE\fR and
are mostly ignored when \fIIFILE\fR is stdin.
.TP
\fBintio\fR={0|1}
set to 1 for allow signals (SIGINT, SIGPIPE and SIGUSR1 (or SIGINFO)) to be
received during IO from \fIIFILE\fR or IO to \fIOFILE\fR or \fIOFILE2\fR.
Default is 0 which causes these signals to be masked during IO operations
with a check for signals prior each IO. As long as IO operations don't lock
up (e.g. SCSI READ and WRITE commands) the default is the safer option. Even
if IO operations do lock up it is best to let the kernel take care of that.
.TP
\fBiseek\fR=\fISKIP\fR
in its simplest form, \fISKIP\fR is a single number: start reading after
\fISKIP\fR blocks (each of \fIIBS\fR bytes) from the start of \fIIFILE\fR.
Default is block 0 (i.e. start of file). This operand is a synonym for
\fIskip=SKIP\fR, see its description.
.TP
\fBito\fR=\fIITO\fR
odx: \fIITO\fR is the inactivity timeout whose units are seconds. The default
value is 0 which means the copy manager will take the default inactivity
timeout value from the Block Device ROD Token Limits descriptor in the
Third Party Copy VPD page. \fIITO\fR is ignored if it it exceeds the maximum
inactivity timeout value in the same descriptor (unless the force flag is
given).
.TP
\fBlist_id\fR=\fILID\fR
\fILID\fR is the xcopy LIST IDENTIFIER field or the STR_ID field for the
WRITE STREAM command. Fo xcopy it is used to associate an originating xcopy
command with follow\-up commands such as RECEIVE ROD TOKEN INFORMATION. If
given, the \fILID\fR should not clash with any other xcopy \fILID\fR
currently in use on this I_T nexus.
.br
xcopy: \fILID\fR is a 1 byte (8 bit) value whose default value is 1 or,
if id_usage=disable, 0 . \fILID\fR must not exceed 255.
.br
odx: \fILID\fR is a 4 byte (32 bit) value whose default value is 257 (i.e.
0x101) and, if a second default is needed, 258 (0x102) is used. If a
clash is detected on the default list identifier value then the next higher
value is tried (stopping after 10 attempts).
.br
oflag=wstream: \fILID\fR is a 2 byte (16 bit) value whose default value is
0. It is the Stream Identifier (STR_ID field) for the WRITE STREAM(16)
command. Valid Stream identifiers are 0x1 to 0xffff (65535) inclusive, so
the default value of 0 is invalid.
.TP
\fBobs\fR=\fIOBS\fR
where \fIOBS\fR is the \fIOFILE\fR block size in bytes. The default value
is \fIBS\fR or its default (512). Conflicts the "bs=" operand (e.g. giving
both "bs=512 obs=512" is considered a syntax error).
If \fIOBS\fR is given then it has the following restriction: the integer
expression (((\fIIBS\fR * \fIBPT\fR) % \fIOBS\fR) == 0) must be true.
Stated another way: the copy buffer size must be an integral multiple of
\fIOBS\fR. If \fIof2=OFILE2\fR is given then \fIOBS\fR is its block size
as well.
.TP
\fBof\fR=\fIOFILE\fR
write to \fIOFILE\fR. The default value is /dev/null . If \fIOFILE\fR is '\-'
then writes to stdout. If \fIOFILE\fR is /dev/null then no actual writes are
performed. If \fIOFILE\fR is '.' (period) then it is treated the same way as
/dev/null . If \fIOFILE\fR exists then it is _not_ truncated
unless "oflag=trunc" is given. See section on DD DIFFERENCES.
.br
odx: if this operand (\fIof=OFILE\fR) is not given and the \fIrtf=RTF\fR
operand is given then the \fIRTF\fR file may be thought of as receiving the
output in the form of one or more ROD Tokens. See the ODX section.
.TP
\fBof2\fR=\fIOFILE2\fR
write output to \fIOFILE2\fR. The default action is not to do this additional
write (i.e. when this operand is not given). \fIOFILE2\fR is assumed to be
a regular file or a fifo (i.e. a named pipe). \fIOFILE2\fR is opened for
writing and is created if necessary. If \fIOFILE2\fR is a fifo (named pipe)
then some other command should be consuming that data (e.g. 'md5sum OFILE2'),
otherwise this utility will block. The write to \fIOFILE2\fR occurs before
the write to \fIOFILE\fR and prior to sparse writing and write sparing
logic. So everything read is written to \fIOFILE2\fR.
.br
\fIOFILE2\fR is not truncated before writing. Assuming that the \fIOFILE2\fR
length is shorter than what is written (or it is created) then its contents
should be the concatenation of all segments (each of ibs*bpt bytes long,
with the last segment being possibly shorter). The gather list given to
\fIskip=SKIP\fR effects what is read into each segment so it indirectly
effects what is written to \fIOFILE2\fR. However the scatter list given to
\fIseek=SEEK\fR has no effect on what is written to \fIOFILE2\fR.
.TP
\fBoflag\fR=\fIFLAGS\fR
where \fIFLAGS\fR is a comma separated list of one or more flags outlined
in the FLAGS section. These flags are associated with \fIOFILE\fR and are
ignored when \fIOFILE\fR is /dev/null, '.' (period), or stdout.
.TP
\fBoseek\fR=\fISEEK\fR
start writing \fISEEK\fR blocks (each of \fIOBS\fR bytes) from the start of
\fIOFILE\fR. Default is block 0 (i.e. start of file). This operand is a
synonym for \fIseek=SEEK\fR, see its description.
.TP
\fBprio\fR=\fIPRIO\fR
xcopy: SCSI EXTENDED COPY parameter list PRIORITY field is set to \fIPRIO\fR.
The default value is 1 .
.TP
\fBprotect\fR=\fIRDP[,WRP]\fR
where \fIRDP\fR is the RDPROTECT field in SCSI READ commands and \fIWRP\fR
is the WRPROTECT field in SCSI WRITE commands. The default value for both
is 0 which implies no additional protection information will be transferred.
Both \fIRDP\fR and \fIWRP\fR can be from 0 to 7. If \fIRDP\fR is greater
than 0 then \fIIFILE\fR must be a pt device. If \fIWRP\fR is greater than 0
then \fIOFILE\fR must be a pt device.
.br
When copying data plus protection information from one disk to another
then 'protect=3,3' will give the least number of problems as that combination
then of PI checking on both the read and write side. See the PROTECTIO
INFORMATION section below.
.TP
\fBretries\fR=\fIRETR\fR
sometimes retries at the host are useful, for example when there is a
transport error. When \fIRETR\fR is greater than zero then SCSI READs and
WRITEs are retried on error, \fIRETR\fR times. Default value is zero.
Only applies to errors on pt devices.
.TP
\fBrtf\fR=\fIRTF\fR
odx: where \fIRTF\fR is a filename. One or more ROD tokens are written to
\fIRTF\fR during a read to tokens variant or a full copy variant. One or
more ROD tokens are read from \fIRTF\fR during a write from token variant.
This operand is not required on a full copy variant. ROD Tokens are 512
bytes long and an extra 8 byte (big\-endian) integer containing the 'number
of bytes represented' is placed after each ROD Token if rtf_len is given.
.TP
\fBrtype\fR=\fIRTYPE\fR
odx: where \fIRTYPE\fR is the ROD Type. The default value (0) indicates that
the copy manager (in the source) decides. \fIRTYPE\fR can be a decimal number,
a hex number (prefixed by 0x or with a "h" appended) or one
of "pit\-def", "pit\-vuln", "pit\-pers", "pit\-cow", "pit\-any" or "zero".
The final truncated word can be spelt out (e.g. "pit\-vulnerable").
The "pit\-" prefix is a shortening of "point in time" copy. The "zero"
causes a special Block device zero Token to be created.
.TP
\fBseek\fR=\fISEEK\fR
start writing \fISEEK\fR blocks (each of \fIOBS\fR bytes) from the start of
\fIOFILE\fR. Default is block 0 (i.e. start of file). The \fISEEK\fR value
may exceed the number of \fIOBS\fR\-sized blocks in \fIOFILE\fR.
.br
\fISEEK\fR can be a scatter (gather) list: see the  SCATTER GATHER LISTS
section below.
.TP
\fBskip\fR=\fISKIP\fR
start reading \fISKIP\fR blocks (each of \fIIBS\fR bytes) from the start of
\fIIFILE\fR. Default is block 0 (i.e. start of file). The \fISKIP\fR value
must be less than the number of \fIIBS\fR\-sized blocks in \fIIFILE\fR.
.br
\fISKIP\fR can be a (scatter) gather list: see the SCATTER GATHER LISTS
section below.
.TP
\fBstatus\fR=\fISTAT\fR
the \fISTAT\fR value of 'noxfer' suppresses the throughput speed and the
copy time reporting at the end of the copy. A \fISTAT\fR value of 'none'
additionally suppresses the records in and out reporting after the copy.
So 'status=none' makes ddpt act like a traditional Unix command in which "no
news is good news".  The default action of ddpt is to show the throughput (in
megabytes per second) and the time taken to do the copy after the "records
in" and "records out" lines at the end of the copy. A \fISTAT\fR value
of 'sgl' together with '\-vv' option will print internally generated scatter
gather lists before the copy begins. When the '\-vv' options is given alone
then internal scatter lists headers are printed, but not individual elements.
In most cases these scatter gather lists will be the same lists given to the
\fIseek=SEEK\fR and \fIskip=SKIP\fR operands.  As a convenience the
value 'null' is accepted for \fISTAT\fR and does nothing.
.br
A \fISTAT\fR value of 'progress' prints a progress report (to stderr) every
two minutes. If 'progress' is used twice, either by repeating
the 'status=progress' operand or by entering 'status=progress,progress',
then a progress report is printed every minute. If it is used thrice, the
a progress report is printed every 30 seconds. Note that care is taken not
to flood the OS with calls to check the time which would slow down the copy
process. The amount of data output by the progress reports can modified at
runtime (e.g. during a long copy). If the verbose flag is 0 or 1 (but not
higher and not if the \fI\-\-quiet\fR option is given) then sending a
SIG_USR1 (or SIGINFO in FreeBSD) signal to the running ddpt process will
toggle the verbose flag between 0 and 1. Note there is now a shorter
form, the command line option: \fI\-\-progress\fR or simply '\-p'.
.br
Note that GNU's dd supports 'noxfer', 'none' and 'progress' with similar
semantics.
.TP
\fBto\fR=\fITO\fR
odx, xcopy: where \fITO\fR is am xcopy originating command timeout in seconds.
The default value is 0 which is converted internally to 600 seconds (10
minutes). Best to set this timeout value well above the expected copy time.
In a odx full copy this timeout is applied to both the POPULATE TOKEN
and WRITE USING TOKEN commands.
.TP
\fBverbose\fR=\fIVERB\fR
as \fIVERB\fR increases so does the amount of debug reporting sent to stderr.
Default value is zero which yields the minimum amount of debug reporting.
A value of 1 reports extra information that is not repetitive. A value
2 reports cdbs and responses for SCSI commands that are not repetitive
(i.e. other that READ and WRITE). Error processing is not considered
repetitive. Values of 3 and 4 yield reporting for all SCSI commands, plus
Unix read() and write() calls, so there can be a lot of output.
.br
If \fIVERB\fR is "\-1" then reporting that would have been sent to stderr
is redirected to /dev/null essentially throwing it away. It has the same
action as the \fI\-\-quiet\fR option.
.br
In some cases the position of \fIverbose=VERB\fR (or \fI\-\-verbose\fR)
on the command line is significant. For example to debug (or at least
list out) a scatter gather list given to \fIskip=SKIP\fR or
\fIseek=SEEK\fR the \fIverbose=VERB\fR operand (or \fI\-\-verbose\fR)
should appear before skip and/or seek.
.SH OPTIONS
Options are listed in alphabetical order, sorted by their long name.
.TP
\fB\-d\fR, \fB\-\-dry\-run\fR
does all the operand and option processing, opens given file and devices but
bypasses the copy stage. For complex command line invocations or for testing
invocations to be placed in script files, this option may be useful to check
for syntax and related errors.
.br
When used once the logic bypasses the copy just before it would normally
start copying. When used twice (or more) it goes deeper into the copy to the
IO call level before bypassing the calls. To see (on stderr) information
for each IO this option combination may be useful: '\-ddvv'.
.TP
\fB\-f\fR, \fB\-\-flexible\fR
this option currently only effects the parsing of sgl_s in files that are in
hexadecimal plus they have a leading line with 'HEX' in them. Without this
option any such line must be invoked with 'H@' before the filename; in other
words the 'H' in the invocation needs to match the HEX in the file. With
this option a sgl in a file can be invoked with '@' and if a line with HEX
is parsed before any LBA,NUM pairs then it switches to hexadecimal mode; so
all the parsed LBA,NUM pairs are assumed to be in hexadecimal.
.TP
\fB\-h\fR, \fB\-\-help\fR
reports usage message then exits.
.TP
\fB\-\-job\fR=\fIJF\fR
where \fIJF\fR is a file name. That file can contain operands and options
listed in this and the previous sections. See the JOB FILES section below.
.TP
\fB\-o\fR, \fB\-\-odx\fR
indicates to this utility that one of the four odx variants is requested.
See ODX section.
.TP
\fB\-P\fR, \fB\-\-prefetch\fR
this option is only active when the \fI\-\-verify\fR option is also given.
It causes the SCSI PRE\-FETCH(OFILE, IMMED) command to be sent at the start
of each copy segment. See the VERIFY section below.
.TP
\fB\-p\fR, \fB\-\-progress\fR
this option has the same effect as status=progress but is shorter to type
and easier to remember. When given once, the default reporting period is
two minutes, if given twice (e.g. '\-pp') that period is shortened to
one minute.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
redirects the messages (sent to stderr) to /dev/null which is essentially
throwing them away. That redirect takes place after the command line
operands and options are parsed and associated sanity checks performed.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
equivalent of \fIverbose=1\fR. If \fI\-\-verbose\fR appears twice then
that is equivalent to \fIverbose=2\fR. Also \fI\-vv\fR is equivalent to
\fIverbose=2\fR.
.TP
\fB\-X\fR, \fB\-\-verify\fR
rather than copy, a comparison is done between \fIIFILE\fR and \fIOFILE\fR.
The compare continues until an inequality is found at which point the
operation stops. This is only available if \fIOFILE\fR is a pass\-through
device that implements VERIFY(10 or 16) with BYTCHK set to 1. See the
VERIFY section below.
.TP
\fB\-V\fR, \fB\-\-version\fR
reports version number information then exits.
.TP
\fB\-w\fR, \fB\-\-wscan\fR
this option is available in Windows only. It lists storage device names
and the corresponding volumes, if any. When used twice it adds the "bus
type" of the closest transport (e.g. a SATA disk in a USB connected
enclosure has bus type USB). When used three times a SCSI adapter scan
is added. When used four times only a SCSI adapter scan is shown.
See EXAMPLES section below and the README.win32 file.
.TP
\fB\-x\fR, \fB\-\-xcopy\fR
this option will attempt to call the SCSI EXTENDED COPY(LID1) command. In
the absence of another indication the xcopy command will be sent to the
destination (i.e. \fIOFILE\fR). See the section on ENVIRONMENT VARIABLES
below.
.SH ARGUMENTS
Arguments do not start with hyphen nor contain a "=".
.TP
\fBddpt\fR
this string is just a marker. It must not appear in the command line and
it must appear in the contents of a job file that isn't part of a
comment (i.e. following a "#" on a line). A syntax error is generated (and
no copy occurs) if these rules are violated.
.TP
\fBJF\fR
a command line element that does not contain a '=' (i.e. a ddpt operand)
and does not start with '\-', apart from the string "ddpt" is treated as a
job file (i.e. \fIJF\fR). See the JOB FILES section below.
.SH CONVERSIONS
One or more conversions can be given to the "conv=" option. If more than
one is given, they should be comma separated. ddpt does not perform the
traditional dd conversions (e.g. ASCII to EBCDIC). Recently added
conversions inherited from GNU's dd overlap somewhat with the some of ddpt
flags.
.TP
fdatasync
equivalent to "oflag=fdatasync". Flushes data associated with the
\fIOFILE\fR to storage at the end of the copy. This conversion is
for compatibility with GNU's dd.
.TP
fsync
equivalent to "oflag=fsync". Flushes data and meta\-data associated
with the \fIOFILE\fR to storage at the end of the copy. This conversion
.TP
no_del_tkn
equivalent to "oflag=no_del_tkn".
.TP
nocreat
\fIOFILE\fR will not be created if it doesn't exist. The default action
if \fIOFILE\fR does not exist is to create a regular file (then write
into it). The default action can be surprising if writing to a device
node in /dev and due to some external action (e.g. a USB key being
removed) that device node name disappears.
.TP
noerror
this conversion is very close to "iflag=coe" and is treated as such. See
the "coe" flag. Note that an error on a block device or regular file
\fIOFILE\fR will stop the copy.
.TP
notrunc
this conversion is accepted for compatibility with dd and ignored since
the default action of this utility is not to truncate \fIOFILE\fR.
.TP
null
has no affect, just a placeholder.
.TP
prefer_rcs
equivalent to "oflag=prefer_rcs".
.TP
resume
See "resume" in the FLAGS sections for more information.
.TP
rtf_len
equivalent to "oflag=rtf_len".
.TP
sparing
See "sparing" in the FLAGS sections for more information.
.TP
sparse
FreeBSD's dd supports "conv=sparse" and now GNU's dd does as well so the
same syntax is supported in ddpt. See "sparse" in the FLAGS sections for
more information.
.TP
sync
is ignored by ddpt. With dd it means supply zero fill (rather than skip)
and is typically used like this "conv=noerror,sync" to have the same
functionality as ddpt's "iflag=coe".
.TP
trunc
if \fIOFILE\fR is a regular file then truncate it prior to starting the
copy. See "trunc" in the FLAGS section.
.SH FLAGS
A list of flags and their meanings follow. The flag name is followed
by one or two indications in square brackets. The first indication is
either "[i]", "[o]" or "[io]" indicating this flag is active for the
\fIIFILE\fR, \fIOFILE\fR or both the \fIIFILE\fR and the \fIOFILE\fR. The
second indication contains some combination of "reg", "blk" "pt", "odx",
or "xcopy". These indicate whether the flag applies to a regular file, a
block device (accessed via Unix read() and write() commands, a pass\-through
device, an ODX offloaded copy or a XCOPY(LID1) offloaded copy respectively.
Other special file types that are sometimes referred to are "fifo"
and "tape".
.TP
00 [i]
This flag may replace \fIIFILE\fR with a source of zero (0x0) bytes. If
\fIIFILE\fR is given and is shorter than \fIOFILE\fR then it continues
to copy after \fIIFILE\fR is exhausted supplying zero fill bytes. Can
only be used on input. Zeros can also be generated by
using "if=/dev/zero" or an equivalent.
.br
If both '00' and 'ff' flags are given then a marching byte pattern is placed
in the segment prior to writing it out. It starts at 0x0 and wraps after
0xff (if the segment is large enough, as it usually is).
.TP
append [o] [reg], [io] [odx]
causes the O_APPEND flag to be added to the open of \fIOFILE\fR. For regular
files this will lead to data being appended to the end of any existing
data. Conflicts the \fIseek=SEEK\fR option. The default action of this
utility is to overwrite any existing data from the beginning of \fIOFILE\fR
or, if \fISEEK\fR is given, starting at block \fISEEK\fR. Note that
attempting to 'append' to a device file (e.g. a disk) will usually be
ignored or may cause an error to be reported.
.br
odx: if the \fIrtf=RTF\fR option is given, \fIRTF\fR exists, is a regular
file and this utility wants to write to \fIRTF\fR then new ROD Tokens are
appended to \fIRTF\fR. The default action is to truncate \fIRTF\fR before
new ROD Tokens are written to it.
.TP
atomic [o] [pt]
this flag changes the pass\-through SCSI WRITE command to the SCSI WRITE
ATOMIC(16) command on \fIOFILE\fR (and the \fIcdbsz=\fR{6|10|12|16|32}
option is ignored for \fIOFILE\fR). If this flag is applied to \fIIFILE\fR
or to a non pass\-through file then it is ignored.
.TP
block [io] [pt]
pass\-through file opens are non\-blocking by default and may report the
pt device is busy. Use this flag to open blocking so utility may wait until
another process locking (or with an exclusive open) is complete before
continuing.
.TP
bytchk [o] [pt]
only active when used together with oflag=wverify. Sets the BYTCHK field in
the SCSI WRITE AND VERIFY command. Since that field is two bits wide, this
flag can be specified multiple times (up to three) to place the corresponding
value in the field.
.TP
cat [io] [xcopy]
xcopy: set CAT (residual data handling) bit in EXTENDED COPY(LID1) parameter
list segment descriptor header. May appear in either flag list when xcopy is
being used. Works with the PAD bit for handling residual data on the
destination side. See the XCOPY section below.
.TP
coe [io] [pt], [i] [reg,blk]
continue on error. 'iflag=coe oflag=coe' and 'coe=1' are equivalent.
Errors occurring on output regular or block files will stop ddpt.
Error messages are sent to stderr. This flag is similar
to 'conv=noerror,sync' in the
.B dd(1)
utility. Unrecovered errors are counted and reported in the summary at
the end of the copy.
.IP
This paragraph concerns coe on pt devices. A medium, hardware or blank
check error during a read operation will will cause the following: first
re\-read blocks prior to the bad block, then try to recover the bad
block (supplying zeros if that fails), and finally re\-read the blocks
after the bad block. A medium, hardware or blank check error while writing
is reported but otherwise ignored. SCSI disks may automatically try and
remap faulty sectors (see the AWRE and ARRE in the read write error
recovery mode page (the sdparm utility can access these attributes)). If
bad LBAs are reported by the pass\-through then the LBA of the lowest and
highest bad block is also reported.
.IP
This paragraph concerns coe on input regular files and block devices.
When a EIO or EREMOTEIO error is detected on a normal segment read then
the segment is re\-read one block (i.e. \fIIBS\fR bytes) at a time. Any
block that yields a EIO or EREMOTEIO error is replaced by zeros. Any
other error, a short read or an end of file will terminate the copy,
usually after the data that has been read is written to the output file.
.TP
dc [io] [blk,pt]
xcopy: set DC (destination counter) bit in EXTENDED COPY(LID1) parameter
list segment descriptor header. May appear in either flag list when xcopy is
being used.
.TP
direct [io] [reg,blk]
causes the O_DIRECT flag to be added to the open of \fIIFILE\fR and/or
\fIOFILE\fR. This flag requires some memory alignment on IO. Hence user
memory buffers are aligned to the page size. May have no effect on pt
devices or cause an error (e.g. Linux seems to dis\-allow O_DIRECT on
character devices (like sg devices) yielding EINVAL). This flag will
bypass caching/buffering normally done by block layer. Beware of data
coherency issues if the same locations have been recently accessed via the
block layer in its normal mode (i.e. non\-direct). See open(2) man page.
.TP
dpo [io] [pt]
set the DPO bit (disable page out) in SCSI READ and WRITE commands. Not
supported for 6 byte cdb variants of READ and WRITE. Indicates that
data is unlikely to be required to stay in device (e.g. disk) cache.
May speed media copy and/or cause a media copy to have less impact
on other device users.
.TP
errblk [i] [pt] [experimental]
attempts to create or append to a file called "errblk.txt" in the current
directory the logical block addresses of blocks that cannot be read. The
first (appended) line is "# start <timestamp>". That is followed by the
LBAs in hex (and prefixed with "0x") of any block that cannot be read,
one LBA per line. If the sense data does not correctly identify the LBA of
the first error in the range it was asked to read then a LBA range is
reported in the form of the lowest and the highest LBA in the range
separated by a "\-". At the end of the copy a line with "# stop <timestamp>"
is appended to "errblk.txt". Typically used with "coe".
.TP
excl [io] [reg,blk]
causes the O_EXCL flag to be added to the open of \fIIFILE\fR and/or
\fIOFILE\fR. See open(2) man page.
.TP
fdatasync [o] [reg,blk]
Flushes data associated with the \fIOFILE\fR to storage at the end of the
copy.
.TP
ff [i]
This flag may replace \fIIFILE\fR with a source of 0xff bytes. If
\fIIFILE\fR is given and is shorter than \fIOFILE\fR then it continues to
copy after \fIIFILE\fR is exhausted supplying 0xff fill bytes. Can only be
used on input.
.br
If both '00' and 'ff' flags are given then a marching byte pattern is placed
in the segment prior to writing it out. It starts at 0x0 and wraps after
0xff (if the segment is large enough, as it usually is).
.TP
flock [io] [reg,blk,pt]
after opening the associated file (i.e. \fIIFILE\fR and/or \fIOFILE\fR)
an attempt is made to get an advisory exclusive lock with the flock()
system call. The flock arguments are "FLOCK_EX | FLOCK_NB" which will
cause the lock to be taken if available else a "temporarily unavailable"
error is generated. An exit status of 90 is produced in the latter case
and no copy is done. See flock(2) man page.
.TP
force [io] [pt] [xcopy,odx]
override difference between given block size and the block size found
by the SCSI READ CAPACITY command. Use the given block size. Without
this flag the copy would not be performed. pt access to what appears
to be a block partition is aborted in version 0.92; that can be overridden
by the force flag. For related reasons the 'norcap' flag requires this
flag when applied to a block device accessed via pt.
.br
xcopy and odx: various limits imposed by associated VPD pages or the RECEIVE
COPY OPERATING PARAMETERS command can be overridden (i.e.  exceeded) if this
flag is given. Note that the copy manager will probably object.
.TP
fsync [o] [reg,blk]
Flushes data and metadata (describing the file) associated with the
\fIOFILE\fR to storage at the end of the copy.
.TP
fua [io] [pt]
causes the FUA (force unit access) bit to be set in SCSI READ and/or WRITE
commands. The 6 byte variants of the SCSI READ and WRITE commands do not
support the FUA bit.
.TP
fua_nv [io] [pt]
causes the FUA_NV (force unit access non\-volatile cache) bit to be set in
SCSI READ and/or WRITE commands. This only has an effect with pt devices.
The 6 byte variants of the SCSI READ and WRITE commands do not support the
FUA_NV bit. The FUA_NV bit was made obsolete in SBC\-3 revision 35d.
.TP
ignoreew [o] [tape]
ignore the early warning indication (of end of tape) when writing to tape.
See TAPE section.
.TP
immed [io] [odx]
sets the IMMED bit in the POPULATE TOKEN (when [i]) or WRITE USING
TOKEN (when [o]) command. That command should return status promptly after
starting the data transfer. The RECEIVE ROD TOKEN INFORMATION command is then
used to poll for completion. SCSI command timeouts should not be exceeded,
even for very large RODs, if this flag is used.
.TP
nocache [io] [reg,blk]
use posix_fadvise(POSIX_FADV_DONTNEED) to advise corresponding file there is
no need to fill the file buffer with recently read or written blocks. If
used with "iflag=" it will increase the read ahead on \fIIFILE\fR.
.TP
no_del_tkn [o] [odx]
will clear the DEL_TKN bit on the last WRITE USING TOKEN command of each ROD
Token in a odx full copy. In a large odx full copy several ROD Tokens may
be used (one after the other). The default action is to set the DEL_TKN bit
on the last WUT command of each ROD. Either way it should not make much
difference because the copy manager deletes a ROD Token when its inactivity
time\-out occurs.
.TP
nocreat [o]
if \fIOFILE\fR does not exist then an error will be generated rather than
creating an empty regular file. This flag has the same action
as "conv=nocreat".
.TP
nofm [o] [tape]
no File Mark (FM) on close when writing to tape. See TAPE section.
.TP
nopad [o] [tape]
when the block to be written to a tape drive contains less than \fIOBS\fR
bytes, then this option causes the partial block to be written as is. The
default action for a tape in this case is to pad the block. See TAPE section.
.TP
norcap [io] [pt]
do not perform SCSI READ CAPACITY command on the corresponding pt device.
If used on block device accessed via pt then 'force' flag is also
required. This is to warn about using pt access on what may be a block
device partition.
.TP
nowrite [o] [reg,blk,pt]
bypass writes to \fIOFILE\fR. The "records out" count is not incremented.
\fIOFILE\fR is still opened but "oflag=trunc" if given is ignored. Also
the ftruncate call associated with the sparse flag is ignored (i.e.
bypassed). Commands such as trim and SCSI SYNCHRONIZE CACHE are still sent.
.TP
null [io]
has no affect, just a placeholder.
.TP
odx [io] [odx]
indicates to this utility that one of the four variants of an odx copy is
requested. Using any of the \fI\-\-odx\fR, \fIrtf=RTF\fR or \fIrtype=RTYPE\fR
options also indicates that odx is requested. See the ODX section.
.TP
pad [o] [reg,blk,pt], [io] [xcopy]
when the block to be written (typically the last block) contains less than
\fIOBS\fR bytes, then this option causes the block to be padded with
zeros (i.e. bytes of binary zero). The default action for a regular file
and a fifo is to do a partial write. The default action of a block
and a pt device is to ignore the partial write. The default action of
a tape is to pad, so this flag is not needed (see the nopad flag).
.br
xcopy: sets the PAD bit in the CSCD descriptor of the associated \fIIFILE\fR
or \fIOFILE\fR. Is associated with residual data handling and works
together with the cat flag. See the XCOPY section below.
.TP
prealloc [o] [reg]
use the fallocate() call prior to starting a copy to set \fIOFILE\fR to its
expected size.
.TP
prefer_rcs [o] [odx]
prefer RECEIVE COPY STATUS (RCS) command to the RECEIVE ROD TOKEN
INFORMATION (RRTI) command which is the default. This only is active when
polling after a WUT command (since polling after a PT command needs
to fetch the ROD Token so it needs the RRTI command).
.TP
pt [io] [blk,pt]
causes a device to be accessed in "pt" mode. In "pt" mode SCSI READ and
WRITE commands are sent to access blocks rather than standard UNIX read()
and write() commands. The "pt" mode may be implicit if the device is only
capable of passing through SCSI commands (e.g. the /dev/sg* and
some /dev/bsg/* devices in Linux). This flag is needed for device nodes
that can be accessed both via standard UNIX read() and write() commands
as well as SCSI commands. Such devices default standard UNIX read()
and write() commands in the absence of this flag.
.TP
rarc [i] [pt]
bit set in READ(10, 12, 16 and 32) to suppress RAID rebuild functions
when a bad (or recovered after difficulties) block is detected.
.TP
resume [o] [reg]
when a copy is interrupted (e.g. with Control\-C from the keyboard)
then using the same invocation again with the addition of "oflag=resume"
will attempt to restart the copy from the point of the interrupt (or
just before that point). It is harmless to use "oflag=resume" when
\fIOFILE\fR doesn't exist or is zero length. If the length of \fIOFILE\fR
is greater than or equal to the length implied by a ddpt invocation that
includes "oflag=resume" then no further data is copied.
.TP
self [io] [pt]
used together with trim flag to do a self trim (trim of segments of a
pt device that contain all zeros). If \fIOFILE\fR is not given, then
it is set to the same as \fIIFILE\fR. If \fISEEK\fR is not given it
set to the same value as \fISKIP\fR (possibly adjusted if \fIIBS\fR
and \fIOBS\fR are different). Implicitly sets "nowrite" flag.
.TP
sparing [o] [reg,blk,pt]
during the copy each \fIIBS\fR * \fIBPT\fR byte segment is read from
\fIIFILE\fR into a buffer. Then, instead of writing that buffer to
\fIOFILE\fR, the corresponding segment is read from \fIOFILE\fR into another
buffer. If the two buffers are different, the former buffer is written to
the \fIOFILE\fR. If the two buffers compare equal then the write to
\fIOFILE\fR is not performed. Write sparing is useful when a write operation
is significantly slower than a read. Under some conditions flash memory
devices have slow writes plus an upper limit on the number of times the same
cell can be rewritten. The granularity of the comparison can be reduced from
the default \fIIBS\fR * \fIBPT\fR byte segment with the the \fIOBPC\fR value
given to the "bpt=" option. The finest granularity is when \fIOBPC\fR is 1
which implies \fIOBS\fR bytes.
.TP
sparse [io] [reg,blk,pt]
after each \fIIBS\fR * \fIBPT\fR byte segment is read from \fIIFILE\fR, it
is checked to see if it is all zeros. If so, that segment is not written to
\fIOFILE\fR. See the section on SPARSE WRITES below for the difference
between using this flag once or twice. The granularity of the zero comparison
can be reduced from the default \fIIBS\fR * \fIBPT\fR byte segment with the
\fIOBPC\fR value given to the "bpt=" option.
.br
The sparse flag may be used on input when a file is only being read (e.g.
when \fIof=OFILE\fR is not given or \fIOFILE\fR is /dev/null) to determine
how many blocks are contained in sparse segments of \fIIFILE\fR.
.TP
ssync [o] [pt]
if \fIOFILE\fR is in "pt" mode then the SCSI SYNCHRONIZE CACHE command is
sent to \fIOFILE\fR at the end of the copy.
.TP
strunc [o] [reg]
perform a sparse copy with a ftruncate system call to extend the length
of the \fIOFILE\fR if required. Sets the sparse flag internally if this
has not been specified on the command line. See the sparse flag and the
section on SPARSE WRITES below.
.TP
sync [io] [reg,blk]
causes the O_SYNC flag to be added to the open of \fIIFILE\fR and/or
\fIOFILE\fR. See open(2) man page.
.TP
rtf_len [io] [odx]
odx: with the 'read to tokens' variant, after 512 bytes of each ROD Token
are written to \fIRTF\fR an additional 8 byte (big endian) integer is
written. That integer is the number of bytes that the associated ROD
represents. The draft standards say for standard ROD types the ROD Token
contains this value. However vendor specific ROD types may be used or
vendors may choose not to comply. Either way the 'write from tokens'
variant needs to know the data size associated with the ROD it is writing
from.
.TP
trim [io] [pt] [experimental]
similar logic to the "sparse" option. However instead of skipping segments
that are full of zeros a "trim" command is sent to \fIOFILE\fR. Usually set
as an oflag argument but for self trim can be used as an iflag
argument (e.g. "iflag=self,trim"). Depending on the usage this may require
the device to support "deterministic read zero after trim". See the
TRIM, UNMAP AND WRITE SAME section below.
.TP
trunc [o] [reg]
if \fIOFILE\fR is a regular file then it is truncated prior to starting the
copy. If \fISEEK\fR is not given or 0 then \fIOFILE\fR is truncated to zero
length; when \fISEEK\fR is larger than zero the truncation takes place at
file byte pointer \fISEEK*OBS\fR.  Ignored if "oflag=append". Conflicts
with "oflag=sparing".
.TP
unmap [io] [pt]
same as the trim flag.
.TP
wverify [o] [pt]
this causes SCSI WRITE AND VERIFY commands to be sent to \fIOFILE\fR (instead
of SCSI WRITE (or WRITE ATOMIC) commands). Note that the fua flag is ignored
when this flag is given. The BYTCHK field in the SCSI WRITE AND VERIFY
commands is set to zero unless the bytchk flag is also given.
.TP
wstream [o] [pt]
this causes SCSI WRITE STREAM(16) command to be sent to \fIOFILE\fR (instead
of SCSI WRITE. The Stream Identify (valid range: 1 to 0xffff (65535)) should
be given via the \fIlist_id=LID\fR operand (note that it defaults to 0 which
is invalid). The stream can be created (closed (for write) or its status
checked) with the sg_stream_ctl utility. It is the user's responsibility
to open a stream before calling "ddpt ... oflag=wstream list_id=<strm_id>"
and close it after, if required.
.TP
xcopy [io] [pt]
invoke SCSI XCOPY(LID1) logic and send the XCOPY command to the either
\fIIFILE\fR or \fIOFILE\fR depending on which flag this called. If both are
given (i.e. an invocation including 'iflag=xcopy  oflag=xcopy') then send
the XCOPY(LID1) to \fIOFILE\fR.
.SH COUNT
When the \fIcount=COUNT\fR option is not given (or \fICOUNT\fR is '\-1')
then an attempt is made to deduce \fICOUNT\fR as follows.
.PP
When both or either \fIIFILE\fR and \fIOFILE\fR are block devices, then
the minimum size, expressed in units of input blocks, is used. When both
or either \fIIFILE\fR and \fIOFILE\fR are pass\-through devices, then the
minimum size, expressed in units of input blocks, is used.
.PP
If a regular file is used as input, its size, expressed in units of input
blocks (and rounded up if necessary) is used. Note that the rounding up
of the deduced \fICOUNT\fR may result in a partial read of the last input
block and a corresponding partial write to \fIOFILE\fR if it is a regular
file. After a regular file to regular file copy the length of \fIOFILE\fR
will be the same as \fIIFILE\fR unless \fIOFILE\fR existed and its length
was already greater than that of \fIIFILE\fR. To get a copy like the
standard Unix cp command, use oflag=trunc with ddpt.
.PP
The size of pt devices is deduced from the SCSI READ CAPACITY command.
Block device sizes (or their partition sizes) are obtained from the
operating system, if available.
.PP
If \fIskip=SKIP\fR or \fIseek=SEEK\fR are given and the \fICOUNT\fR is
deduced (i.e. not explicitly given) then that size is scaled back so
that the copy will not overrun the file or device.
.PP
If \fICOUNT\fR is not given and \fIIFILE\fR is a fifo (and stdin is
treated as a fifo) then \fIIFILE\fR is read until an EOF is detected.
If \fICOUNT\fR is not given and \fIIFILE\fR is a /dev/zero (or
equivalent) then zeros are read until an error occurs (e.g. file
system full).
.PP
If \fICOUNT\fR is not given and cannot be deduced then an error message
is issued and no copy takes place.
.SH JOB FILES
Some operands can have long arguments (e.g. \fIskip=SKIP\fR and
\fIiflag=FLAGS\fR) so that the command line can become quite long. Also
scatter gather lists can be arbitrarily long and may be generated by a
program; then it would be tiresome and error\-prone to re\-type them
on the command line. So the job file was introduced to hold this utility's
operands and options.
.PP
A job file is invoked by either the \fI\-\-job=JF\fR option or by placing
the job filename (\fIJF\fR) unadorned on the command line. The job filename
cannot contain a "=", start with a hyphen nor be called "ddpt". It is parsed
when it is detected, in a left to right scan of the command line. The
\fIJF\fR file must contain the string "ddpt" and may invoke other job
files (to a maximum depth of 4). A job file should not invoke itself. Also
the first line of the job file should not contain any characters (bytes)
with their top bit set; in other words it should be restricted to 7 bit
ASCII (otherwise sanity checks might think it is a binary file and reject it).
.PP
The operands and options within a job file are processed in the order
they are found (i.e. parsing lines left to right, top (of file) to bottom).
The operands and options may contradict (and cause a syntax error), override
or accumulate with earlier ones, the same as if they appeared on the command
line. For example '\-v' on the command line followed by a job file
containing '\-vv' will result in a verbosity level of '\-vvv' during the
copy phase. Empty lines, lines only containing whitespace(s) and anything
from and including a '#' in a job file line are ignored.
.SH SCATTER GATHER LISTS
Each element of a scatter gather list (sgl, plural: sgl_s) is made up of a
starting logical block address (LBA, plural: LBAs), and a number of
blocks (NUM) to be accessed from that starting LBA.
.PP
The \fIskip=SKIP\fR and \fIseek=SEEK\fR options (and their aliases) can take
scatter gather lists. These can be explicit on the command line, fed in
through stdin or in a file whose name is prefixed by "@" or "H@" on the
command line. For large scatter gather lists, placing them in a file is the
most practical as command lines are limited in length. Scatter gather
list (sgl) is a collective term for either a scatter list or a gather list.
The actual implementation of each sgl is an array. Syntactically a scatter
list and a gather list are the same.
.PP
Conceptually these sgl_s refer to what happens at the "far end" (e.g. within
a hard disk or SSD), not what happens in the computer's memory. So a gather
list is associated with the read part of a copy (i.e. the first half) where
a list of Logical Blocks (LBs, identified by their addresses, hence LBAs) and
a number of consecutive, following blocks are "gathered" from the
medium (e.g. a SSD). They are formed into a linear sequence of bytes that is
transferred into a segment in the computer's RAM. The second half of the
copy, the write part, may use a scatter list. A scatter list starts with a
linear sequence of bytes, taken from the segment, that is transferred to the
device and then "scattered" on the medium as indicated by the list of
LBA,NUM pairs.
.PP
In the simplest case a sgl is given on the command line and has the form:
LBA1,NUM1[,LBA2,NUM2[,LBA3,NUM3...]]. There must be an even number of
items (i.e. for every LBAn there should be a following NUMn) with one
exception: when LBA1 alone is given, in which case the value 0 is assumed
for NUM1. Comma is the simplest separator for the command line, but
whitespace may also be used (but needs to be escaped because the shell
usually interprets whitespace as an option separator). In a file (or read
from stdin or file redirection) more flexibility is permitted in the format.
The LBA,NUM pairs could all appear on one line in a file but the line
length is limited to 1024 characters (with a maximum of 256 parseable items
on it). So for longer sgl_s one pair per line is recommended in file format.
Also in file format everything from and including '#' to the end of that
line is ignored as are lines that are empty or only contain whitespace(s).
.PP
Each pair becomes one element (or more, see below) of the sgl. By default
all numbers given for LBA and NUM items are in decimal with optional suffix
multipliers. Hex numbers use either a "0x" prefix or a 'h' suffix (hex
notation and suffix multipliers cannot be mixed). In the case of a 'H@'
lead\-in to the filename on the command line, all numbers are interpreted
as hex with no suffix multipliers permitted. Further, with the 'H@'
lead\-in the file may contain the string 'HEX' before any numbers are
given. The 'HEX' is ignored. The point of this is to catch when a sgl
file with default hexadecimal numbers is given without the 'H@' lead\-in;
in this case this utility will exit saying that file is in the wrong format.
This "wrong format" action can be bypassed with the \fI\-\-flexible\fR
option.
.PP
Allowing sgl_s brings lots of flexibility (including the possibility to use
the SCSI WRITE SCATTERED command) but with that comes complexity. Every sgl
is scanned to determine if it is monotonic and whether it has overlapping
elements. The term monotonic is used to indicate whether each LBA is in
ascending order, with each LBA greater than the previous element's LBA.
Overlapping refers to the situation when any element's LBA range intersects
with any other element's range. Elements that have zero number of
blocks (described here as "degenerate") are ignored for determining
monotonic and overlapping (and the lowest LBA). Overlapping elements are not
ideal (but not necessarily fatal). The above mentioned WRITE SCATTERED
command allows the medium's logic to write elements in any order it prefers.
That means if elements overlap, then the user doesn't know which one gets
written last (overwriting the one written to the same LBA earlier).
Determining whether element ranges overlap is difficult in the general
case (so this utility doesn't do it) but easy in the case of a monotonic
sgl (so this utility does do it). Warnings are issued in dangerous
situations, with the force flag allowing the warning to be overridden.
.PP
A degenerate sgl element is one that has zero in its NUM field.
Normally degenerate elements are ignored with some exceptions. The
definition of the SCSI WRITE SCATTERED command clearly states that degenerate
elements are valid, thus do not cause an error, but cause no associated
action. This utility uses the concept of a 'hard' and 'soft' sgl: a 'soft'
sgl is one in which the last element's NUM is zero (i.e.
its last element is degenerate). A sgl with a non\-zero NUM in
its last element is considered 'hard'. In a 'soft' sgl the LBA of the last
element should be greater than or equal to any LBA+NUM of earlier elements.
Because this is hard to check it is not enforced, so the decision is made
on whether a sgl is hard or soft simply by checking the NUM of that last
element. The difference between a hard and soft sgl is the way the sum of
NUM of all elements is used by this utility.  For a 'hard' sgl
that sum is used for \fICOUNT\fR when the \fIcount=COUNT\fR option is not
given; and if \fIcount=COUNT\fR is given and the counts differ then those
two values are output and this utility exits with a syntax error. For
a 'soft' sgl the degenerate last element is interpreted as "from the
highest LBA in the list to the end of the copy" where the \fICOUNT\fR is
determined some other way. The "highest LBA" is calculated from all
elements that have a non\-zero number of blocks plus the LBA of the last
element (regardless of whether it is degenerate or not).
.PP
The rules in the above paragraph make a one item skip or seek argument (e.g.
skip=0x123) in this utility first become a one element sgl (e.g. containing
the pair [0x123, 0x0]). Since this is the last element, it is a soft sgl
and the transfer will start from the given lba (i.e. 0x123) and continues
for the number of blocks indicated by some other mechanism (e.g.  an option
such as \fIcount=COUNT\fR or the length of \fIIFILE\fR). This mirrors what
the classic
.B dd
command does with its skip= and seek= options.
.PP
Some sgl implementation details: LBAs are stored in 64 bit integers which
is more than sufficient to span even the largest disk array behind a logical
device, even if the block size is one byte, which is unlikely. The NUM field
is a 32 bit integer and this is more problematic. The reason is that SCSI
WRITE commands (and their variants) only allocate at most a 32 bit integer
for this value. Further, modern operating systems do not allow any driver
to get large amounts of contiguous system RAM, even if the machine has it
available. A 32 bit integer for NUM with each block at 512 bytes is around
2 TB of storage. Unix system calls (in Linux) also limit each read(2) and
write(2) system call to 32 bits of single bytes which is 4 GB. The problem
for this utility is that the NUM can easily exceed 32 bits when a single
scatter gather list element refers to the whole device. The action taken
by this utility is to allow larger than 32 bit NUM values to be given on
the command line (or in a scatter gather list file). However such a large
element will be split into multiple elements internally. This will be
visible to the user when the \fIverbose=VERB\fR option (or one of its
variants) is used with an elevated value.
.PP
There is a helper utility called ddpt_sgl in this package for generating,
manipulating and checking scatter gather lists. See its manpage.
.SH SANITY CHECKS
With powerful data tools, the ability to accidentally overwrite and hence
lose important data is ever present. So a significant portion of the code
is dedicated to checking the input arguments for duplications and
contradictions. Still nothing is better than re\-reading the command
line (which can be quite long) before hitting the enter key.
.PP
Other useful possibilities are to use job files (see the \fIJF\fR argument
and the \fI\-\-job=JF\fR option) and the \fI\-\-dry\-run\fR option.
The "dry run" option is becoming popular in modern command line utilities
and more or less does what the user would expect. Firstly it parses all
the command line arguments then opens \fIIFILE\fR, \fIOFILE\fR and
\fIOFILE2\fR as directed by the command line and does any meta\-data
operations that it would typically do (e.g. check a pass\-though or
block device's logical block size and object if it differs from
\fIBS\fR, \fIIBS\fR or \fIOBS\fR (whichever applies)). Then just at the
point where the code would commence the actual copy (or read) it does a
premature exit. If the \fI\-\-dry\-run\fR option is given twice, the code
continues into the copy logic and bypasses the low level read and write
calls (and file repositioning). That inner level of "dry run" is useful
for debugging and can be used with multiple \fIverbose=VERB\fR options.
.PP
The \fIverbose=VERB\fR option sends diagnostic messages to stderr. The higher
value of \fIVERB\fR (in \fIverbose=VERB\fR) or the more times that \fI\-v\fR
is used, the greater the volume of diagnostic messages. When use three or
more times then diagnostic messages are generated for each read to, and write
from, the working copy buffer; so the volume of messages is proportional to
the number of reads and writes that are done; this can easily be in the
megabyte range. If used less than three times, the reads and writes
associated with the copy do not generate diagnostic messages (unless abnormal
situations are encountered). These diagnostic messages are mainly associated
with command line parsing and fetching meta\-data about the given files, plus
messages from the cleanup at the end of the copy.
.PP
The following command line arguments are checked that they don't appear
more than once: \fIbpt=BPT[,OBPC]\fR, \fIbs=BS\fR, \fIcount=COUNT\fR,
\fIibs=IBS\fR, \fIif=IFILE\fR, \fIiseek=SKIP\fR, \fIobs=OBS\fR,
\fIof=OFILE\fR, \fIof2=OFILE2\fR, \fIoseek=SEEK\fR, \fIseek=SEEK\fR and
\fIskip=SKIP\fR. On the other hand, some arguments are additive, for example
\fIiflag=FLAGS\fR, \fIoflag=FLAGS\fR, \fIstatus=STAT\fR and
\fI\-\-verbose\fR and may appear as many times as required.
.SH XCOPY
This section describes XCOPY(LID1) support with this utility. For ODX
support (XCOPY(LID4) subset) see the ODX section.
.PP
A device (logical unit (LU)) that supports XCOPY operations should set
the 3PC field (3PC stands for Third Party Copy) in its standard INQUIRY
response. That is not checked when this utility does an xcopy operation
but if it fails, that is one thing that the user may want to check.
.PP
If the xcopy starts and fails while underway, then 'sg_copy_results \-s'
may be useful to view the copy status. It might also be used from a
different process with the same I_T nexus (i.e. the same machine)
to check status during an xcopy operation.
.PP
The \fIpad\fR and \fIcat\fR flags control the handling of residual
data. As the data can be specified either in terms of source or target
block size and both might have different block sizes residual data is
likely to happen in these cases.
If both block sizes are identical these bits have no effect as
residual data will not occur.
.PP
If neither of these flags are set, the EXTENDED COPY command will be
aborted with additional sense 'UNEXPECTED INEXACT SEGMENT'.
.PP
If only the \fIcat\fR flag is set the residual data will be retained
and made available for subsequent segment descriptors. Residual data
will be discarded for the last segment descriptor.
.PP
If the \fIpad\fR flag is set for the source descriptor only, any
residual data for both source or destination will be discarded.
.PP
If the \fIpad\fR flag is set for the target descriptor only any
residual source data will be handled as if the \fIcat\fR flag is set,
but any residual destination data will be padded to make a whole block
transfer.
.PP
If the \fIpad\fR flag is set for both source and target any residual
source data will be discarded, and any residual destination data will
be padded.
.PP
There is a web page discussing ddpt, XCOPY and ODX at
https://sg.danny.cz/sg/ddpt_xcopy_odx.html
.SH ODX
This section describes ODX support (an XCOPY(LID4) subset) for this utility.
ODX descriptions use the following command name abbreviations: PT for
the POPULATE TOKEN command, RRTI for the READ ROD TOKEN INFORMATION command,
and WUT for the WRITE USING TOKEN command.
.PP
A device (logical unit (LU)) that supports ODX operations is required to set
the 3PC field (3PC stands for Third Party Copy) in its standard INQUIRY
response and support the Third Party Copy VPD page. If this utility generates
errors noting the absence of these then the device in question probably does
not support ODX.
.PP
There a four variants of ODX supported by ddpt:
.br
  \fBfull copy\fR : ddpt \-\-odx if=/dev/sg3 bs=512 of=/dev/sg4
.br
  \fBzero output blocks\fR : ddpt if=/dev/null rtype=zero bs=512 of=/dev/sg4
.br
  \fBread to tokens\fR : ddpt if=/dev/sg3 bs=512 skip=@gath.lst rtf=a.rt
.br
  \fBwrite from tokens\fR : ddpt rtf=a.rt bs=512 of=/dev/sg4 seek=@scat.lst
.PP
The full copy will call PT and WUT commands repeatedly until the copy is
complete. More precisely the full copy will make the largest single call
to PT allowed by the input's Third Party Copy VPD page (and, if given,
allowed by the \fIBPT\fR argument in the \fIbpt=BPT[,OBPC]\fR option). Then
one or more WUT calls are made to write out from the ROD created by the PT
step. The largest single WUT call is constrained by the output's Third Party
Copy VPD page (and, if given, allowed by the \fIOBPC\fR argument in the
\fIbpt=BPT[,OBPC]\fR option). This sequence continues until the requested
copy is complete.
.PP
The zero output blocks variant is a special case of the full copy in
which only WUT calls are made. ODX defines a special ROD Token to
zero blocks. That special ROD Token has a fixed pattern (shown in SBC\-3)
and does not need to be created by a PT command like normal ROD Tokens.
.PP
The read to tokens and the write from tokens variants are designed to be
the read (input) and write (output) sides respectively of a network copy.
Each can run on different machines by sending the \fIRTF\fR file from
the machine doing the read to the machine doing the write. The read to
tokens will make one or more PT calls and output the resulting ROD Tokens
to the \fIRTF\fR file. \fIRTF\fR might be a regular file or a named pipe.
.PP
All four variants can have the immed flag set. Then the PT and/or WUT
commands are issued with the IMMED bit set and the RRTI command is used to
poll for completion. The delay between the polls is as suggested by the
RRTI command (or if no suggestion is made, 500 milliseconds). Either
iflag=immed, oflag=immed or both can be given but are only effective if
the corresponding \fIIFILE\fR or \fIOFILE\fR sends a PT or WUT command.
.PP
Typically there is no need to give the \fIlist_id=LID\fR option. If this
option is not given then 257 is chosen. If that is busy then 258 is tried.
That continues until a usable \fILID\fR is found or 10 \fILID\fRs have been
tried. In the latter case ddpt exits with status of 55 (operation in
progress). If the user gives \fIlist_id=LID\fR option and \fILID\fR is
busy then ddpt exits with exit status 55.
.PP
If the block size of the input and output are different (i.e. \fIIBS\fR
is not equal to \fIOBS\fR) then one must be a multiple of the other. So
an input block size of 512 bytes and an output block size of 4096
bytes (or vice versa) is acceptable.
.PP
The four ODX variants are distinguished as follows: if \fIOFILE\fR is a
pass\-through device, if=/dev/null (or equivalent) and rtype=zero then the
zero output blocks variant is selected. If both \fIIFILE\fR and \fIOFILE\fR
are pass\-through devices and there is some indication of an ODX request (e.g.
the \fI\-\-odx\fR option), then the full copy variant is selected. The read
to tokens and the write from token variants are indicated by the absence
of either a \fIof=OFILE\fR or a \fIif=IFILE\fR option, respectively, plus
the presence of a \fIrtf=RTF\fR option.
.PP
The helper utility ddptctl contains options to issue a single PT, RRTI,
WUT or COPY OPERATION ABORT command. It can also issue a series of
polling RRTI commands. It can decode information in ROD Tokens (which is
not as informative as it should be) and print the number of blocks and block
size of a disk, plus protection information if available. See ddptctl.
.PP
There is a web page discussing ddpt, XCOPY and ODX at
https://sg.danny.cz/sg/ddpt_xcopy_odx.html
.SH SPARSE WRITES
Bypassing writes of blocks full of zeros can save a lot of IO. However
with regular files, bypassed writes at the end of the copy can lead
to an \fIOFILE\fR which is shorter than it would have been without
sparse writes. This can lead to integrity checking programs like md5sum
and sha1sum generating different values.
.PP
This utility has two ways of handling this file length problem: writing
the last block (even if it is full of zeros) or using the ftruncate
system call. A third approach is to ignore the problem (i.e. leaving
\fIOFILE\fR shorter). The ftruncate approach is used when "oflag=strunc"
while the last block is written when "oflag=sparse". To ignore the
file length issue use "oflag=sparse,sparse". Note that if \fIOFILE\fR's
length is already correct or longer than required, no action is taken.
.PP
The support for sparse writing of regular files may depend on the OS, the
file system and the settings of \fIOFILE\fR. POSIX makes few guarantees
when the ftruncate system call is used to extend a file's length, as may
occur when "oflag=strunc". Further, primitive file systems like VFAT may not
accept sparse writes or simulate the effect by writing blocks of zeros. The
latter approach will defeat any sparse writing performance gain.
.SH TRIM, UNMAP AND WRITE SAME
This is a new storage feature often associated with Solid State
Disks (SSDs) or disk arrays with "thin provisioning". In the ATA command
set (ACS\-2) the relevant command is DATA SET MANAGEMENT with the TRIM
bit set. In the SCSI command set (SBC\-3) it is either the UNMAP or
WRITE SAME command. Note there is no TRIM command however the term is
frequently used in the technical press.
.PP
Trim is a way of telling a storage device that blocks are no longer needed.
Keeping the pool of unwritten blocks large is important for the write
performance of SSDs and the thrifty use of real storage in thin provisioned
arrays. Currently file systems in recent OSes may issue trims associated
with file deletes. The trim option in ddpt may be useful when a partition
or a whole SSD is to be "deleted". Note that ddpt is bypassing file
systems in that it only offers trim on pass\-through (pt) devices.
.PP
This utility issues SCSI commands to pt devices and for "trim" currently
issues a SCSI WRITE SAME(16) command with the UNMAP bit set. If the pt
device is a SSD with a ATA interface then recent versions of Linux
will translate the SCSI WRITE SAME to the ATA DATA SET MANAGEMENT command
with the TRIM bit set. The maximum size of each "trim" command sent
is the size of the copy buffer (i.e. \fIIBS\fR * \fIBPT\fR bytes). And
that maximum can be reduced with the \fIOBPC\fR argument of the "bpt="
option.
.PP
The trim can be used various ways. One way is a copy where the copy
buffer (or some part of it) is checked for zeros as is done by the
sparse oflag. When a zero segment is found, a trim "command" is
sent to the \fIOFILE\fR. For example:
.PP
   ddpt if=dsk.img bs=512 of=/dev/sdc oflag=pt,trim
.PP
The copy buffer is 64 KiB (since \fIBPT\fR and \fIOBPC\fR default to 128
when "bs=512") and it is checked for all zeros. If it is all zeros then
a trim command is sent to the corresponding location of /dev/sdc
which is accessed via the pt interface. If it is not all zeros
then a SCSI WRITE command is sent. Another way is to trim all or
part of a disk. To trim a whole disk (i.e. deleting all its data):
.PP
   ddpt if=/dev/zero bs=512 of=/dev/sdc oflag=pt,trim
.PP
A third way is to "self\-trim" which is to only trim those parts
of a disk that contain segments full of zeros:
.PP
   ddpt if=/dev/sdc skip=0x2300 bs=512 iflag=pt,self,trim count=0x1234f0
.PP
The "self" oflag automatically sets up the output side of the copy
to send trim commands (if required) back the the same device (i.e. /dev/sdc).
If this example was self\-trimming a partition then the partition would
start at LBA 0x2300 and be 0x1234f0 blocks long.
.PP
Some random product examples: the Intel X25\-M G2 SSDs have trim with
recent firmware and they do deterministic read zero after trim. The
Seagate Pulsar SSD has an ATA interface which supports the deterministic
reads of zero after the DATA SET MANAGEMENT command with the TRIM option.
.SH NVME SUPPORT
The following information is Linux specific at this time. NVMe devices in
Linux have names like /dev/nvme0, /dev/nvme0n1 and /dev/nvme0n1p3. The first
device name is a character device and some "Admin" commands can be sent to
it (e.g. Identify) but no media access commands (which the NVMe
specification calls the "NVM" Command set). The number given is a controller
identifier. Storage in NVMe is associated with namespaces which are numbered
within a controller, starting at 1 (e.g. /dev/nvme0n1 is controller 0,
namespace 1). These device nodes are block devices and can be given as
\fIIFILE\fR and/or \fIOFILE\fR. The third type of NVMe device node
selects a partition (within a namespace, within a controller). Partition
numbers also start with 1.
.PP
By default ddpt will treat the second and third form (of NVMe device nodes)
as standard Linux block devices. So ddpt will act in the same as the
dd utility would. In a similar fashion to accessing SCSI block devices (e.g.
/dev/sdc3) get access NVMe block devices the "pt" flag is required, either
with \fIiflag=FLAGS\fR and/or \fIoflag=FLAGS\fR. There is a SCSI to NVMe
Translation Layer (SNTL) in the sg3_utils library which underpins this
utility.
.SH DD DIFFERENCES
dd defaults "if=" and "of=" to stdin and stdout respectively. This follows
Unix filter conventions. However since dd and ddpt are often used to read
binary data for timing purposes, having to supply "of=/dev/null" can
be easily forgotten. Without it dd will typically spew binary data on the
console. So ddpt has changed its defaults: the "if=\fIIFILE\fR" is now
mandatory for direct copies and to read from stdin "if=\-" can be
used; "of=\fIOFILE\fR" remains optional but its default changes
to "/dev/null" (or "NUL" in Windows). To send output to stdout ddpt
accepts "of=\-".
.PP
dd truncates \fIOFILE\fR unless "conv=notrunc" is given. When dd truncates,
it truncates to zero length unless \fISEEK\fR is greater than zero. ddpt
does not truncate \fIOFILE\fR by default. If \fIOFILE\fR exists it will be
overwritten. The overwrite starts at block zero unless \fISEEK\fR
or "oflag=append" is given. If \fIOFILE\fR is a regular file
then "oflag=trunc" (or "conv=trunc") will truncate \fIOFILE\fR prior to the
copy.
.PP
Numeric arguments to ddpt can be given in hexadecimal, either with a
leading "0x" or "0X" or with a trailing "h". Note that dd accepts "0x123"
but interprets it as "0 * 123" (i.e. zero). ddpt will also interpret "x"
as multiplies unless the left operand is zero (e.g. "0x123"). So both
dd and ddpt will interpret "skip=2x123" as "skip=246".
.PP
Terabyte size disks make it impractical to copy all the data into a single
buffer of 512 bytes length before writing it out. Therefore both dd and ddpt
read a relatively small amount of data into a copy (or transfer) buffer then
write it out to the destination, repeating this process until the
\fICOUNT\fR is exhausted.
.PP
A major difference in ddpt is the addition of \fIBPT\fR (Blocks Per Transfer)
to control the size of the copy buffer. With dd, \fIIBS\fR is the size of the
copy buffer and the unit of \fISKIP\fR and \fICOUNT\fR. With ddpt,
\fIIBS\fR * \fIBPT\fR is the size of the copy buffer and \fIIBS\fR is the
unit of \fISKIP\fR and \fICOUNT\fR. This allows ddpt to have its \fIIBS\fR
set to the logical block size of \fIIFILE\fR without unduly restricting the
size of the copy buffer. And setting \fIIBS\fR (and \fIOBS\fR for
\fIOFILE\fR) accurately is required when the pass\-through interface is used
since with the SCSI READ and WRITE commands the logical block size is
implicit.
.PP
The way dd handles its copy buffer (outlined in SUSv4 description of dd)
is relatively complex, especially when \fIIBS\fR and \fIOBS\fR are different
sizes. The restriction that ddpt places on \fIIBS\fR and \fIOBS\fR (
i.e. (((\fIIBS * BPT\fR) % \fIOBS\fR) == 0) ) means that a single
copy buffer can be used since its size is a multiple of both \fIIBS\fR and
\fIOBS\fR. Being able to precisely define the copy buffer size in ddpt
makes sparse writing, write sparing and trim operations simpler to
define and the user to control.
.PP
ddpt does not support dd's "cbs=" option (conversion block size). If
the "cbs=" option is given to ddpt then it is ignored.
.PP
ddpt adds two types of disk to disk, offloaded copies: XCOPY(LID1) first
introduced in SPC\-2 (standardized in 2001), and ODX which is a subset of
XCOPY(LID4) first introduced in SPC\-4 draft (revision 34, 2012).
.SH PROTECTION INFORMATION
This section is about protection information which is typically an extra 8
bytes associated with each logical block. Those 8 byte are divided into 3
fields: logical block guard (16 bit (2 byte) CRC), logical block application
tag (2 bytes) and the logical block reference tag (4 bytes). The acronym
DIF is sometimes used for protection information.
.PP
The feature to read and/or write protection information by using the
\fIprotect=RDP[,WRP]\fR option is currently experimental. It should be used
with care and may not "play well" with some other features such as write
sparing and sparse writing. It should be used to copy user data plus the
associated protection information to or from a regular file. It could also
be used for a device to device copy assuming the "pt" interface is used
for both. Also only modern SCSI disks support protection information.
.PP
When \fIRDP\fR or \fIWRP\fR is greater than 0 then a copy with associated
protection information is active. In this state \fIIBS\fR and \fIOBS\fR
must be the same and equal to the logical block size of the device(s)
formatted with protection information. If a SCSI disk with 512 byte logical
block size has protection information then the actual number of bytes
transferred for each logical block is typically 520 bytes. For such a disk
\fIBS=512\fR is required even when additional protection information is
being transferred.
.PP
When protection type 2 is used, the "normal" READ, WRITE and VERIFY SCSI
commands are disallowed. In this context "normal" means the 6, 10, 12, and
16 byte variants. Only READ(32) and WRITE(32) can be used. The 32 byte
variants can be selected in this utility by using the operand 'cdbsz=32'.
.SH MULTIPLIERS
By default numeric arguments to options are assumed to be decimal. Almost
all numeric arguments to options (e.g. \fICOUNT\fR in the \fIcount=COUNT\fR
option) may include one of these multiplicative suffixes:
c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576;
MB *1,000,000 . This pattern continues for "G", "T" and "P". The latter two
suffixes can only be used for 64 bit values. Some numeric arguments are
limited to 32 bit values (e.g. \fIBS\fRin the \fIbs=BS\fR option).
Also a suffix of the form "x<n>" multiplies the leading number by <n>;
however the combinations "0x" and "0X" are treated differently, see the
next paragraph. These multiplicative suffixes are compatible with GNU's
dd command (since 2002) which claims compliance with the SI and with
IEC 60027\-2 standards.
.PP
Alternatively numerical values can be given in hexadecimal indicated by
either a leading "0x" or "0X", or by a trailing "h" or "H". When hex numbers
are given, suffix multipliers cannot be used.
.PP
If a numeric argument is required to fit in 32 bits and is too large then
an error is reported. Usually negative numbers are not permitted
but "count=\-1" is a special case and means "all available"; "verbose=\-1"
is another special case.
.SH NOTES
Copying data behind an Operating System's back can cause problems. In the
case of Linux, users should look at this link:
https://linux\-mm.org/Drop_Caches
.br
This command sequence may be useful:
.br
  sync; echo 3 > /proc/sys/vm/drop_caches
.PP
A partial write is a write to the \fIOFILE\fR of less than \fIOBS\fR
bytes. This typically occurs at the end of a copy. dd can do partial
writes. ddpt does partial writes to regular files and fifos (including
stdout). However ddpt ignores partial writes when \fIOFILE\fR is a block
device or a pt device. When ddpt ignores a partial write, it sends a
warning to the console (stderr).
.PP
At the end of the copy two lines are reported to the console:
.br
   <in_full>+<in_partial> records in
.br
   <out_full>+<out_partial> records out
.PP
The "records in" line is the number of full input blocks (each of
\fIIBS\fR bytes) that have been read plus the number of partial blocks (
usually less than \fIIBS\fR bytes) that have been read. Following the lead
of dd when 'iflag=coe' is active a block that cannot be read (and has zeros
substituted for its output) is regarded as a partial read. The "records out"
line is the number of full output blocks (each of \fIOBS\fR bytes) that
have been written plus the number of partial blocks (usually less than
\fIOBS\fR bytes) that have been written.
.PP
Block devices (e.g. /dev/sda and /dev/hda) can be given for \fIIFILE\fR.
If neither 'iflag=direct' nor 'iflag=pt' is given then normal block IO
involving buffering and caching is performed. If 'iflag=direct' is given
then the buffering and caching is bypassed (this is applicable to both SCSI
devices and ATA disks). When 'iflag=pt' is given SCSI commands are sent to
the device which bypasses most of the actions performed by the block layer.
The same applies for block devices given for \fIOFILE\fR.
.PP
.PP
All informative, warning and error reports are sent to stderr so that
dd's output file can be stdout and remain unpolluted. If no options
are given, then no copying (nor reading) takes place and a brief message
is sent to stderr inviting the user to invoke ddpt again but with '\-\-help'
option to get the usage message.
.PP
Disk partition information can often be found with
.B fdisk(8)
[the "\-ul" argument is useful in this respect]. Also
.B parted(8)
can be used like this: 'parted /dev/sda unit s print' .
.PP
For pt devices this utility issues SCSI READ and WRITE (SBC) commands which
are appropriate for disks and reading from CD/DVD/BD drives. Those
commands are not formatted correctly for tape drives so ddpt cannot be
used on tape drives via a pt device. If the largest block address of the
requested transfer exceeds a 32 bit block number (i.e 0xffffffff) then a
warning is issued and the pt device is accessed via SCSI READ(16) and
WRITE(16) commands.
.PP
.B The attributes of a block device (e.g. partitions) are ignored when the
.B pt flag is used.
Hence the whole device is read (rather than just the second partition) by
this invocation:
.PP
   ddpt if=/dev/sdb2 iflag=pt of=t bs=512
.PP
Assuming /dev/sdb and /dev/sg2 refer to the same device, then after the
following two invocations, the contents of the files "t", "tt" and "ttt"
should be same:
.PP
   ddpt if=/dev/sdb of=tt bs=512
.PP
   ddpt if=/dev/sg2 of=ttt bs=512
.PP
The SCSI READ(32) and WRITE(32) commands are restricted to media that is
formatted with protection type 2. This is a T10 restriction.
.SH SIGNALS
The signal handling has been borrowed from GNU's dd: SIGINT, SIGQUIT and
SIGPIPE report the number of remaining blocks to be transferred and the
records in + out counts; then they have their default action. SIGUSR1 (or
SIGINFO) causes the same information to be output and the copy continues.
All output caused by signals is sent to stderr.
.PP
Like GNU's dd, ddpt respects the signal disposition of "ignored" (SIG_IGN)
set by the shell, script or other program that invokes ddpt. So in that
case it will ignore such signals. Further dd ignores SIGUSR1 if the
environment variable POSIXLY_CORRECT is set because POSIX defines dd will
only act on SIGINFO (and Linux has no such signal); ddpt ignores the
POSIXLY_CORRECT environment variable. As recommended by Susv3, ddpt does
not expect the signal (blocking) mask to be blocking SIGUSR1 (SIGINFO),
SIGINT or SIGPIPE on entry.
.PP
Unix system calls that do IO can be interrupted by signal processing,
typically returning an EINTR error number. The dd utility (and many other
Unix utilities) restart the IO operation that was interrupted. While
this will work most of the time for disk IO it is problematic for tape
drives because the implicit position pointer on the tape may have moved.
So the default (i.e. "intio=0") in this utility is to mask those signals
during IO operations and only check them prior to starting an IO operation.
Most low level IO (e.g. using SCSI command to write to a disk) will
timeout if there is a low level error. However NFS (the Network File
System) will potentially wait for a long time (e.g. expecting a network
problem will soon be fixed) and in this case using "intio=1" may be
best.
.SH VERIFY
The usual way to check the two disks (or part of the disks) are the same
is to move through the segments to be compared, reading from both and
comparing the returned buffers, stopping if there is an in equality.
.PP
This utility takes a different approach that relies on the \fIOFILE\fR
being a pass through device. That pass\-through device needs to support
the SCSI VERIFY command with the BYTCHK field set to 1. Optionally, for
the \fI\-\-prefetch\fR option to improve performance that pass\-through
device needs to support the SCSI PRE\-FETCH command with its IMMED bit
set.
.PP
When the \fI\-\-verify\fR option is given, instead of reading both
\fIIFILE\fR and \fIOFILE\fR, only the \fIIFILE\fR is read. Then the result
of that read is sent to the \fIOFILE\fR device as the data\-out buffer
of a VERIFY(BYTCHK=1) command. So the comparison is actually done on the
\fIOFILE\fR device rather than the host computer's main memory.
.PP
If the \fI\-\-prefetch\fR option is also given, then before the \fIIFILE\fR
read, a PRE\-FETCH(OFILE, IMMED) is sent. The IMMED bit will make it return
more or less immediately. The effect of the PRE\-FETCH should be to bring
the contents of the data to be used for the \fIOFILE\fR side of the
comparison, into the \fIOFILE\fR device's cache. And that should make the
later VERIFY(BYTCHK=1) command faster.
.SH TAPE
There is support for copies to and from tape drives in Linux. Only the st
driver device names can be used (e.g. /dev/st0 and /dev/nst2). Hence use of
Linux pass\-through device names (e.g. /dev/sg2) for tape drives is not
supported. On Debian\-based distributions, it is suggested that the mt\-st
package is installed as it provides a more fully\-featured version of
the "mt" tape control program.
.PP
Tape drives can operate in fixed\- or variable\-length block modes. In
variable\-block mode, each write to the tape writes a single block of that
size. In fixed\-block mode, each write to the tape must be a multiple of the
previously\-selected block size.
.PP
The block size/mode can be set with the mt command prior to invoking ddpt.
For example:
.br
  # mt \-f /dev/nst0 setblk 0
.br
sets variable\-block mode, and
.br
  # mt \-f /dev/nst0 setblk 32768
.br
sets fixed\-block mode with block size 32768 bytes.
.PP
Note that some tape drives support only fixed\-block mode, and possibly
even only one block size. (For example, QIC\-150 tapes use a fixed block
size of 512 bytes.) There may also be restrictions on the block size, e.g.
it may have to be even.
.PP
When using ddpt to write to tape, if the final read from the input is less
than \fIOBS\fR, it is padded to \fIOBS\fR bytes before writing to tape to
ensure that all blocks of the tape file are the same length. Having a
shorter final block would fail if the drive is in fixed\-block mode, and
could create interchange problems. It is common to expect all blocks in a
file on tape to be the same length. However, to tell ddpt to not pad the
final block, use 'oflag=nopad'.
.PP
The st tape driver normally writes a filemark when the file (e.g. /dev/nst0)
is closed. To not have the filemark written, use 'oflag=nofm'. One use case
for that might be if using ddpt several times in succession to append more
data to the same file on tape. In that case it is probably desirable to
write the filemark at the end of the sequence. So either omit 'oflag=nofm'
on the last ddpt invocation, or manually write a filemark using mt after
ddpt exits:
.br
  # mt \-f /dev/nst0 weof 1
.PP
For reading from an unknown tape where the block size(s) is not known, read
in variable\-block mode specifying a large \fIIBS\fR. The st driver returns
a smaller amount of data if the size of the block read is smaller. Thus a
command like:
.br
  # ddpt if=/dev/nst0 of=output.bin bs=262144
.br
should read the file from tape regardless of the block size used (assuming
no blocks are larger than 256KB). ddpt's verbose option will display what
the actual block size(s) is.
.SH ENVIRONMENT VARIABLES
If the command line invocation of an xcopy does not explicitly (and
unambiguously) indicate whether the XCOPY SCSI command should be sent
to \fIIFILE\fR (i.e.  the source) or \fIOFILE\fR (i.e. the destination)
then a check is made for the presence of the XCOPY_TO_SRC and
XCOPY_TO_DST environment variables. If either one exists (but not both)
then it indicates where the SCSI XCOPY command will be sent. By default
the XCOPY command is sent to \fIOFILE\fR.
.PP
The ODX write from tokens variant is very complex to implement if the amount
of data held in each ROD is not known. The value should be found in
the "number of bytes represented" field in the ROD Token but that is not well
supported yet by vendors. So for such cases, that number can be appended as a
big endian 8 byte integer following each ROD Token in the \fIRTF\fR file. The
\fIconv=rtf_len\fR will cause that length to be appended. Specifying that
option on each read to tokens and write from tokens invocation can be a
nuisance. Setting the environment variable ODX_RTF_LEN will cause this
utility to act as if the \fIconv=rtf_len\fR option has been given.
.PP
Sometimes the default block size of 512 can be a nuisance. This can be
overridden by the value associated with the DDPT_DEF_BS environment
variable. If the environment variable is not found, the value cannot
be decoded or is zero or less, then the default block size remains
at 512 bytes.
.SH EXIT STATUS
To aid scripts that call ddpt, the exit status is set to indicate
success (0) or failure (1 or more). Note that some of the lower values
correspond to the SCSI sense key values. The exit status values are:
.TP
.B 0
success. Also conveys boolean true for actions that result in true or
false (e.g. sgl equality tests)
.TP
.B 1
syntax error. Either illegal command line options, options with bad
arguments or a combination of options that is not permitted.
.TP
.B 2
the device reports that it is not ready for the operation requested.
The device may be in the process of becoming ready (e.g.  spinning up but
not at speed) so the utility may work after a wait.
.TP
.B 3
the device reports a medium or hardware error (or a blank check). For example
an attempt to read a corrupted block on a disk will yield this value.
.TP
.B 5
the device reports an "illegal request" with an additional sense code other
than "invalid operation code". This is often a supported command with a
field set requesting an unsupported capability.
.TP
.B 6
the device reports a "unit attention" condition. This usually indicates
that something unrelated to the requested command has occurred (e.g. a
device reset) potentially before the current SCSI command was sent. The
requested command has not been executed by the device. Note that unit
attention conditions are usually only reported once by a device.
.TP
.B 7
the device reports a "data protect" sense key. This implies some
mechanism has blocked writes (or possibly all access to the media).
.TP
.B 9
the device reports an illegal request with an additional sense code
of "invalid operation code" which means that it doesn't support the
requested command.
.TP
.B 10
the device reports a "copy aborted". This implies another command or
device problem has stopped and copy operation. The EXTENDED COPY family of
commands (including WRITE USING TOKEN) may return this sense key.
.TP
.B 11
the device reports an aborted command. In some cases aborted commands can
be retried immediately (e.g. if the transport aborted the command due to
congestion).
.TP
.B 14
the \fIDEVICE\fR reports a miscompare sense key. VERIFY and COMPARE AND
WRITE commands may report this.
.TP
.B 15
the utility is unable to open, close or use the given \fIIFILE\fR,
\fIOFILE\fR or other file. The given file name could be incorrect or there
may be permission problems. Adding the \fI\-v\fR option may give more
information.
.TP
.B 20
the device reports it has a check condition but "no sense".
It is unlikely that this value will occur as an exit status.
.TP
.B 21
the device reports a "recovered error". The requested command was successful.
Most likely a utility will report a recovered error to stderr and continue,
probably leaving the utility with an exit status of 0 .
.TP
.B 24
the device reports a SCSI status of "reservation conflict". This
means access to the device with the current command has been blocked
because another machine (HBA or SCSI "initiator") holds a reservation on
this device. On modern SCSI systems this is related to the use of
the PERSISTENT RESERVATION family of commands.
.TP
.B 25
the \fIDEVICE\fR reports a SCSI status of "condition met". Currently only
the PRE\-FETCH command (see SBC\-4) yields this status.
.TP
.B 26
the \fIDEVICE\fR reports a SCSI status of "busy". SAM\-5 defines this
status as the logical unit is temporarily unable to process a command.
It is recommended to re\-issue the command.
.TP
.B 27
the \fIDEVICE\fR reports a SCSI status of "task set full".
.TP
.B 28
the \fIDEVICE\fR reports a SCSI status of "ACA active". ACA is "auto
contingent allegiance" and is seldom used.
.TP
.B 29
the \fIDEVICE\fR reports a SCSI status of "task aborted". SAM\-5 says:
"This status shall be returned if a command is aborted by a command or task
management function on another I_T nexus and the Control mode page TAS bit
is set to one".
.TP
.B 31
error involving two or more command line options. Either they contradict
or select an unsupported mode.
.TP
.B 32
the is a logic error in the utility. It corresponds to code comments
like "shouldn't/can't get here". Perhaps the author should be contacted.
.TP
.B 33
the command sent to device has timed out. This occurs in Linux only; in
other ports a command timeout will appear as a transport (or OS) error.
.TP
.B 36
no error has occurred. For actions that result in a boolean, this exit
status indicates false.
.TP
.B 40
the command sent to a device has received an "aborted command" sense
key with an additional sense code of 0x10. This value is related to
problems with protection information (PI or DIF). For example this error
may occur when reading a block on a drive that has never been written (or
is unmapped) if that drive was formatted with type 1, 2 or 3 protection.
.TP
.B 48
this is an internal message indicating a NVMe status field (SF) is other
than zero after a command has been executed (i.e. something went wrong).
Work in this area is currently experimental.
.TP
.B 49
low level driver reports a response's residual count (i.e. number of bytes
actually received by HBA is 'requested_bytes \- residual_count') that is
too high. So no useful processing can be done with that response.
.TP
.B 50 + <os_error_number>
OS system calls that fail often return a small integer number to help
indicate what the error is. For example in Unix the inability of a system
call to allocate memory returns (in 'errno') ENOMEM which often is
associated with the integer 12. So 62 (i.e. '50 + 12') may be returned
by a utility in this case.
.TP
.B 90
the flock flag has been given on a device and some other process holds the
advisory exclusive lock.
.TP
.B 97
the response to a SCSI command failed sanity checks.
.TP
.B 98
the device reports it has a check condition but the error doesn't fit into
any of the above categories.
.TP
.B 99
any errors that can't be categorized into values 1 to 98 may yield
this value. This includes transport and operating system errors
after the command has been sent to the device.
.TP
.B 100
a command received a 'parameter list length error'.
.TP
.B 101
a command received 'illegal field in parameter list'. This may occur with an
odx copy if some combination of parameters is illegal or not supported (e.g.
iflag=immed).
.TP
.B 105
a command received 'operation in progress'. This may occur with an odx copy
when the given \fILID\fR is already being used by another process (e.g. also
using odx) on the same machine. Choose another \fILID\fR.
.TP
.B 110
a command received 'invalid token operation, cause not reportable'. This may
occur with an odx operation when the given ROD Token is invalid. One reason
for that may be the inactivity timeout has been reached and the copy manager
has cancelled the ROD Token.
.TP
.B 110 + <asc_23h_ascq_code>
these status values provide more information than exit status 110. See SPC\-5
ASC and ASCQ assignments (currently in Annex F.2), specifically the entries
for asc=23h . For example exit status 112 corresponds to asc=23h, ascq=2h
which implies the odx copy manager does not support copies between LUs in
different targets. That is optional; an odx copy manager is required to
support copies between LUs (that are block devices) in the same target.
.TP
.B 126
the utility was found but could not be executed. That might occur if the
executable does not have execute permissions.
.TP
.B 127
This is the exit status for utility not found. That might occur when a
script calls a utility in this package but the PATH environment variable
has not been properly set up, so the script cannot find the executable.
.TP
.B 128 + <signum>
If a signal kills a utility then the exit status is 128 plus the signal
number. For example if a segmentation fault occurs then a utility is
typically killed by SIGSEGV which according to 'man 7 signal' has an
associated signal number of 11; so the exit status will be 139 .
.TP
.B 255
the utility tried to yield an exit status of 255 or larger. That should
not happen; given here for completeness.
.SH EXAMPLES
The examples in this page use Linux device names. For suitable device
names in other supported Operating Systems see this web page:
https://sg.danny.cz/sg/device_name.html . The sg3_utils(8) man page
in the sg3_utils package also covers device naming.
.PP
ddpt usage looks quite similar to dd:
.PP
   ddpt if=/dev/sg0 of=t bs=512 count=1MB
.PP
This will copy 1 million 512 byte blocks from the device associated with
/dev/sg0 (which should have 512 byte blocks) to a file called t.
Assuming /dev/sda and /dev/sg0 are the same device then the above is
equivalent to:
.PP
   dd if=/dev/sda iflag=direct of=t bs=512 count=1000000
.PP
although dd's speed may improve if bs was larger and count was suitably
reduced. The use of the 'iflag=direct' option bypasses the buffering and
caching that is usually done on a block device.
.PP
The dd command's bs argument can be thought of as roughly equivalent to
ddpt's bs*bpt . dd almost assumes buffering on a block device and will
work as long as bs is a multiple of the actual logical block size.
Since ddpt can work at a lower level in some cases the bs argument must be
a disk's actual logical block size. Thus the bpt argument was introduced
to make the copy more efficient. So these two invocations are roughly
equivalent:
.PP
   dd if=/dev/sda of=t bs=8k count=64
.br
   ddpt if=/dev/sda of=t bs=512 bpt=16 count=1k
.PP
In both cases the total number of bytes moved is bs*count . And that will
be done by reading 8k (8192 bytes) into a buffer then writing out that
buffer to the file t. The read write sequence continues until the
count is complete or an error occurs.
.PP
The 'of2=' option can save time when the input would otherwise need to be
read twice. For example, to copy data and take a md5sum of it without
needing to re\-read the data:
.PP
  mkfifo fif
.br
  md5sum fif &
.br
  ddpt if=/dev/sg3 iflag=coe of=sg3.img oflag=sparse of2=fif bs=512
.PP
This will image /dev/sg3 (e.g. an unmounted disk) and place the contents
in the (sparse) file sg3.img . Without re\-reading the data it will also
perform a md5sum calculation on the image.
.PP
Now we use sparse writing logic to get some idea of how many blocks
on a disk are full of zeros. After a SCSI FORMAT UNIT command or an ATA
SECURITY ERASE command a disk may be all zeros.
.PP
   ddpt if=/dev/sdc bs=512 oflag=sparse
.PP
Since no "of=" option is given, output goes to /dev/null so nothing
is actually written so the "records out" will be zero. However there
will be a count of "records in" and "bypassed records out". If /dev/sdc is
full of zeros then "records in" and "bypassed records out" will be
the same. Since the "bpt=" option is not given it defaults to "bpt=128,128"
so the copy buffer will be 64 KiB and the sparse check for zeros will
be done with 64 KiB (128 block) granularity.
.PP
For examples of the trim and self,trim options see the section above
on TRIM, UNMAP AND WRITE SAME.
.PP
Following is an example run on a Windows OS using the '\-\-wscan' option
which shows the available device names (e.g. PD1) and the associated volume
name(s):
.PP
   ddpt \-w
.br
PD0     [C]     FUJITSU   MHY2160BH         0000
.br
PD1     [DF]    WD        2500BEV External  1.05  WD\-WXE90
.br
CDROM0  [E]     MATSHITA DVD/CDRW UJDA775  CB03
.PP
So, for example, volumes D: and F: reside on PhysicalDisk1 (abbreviated to
"PD1") which is manufactured by WD (Western Digital).
.PP
Further examples can be found on this web page:
https://sg.danny.cz/sg/ddpt.html . There is a text file containing examples
called ddpt_examples.txt in the "doc" directory of this package's
distribution tarball. The ddpt_examples.txt file contains some examples of
using job files.
.SH AUTHORS
Written by Doug Gilbert
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2008\-2021 Douglas Gilbert
.br
This software is distributed under the GPL version 2. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
This utility has companion/helper utilities
.B ddptctl(8), ddpt_sgl(8)
.br
There is a web page discussing ddpt at https://sg.danny.cz/sg/ddpt.html
.PP
The lmbench package contains
.B lmdd
which is also interesting. For moving data to and from tapes see
.B dt
which is found at http://www.scsifaq.org/RMiller_Tools/index.html
.PP
To change mode parameters that effect a SCSI device's caching and error
recovery see
.B sdparm(sdparm)
.PP
To verify the data on the media is readable see:
.B sg_verify(sg3_utils)
.PP
To scan and repair disk partitions see TestDisk (testdisk).
.PP
Additional references:
.B dd(1), open(2), flock(2), sg_xcopy,sg_copy_results,
.B sg_dd(sg3_utils)